Public : Документация для партнеров. API для управления подписным ко-бренд сервисом

Created by Дмитрий Коняев on окт. 22, 2025
Версия документа1.7
Дата последнего обновления2025-07-22

2023-10-30 | Версия 1.2 - Добавлен новый метод, для проверки статуса конкретной подписки у пользователя  - /api/subscription/user/status
2023-11-17   | Версия 1.3 - В метод "new" добавлен новый необязательный параметр is_after_suspension
2024-01-24 | Версия 1.4 - Добавлен метод, для проверки статуса всех подписок оператора у пользователя - /api/subscription/user/status/all
2024-06-19 | Версия 1.5 - Добавлены примеры запросов, описание ошибок
2024-11-27 | Версия 1.6 - Добавлены два новых метода - для замены и удаления msisdn пользователя
2025-07-22 | Версия 1.7 - Добавлен новый метод - авторегистрация пользователя, получение user_id по msisdn

Введение

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

Доступы

Боевой URL для запросов - https://api.litres.ru/operator-integrations/
Тестовый URL для запросов - https://demo.api.litres.ru/operator-integrations/

Для доступа к тестовому окружению, партнер должен предоставить ip адреса, с которых планируется проводить тестирование

На стороне Литрес заводятся доступы и партнеру выдаются следующие данные

  • Partner_id -  указывается в теле запроса
  • Секретный API ключ партнера (secret_key) - используется для шифрования подписи запроса - signature
  • subscription_id - идентификатор подписки с уникальными настройками

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

Заголовки

Для авторизации запросов в API необходимы следующие заголовки:

  • Timestamp: Unix-таймстемп запроса в формате UTC.
  • Signature: HMAC(SHA-256 хэш от строки параметров, Секретный API ключ партнера).

Пример шифрования подписи:

const dataToHash = `${timestamp}.${partner_id}.${subscription_id}.${user_id}.${referral_partner_id}.${valid_till}.${start_time}`; 
const signature = CryptoJS.HmacSHA256(dataToHash, secretKey).toString();

Если вместо user_id, указывается msisdn - его и следует использовать для шифрования подписи
Если какой-либо, из необязательных параметров не передается в запросе - он не должен участвовать в формировании подписи 

Принимаются запросы с таймстемпом в пределах 5 минут от получения запроса. Для расчета подписи можно использовать например данный инструмент.

Эндпоинты

POST /api/subscription/new

Создание подписки у пользователя.

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

ПараметрТипНаличиеОписание
partner_idint

ОБЯЗАТЕЛЬНО

id партнера
user_idint

ОБЯЗАТЕЛЬНО*

Id пользователя Литрес
msisdnstr

ОБЯЗАТЕЛЬНО*

Номер телефона пользователя. Только цифры, без доп. символов, например 79998887766
subscription_idint

ОБЯЗАТЕЛЬНО

Id подписки
referral_partner_idint

НЕОБЯЗАТЕЛЬНО

Реферальный id партнера
start_time

str

ОБЯЗАТЕЛЬНО

Дата начала подписки (в формате ISO 8601) пример ожидаемого формата - 2024-01-01T00:00:00+03:00
valid_tillstr

НЕОБЯЗАТЕЛЬНО

Дата окончания подписки (в формате ISO 8601) пример ожидаемого формата - 2024-01-01T00:00:00+03:00
is_after_suspension
bool

НЕОБЯЗАТЕЛЬНО

Флаг, который сигнализирует выход пользователя из финансовой блокировки (по умолчанию значение False)

Примечание

  • Хотя бы одно из значений параметров (user_id или msisdn) должно присутствовать в запросе.
  • Параметр is_after_suspension может применяться в том случае, если в рамках интеграции, отправка смс сообщений осуществляется со стороны Литрес. При указании в запросе параметра со значением "true" - смс о возобновлении подписки не будет отправлена пользователю.
  • В случае, если не передан valid_till - подписка подключается на установленный срок, согласно ее настройкам на стороне Литрес

Пример запроса

Подключение подписки
curl -X POST \
  https://demo.api.litres.ru/operator-integrations/api/subscription/new \
  -H 'Timestamp: 1718800482' \
  -H 'Content-Type: application/json' \
  -H 'Signature: ea95c487e18e7d5b65852a9c135c8f42b1daed970c5ce2e3015e5c780c443265' \
  -d '{"partner_id":100,
       "msisdn":"79999999999",
       "subscription_id":1,
       "start_time":"2024-06-19T12:00:00+03:00"
      }' \
  -k

Схема ответов

201 Created | Успешное подключение подписки
{
    "status": 201,
    "error": {},
    "payload": {
        "data": {
            "user_id": 10000000,
            "msisdn": null
        }
    }
}
401 - Неверная подпись запроса
{
    "status": 401,
    "error": {
        "type": "InvalidSignature",
        "detail": "Invalid signature value"
    }
}
404 - Указанный subscription_id или user_id не найдены
{
    "status": 404,
    "error": {
        "type": "ResourceNotFound"
    }
}
409 - У указанного user_id уже имеется активная подписка
{
    "status": 409,
    "error": {
        "type": "DuplicateError"
    }
}
422 - Обязательный параметр не передан
{
    "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",
                    "subscription_id"
                ],
                "msg": "Field required",
                "type": "missing"
            }
        ]
    }
}

 

POST /api/subscription/prolong

Пролонгация подписки у пользователя.
Обратите внимание - для успешной пролонгации, у пользователя, на момент отправки запроса на продление, подписка должна быть активна.

ПараметрТипНаличиеОписание

partner_id

int

ОБЯЗАТЕЛЬНО

id партнера

user_id

int

ОБЯЗАТЕЛЬНО*

Id пользователя Литрес
msisdnstr

ОБЯЗАТЕЛЬНО*

Номер телефона пользователя
subscription_id

int

ОБЯЗАТЕЛЬНО

Id подписки
referral_partner_idint

НЕОБЯЗАТЕЛЬНО

Реферальный id партнера
valid_tillstr

НЕОБЯЗАТЕЛЬНО

Дата окончания подписки (в формате ISO 8601)

Примечание

  • Хотя бы одно из значений параметров (user_id или msisdn) должно присутствовать в запросе.
  • Если в запросе не передан valid_till - подписка продляется на установленный срок, от текущей даты окончания 

Пример запроса

Продление (данные вымышленные)
curl -X POST \
  https://demo.api.litres.ru/operator-integrations/api/subscription/prolong \
  -H 'Timestamp: 1718800482' \
  -H 'Content-Type: application/json' \
  -H 'Signature: ebe3e1117088f0ec467b15fc2d0650d681f09fdbfd3b614a4536a3426af6e4d8' \
  -d '{"partner_id":100,
       "msisdn":"79999999999",
       "subscription_id":1
      }' \
  -k

Схема ответов

202 Accepted | Успешное продление подписки
{
    "status": 202,
    "error": {},
    "payload": {
        "data": {
            "user_id": 10000000,
            "msisdn": null
        }
    }
}
401 - Неверная подпись запроса
{
    "status": 401,
    "error": {
        "type": "InvalidSignature",
        "detail": "Invalid signature value"
    }
}
404 - Указанный subscription_id или user_id не найдены или подписка не активна
{
    "status": 404,
    "error": {
        "type": "ResourceNotFound"
    }
}
422 - Обязательный параметр не передан
{
    "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",
                    "subscription_id"
                ],
                "msg": "Field required",
                "type": "missing"
            }
        ]
    }
}

POST /api/subscription/cancel

Отмена (отключение) подписки у пользователя.

ПараметрТипНаличиеОписание
partner_idint

ОБЯЗАТЕЛЬНО

id партнера
user_idint

ОБЯЗАТЕЛЬНО*

Id пользователя Литрес
msisdnstr

ОБЯЗАТЕЛЬНО*

Номер телефона пользователя
subscription_idint

ОБЯЗАТЕЛЬНО

Id подписки
referral_partner_idint

НЕОБЯЗАТЕЛЬНО

Реферальный id партнера
valid_tillstr

НЕОБЯЗАТЕЛЬНО

Дата окончания подписки (в формате ISO 8601)

Примечание

Хотя бы одно из значений параметров (user_id или msisdn) должно передаваться в запросе.

Пример запроса

Отключение подписки
curl -X POST \
  https://demo.api.litres.ru/operator-integrations/api/subscription/cancel \
  -H 'Timestamp: 1718802700' \
  -H 'Content-Type: application/json' \
  -H 'Signature: 8e7c92e08424009361e8e9ee640c44356774f724c5dfc6a624b8be7f30128080' \
  -d '{"partner_id":100,
       "msisdn":"79999999999",
       "subscription_id":1
      }' \
  -k

Схема ответов

202 Accepted | Успешное отключение подписки
{
    "status": 202,
    "error": {},
    "payload": {
        "data": {
            "user_id": 100000000
        }
    }
}
401 - Неверная подпись запроса
{
    "status": 401,
    "error": {
        "type": "InvalidSignature",
        "detail": "Invalid signature value"
    }
}
404 - Указанный subscription_id или user_id не найдены или подписка не активна
{
    "status": 404,
    "error": {
        "type": "ResourceNotFound"
    }
}
422 - Обязательный параметр не передан 
{
    "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",
                    "subscription_id"
                ],
                "msg": "Field required",
                "type": "missing"
            }
        ]
    }
}

GET /api/subscription/user/status

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

ПараметрТипНаличиеОписание
partner_idint

ОБЯЗАТЕЛЬНО

id партнера
user_idint

ОБЯЗАТЕЛЬНО

id пользователя Литрес
subscription_idint

ОБЯЗАТЕЛЬНО

id подписки

Формирование signature

Для данного метода также необходимо указывать хедеры timestamp и signature
Пример шифрования подписи signature:

const dataToHash = `${timestamp}.${partner_id}.${subscription_id}.${user_id}`;

const signature = CryptoJS.HmacSHA256(dataToHash, secretKey).toString();

Пример запроса

Получение статуса по всем подпискам партнера
curl -X GET \
  "https://demo.api.litres.ru/operator-integrations/api/subscription/user/status?partner_id=1&subscription_id=1&user_id=999" \
  -H "Timestamp: 1717405081" \
  -H "Content-Type: application/json" \
  -H "Signature: 9deaf8a421e34ec9fef47ead3477764b0fe3337b7b0962034eb426aa4d6c038e" \
  -k

Схема ответов

Успешное получение статуса подписки
{
    "status": 200,
    "error": {},
    "payload": {
        "data": {
            "user_id": 999,
            "subscription_id": 1,
            "start_time": "2023-10-26T10:29:28",
            "valid_till": "2023-11-25T10:29:28"
        }
    }
}
404 - Указанный user_id не найден
{
    "status": 404,
    "error": {
        "type": "ResourceNotFound"
    }
}
422 - Обязательный параметр не передан
{
    "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": [
                    "query",
                    "user_id"
                ],
                "msg": "Field required",
                "type": "missing"
            }
        ]
    }
}

GET /api/subscription/user/status/all

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

ПараметрТипНаличиеОписание
partner_idint

ОБЯЗАТЕЛЬНО

id партнера
user_idint

ОБЯЗАТЕЛЬНО*

id пользователя Литрес
msisdnint

ОБЯЗАТЕЛЬНО*

номер телефона

Примечание

Хотя бы одно из значений параметров (user_id или msisdn) должно передаваться в запросе.

Если вместо user_id, указывается msisdn - его и следует использовать для шифрования подписи

Формирование signature

Для данного метода также необходимо указывать хедеры timestamp и signature
Пример шифрования подписи signature:

const dataToHash = `${timestamp}.${partner_id}.${user_id}`;

const signature = CryptoJS.HmacSHA256(dataToHash, secretKey).toString();

Пример запроса
curl -X GET \
  "https://demo.api.litres.ru/operator-integrations/api/subscription/user/status/all?partner_id=6&msisdn=79991112232" \
  -H "Timestamp: 1717405081" \
  -H "Content-Type: application/json" \
  -H "Signature: 9deaf8a421e34ec9fef47ead3477764b0fe3337b7b0962034eb426aa4d6c038e" \
  -k
200 - Успешное получение статуса подписки
{
    "status": 200,
    "error": {},
    "payload": {
        "data": [
            {
                "subscription_id": 999,
                "start_time": "2024-01-23T10:23:00",
                "valid_till": "2024-01-25T10:23:00"
            }
        ]
    }
}
200 - Отсутствие активных подписок
{
    "status": 200,
    "error": {},
    "payload": {
        "data": []
    }
}
401 - Неверная подпись запроса
{
    "status": 401,
    "error": {
        "type": "InvalidSignature",
        "detail": "Invalid signature value"
    }
}
404 - Указанный user_id или msisdn не найден
{
    "status": 404,
    "error": {
        "type": "ResourceNotFound"
    }
}

PUT /api/subscription/user/msisdn

Изменение msisdn пользователя


ПараметрТипНаличиеОписание
partner_idint

ОБЯЗАТЕЛЬНО

id партнера
user_idint

ОБЯЗАТЕЛЬНО*

id пользователя Литрес
msisdnstr

ОБЯЗАТЕЛЬНО*

номер телефона
new_msisdnstr

ОБЯЗАТЕЛЬНО

Новый msisdn пользователя


Примечание

1) Хотя бы одно из значений параметров (user_id или msisdn) должно передаваться в запросе.
2) Номер нельзя изменить, если:
 - new_msisdn принадлежит другому аккаунту на стороне Литрес
 - аккаунт не имеет существующей связки с номером телефона
 - у пользователя никогда не было подписки партнера

Формирование signature

Для данного метода также необходимо указывать хедеры timestamp и signature
Пример шифрования подписи signature:

const dataToHash = `${timestamp}.${partner_id}.${user_id OR msisdn}.${new_msisdn}`;

const signature = CryptoJS.HmacSHA256(dataToHash, secretKey).toString();

Пример запроса
curl -X PUT "https://demo.api.litres.ru/operator-integrations/api/subscription/user/msisdn" \
-H "Content-Type: application/json" \
-H "timestamp: 1732201523" \
-H "signature: 8fd090c9a80484e8876abc919916c9de8b8ab5938fe3c25c00242c3cd164d072" \
-d '{
  "partner_id": 100,
  "msisdn": "79990001122", 
  "new_msisdn": "79992221100"
}'
200 - Успешная смена номера
{
    "error": {},
    "payload": {},
    "status": 200
}
404 - Указанный user_id или msisdn не найдены
{
    "status": 404,
    "error": {
        "type": "ResourceNotFound"
    }
}
409 - new_msisdn уже привязан к другому аккаунту
{
    "status": 409,
    "error": {
        "type": "UserNewPhoneAlreadyExistsError"
    }
}
424 -у пользователя не было подписки партнера
{
  "status": 424,
  "error": {
    "type": "UserNotBelongToOperatorError"
  }
}
424 - передан user_id к которому не привязан msisdn 
{
  "status": 424,
  "error": {
    "type": "UserPhoneNotExistsError"
  }
}

DELETE /api/subscription/user/msisdn

Удаление msisdn пользователя

ПараметрТипНаличиеОписание
partner_idint

ОБЯЗАТЕЛЬНО

id партнера
user_idint

ОБЯЗАТЕЛЬНО*

id пользователя Литрес
msisdnstr

ОБЯЗАТЕЛЬНО*

номер телефона

Примечание

0) Номер не следует удалять, если абонент перешел к другому оператору, при этом сохранив номер.
1) Хотя бы одно из значений параметров (user_id или msisdn) должно передаваться в запросе.
2) Номер нельзя удалить, если:
 - у пользователя никогда не было подписки партнера
 - у пользователя есть купленные книги на аккаунте

Формирование signature

Для данного метода также необходимо указывать хедеры timestamp и signature
Пример шифрования подписи signature:

const dataToHash = `${timestamp}.${partner_id}.${user_id OR msisdn}`;

const signature = CryptoJS.HmacSHA256(dataToHash, secretKey).toString();

Пример запроса
curl -X DELETE "https://demo.api.litres.ru/operator-integrations/api/subscription/user/msisdn?partner_id=100&msisdn=79990001122" \
-H "timestamp: 1732203932" \
-H "signature: 62ca19a07f88c40cb147367ac5a264ed6052913d6bdf66d8f9d5abaa9f1ef7ff" \
-k
200 - Успешное удаление номера
{
    "status": 200,
    "error": {},
    "payload": {}
}
404 - Номер не найден в базе данных
{
    "status": 404,
    "error": {
        "type": "ResourceNotFound"
    }
}
409 - На аккаунте пользователя есть покупки
{
  "status": 409,
  "error": {
    "type": "CanNotDeleteActiveUserPhoneError"
  }
}
424 - передан user_id к которому не привязан номер телефона
{
  "status": 424,
  "error": {
    "type": "UserPhoneNotExistsError"
  }
}
424 - у пользователя никогда не было подписки оператора
{
  "status": 424,
  "error": {
    "type": "UserNotBelongToOperatorError"
  }
}

POST /api/subscription/user/msisdn

Авторегистрация пользователя, получение user_id по msisdn

ПараметрТипНаличиеОписание

partner_id

int

ОБЯЗАТЕЛЬНО

id партнера
msisdnint

ОБЯЗАТЕЛЬНО

Номер телефона пользователя. Только цифры, без доп. символов, например 79998887766
is_pass_pushedstr

НЕОБЯЗАТЕЛЬНО

True - СМС с авторизационными данными новому пользователю отправляет Литрес, False - в ответе на запрос партнер получает пароль нового пользователя. Если msisdn пользователя уже зарегистрирован в Литрес - СМС не отправляем, пароль в ответе не возвращается, возвращается user_id


Формирование signature

Для данного метода также необходимо указывать хедеры timestamp и signature
Пример шифрования подписи signature:

const dataToHash = `${timestamp}.${partner_id}.${msisdn}`;

const signature = CryptoJS.HmacSHA256(dataToHash, secretKey).toString();

Пример запроса
curl --location 'https://api.litres.ru/operator-integrations/api/subscription/user/msisdn' \
--header 'timestamp: {{timestamp}}' \
--header 'signature: {{signature}}' \
--header 'Content-Type: application/json' \
--data '{
  "partner_id": 100,
  "msisdn": "79999999999", 
  "is_pass_pushed": "true"
}'
201 - Успешная регистрация нового пользователя ("is_pass_pushed":"false")
{
    "status": 201,
    "error": {},
    "payload": {
        "data": {
            "user_id": 1000000000,
            "user_password": "d9elftya"
        }
    }
}


200 - Получение user_id по msisdn существующего пользователя ("is_pass_pushed":"false")
{
    "status": 200,
    "error": {},
    "payload": {
        "data": {
            "user_id": 1000000000,
            "user_password": null
        }
    }
}
201 - Успешная регистрация нового пользователя ("is_pass_pushed":"true")
{
    "status": 201,
    "error": {},
    "payload": {
        "data": {
            "user_id": 1000000000,
            "user_password": null
        }
    }
}
200 - Получение user_id по msisdn существующего пользователя ("is_pass_pushed":"true")
{
    "status": 200,
    "error": {},
    "payload": {
        "data": {
            "user_id": 1000000000,
            "user_password": null
        }
    }
}

Swagger

openapi.json

Attachments:

openapi.json (application/octet-stream)