Версия документа - 1.1
Дата последнего обновления - 2026-03-13

В версии 1.1 добавлено описание: основных терминов, формат передачи данных, повторы запросов (idempotency), список возможных ошибок, их описание, информация о тестовом окружении и получении к нему доступов. Добавлена ссылка на Google диск, для скачивания Postman коллекции.

• Введение
  • Термины
    • Основные возможности API:
• Базовый URL и доступы
  • Prod
  • Test
• Авторизация
  • Заголовки запроса
  • Формирование подписи
• Формат данных
  • Тип данных
  • Временные метки
  • Пагинация
• Ограничения
• Повторы запросов (idempotency)
• Ошибки
  • Тело
  • Список возможных ошибок
• Методы
  • Получение списка доступных для выпуска серий кодов
    • Запрос
      • Параметры пути
      • Параметры запроса
    • Ответ
      • Успешное получение списка доступных для выпуска серий кодов
        • Код статуса
        • Тело
  • Получение списка непогашенных кодов
    • Запрос
      • Параметры пути
      • Параметры запроса
    • Ответ
      • Успешное получение списка непогашенных кодов
        • Код статуса
        • Тело
  • Получение списка погашенных кодов
    • Запрос
      • Параметры пути
      • Параметры запроса
    • Ответ
      • Успешное получение списка погашенных кодов
        • Код статуса
        • Тело
  • Получение информации о коде
    • Запрос
      • Параметры пути
    • Ответ
      • Успешное получение информации о коде
        • Код статуса
        • Тело
  • Выпуск кодов из серии кодов
    • Запрос
      • Параметры пути
      • Тело
    • Ответ
      • Успешный выпуск кодов из серии кодов
        • Код статуса
        • Тело
  • Удаление кодов
    • Запрос
      • Параметры пути
      • Тело
    • Ответ
      • Успешное удаление кодов
        • Код статуса
        • Тело
  • Регистрация продажи кодов
    • Запрос
      • Параметры пути
      • Тело
    • Ответ
      • Успешная регистрация продажи кода
        • Код статуса
        • Тело
• Коллекция Postman
• Поддержка
• Возможные вопросы

Введение

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

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

Термины

Серия - сущность, внутри которой выпускаются коды, предполагающие определенный тип контента, например подписка или номинал денежных средств, которые можно потратить на покупки внутри сервиса Литрес. Может иметь срок годности (valid_unltil), но также может быть и бессрочной. Сроком действия серии может управлять бизнес-менеджер или аккаунт-менеджер Литрес, значение может изменяться как в бОльшую, так и меньшую сторону. При достижении срока истечения, коды выпущенные в рамках серии будет невозможно активировать. Но если срок действия серии будет продлен - коды можно будет активировать. Как правило, для бесперебойной работы партнера с API, устанавливается срок действия на десятки лет вперед, или же не ограничивается вовсе.

Код (купон/сертификат) - цифровое или буквенно-цифровое значение (формат настраивается менеджером Литрес, но как правило используется цифровой 16-значный формат, например 0000111122223333 ), активация которого, внутри сервиса Литрес, подразумевает предоставление пользователю контента (например Литрес подписки, денежного номинала на счет аккаунта Литрес или книги). Срок действия купона привязан к сроку годности серии, если истекла серия - значит истекли все купоны, выпущенные в ее рамках. Код может иметь четыре основных состояния:

1. Выпущен - получен партнером посредством запроса в API
2. Активирован (погашен) пользователем в Литрес
3. Просрочен (истек) - в случае наступления valid_until у серии
4. Удален - стерт из базы данных Литрес

Погашение кода (активация) - активация кода пользователем на лендинге сайта или в приложении Литрес.

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

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

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

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

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

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

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

Базовый URL и доступы

Prod

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

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

Для работы с API, со стороны Литрес, партнеру выдаются:

partnerId - идентификатор партнера

partnerKey - секретный ключ для подписи запросов

seriesId - id серии/серий (при необходимости, получить список доступных серий партнер может вызвав метод /series)

Test

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

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

Для работы в тестовом окружении, со стороны Литрес, партнеру выдается отдельные:

partnerId - идентификатор партнера

partnerKey - секретный ключ для подписи запросов

seriesId - id серии

Авторизация

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

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

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

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

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

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

Где:

• timestamp – UNIX-timestamp;

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

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

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

Тип данных

application/json

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

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

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

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

Пагинация

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

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

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

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

Ограничения

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

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

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

4. Ограничений по RPS - нет
5. Ограничений по количеству параллельных запросов - нет

Повторы запросов (idempotency)

• Метод issue не является idempotent - повторный вызов с теми же параметрами сгенерирует новые коды (для проверки выпущенных кодов рекомендуется использовать метод GET /promocodes/{code})
• Нет механизма idempotency-key для повторных запросов
• Метод remove также не idempotent - удаление уже удаленного кода вернет is_removed: False с причиной NOT_FOUND в FailureReasonStatus

Ошибки

Запросы к 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"
            }
        ]
    }
}

Список возможных ошибок

Методы

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

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

Запрос

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

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

Ответ

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

Код статуса

200 OK

Тело

status

error

payload

├ pagination

│ ├ next_page

│ ├ previous_page

├ data

│ ├ id

│ ├ quantity

│ ├ configuration_id

│ ├ nominal

│ ├ discount

│ │ ├ discount_percent

│ │ ├ discount_duration_days

│ │ ├ discount_collection_id

│ ├ price

│ ├ description

│ ├ message_subject

│ ├ message_body

│ ├ 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
            }
        ]
    }
}

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

Запрос

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

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

Ответ

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

Код статуса

200 OK

Тело

status

error

payload

├ pagination

│ ├ next_page

│ ├ previous_page

├ 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": []
            }
        ]
    }
}

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

Если параметры from / to не переданы - по умолчанию возвращаются погашенные коды за последние сутки.

Запрос

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

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

Ответ

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

Код статуса

200 OK

Тело

status

error

payload

├ pagination

│ ├ next_page

│ ├ previous_page

├ 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
            }
        ]
    }
}

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

Запрос

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

Ответ

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

Код статуса

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": []
        }
    }
}

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

Запрос

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

Тело

Ответ

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

Код статуса

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"
                }
            ]
        }
    }
}

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

Запрос

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

Тело

Ответ

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

Код статуса

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
                }
            ]
        }
    }
}

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

Запрос

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

Тело

Ответ

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

Код статуса

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 и попробовать его методы. В коллекции реализована автоматическая авторизация запросов. Для работы автоматической авторизации запросов требуется заполнить специальные переменные в коллекции. 

Ссылка на Google Диск

Поддержка

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

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

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

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

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

Возможные вопросы

• Всегда ли сервер возвращает X-Request-ID в ответе? - Да.
• Есть ли SLA по времени ответа API? - 400 миллисекунд для 90-го процентиля.
• Как быстро после погашения код появляется в списке redeemed? - Сразу после погашения кода.