Public : API Литрес для интеграции партнеров

Версия документа

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 запросов

{timestamp}.{partner_id}

* – время действия подписи 5 мин

Эндпоинты

POST /api/partner/catalog/new

Запрос для формирования файла с каталогом/обновлениями

  1. Партнер выполняет HTTP запрос в эндпоинт /partner/catalog/new
  2. Партнер получает ID будущего каталога:
    1. Если для партнера уже есть каталог, который находится в процессе генерации, то партнер получит ID каталога из кэша
    2. Если для партнера нет каталога, который находится в процессе генерации, то запускается задача на генерацию каталога
  3. Каждый запрос партнера, после которого запускается генерация файла с каталогом/обновлениями расходует суточный лимит запросов
    1. Суточный лимит сбрасывается через 24 часа после первого запроса, для конкретного партнера
    2. В сутки конкретному партнеру доступно 10 генераций каталога/обновлений
    3. Остаток лимита не уменьшается, если партнер делает запросы во время активной генерации каталога.

Тело запроса

ПолеТипНаличиеЗначение по умолчаниюОписание
partner_idINT

ОБЯЗАТЕЛЬНО

ОТСУТСТВУЕТ

ID партнера, используемое для шифрования подписи
last_updated_atSTR

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

2000-01-01T00:00:00Книги с последним обновлением позже этой даты попадут в файл с каталогом. Не передавайте этот параметр, чтобы получить весь имеющийся каталог на данный момент. Передаваемое значение всегда должно быть в прошлом.
is_compressedBOOL

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

TRUEФлаг наличия компрессии у каталога по алгоритму GZip
has_annotationBOOL

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

TRUEФлаг наличия текста аннотаций у артов в каталоге. Запрос каталога без аннотаций может заметно уменьшить размер конечного файла.

Успешное тело ответа

ПолеТипЗначение по умолчаниюОписание
catalog_idSTRОтсутствует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 партнера (значение используемое для шифрования подписи)
catalog_id
STR

ОБЯЗАТЕЛЬНО

ОТСУТСТВУЕТ

ID каталога партнера UUID4

Успешное тело ответа

ПолеТипЗначение по умолчаниюОписание
status
STRОтсутствует

Статус каталога ENUM:

  • created – таска на генерацию каталога создана и ожидает выполнения


  • in_progress – генерация каталога в процессе, ждите


  • failed – генерация каталога окончена не успешно


  • success – генерация каталога окончена успешно

download_url
STR / NULLNULLПрямая ссылка для загрузки каталога. Файл каталога доступен для загрузки 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 дней после генерации, каталог будет невозможно загрузить.

Описание метаданных

Поле



Тип

Значение по умолчанию

Описание
idINT 

ОТСУТСТВУЕТ

Числовое ID книги
uuid STR

ОТСУТСТВУЕТ

ID арта в формате UUID4
title STR

ОТСУТСТВУЕТ

Название книги
subtitle STR | NULL 

NULL 

Подзаголовок книги
html_annotation STR | NULL

NULL 

Аннотация книги в формате HTML
language_code STR | NULL 

NULL 

Код языка книги в ISO 639-1
source_language_code STR | NULL 

NULL 

Код оригинального языка книги (если у книги есть перевод на другой язык) в ISO 639-1
is_available BOOL 

ОТСУТСТВУЕТ

Главный флаг доступности книги для партнера. Если флаг имеет значение FALSE – книгу надо немедленно снять с продажи

status ENUM[INT] 

ОТСУТСТВУЕТ

Внутренний статус книги в Литрес. Значения статусов:

  • -1, 0 – книга не доступна к продаже
  • 1 – книга доступна к продаже
  • 2 – книга скоро поступит в продажу, дата поступления неизвестна
  • 6 – книга скоро поступит в продажу, дата поступления известна
yearly_rating FLOAT 

ОТСУТСТВУЕТ

Годовой рейтинг книги по 10-ти бальной шкале

cover_url STR 

ОТСУТСТВУЕТ

Относительный URL на файл обложки книги
available_at DATETIME | NULL 

NULL 

Дата когда книга поступит в продажу (ISO 8601)
released_at DATETIME | NULL

NULL 

Главная дата обновления файла книги. Последняя дата технического релиза книги в Литрес (ISO 8601). Это означает, что файл с контентом книги обновился в эту дату.

min_age INT 

ОТСУТСТВУЕТ

Минимальный допустимый возраст читателя
type ENUM[INT] 

ОТСУТСТВУЕТ

Тип книги:

  • 0 – электронная текстовая книга
  • 1 – электронная аудио книга
  • 4 – PDF книга
  • 24 – EPUB книга
  • 22,23 – подкасты
  • 25,26 – вебтуны
isbn STR | NULL 

NULL 

ISBN-13 или ISBN-10 книги

year_written_at STR | NULL 

NULL 

Год написания книги. Может быть несколько годов перечисленных через знаки:

  • "," (запятая)
  • "-" (минус)
date_written_at DATE | NULL 

NULL 

Дата написания книги YYYY-MM-DD

updated_at DATETIME 

ОТСУТСТВУЕТ

Главная дата обновления метаданных книги. Дата обновления книги (ISO 8601)

merged_from INT | NULL 

NULL 

Если книга сменила свой ID, то здесь будет указан ее старый ID

file_groups

ARRAY[DICT] 

[] 

Группа файлов книги

id

 
INT

ОТСУТСТВУЕТ

Номер группы


group_name
STR | NULL

NULL 

Название группы


files[...]ARRAY[DICT] 

[] 

Список файлов книги группы


id INT 

ОТСУТСТВУЕТ

ID файла книги



size INT 

ОТСУТСТВУЕТ

Размер файла книги в байтах



typeSTR

ОТСУТСТВУЕТ

MIME формат книги



symbols_countINT 

0

Количество символов в книги



seconds_countINT 

0

Количество секунд в аудио книге


images_countINT 

1

Количество иллюстраций в книге с учетом обложки
persons[...] ARRAY[DICT] []Связанные персоны с книгой (автор, иллюстратор, чтец, и т.д.)

id INT 

ОТСУТСТВУЕТ

ID персоны

url STR

"" 

Относительный URL на персону в Литрес


first_name STR | NULL 

NULL 

Имя

last_name STR | NULL 

NULL 

Фамилия

full_name STR | NULL 

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 

NULL 

Код жанра в международной системе BISAC

tags[...] ARRAY[DICT] []Теги для книги

id INT 

ОТСУТСТВУЕТ

ID тега книги

title STR 

ОТСУТСТВУЕТ

Название тега

series[...] ARRAY[DICT] [] Серии книги

id INT 

ОТСУТСТВУЕТ

ID серии книги

title STR 

ОТСУТСТВУЕТ

Название серии книги


number INT | NULL 

NULL 

Порядковый номер книги в серии

price[...]DICTNULL Цена книги

value FLOAT 

ОТСУТСТВУЕТ

Значение цены книги в Литрес

currency STR RUBВалюта книги, всегда в рублях
copyrights[...] ARRAY[DICT] [] Список правообладателей книги

idINT | NULL 

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 

NULL 

Ссылка на видже книги на LiveLib

widget_url_signed STR | NULL 

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-CodeSTR 

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

ru В каком языке нужно выдавать наименования жанров

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

ПолеТип

Наличие

Значение по умолчанию

Описание

art_group INT 

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

0 

Группы книг, для которых доступно формирование дерева жанров.
Выводится кол-во книг соотв. типа в каждом жанре

  • 0 – все книги
  • 1 – текстовые
  • 2 – аудио
only_root BOOL 

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

FALSE 

Флаг вывода только корневых жанров

subgenre_depth INT | NULL 

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

NULL 

Максимальная глубина дерева жанров. Если параметр не передан, то отдаются все уровни. Значение параметра должно быть больше 1 и меньше 5. 1 означает получить корневые жанры и 1 уровень дочерних жанров. При значении 5 дерево жанров может иметь глубину поджанров вплоть до 5 штук.

api_version
INT 

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

1 

  • 1 – без учета вебтунов
  • 2 – с учетом вебтунов

Кэширование запросов

Запросы кэшируются на 1 час

Успешное тело ответа

ПолеТипЗначение по умолчаниюОписание

id 

INT 

ОТСУТСТВУЕТ

Числовое ID жанра в Литрес

uuid 

UUID4 

ОТСУТСТВУЕТ

UUID жанра в Литрес

name 

STR 

ОТСУТСТВУЕТ

Имя жанра

is_root 

BOOL 

ОТСУТСТВУЕТ

Флаг обозначающий, является ли жанр корнем дерева жанров

url 

STR | NULL NULL URL на страницу жанра в Литрес

arts_count 

INT 0 Кол-во книг с таким жанром в Литрес

cover_url 

STR | NULL NULL URL на обложку жанра

logo_url 

STR | NULL NULL URL на логотип жанра

token 

STR | NULL NULL Мненмонический токен жанра

subgenres 

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