Public : API для работы с купонами партнеров Литрес 2.0

Created by Дмитрий Коняев, last modified on февр. 11, 2026

Введение

Партнерский API промокодов и сертификатов предоставляет программный интерфейс для управления промокодами и сертификатами в системе Литрес. API позволяет партнерам автоматизировать процессы выпуска, отслеживания и управления кодами.

Старая версия API - https://docs.litres.ru/public/6425738.html

Основные возможности API:

  • Получение списка доступных серий кодов.

  • Выпуск новых кодов из существующих серий кодов.

  • Получение списка активных (непогашенных) и погашенных кодов.

  • Просмотр детальной информации о конкретном коде.

  • Регистрация продаж кодов.

  • Удаление кодов.

Базовый URL

Все запросы выполняются к базовому URL:

https://api.litres.ru/foundation/api

Авторизация

Для доступа к API используется HMAC-подпись на основе секретного ключа партнера. 

Заголовки запроса

Каждый запрос должен содержать следующие заголовки:


ЗаголовокОписаниеПример

X-Timestamp

Текущая временная метка в формате UNIX-timestamp.

1738575385

X-Signature

HMAC-SHA256 подпись в строковом представлении.

a1b2c3d4e5f6...

Формирование подписи

Подпись формируется по формуле: 

HMAC-SHA256(timestamp + "." + partnerId, partnerKey)

Где:

  • timestamp – UNIX-timestamp;

  • partnerId – идентификатор партнера;

  • partnerKey – секретный ключ партнера.

Формат данных

Временные метки

Все временные метки в API передаются в формате ISO 8601 с часовым поясом, предпочтительно в UTC:

  • "2026-02-02T09:00:00Z"

  • "2026-12-31T20:59:00Z"

Пагинация

Методы, возвращающие списки, поддерживают курсорную пагинацию через объект pagination:

  • next_page – URL для получения следующей страницы

  • previous_page – URL для получения предыдущей страницы

Размер страницы регулируется при отправлении запроса параметром запроса limit . 

Ограничения

  1. Частота запросов: Соблюдайте разумные интервалы между запросами.

  2. Количество кодов: Ограничение на выпуск кодов – 1000 кодов за раз.

  3. Время жизни подписи: Подпись действительна в течение 1 минуты.

Ошибки

Запросы к API могут возвращать разные ошибки, как ошибки партнерского API промокодов и сертификатов, так и ошибки сервера.

В объекте ошибки всегда присутствует набор из 3 полей: type, title и detail. Поле type есть всегда, поля title и detail могут не отправляться сервером в зависимости от специфики ошибки, но все равно следует ожидать, что они могут быть, чтобы иметь возможность их обработать.

Также к каждому из типов ошибки могут добавляться свои собственные уникальные поля. Обрабатывать их требуется только в том случае, если это нужно для функционирования интеграции с API. В остальных случаях достаточно обрабатывать набор из 3 полей.

Ниже будет приведена общая структура данных для всех возможных ошибок при запросах к API на примере общей ошибки сервера.

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка.
├ type
Строка

Обязательный

Тип ошибки.
├ title
Строка

Необязательный

Название ошибки, если есть.
├ detail
Строка

Необязательный

Детали ошибки, если есть.
├ error_descriptions
Объект

Необязательный

Собственные данные ошибки. 
{
    "status": 422,
    "error": {
        "type": "ParamValidationError",
        "title": "Validation error because of request parameters",
        "detail": "Received a validation error while interpreting request parameters. See error_descriptions for details",
        "error_descriptions": [
            {
                "loc": [
                    "body",
                    "quantity"
                ],
                "msg": "Input should be greater than or equal to 1",
                "type": "greater_than_equal"
            }
        ]
    }
}


Методы

Получение списка доступных для выпуска серий кодов

Метод

Путь

GET/partners/:partnerId/promocodes/series

Запрос

Параметры пути

Название

Тип

Наличие

Описание

partnerIdЦелое число

Обязательный

Идентификатор партнера.

Параметры запроса

Название

Тип

Наличие

Описание

limitЦелое число

Необязательный

Количество записей на странице, от 1 до 100, по умолчанию 10.
beforeСтрока

Необязательный

Указатель предыдущей страницы, предоставляет сервер.
afterСтрока

Необязательный

Указатель следующей страницы, предоставляет сервер.

Ответ

Успешное получение списка доступных для выпуска серий кодов

Код статуса

200 OK

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка, есть есть ошибка.
payload
Объект

Обязательный

Полезная нагрузка, если нет ошибки.
├ pagination
Объект

Обязательный

Пагинация.
│ ├ next_page
URL

Обязательный

URL следующей страницы, если есть.

│ ├ previous_page
URL

Обязательный

URL предыдущей страницы, если есть.
├ data
Список объектов

Обязательный

Список данных.
│ ├ id
Целое число

Обязательный

Идентификатор серии кодов.
│ ├ quantity
Целое число

Обязательный

Количество кодов в серии кодов.
│ ├ configuration_id
Целое число

Обязательный

Идентификатор конфигурации кода. 
│ ├ nominal
Строка

Обязательный

Номинал кода, в десятичном выражении.
│ ├ discount
Объект

Обязательный

Скидка.
│ │ ├ discount_percent
Целое число

Обязательный

Процент скидки.
│ │ ├ discount_duration_days
Целое число

Обязательный

Продолжительность скидки в днях.
│ │ ├ discount_collection_id
Целое число

Обязательный

Идентификатор скидочной коллекции, если есть.
│ ├ price
Строка

Обязательный

Цена кода, в десятичном выражении.
│ ├ description
Строка

Обязательный

Описание серии кодов, если есть.
│ ├ message_subject
Строка

Обязательный

Тема сообщения, если есть.
│ ├ message_body
Строка

Обязательный

Тело сообщения в HTML-формате, если есть.
│ ├ valid_until
Временная метка

Обязательный

Дата и время истечения действия серии кодов.
│ ├ arts
Список объектов

Обязательный

Список книг прикрепленных к серии кодов.
│ │ ├ art_id
Целое число

Обязательный

Идентификатор книги.
│ ├ is_arts_override_allowed
Флаг

Обязательный

Разрешено ли переопределение книгприкрепленных к серии кодов.
{
    "status": 200,
    "error": null,
    "payload": {
        "pagination": {
            "next_page": null,
            "previous_page": null
        },
        "data": [
            {
                "id": 355178,
                "quantity": 8,
                "configuration_id": 198268,
                "nominal": "0.0",
                "discount": {
                    "discount_percent": 0,
                    "discount_duration_days": 0,
                    "discount_collection_id": null
                },
                "price": "0.0",
                "description": "Партнерская подписка N",
                "message_subject": "Подписка N активирована",
                "message_body": "<p>Поздравляем с активацией подписки N!</p>",
                "valid_until": "2026-12-31T20:59:00Z",
                "arts": [],
                "is_arts_override_allowed": false
            }
        ]
    }
}


Получение списка непогашенных кодов

Метод

URL

GET/partners/:partnerId/promocodes/active

Запрос

Параметры пути

Название

Тип

Наличие

Описание

partnerIdЦелое число

Обязательный

Идентификатор партнера.

Параметры запроса

Название

Тип

Наличие

Описание

limitЦелое число

Необязательный

Количество записей на странице, от 1 до 100, по умолчанию 10.
beforeСтрока

Необязательный

Указатель предыдущей страницы, предоставляет сервер.
afterСтрока

Необязательный

Указатель следующей страницы, предоставляет сервер.

Ответ

Успешное получение списка непогашенных кодов

Код статуса

200 OK

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка, заполнен только есть есть ошибка.
payload
Объект

Обязательный

Полезная нагрузка, заполнена только если нет ошибки.
├ pagination
Объект

Обязательный

Пагинация.
│ ├ next_page
URL

Обязательный

URL следующей страницы, заполнен если есть.

│ ├ previous_page
URL

Обязательный

URL предыдущей страницы, заполнен если есть.
├ data
Список объектов

Обязательный

Список данных.
│ ├ code
Строка

Обязательный

Код.
│ ├ id
Целое число

Обязательный

Идентификатор кода. 
│ ├ series_id
Целое число

Обязательный

Идентификатор серии кодов. 
│ ├ expires_at
Временная метка

Обязательный

Дата и время истечения кода. 
│ ├ promocode_arts
Список объектов

Обязательный

Список книг прикрепленных к коду. 
│ │ ├ art_id
Целое число

Обязательный

Идентификатор книги.
│ ├ promocode_bonus_arts
Список объектов

Обязательный

Список бонусных книг прикрепленных к коду. 
│ │ ├ art_id
Целое число

Обязательный

Идентификатор книги.
{
    "status": 200,
    "error": null,
    "payload": {
        "pagination": {
            "next_page": null,
            "previous_page": null
        },
        "data": [
            {
                "code": "4810553506676722",
                "id": 6504523553,
                "series_id": 355178,
                "expires_at": "2026-12-31T20:59:00Z",
                "promocode_arts": [],
                "promocode_bonus_arts": []
            },
            {
                "code": "1407632935067730",
                "id": 6504523558,
                "series_id": 355178,
                "expires_at": "2026-12-31T20:59:00Z",
                "promocode_arts": [],
                "promocode_bonus_arts": []
            }
        ]
    }
}


Получение списка погашенных кодов

Метод

URL

GET/partners/:partnerId/promocodes/redeemed

Запрос

Параметры пути

Название

Тип

Наличие

Описание

partnerIdЦелое число

Обязательный

Идентификатор партнера.

Параметры запроса

Название

Тип

Наличие

Описание

fromВременная метка

Необязательный

Дата и время начала периода, для которого нужно получить список погашенных кодов.
toВременная метка

Необязательный

Дата и время конца периода, для которого нужно получить список погашенных кодов.
limitЦелое число

Необязательный

Количество записей на странице, от 1 до 100, по умолчанию 10.
beforeСтрока

Необязательный

Указатель предыдущей страницы, предоставляет сервер.
afterСтрока

Необязательный

Указатель следующей страницы, предоставляет сервер.

Ответ

Успешное получение списка погашенных кодов

Код статуса

200 OK

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка, заполнен только есть есть ошибка.
payload
Объект

Обязательный

Полезная нагрузка, заполнена только если нет ошибки.
├ pagination
Объект

Обязательный

Пагинация.
│ ├ next_page
URL

Обязательный

URL следующей страницы, заполнен если есть.

│ ├ previous_page
URL

Обязательный

URL предыдущей страницы, заполнен если есть.
├ data
Объект

Обязательный

Данные.
│ ├ code
Строка

Обязательный

Код.
│ ├ redeemed_at
Временная метка

Обязательный

Дата и время погашения кода.
│ ├ id
Целое число

Обязательный

Идентификатор кода. 
{
    "status": 200,
    "error": null,
    "payload": {
        "pagination": {
            "next_page": null,
            "previous_page": null
        },
        "data": [
            {
                "code": "sxk8s8h2hd4stndt",
                "redeemed_at": "2026-02-02T09:02:54Z",
                "id": 6504742761
            }
        ]
    }
}

Получение информации о коде

Метод

URL

GET/partners/:partnerId/promocodes/:code

Запрос

Параметры пути

Название

Тип

Наличие

Описание

partnerIdЦелое число

Обязательный

Идентификатор партнера.
codeСтрока

Обязательный

Код.

Ответ

Успешное получение информации о коде

Код статуса

200 OK

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка, заполнен только есть есть ошибка.
payload
Объект

Обязательный

Полезная нагрузка, заполнена только если нет ошибки.
├ data
Список объектов

Обязательный

Список данных.
│ ├ code
Строка

Обязательный

Код.
│ ├ id
Целое число

Обязательный

Идентификатор кода. 
│ ├ series_id
Целое число

Обязательный

Идентификатор серии кодов. 
│ ├ expires_at
Временная метка

Обязательный

Дата и время истечения кода. 
│ ├ promocode_arts
Список объектов

Обязательный

Список книг прикрепленных к коду. 
│ │ ├ art_id
Целое число

Обязательный

Идентификатор книги.
│ ├ promocode_bonus_arts
Список объектов

Обязательный

Список бонусных книг прикрепленных к коду. 
│ │ ├ art_id
Целое число

Обязательный

Идентификатор книги.
{
    "status": 200,
    "error": null,
    "payload": {
        "data": {
            "code": "sxk8s8h2hd4stndt",
            "id": 6504742761,
            "series_id": 355178,
            "expires_at": "2026-12-31T20:59:00Z",
            "promocode_arts": [],
            "promocode_bonus_arts": []
        }
    }
}

Выпуск кодов из серии кодов

Метод

URL

POST/partners/:partnerId/promocodes/series/:seriesId/issue

Запрос

Параметры пути

Название

Тип

Наличие

Описание

partnerIdЦелое число

Обязательный

Идентификатор партнера.
seriesIdЦелое число

Обязательный

Идентификатор серии кодов.

Тело

Название

Тип

Наличие

Описание

quantity

Целое число

Обязательный

Количество кодов, от 1 до 1000.
uuidsСписок UUID

Необязательный

Список UUID книг, которые нужно прикрепить к выпускаемым кодам. При передаче этого поля книги в серии кодов будут переопределены.
bonus_uuidsСписок UUID

Необязательный

Список UUID бонусных книг, которые нужно прикрепить к выпускаемым кодам. Если указан список UUID книг, этот список будет проигнорирован.

Ответ

Успешный выпуск кодов из серии кодов

Код статуса

201 Created

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка, заполнен только есть есть ошибка.
payload
Объект

Обязательный

Полезная нагрузка, заполнена только если нет ошибки.
├ data
Список объектов

Обязательный

Список данных.
│ ├ issued_quantity
Целое число

Обязательный

Количество выпущенных кодов из серии кодов.
│ ├ promocodes
Список объектов

Обязательный

Список выпущенных кодов.
│ │ ├ id
Целое число

Обязательный

Идентификатор кода.
│ │ ├ code
Строка

Обязательный

Код.
{
    "status": 201,
    "error": null,
    "payload": {
        "data": {
            "issued_quantity": 2,
            "promocodes": [
                {
                    "id": 6506041616,
                    "code": "7kcht248mh8brc3t"
                },
                {
                    "id": 6506041621,
                    "code": "rvjvr4f5g5njbz7h"
                }
            ]
        }
    }
}

Удаление кодов

Метод

URL

POST/partners/:partnerId/promocodes/remove

Запрос

Параметры пути

Название

Тип

Наличие

Описание

partnerIdЦелое число

Обязательный

Идентификатор партнера.

Тело

Название

Тип

Наличие

Описание

codes

Список строк

Обязательный

Список кодов для удаления, от 1 до 100.

Ответ

Успешное удаление кодов

Код статуса

200 OK

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка, заполнен только есть есть ошибка.
payload
Объект

Обязательный

Полезная нагрузка, заполнена только если нет ошибки.
├ data
Список объектов

Обязательный

Список данных.
│ ├ requested_quantity
Целое число

Обязательный

Количество запрошенных к удалению кодов.
│ ├ removed_quantity
Целое число

Обязательный

Количество удаленных кодов.
│ ├ results
Список объектов

Обязательный

Список результатов удаления кодов.
│ │ ├ id
Целое число

Обязательный

Идентификатор кода.
│ │ ├ redeem_at
Временная метка

Обязательный

Дата и время погашения кода.
│ │ ├ code
Строка

Обязательный

Код.
│ │ ├ is_removed
Флаг

Обязательный

Удален ли код.
│ │ ├ failure_reason
Строка

Обязательный

Причина отказа в удалении, если есть.
{
    "status": 200,
    "error": null,
    "payload": {
        "data": {
            "requested_quantity": 2,
            "removed_quantity": 2,
            "results": [
                {
                    "id": 6506041616,
                    "redeem_at": null,
                    "code": "7kcht248mh8brc3t",
                    "is_removed": true,
                    "failure_reason": null
                },
                {
                    "id": 6506041626,
                    "redeem_at": null,
                    "code": "p6p8fq5t3d6vq8vr",
                    "is_removed": true,
                    "failure_reason": null
                }
            ]
        }
    }
}

Регистрация продажи кодов

Метод

URL

POST/partners/:partnerId/promocodes/sold

Запрос

Параметры пути

Название

Тип

Наличие

Описание

partnerIdЦелое число

Обязательный

Идентификатор партнера.

Тело

Название

Тип

Наличие

Описание

series_id

Целое число

Обязательный

Идентификатор серии кодов.

code

Строка

Обязательный

Код.

sold_at

Временная метка

Обязательный

Дата и время продажи кода.

Ответ

Успешная регистрация продажи кода

Код статуса

200 OK

Тело

Название

Тип

Наличие

Описание

status
Целое число

Обязательный

Код статуса.
error
Объект

Обязательный

Ошибка, заполнен только есть есть ошибка.
payload
Объект

Обязательный

Полезная нагрузка, заполнена только если нет ошибки.
├ data
Список объектов

Обязательный

Список данных.
│ ├ id
Целое число

Обязательный

Идентификатор кода.
│ ├ series_id
Целое число

Обязательный

Идентификатор серии кодов.
│ ├ sold_at
Временная метка

Обязательный

Дата и время продажи кода.
{
    "status": 200,
    "error": null,
    "payload": {
        "data": {
            "id": 6504742761,
            "series_id": 355178,
            "sold_at": "2026-02-02T09:00:00Z"
        }
    }
}

Коллекция Postman

Для партнерского API промокодов и сертификатов реализована коллекция запросов для Postman, которая позволяет лучше разобраться в устройстве API и попробовать его методы. В коллекции реализована автоматическая авторизация запросов. Для работы автоматической авторизации запросов требуется заполнить специальные переменные в коллекции. 

Партнерский API промокодов и сертификатов.postman_collection.json

Поддержка

При возникновении вопросов или проблем с API обращайтесь к отделу разработки Литрес с указанием:

  • Идентификатора партнера;

  • Времени возникновения ошибки;

  • X-Request-ID из заголовков ответа;

  • Подробного описания проблемы.


Attachments:

Партнерский API промокодов и сертификатов.postman_collection.json (application/octet-stream)