Версия документа | 1.3 |
|---|---|
| Дата последнего обновления | 2025-11-05 |
2025-10-22 - Добавлена информация о ручке для получения дерева жанров
2025-10-29 - В метаданные добавлены элементы - tags, filegroups
2025-11-05 - Добавлена ручка для получения данных по списку книг GET /api/partner/catalog/list
Аннотация
Данное api позволяет получить каталог электронных книг и аудиокниг, в формате jsonl. Этот документ описывает исключительно техническую сторону взаимодействия между Литрес и партнерами. Юридические, организационные и договорные вопросы решаются отдельно.
URL для запросов - https://api.litres.ru/integrations
1) Получение каталога и обновлений
Заголовки запросов
Timestamp - Unix-таймстемп запроса в UTC
Signature - HMAC(SHA-256 хэш от строки см. ниже, Секретный ключ партнера)*
Signature для POST/GET запросов
|
* – время действия подписи 5 мин
Эндпоинты
POST /api/partner/catalog/new
Запрос для формирования файла с каталогом/обновлениями
- Партнер выполняет HTTP запрос в эндпоинт /partner/catalog/new
- Партнер получает ID будущего каталога:
- Если для партнера уже есть каталог, который находится в процессе генерации, то партнер получит ID каталога из кэша
- Если для партнера нет каталога, который находится в процессе генерации, то запускается задача на генерацию каталога
- Каждый запрос партнера, после которого запускается генерация файла с каталогом/обновлениями расходует суточный лимит запросов
- Суточный лимит сбрасывается через 24 часа после первого запроса, для конкретного партнера
- В сутки конкретному партнеру доступно 10 генераций каталога/обновлений
- Остаток лимита не уменьшается, если партнер делает запросы во время активной генерации каталога.
Тело запроса
| Поле | Тип | Наличие | Значение по умолчанию | Описание |
|---|---|---|---|---|
partner_id | INT | ОБЯЗАТЕЛЬНО | ОТСУТСТВУЕТ | ID партнера, используемое для шифрования подписи |
last_updated_at | STR | НЕОБЯЗАТЕЛЬНО | 2000-01-01T00:00:00 | Книги с последним обновлением позже этой даты попадут в файл с каталогом. Не передавайте этот параметр, чтобы получить весь имеющийся каталог на данный момент. Передаваемое значение всегда должно быть в прошлом. |
is_compressed | BOOL | НЕОБЯЗАТЕЛЬНО | TRUE | Флаг наличия компрессии у каталога по алгоритму GZip |
has_annotation | BOOL | НЕОБЯЗАТЕЛЬНО | TRUE | Флаг наличия текста аннотаций у артов в каталоге. Запрос каталога без аннотаций может заметно уменьшить размер конечного файла. |
Успешное тело ответа
| Поле | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
| catalog_id | STR | Отсутствует | ID генерируемого каталога UUID4 |
Схема ответов
POST /api/partner/catalog/new
Server response:
201
Content-Type: application/json
{
"status": 201,
"error": {},
"payload": {
"data": {
"catalog_id": "f7f8d52c-c0ae-482c-a481-a093e498c403"
}
}
}
Server response:
401
Content-Type: application/json
{
"error": {
"type": "MissingSignature"
},
"status": 401
}
Server response:
401
Content-Type: application/json
{
"error": {
"type": "InvalidSignature"
},
"status": 401
}
Server response:
429
Content-Type: application/json
{
"error": {
"type": "TooManyRequests"
},
"status": 429
}
GET /api/partner/catalog/status
Получение статуса готовности каталога для партнера
Лимит запросов отсутствует
Параметры запроса
| Поле | Тип | Наличие | Значение по умолчанию | Описание |
|---|---|---|---|---|
partner_id | INT | ОБЯЗАТЕЛЬНО | ОТСУТСТВУЕТ | ID партнера (значение используемое для шифрования подписи) |
| STR | ОБЯЗАТЕЛЬНО | ОТСУТСТВУЕТ | ID каталога партнера UUID4 |
Успешное тело ответа
| Поле | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
| STR | Отсутствует | Статус каталога ENUM:
|
| STR / NULL | NULL | Прямая ссылка для загрузки каталога. Файл каталога доступен для загрузки 7 дней, с момента получения статуса success |
Схема ответов
GET /api/partner/catalog/status?partner_id=25&catalog_id=f7f8d52c-c0ae-482c-a481-a093e498c403
Server response:
200
Content-Type: application/json
{
"status": 200,
"error": {},
"payload": {
"data": {
"status": "success",
"download_url": "https://partnerscatalogs.litres.ru/partners-catalogs/catalogs/f7/f8/f7f8d52c-c0ae-482c-a481-a093e498c403.jsonl.gz"
}
}
Server response:
404
Content-Type: application/json
{
"error": {
"type": "ResourceNotFoundByID"
},
"status": 404
}
Server response:
401
Content-Type: application/json
{
"error": {
"type": "MissingSignature"
},
"status": 401
}
Server response:
401
Content-Type: application/json
{
"error": {
"type": "InvalidSignature"
},
"status": 401
}
GET /api/partner/catalog/list
Синхронный запрос на генерацию каталога по ID или UUID книг, которые доступны для партнера. Если книги никогда не было в каталоге партнера, то данных по ней не будет в теле ответа.
Параметры запроса
partner_id | INT | ОБЯЗАТЕЛЬНО | ОТСУТСТВУЕТ | ID партнера (значение используемое в подписе) |
ids | ARRAY[INT] | НЕОБЯЗАТЕЛЬНО* | ОТСУТСТВУЕТ | Массив ID книг через запятую. Максимальное количество 10шт. |
uuids | ARRAY[UUID] | НЕОБЯЗАТЕЛЬНО* | ОТСУТСТВУЕТ | Массив UUID книг через запятую. Максимальное количество 10шт. |
* – Если переданы оба параметра ids и uuids, то параметр uuids игнорируется. Хотя бы 1 из параметров ids или uuids обязан присутствовать в запросе
Успешное тело ответа
См. Формат каталога → Описание метаданных
Лимит запросов
Лимит запросов отсутствует.
Схема ответов
GET /api/partner/catalog/list?partner_id=16&ids=120421
Server response:
200
Content-Type: application/json
{
"status": 200,
"error": {},
"payload": {
"data": [
{
"id": 120421,
"uuid": "65830123-26b8-4b07-8098-c18229e5026e",
"title": "Психология искусства",
"subtitle": null,
"type": 0,
"min_age": 12,
"html_annotation": "<p>Книга выдающегося советского ученого Л. С. Выготского «Психология искусства» вышла первым изданием в 1965 г., вторым – в 1968 г. и завоевала всеобщее признание. В ней автор резюмирует свои работы 1915–1922 годов и вместе с тем готовит те новые психологические идеи, которые составили главный вклад Выготского в науку. «Психология искусства» является одной из фундаментальных работ, характеризующих развитие советской теории и искусства.</p>\n<p>Книга рассчитана на специалистов – эстетиков, психологов, искусствоведов, а также на широкий круг читателей.</p>\n",
"language_code": "ru",
"source_language_code": "",
"released_at": "2008-01-23T23:31:26",
"year_written_at": "1922",
"date_written_at": "1922-01-01",
"yearly_rating": 2.39445,
"merged_from": null,
"price": {
"value": "99.90",
"currency": "RUB"
},
"file_groups": [
{
"id": 0,
"group_name": "Текстовые файлы",
"files": [
{
"id": 105707968,
"size": 1468096,
"type": "fb2.zip",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 1375205,
"type": "txt",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 534328,
"type": "txt.zip",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 1486103,
"type": "rtf.zip",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 2731491,
"type": "a4.pdf",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 3376034,
"type": "a6.pdf",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 2247795,
"type": "mobi.prc",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 2467699,
"type": "epub",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 1586979,
"type": "ios.epub",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
},
{
"id": 105707968,
"size": 1468316,
"type": "fb3",
"images_count": 2,
"seconds_count": 0,
"symbols_count": 1177832
}
]
}
],
"persons": [
{
"id": 30932777,
"first_name": "Лев",
"last_name": "Выготский",
"full_name": "Лев Семенович Выготский",
"role": 0,
"url": "/author/lev-vygotskiy-30932777/"
}
],
"genres": [
{
"id": 5251,
"title": "классики психологии",
"bisac_code": "PSY000000"
},
{
"id": 5249,
"title": "общая психология",
"bisac_code": "PSY000000"
}
],
"tags": [
"психология творчества"
],
"series": [],
"copyrights": [
{
"id": null,
"title": "Public Domain"
}
],
"relations": [
{
"id": 177314,
"type": 8
},
{
"id": 24079950,
"type": 8
},
{
"id": 68959578,
"type": 8
},
{
"id": 70543858,
"type": 8
},
{
"id": 71697985,
"type": 8
}
],
"livelib_data": {
"rated_avg": 4.0715,
"readers_count": 287,
"widget_url": "https://u.livelib.ru/book/433747/ratingbutton2015.png",
"widget_url_signed": "https://u.livelib.ru/book/433747/ratingbuttonwhite.png",
"rated_1_count": 4,
"rated_2_count": 5,
"rated_3_count": 30,
"rated_4_count": 98,
"rated_5_count": 80
},
"status": 1,
"is_available": true,
"cover_url": "/pub/c/cover/120421.jpg",
"isbn": "978-5-457-01582-1",
"updated_at": "2020-12-10T16:37:02",
"available_at": "2012-07-10T20:12:09"
}
]
}
}
Формат каталога
Содержание каталога находится в формате JSONL. Каждая новая строка – валидный JSON. Читать каталог можно построчно. Весь каталог не является валидным JSON-ом (это не объект JSON, а набор объектов JSON). Строка каталога – JSON словарь, содержащий метаданные книги.
TTL каталога
Время, в течение которого каталог доступен для загрузки, составляет 7 дней. Через 7 дней после генерации, каталог будет невозможно загрузить.
Описание метаданных
Поле | Тип | Значение по умолчанию | Описание | ||
|---|---|---|---|---|---|
id | INT | ОТСУТСТВУЕТ | Числовое ID книги | ||
uuid | STR | ОТСУТСТВУЕТ | ID арта в формате UUID4 | ||
title | STR | ОТСУТСТВУЕТ | Название книги | ||
subtitle | STR | NULL |
| Подзаголовок книги | ||
html_annotation | STR | NULL |
| Аннотация книги в формате HTML | ||
language_code | STR | NULL |
| Код языка книги в ISO 639-1 | ||
source_language_code | STR | NULL |
| Код оригинального языка книги (если у книги есть перевод на другой язык) в ISO 639-1 | ||
is_available | BOOL | ОТСУТСТВУЕТ | Главный флаг доступности книги для партнера. Если флаг имеет значение FALSE – книгу надо немедленно снять с продажи | ||
status | ENUM[INT] | ОТСУТСТВУЕТ | Внутренний статус книги в Литрес. Значения статусов:
| ||
yearly_rating | FLOAT | ОТСУТСТВУЕТ | Годовой рейтинг книги по 10-ти бальной шкале | ||
cover_url | STR | ОТСУТСТВУЕТ | Относительный URL на файл обложки книги | ||
available_at | DATETIME | NULL |
| Дата когда книга поступит в продажу (ISO 8601) | ||
released_at | DATETIME | NULL |
| Главная дата обновления файла книги. Последняя дата технического релиза книги в Литрес (ISO 8601). Это означает, что файл с контентом книги обновился в эту дату. | ||
min_age | INT | ОТСУТСТВУЕТ | Минимальный допустимый возраст читателя | ||
type | ENUM[INT] | ОТСУТСТВУЕТ | Тип книги:
| ||
isbn | STR | NULL |
| ISBN-13 или ISBN-10 книги | ||
year_written_at | STR | NULL |
| Год написания книги. Может быть несколько годов перечисленных через знаки:
| ||
date_written_at | DATE | NULL |
| Дата написания книги YYYY-MM-DD | ||
updated_at | DATETIME | ОТСУТСТВУЕТ | Главная дата обновления метаданных книги. Дата обновления книги (ISO 8601) | ||
merged_from | INT | NULL |
| Если книга сменила свой ID, то здесь будет указан ее старый ID | ||
file_groups | ARRAY[DICT] |
| Группа файлов книги | ||
| INT | ОТСУТСТВУЕТ | Номер группы | ||
| STR | NULL |
| Название группы | ||
| files[...] | ARRAY[DICT] |
| Список файлов книги группы | ||
id | INT | ОТСУТСТВУЕТ | ID файла книги | ||
size | INT | ОТСУТСТВУЕТ | Размер файла книги в байтах | ||
type | STR | ОТСУТСТВУЕТ | MIME формат книги | ||
symbols_count | INT | 0 | Количество символов в книги | ||
seconds_count | INT | 0 | Количество секунд в аудио книге | ||
images_count | INT | 1 | Количество иллюстраций в книге с учетом обложки | ||
persons[...] | ARRAY[DICT] | [] | Связанные персоны с книгой (автор, иллюстратор, чтец, и т.д.) | ||
id | INT | ОТСУТСТВУЕТ | ID персоны | ||
url | STR |
| Относительный URL на персону в Литрес | ||
first_name | STR | NULL |
| Имя | ||
last_name | STR | NULL |
| Фамилия | ||
full_name | STR | NULL |
| Фамилия Имя Отчество | ||
role | ENUM[INT] | ОТСУТСТВУЕТ | Роль персоны для книги. Возможные значения: 0 - Автор текста 1 - Переводчик 2 - Агент 3 - Художник 4 - Составитель 5 - Пересказчик 6 - Чтец 7 - Исполнитель 8 - Производитель 9 - Редактор 10 - Актер 11 - Режиссер 15 - Продюсер 19 - Композитор 23 - Звукорежиссер 26 - Издатель 27 - Сценарист 28 - Владелец прав 29 - Верстальщик 30 - Адаптация 31 - Диалоги 32 - Концепция 33 - Отзыв 34 - Предисловие 35 - Послесловие 36 - Аккомпаниаторы 37 - Цитаты 38 - Аннотация 39 - Связывается с 40 - Комментатор 41 - Консультант 42 - Корректор 43 - Научный советник 44 - Вероятный автор 45 - Дизайнер 46 - Получатель писем 47 - Спонсор 48 - Фотограф 49 - Прочее 50 - Не определено 51 - Главный редактор 52 - Член редколлегии 53 - Ответственный редактор 54 - Соавтор 55 - Иллюстратор 56 - Дизайнер обложки 57 - Лектор 58 - Литературная обработка 59 - Комментарии 60 - Примечания 61 - Подготовка текста | ||
genres[...] | ARRAY[DICT] | [] | Жанры книги | ||
id | INT | ОТСУТСТВУЕТ | ID жанра книги | ||
title | STR | ОТСУТСТВУЕТ | Название жанра | ||
bisac_code | STR | NULL |
| Код жанра в международной системе BISAC | ||
tags[...] | ARRAY[DICT] | [] | Теги для книги | ||
id | INT | ОТСУТСТВУЕТ | ID тега книги | ||
title | STR | ОТСУТСТВУЕТ | Название тега | ||
series[...] | ARRAY[DICT] | [] | Серии книги | ||
id | INT | ОТСУТСТВУЕТ | ID серии книги | ||
title | STR | ОТСУТСТВУЕТ | Название серии книги | ||
number | INT | NULL |
| Порядковый номер книги в серии | ||
| price[...] | DICT | NULL | Цена книги | ||
value | FLOAT | ОТСУТСТВУЕТ | Значение цены книги в Литрес | ||
currency | STR | RUB | Валюта книги, всегда в рублях | ||
copyrights[...] | ARRAY[DICT] | [] | Список правообладателей книги | ||
id | INT | NULL |
| ID правообладателя | ||
title | STR | ОТСУТСТВУЕТ | Название правообладателя | ||
relations[...] | ARRAY[DICT] |
| Связи с другими книгами | ||
id | INT | ОТСУТСТВУЕТ | ID связанной книги | ||
type | ENUM[INT] | ОТСУТСТВУЕТ | Тип связи со связанной книгой. Возможные значения: 1 - Предыдущий выпуск 2 - Следующий выпуск 3 - Перевод с 4 - Перевод 5 - Сборник 6 - Часть 7 - Переиздание 8 - Другой носитель 9 - См. также 10 - Продолжение 11 - Предыстория 12 - Аксесcуар 13 - Подходит к 14 - Другой цвет 15 - Другой перевод 16 - Другой перевод на другом носителе 17 - Сборник (другой перевод) 18 - Часть (другой перевод) 19 - Пересекается с 20 - Приложение 21 - Эта книга - приложение к 22 - Перевод на другой язык 23 - Сборник (другой носитель) 24 - Часть (другой носитель) 25 - Аналог на другом носителе 26 - Авторечь 27 - В кратком изложении 28 - Полная книга 29 - Авторечь платная 255 - Связь удалена редактором | ||
livelib_data[...] | DICT | NULL | Данные для сервиса LiveLib | ||
rated_avg | FLOAT | ОТСУТСТВУЕТ | Рейтин книги на LiveLib | ||
readers_count | INT | ОТСУТСТВУЕТ | Кол-во читавших книгу на LiveLib | ||
widget_url | STR | NULL |
| Ссылка на видже книги на LiveLib | ||
widget_url_signed | STR | NULL |
| Ссылка на виджет книги с подписью LiveLib | ||
rated_1_count | INT | ОТСУТСТВУЕТ | Кол-во поставивших оценку "1" для книги на LiveLib | ||
rated_2_count | INT | ОТСУТСТВУЕТ | Кол-во поставивших оценку "2" для книги на LiveLib | ||
rated_3_count | INT | ОТСУТСТВУЕТ | Кол-во поставивших оценку "3" для книги на LiveLib | ||
rated_4_count | INT | ОТСУТСТВУЕТ | Кол-во поставивших оценку "4" для книги на LiveLib | ||
rated_5_count | INT | ОТСУТСТВУЕТ | Кол-во поставивших оценку "5" для книги на LiveLib | ||
2) Дерево жанров Литрес
Авторизация запросов
Авторизация не требуется.
URL для запросов
GET api.litres.ru/foundation/api/genres
Получения всех существующих деревьев жанров в Литрес. Выводятся без пагинации.
Заголовки запроса
| Имя заголовка | Тип | Наличие | Значение по умолчанию | Описание |
|---|---|---|---|---|
Client-Host | STR | NULL | НЕОБЯЗАТЕЛЬНО | ОТСУТСТВУЕТ | При указании в ответе будут только жанры актуальные для каталога партнера. |
| UI-Language-Code | STR | НЕОБЯЗАТЕЛЬНО | ru | В каком языке нужно выдавать наименования жанров |
Параметры запроса
| Поле | Тип | Наличие | Значение по умолчанию | Описание |
|---|---|---|---|---|
art_group | INT | НЕОБЯЗАТЕЛЬНО | 0 | Группы книг, для которых доступно формирование дерева жанров.
|
only_root | BOOL | НЕОБЯЗАТЕЛЬНО |
| Флаг вывода только корневых жанров |
subgenre_depth | INT | NULL | НЕОБЯЗАТЕЛЬНО |
| Максимальная глубина дерева жанров. Если параметр не передан, то отдаются все уровни. Значение параметра должно быть больше 1 и меньше 5. 1 означает получить корневые жанры и 1 уровень дочерних жанров. При значении 5 дерево жанров может иметь глубину поджанров вплоть до 5 штук. |
api_version | INT | НЕОБЯЗАТЕЛЬНО |
|
|
Кэширование запросов
Запросы кэшируются на 1 час
Успешное тело ответа
| Поле | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
| INT | ОТСУТСТВУЕТ | Числовое ID жанра в Литрес |
| UUID4 | ОТСУТСТВУЕТ | UUID жанра в Литрес |
| STR | ОТСУТСТВУЕТ | Имя жанра |
| BOOL | ОТСУТСТВУЕТ | Флаг обозначающий, является ли жанр корнем дерева жанров |
| STR | NULL | NULL | URL на страницу жанра в Литрес |
| INT | 0 | Кол-во книг с таким жанром в Литрес |
| STR | NULL | NULL | URL на обложку жанра |
| STR | NULL | NULL | URL на логотип жанра |
| STR | NULL | NULL | Мненмонический токен жанра |
| ARRAY[DICT] | [] | Массив со словарями, которые содержат все поля описанные выше. Если данное поле это не пустой массив, то жанр является контейенером и содержит дочернии жанры. Дочернии жанры тоже могут быть контейнерами (ветвями дерева) |
Схема ответов
GET /api/genres
Server response:
200
Content-Type: application/json
{
"status": 200,
"payload": {
"data": [
{
"id": 201583,
"uuid": "8974ae57-db67-11e7-8020-0cc47a545a1e",
"name": "легкое чтение",
"is_root": true,
"url": "/genre/legkoe-chtenie-201583/",
"arts_count": 462775,
"cover_url": "/pub/c/cover/66732098.jpg",
"subgenres": [
{
"id": 5022,
"uuid": "ed1606a8-f034-11e5-a511-0cc47a5454c6",
"name": "детективы",
"is_root": false,
"url": "/genre/knigi-detektivy-5022/",
"arts_count": 83206,
"cover_url": "/pub/c/cover/66978088.jpg",
"subgenres": [
{
"id": 5219,
"uuid": "ed1744cd-f034-11e5-a511-0cc47a5454c6",
"name": "зарубежные детективы",
"is_root": false,
"url": "/genre/zarubezhnye-5219/",
"arts_count": 23504,
"cover_url": "/pub/c/cover/63429581.jpg",
"subgenres": [],
"logo_url": null,
"token": "knigi_detektivy_zarubezhnye"
},
{
"id": 5265,
"uuid": "ed1779bb-f034-11e5-a511-0cc47a5454c6",
"name": "крутой детектив",
"is_root": false,
"url": "/genre/krutoy-detektiv-5265/",
"arts_count": 2877,
"cover_url": "/pub/c/cover/65843121.jpg",
"subgenres": [],
"logo_url": null,
"token": "knigi_detektivy_hard"
}
],
"logo_url": "/pub/genres/logos/detective/detective.png",
"token": "knigi_detektivy"
}
],
"logo_url": null,
"token": null
}
]
}
}
Тестовые доступы:
partner_id = 16
secret_key (секретный ключ партнера) = 93w4jfhs8imksGo-oa3s85d6Akmkkbnsi9