Партнерам : Интерфейс работы сервисов электронного самиздата с магазином ЛитРес (API для «самиздателей»)

Created by Кристина Курашова, last modified on Aug 01, 2018


Версия документа1.39
Дата последнего обновления03 июля 2022 г.
Адрес постоянного размещенияhttps://docs.litres.ru/x/joh8

1 Аннотация

Компания ЛитРес разработала API для издательств и сервисов электронного самиздата, который позволяет автоматизировать процесс размещения электронных книг в каталоге ЛитРес для последующей продажи или бесплатного распространения.
О возможных вариантах сотрудничества вы можете узнать у менеджеров ЛитРес (http://www.litres.ru/o-kompanii/contactnaya-informaciya/).

2 Возможности API

  1. Загрузка и предварительное размещение в каталоге ЛитРес электронных книг в форматах FB2/FB3, а также PDF и аудио книг.
  2. Редактирование информации, связанной с загруженными книгами (авторы, серии, жанры, ключевые слова, аннотации, обложки, цены и пр.).
  3. Подача запросов на размещение загруженных материалов в общедоступном каталоге ЛитРес для продажи или бесплатного распространения.
  4. Просмотр статистики по продажам и онлайн-чтению.

3 Последовательность размещения книг в продажу

Пунктирной рамкой выделены не обязательные этапы. Стрелками обозначены основные данные, которые используются при формировании запросов на последующих этапах. Выноски справа обозначают названия запросов к API.

4 Общая информация по работе API

  1. После заключения договора с ЛитРес партнер (издательство или сервис электронного самиздата) получает индивидуальные ключи, которые будут использоваться при формировании запросов к API:
    • partner – идентификатор партнера. Например: «51221432»;
    • secret_key – секретный ключ партнера. Например: «password»;
    • owner – один или несколько идентификаторов правообладателей партнера, определяющих набор ресурсов (сайтов, мобильных приложений и пр.), на которых будут размещаться книги. Например: «9351135».
  2. Работа с API сервера ЛитРес для любой программы-клиента строится по схеме запрос-ответ: клиент формирует и передает запрос, а сервер в ответ возвращает XML-документ с ответом.
  3. Все запросы к серверам ЛитРес осуществляются только по протоколу HTTPS.
  4. Во всех запросах к серверам ЛитРес (если не указано обратное) передаются параметры partner и sha:
    • partner – идентификатор партнера;

    • sha – хеш SHA-256, формируемый индивидуально для каждого из запросов и рассчитываемый как

      $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

      где:

      • $timestamp – московское время в формате «2014-11-07T16:21:02+03:00». Каждое значение timestamp можно использовать только один раз, причем оно не может отличаться от серверного (московского) времени более чем на 300 секунд в обе стороны;, где:
      • $secret_key – секретный ключ партнера;
      • $partner – идентификатор партнера.

    Далее в документации все обязательные параметры отмечены красной звездочкой (*).

  5. Все текстовые данные передаются и обрабатываются в кодировке UTF-8.

  6. Все ответы сервера передаются в виде XML, который всегда имеет кодировку UTF-8 (о чем сообщает HTTP-заголовок «Content-type: text/xml; charset=utf-8»);

  7. В XML-ответах, отдаваемых сервером ЛитРес, помимо описанного в документации содержимого, может размещаться, добавляться и удаляться неограниченное и не регламентированное содержание – узлы, текст и атрибуты. Софт на стороне партнера должен корректно отбрасывать и обрабатывать ситуации, при которых, например, в документации описана структура

    <a b="c"><d/></a>

    а фактически возвращается

    <a b="c" y="x" s="z"><i/><d/><m>text</m></a>

    Атрибуты и параметры, которые вас интересуют, гарантировано останутся по прежнему адресу a/@b и a/d, но дополнительное содержимое может (и будет) появляться и пропадать. Учитывайте эту особенность.

  8. Для всех дробных чисел (например, для цен) в качестве разделителя дробной части используется точка. Число 15,50 является некорректным, а 15.50 и 15.5 – корректными;
  9. Перед размещением книги в общедоступном каталоге ЛитРес, она, а также вся связанная с ней информация (авторы, жанры, серии, цена и т. д.), должна пройти процедуру модерации (одобрения редактором ЛитРес). После того, как книга одобрена и размещена в публичном доступе, единственное, что можно поменять через данное API – её цену. Если требуется переопределить какие-либо другие атрибуты, книга должна заново пройти полную процедуру одобрения.
  10. Все UUID обязательно должны быть сформированы по стандарту RFC 4122. Запрещается генерировать UUID упрощенным генератором случайных символов, т. к. это может вызвать коллизии с другими объектами системы.

5 Жанры ЛитРес

Загружаемая книга должна иметь привязку минимум к одному жанру (но не более четырех!), из классификации ЛитРес (создавать свои жанры нельзя). Книгам присваиваются токены только из «конечных» жанров (type="genre" в ответе сервера). Все остальные контейнеры (type="container") и корневые жанры (type="root") предназначены только для определения иерархической структуры жанрового дерева, обладающего неограниченной вложенностью. 

Учитывайте, что жанровое дерево может изменяться. Со временем, например, конечные жанры (genre) могут превратиться в контейнеры (container). Поэтому рекомендуется обновлять информацию по жанровому дереву не реже раза в сутки. Если частые обращения к серверу нежелательны, можно обновлять дерево жанров реже, но ни в коем случае не реже одного раза в 30 дней.

5.1 Запрос списка жанров

Для получения списка жанров ЛитРес используется следующий URL (без каких-либо параметров):
https://sp.litres.ru/genres_list_2/

5.2 Ответ сервера

Пример возвращаемого XML:

<genres>
	<genre id="5003" title="бизнес-книги" type="root">
		<genre id="5049" title="банковское дело" token="bankovskoe_delo" type="genre"/>
		<genre id="5051" title="бухучет / налогообложение / аудит" token="buhuchet_nalogooblozhenie_audit" type="genre"/>
		<genre id="6784" title="государственное и муниципальное управление" token="gosudarstvennoe_i_munitsipalnoe_upravlenie" type="genre"/>
		<genre id="5060" title="делопроизводство" token="deloproizvodstvo" type="genre"/>
		<genre id="5061" title="зарубежная деловая литература" token="zarubezhnaya_delovaya_literatura" type="genre"/>
		<genre id="5062" title="интернет-бизнес" token="internet" type="genre"/>
		<genre id="5047" title="кадровый менеджмент" token="kadrovyj_menedzhment" type="container">
			<genre id="5334" title="аттестация персонала" token="attestaciya_personala" type="genre"/>
			<genre id="5330" title="гендерные различия" token="gendernyye_razlichiya" type="genre"/>
			<genre id="5332" title="конфликты" token="konflikty" type="genre"/>
			<genre id="5336" title="коучинг" token="kouching" type="genre"/>
			<genre id="5333" title="мотивация" token="motivaciya" type="genre"/>
			<genre id="5335" title="поиск и подбор персонала" token="poisk_presonala_hr" type="genre"/>
			<genre id="5331" title="тимбилдинг" token="timbilding" type="genre"/>
			<genre id="6583" title="управление персоналом" token="upravlenie_personalom" type="genre"/>
	</genre>
</genres>

Таким образом, в примере допустимые жанры и их @token'ы расположены в строках 3-8 и 10-17 (обратите внимание, строка 9 это контейнер). В дальнейшем эти токены используются для привязки книги к какому-то жанру в запросе редактирования карточки книги (partner_object_update), а также внутри FB2-книги в запросе загрузки файла (partner_fb2_upload).

6 Теги ЛитРес

Рекомендуется, чтобы загружаемая книга имела привязку к хотя бы одному-двум тегам (ключевым словам) из классификации ЛитРес. Также рекомендуется регулярно сверять словарь тегов ЛитРес, т.к. теги могут появляться, удаляться, а также незначительно менять текстовое описание.

6.1 Запрос списка тегов

Для получения списка тегов ЛитРес используется URL: https://sp.litres.ru/get_litres_keywords/.

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

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00».

Изучить пример кода для формирования sha и посмотреть актуальный список тегов можно с помощью тестового файла SP_LitRes_get_litres_keywords.html.

6.2 Ответ сервера

Пример возвращаемого XML:

<tags timestamp="2015-02-27T18:35:32+03:00">
	<tag uuid="6156b4b6-5b5b-11e4-96e2-0025905a06ea" tag_title="облачные сервисы"/>
	<tag uuid="614bcc80-5b5b-11e4-96e2-0025905a06ea" tag_title="облачные технологии"/>
	<tag uuid="61238fb8-5b5b-11e4-96e2-0025905a06ea" tag_title="обливание"/>
	<tag uuid="bb25750f-9a73-11ea-a00d-441ea1508474" tag_title="обложка ню" visible="0"/>
	<tag uuid="6165b878-5b5b-11e4-96e2-0025905a06ea" tag_title="облучение"/>
	<tag uuid="61415df6-5b5b-11e4-96e2-0025905a06ea" tag_title="обманы зрения"/>
</tags>

Корневой элемент tags имеет атрибут @timestamp, содержащий текущее время сервера.

В tags хранится список ключевых слов, каждое каждое из которых представлено элементом tag со следующим содержимым:

  • @uuid – идентификатор тега. Используется в запросе редактирования карточки книги (partner_object_update);
  • @tag_title – текстовое описание тега. Используется внутри FB2-книги в запросе загрузки файла (partner_fb2_upload);
  • @visible – атрибут, определяющий «видимость» одобренного тега на карточке книги. Может отсутствовать, что означает, что тег будет отображается, по умолчанию.
    Может принимать следующие значения:
    • 0 – тег не виден на карточке книги, даже если он является одобренным;
    • 1 – тег виден на карточке книги.

7 Цены ЛитРес

ЛитРес продает книги по определенной ценовой сетке. Если указанная партнером цена будет отличаться от представленных в сетке, то произойдет округление вверх до ближайшего ценового уровня (или до максимального, если переданная цена выше).

7.1 Запрос ценовой сетки

Для получения ценовой сетки ЛитРес используется следующий URL (без каких-либо параметров): https://sp.litres.ru/static/ds/price_grid.xml.

7.2 Ответ сервера

Пример возвращаемого XML:

<price_data>
	<price value="0.00"/>
	<price value="5.99"/>
	<price value="9.99"/>
	<price value="14.99"/>
	<price value="19.99"/>
	<price value="399.00"/>
	<price value="439.00"/>
	<price value="490.00"/>
</price_data>

Каждый элемент из сетки цен представлен тегом price с атрибутом @value, в котором указана цена в рублях. Данная цена используется в запросе редактирования карточки книги (partner_object_update), а также в запросе изменения цены (partner_art_price_change).

8 Создание и редактирование серий, персон, книг

Для создания и редактирования серий, авторов, переводчиков и самих книг используется единый формат запроса. Причем за один запрос к серверу могут быть созданы или изменены сразу несколько серий/персон/книг.

8.1 Запрос на создание/редактирование серии, персоны, книги

Используется следующий URL: https://sp.litres.ru/partner_object_update/.
Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • request* – в данном параметре необходимо передать XML-документ, содержание которого изменяется в зависимости от того, что необходимо создать или отредактировать (подробнее они рассмотрены ниже):

Если в XML-документе будет содержаться сразу несколько создаваемых или изменяемых элементов, то они будут обработаны на стороне сервера в следующей последовательности: сначала все серии, затем все персоны и все книги.
Проверить корректность (валидность) XML-документа можно с помощью XSD-схемы query_samizdat.xsd.
Протестировать запросы создания/редактирования элементов можно с помощью тестового файла SP_LitRes_partner_object_update.html.

8.1.1 XML для запроса создания/редактирования серии

Если планируется, что книга будет логически объединена в серию или цикл с какими-то другими книгами, то для них создается «серия» с общим названием.

Пример XML:

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
  <serie uuid="9b9bbdad-22f2-455d-bfe2-73d8f35d340b" name="Название серии" text_descr_source="Подробное описание серии" />
</update_object>

В теге серии update_object/serie указываются следующие атрибуты (обязательные атрибуты отмечены красной звездочкой):

  • @uuid* – уникальный идентификатор серии. Генерируется на стороне партнера при создании новой серии. Если необходимо отредактировать название или описание ранее созданной серии, то используется её старый UUID;
  • @name* – название серии. Значение должно быть уникальным среди всех серий партнера. Иначе запрос вернет ошибку. Максимальная длина – 255 символов. Первая буква заглавная. Точка в конце не нужна. «Капс» запрещен (исключение – аббревиатуры и пр.). Примеры:
    • Библиотека делового человека.
    • 50 оттенков.
    • Журнал «Коллекция Караван историй» 2014.
  • @text_descr_source – описание серии. Примеры:
    • Еженедельный аналитический журнал. На страницах издания вы найдете материалы о политических организациях, власти денег, анализ религиозных и научных идей. В каждом номере рассматриваются такие вопросы как, каким людям и корпорациям принадлежит сегодняшняя власть в России и за рубежом, что представляет собой расстановка сил в политической элите, и многое другое. Ведущие политики и экономисты дают комментарии событиям прошедшей недели и делают точные прогнозы на скорое будущее.
    • «Авантюрный детектив» – серия приключенческих романов Татьяны Поляковой, умело сочетающей захватывающие дух погони, сложные расследования и интригующую любовную линию. Критики и читатели отмечают в своих отзывах, что у разных книг цикла различные оттенки – среди них есть истории с политической окраской, встречаются произведения, щедро сдобренные историческими фактами, а бывают и явно мелодраматические сюжеты, однако легкость восприятия, неизменный юмор автора и счастливые финалы присутствуют всюду. В серию вошло около пятидесяти произведений автора, среди которых романы «Огонь, мерцающий в сосуде», «Я – ваши неприятности», «Уходи красиво» и «Мое второе я». По мотивам авантюрных детективов Татьяны Поляковой снят фильм «Тонкая штучка», а также популярные сериалы «Как бы не так» и «Строптивая мишень».

Проверить корректность (валидность) XML-документа можно с помощью XSD-схемы query_samizdat.xsd.

8.1.2 XML для запроса создания/редактирования персоны

С книгой могут быть связаны различные персоны, такие как авторы, переводчики, художники, составители, редакторы и т.д. Причем в приведенным далее XML сначала создается только описание персоны (ФИО, дата рождения, фотография и пр.), а её роль (автор, переводчик и т. д.) указывается уже в запросе создания/редактирования описания к книге.

Авторско-правовой отдел (АПО) может объединить несколько персон в одну. Например, вы ввели персону Пушкин и загружаете несколько его книг. Но в системе Литрес существует уже Пушкин со множеством других книг. Редактора АПО определили что это одна и та же персона и объединили. С этого момента вы теряете право обновлять описание персоны (будет приходить код ошибки 102216), но можете по прежнему привязывать книги к этой персоне использую ваш старый uuid.

Пример XML:

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
	<person uuid="01f10c47-7369-4702-8d8b-f98fedf05798" first_name="Петр" middle_name="Сергеевич" last_name="Антонов" auto_sklon="1" inverse_full_name="Антонов Петр" birth_year="1969" photo_url="our_authors/123.jpg">
		<description>
			<p>текст <b>жирный текст</b></p>
			<p>Список:</p>
			<ul><li>Элемент1</li><li>Элемент2</li><li>Элемент3</li></ul>
		</description>
	</person>
</update_object>

Ещё пример XML:

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
	<person uuid="33530e47-2cbf-4791-8493-c25b05cf3622" first_name="Дарья" last_name="Донцова" auto_sklon="0" last_rodit="Донцовой" last_dateln="Донцовой" last_vinit="Донцову" last_tvorit="Донцовой" last_predl="Донцовой" full_name="Дарья Донцова" full_rodit="Дарьи Донцовой" full_dateln="Дарье Донцовой" full_vinit="Дарью Донцову" full_tvorit="Дарьей Донцовой" full_predl="Дарье Донцовой" inverse_full_name="Донцова Дарья"/>
</update_object>

В теге персоны update_object/person указываются следующие атрибуты (обязательные атрибуты отмечены красной звездочкой):

  • @uuid* – уникальный идентификатор персоны. Генерируется на стороне партнера при создании новой персоны. Если необходимо отредактировать ранее созданную персону, то используется её старый UUID;
  • @first-name – имя. Максимальная длина – 255 символов. «Капс» запрещен. Точка в конце не нужна (исключение – когда в качестве имени указывается только лишь инициал, например, «А.»;
  • @middle-name – отчество. Максимальная длина – 255 символов. «Капс» запрещен. Точка в конце не нужна (исключение – когда в качестве отчества указывается только лишь инициал, например, «В.»;

  • @last-name* – фамилия. Максимальная длина – 255 символов. Точка в конце не нужна. «Капс» запрещен. Поле @last-name должно быть заполнено обязательно (warning).
    Если персона не имеет фамилии, а использует только псевдоним или имя – оно указывается именно в @last-name;

    Примечание: если необходимо создать нестандартную персону, например, коллектив редакции журнала, тогда в атрибуте @last-name достаточно указать слово «Редакция» или «Издательство».

  • @auto_sklon* – если в этом атрибуте передано значение «1», то склонение имени и фамилии персоны по падежам будет происходить в автоматическом режиме (рекомендуется только для «простых» ФИО). Если указать в атрибуте «0», то необходимо в явном виде «просклонять» персону в следующих дополнительных атрибутах:

    • @last_rodit – фамилия (родительный падеж);
    • @last_dateln – фамилия (дательный падеж);
    • @last_vinit – фамилия (винительный падеж);
    • @last_tvorit – фамилия (творительный падеж);
    • @last_predl – фамилия (предложный падеж);
    • @full_name – «полное имя» (обычно это имя и фамилия) в именительном падеже. Если этот параметр не передан в запросе, то он автоматически формируется из имени, отчества и фамилии, разделенных пробелами: «first-name middle-name last-name». Рекомендуется, чтобы значение в @full_name (или сформированное автоматически) было уникальным среди всех персон партнера. Если же партнер добавит через API пять персон с одинаковыми «полными именами», то при попытке добавить шестую запрос вернет ошибку;
    • @full_rodit – полное имя (родительный падеж);
    • @full_dateln – полное имя (дательный падеж);
    • @full_vinit – полное имя (винительный падеж);
    • @full_tvorit – полное имя (творительный падеж);
    • @full_predl – полное имя (предложный падеж);
    • @inverse_full_name – полное имя в обратном порядке слов в именительном падеже;
  • @birth_year – год рождения в формате «ГГГГ»;
  • @photo_url – относительный путь до изображения/фотографии персоны на сервере партнера, например «our_authors/123.jpg». Допустимый формат файла: JPEG (RGB), картинка должна быть квадратной (warning) и иметь размер не менее 100px;
  • @uilang – необязательный параметр «язык описания автора», двубуквенный символ. По умолчанию ru (и он же основной). Вы можете добавлять варианты написания автора и текста его биографии на других языках отдельными запросами. 
    При заключении договора партнер передает ЛитРес URL директории на своем сервере, в которой будут размещаться фотографии персон, например, «http://www.site.ru/ext_photo/» (загрузка изображений со сторонних ресурсов не допустима). И при обработке запроса на создание/редактирование персоны происходит синхронное скачивание фотографии с комбинированного URL: http://www.site.ru/ext_photo/our_authors/123.jpg. Важно, чтобы изображение было доступно по HTTP без авторизации. Т. к. если произойдет ошибка на этапе загрузки изображения, то весь запрос на обновление персоны получит статус ошибочного;
  • @description – описание автора. Должен содержать один или несколько абзацев или списков, каждый из которых должен быть обрамлен тегами <p></p>,<ul></ul>,<ol></ol>, элемент списка - <li></li>. Стили <b></b><i></i><u></u><sub></sub><sup></sup>. Пустые абзацы не допускаются. Размещение ссылок в description не допускается (warning) (при попытке сервер вернет ошибку 102200 – см. Коды ошибок). 
  • @art_id - ID арта для промоблока (положительное integer или пустая строка). Проверяется на наличие такого арта в базе fbhub.arts.id. Если передана пустая строка - в базу заносится NULL. Сохраняется в lib_area_100.persons_descrs.art.
    Возможные ошибки: 102220, 102221.
  • @valid_till - дата/время истечения промоблока. Формат ISO: "2015-05-27T18:20:30+00:00" (нужно отправлять в UTC, чтобы в БД сохранилось "2015-05-27T21:20:30") в базе сохраняется в таймзоне 'Europe/Moscow'. Если передана пустая строка - в базу заносится NULL. Сохраняется в lib_area_100.persons_descrs.valid_till.
    Возможная ошибка: 102222.

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
	<person last_name="Редакция" uuid="01f10c46-7329-4749-8d8b-f93fedf05699" auto_sklon="1"/>
</update_object>

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

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
	<person uuid="33530e47-2cbf-4791-8493-c25b05cf3622" last_name="Редакция журнала «Вопросы экологии»" auto_sklon="0" last_rodit="Редакции журнала «Вопросы экологии»" last_dateln="Редакции журнала «Вопросы экологии»" last_vinit="Редакцию журнала «Вопросы экологии»" last_tvorit="Редакцией журнала «Вопросы экологии»" last_predl="Редакции журнала «Вопросы экологии»" full_name="Редакция журнала «Вопросы экологии»" full_rodit="Редакции журнала «Вопросы экологии»" full_dateln="Редакции журнала «Вопросы экологии»" full_vinit="Редакцию журнала «Вопросы экологии»" full_tvorit="Редакцией журнала «Вопросы экологии»" full_predl="Редакции журнала «Вопросы экологии»" inverse_full_name="Редакция журнала «Вопросы экологии»"/>
</update_object>

Проверить корректность (валидность) XML-документа можно с помощью XSD-схемы query_samizdat.xsd. 

8.1.3 XML для запроса создания/редактирования описания к книге

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

Пример XML:

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
   <art_to_update uuid="63c38eb5-c0f1-4cae-b170-0bfa812e5c5f" name="Двести возможно лучших рецептов" type="fb2" owner="9351135" date_written_s="2012" date_written_d="2012-01-01" date_translate_s="2014" date_translate_d="2014-01-03" price="14.99" draft="1" update_period="200" publisher="Издательство Привет" isbn="9785170642281" adult="12" adult_cover="yes" adult_annotation="yes" trial_percent="8" valid_till="2015-05-01">
      <title-info>
         <genre>home_cooking</genre>
         <genre>home_crafts</genre>
         <annotation>
            <p>Замечательные рецепты на все случаи жизни.</p>
            <p>Одна из лучших книг в своем серии. Убедительно, ярко, вкусно!</p>
         </annotation>
         <title-relations>
            <related-title uuid="33b19c47-7369-4702-8d8b-f98fedf05798" relation="sequel"/>
            <related-title uuid="58f47daf-aadd-49f7-aaf0-8ff0a6c4e574" relation="prequel"/>
         </title-relations>
         <item-relations>
            <person uuid="5fec2133-b3e1-4a0a-961e-81493c9dfd6d" relation="author"/>
         </item-relations>
         <item-series>
            <related-serie uuid="ab940dec-936d-40fc-8ce4-357e75917e34" />
            <related-serie uuid="9b9bbdad-22f2-455d-bfe2-73d8f35d340b" number="5"/>
         </item-series>
         <art_tags>
            <tag uuid="617082dd-5b5b-11e4-96e2-0025905a06ea"/>
            <tag uuid="61799487-5b5b-11e4-96e2-0025905a06ea"/>
         </art_tags>
         <lang>ru</lang>
         <src-lang>en</src-lang>
         <udc>656.11</udc>
         <udc>[32 + 338](470)</udc>
         <bbk>60.9я73</bbk>
         <bbk>66.2(2Рос) + 65.9(2Рос)</bbk>
      </title-info>
   </art_to_update>
</update_object>

Еще один пример XML с минимальным обязательным набором параметров:

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
   <art_to_update uuid="63c38eb5-c0f1-4cae-b170-0bfa812e5c5f" name="Двести возможно лучших рецептов" type="fb2" owner="9351135" price="14.99" adult="12">
      <title-info>
         <genre>home_cooking</genre>
         <annotation>
		<p>текст <b>жирный текст</b></p>
		<p>Список:</p>
		<ul><li>Элемент1</li><li>Элемент2</li><li>Элемент3</li></ul>
         </annotation>
         <item-relations>
            <person uuid="5fec2133-b3e1-4a0a-961e-81493c9dfd6d" relation="author"/>
         </item-relations>
         <lang>ru</lang>
      </title-info>
   </art_to_update>
</update_object>

Имейте в виду, что в этом запросе важен порядок тегов. Сначала в art_to_update/title-info должны идти жанры (не более четырех), затем аннотация, связи с другими книгами, связи с персонами, серии, теги, язык произведения, язык его оригинала и индексы УДК/ББК (обязательные элементы отмечены красной звездочкой):

  • genre* (не более четырех);
  • annotation*;
  • title-relations;
  • item-relations*;
  • item-series;
  • art_tags;
  • lang*;
  • src-lang;
  • udc;
  • bbk.

Если расположить элементы в ином порядке, то API будет выдавать ошибку. Проверить корректность (валидность) XML-документа можно с помощью XSD-схемы query_samizdat.xsd.

Описание создаваемой/редактируемой книги представляется тегом update_object/art_to_update со следующим содержимым (обязательные теги и атрибуты отмечены красной звездочкой):

  • @uuid* – уникальный идентификатор книги. При создании новой книги UUID должен быть сгенерирован партнером. Если в этом параметре передается UUID от созданной ранее книги, то происходит обновление параметров, перечисленных в запросе;
  • @name* – полное название книги. Оно должно быть уникальным среди всех книг партнера, иначе запрос вернет ошибку. Рекомендации по названию:
    • название книги не должно состоять из прописных буква, т. е. названия «капсом» запрещены. Допускается в исключительных случаях, например: 100 мест всемирного наследия ЮНЕСКО;
    • в начале и конце названия не должно быть пробелов;
    • в конце названия точка не требуется. Примеры-исключения: Великие сражения 1920–1870 гг. Исторические завитушки – или проба пера?..;
    • если в названии книги есть кавычки-лапки, то их рекомендуется заменить на кавычки-ёлочки. Пример корректных кавычек: Операция «Багратион»;
  • @type* – формат книги. Допустимые значения: «fb2», «fb3» и «pdf», «audio», «epub»;
  • @owner* – уникальный идентификатор правообладателя партнера, определяющий набор ресурсов/площадок, на которых будет размещена книга (значение для этого параметра передается партнеру при заключении договора с ЛитРес);
  • @date_written_s – дата написания книги в формате «ГГГГ»;
  • @date_written_d – дата написания книги в формате «ГГГГ-ММ-ДД»;
  • @date_translate_s – дата перевода книги с языка оригинала в формате «ГГГГ»;
  • @date_translate_d – дата перевода книги с языка оригинала в формате «ГГГГ-ММ-ДД»;
  • @draft – атрибут, указывающий на то, что книга является «черновиком». Данный атрибут принимается только для книг типа «0»;
  • @update_period – периодичность обновления «черновика» в днях. Передается только совместно с атрибутом «draft» и может принимать целочисленные значение в промежутке от 0 до 255;
  • @price* – цена на книгу в рублях в формате дробного числа с точкой в качестве разделителя дробной части, например: «99.90» или «99.9». Сетка доступных для использования цен приводится в главе «цены ЛитРес». Если в данном параметре будет передана иная цена, то при размещении книги в продажу она все равно округлится вверх до ближайшего значения из сетки цен (но не больше максимального). Если необходимо распространять книгу бесплатно, то укажите цену «0.00»;
  • @publisher – полное название издательства, опубликовавшего книгу, например «Эксмо-Пресс»;
  • @publisher_code – внутренний издательский код книги. Длина до 100 символов.
  • @isbn – ISBN книги (целое число, состоящее из 13 цифр без разделителей);
  • @adult* – возрастное ограничение, накладываемое на содержание книги (целое число). Доступные значения: 0, 6, 12, 16, 18, 21;
  • @adult_cover – если на обложке книги есть что-то, подпадающее под возрастное ограничение «18+», то в этом атрибуте необходимо передать значение «yes». Иначе по умолчанию используется значение «no»;
  • @adult_annotation – если в аннотации книги есть что-то, подпадающее под возрастное ограничение «18+», то в этом атрибуте необходимо передать значение «yes». Иначе по умолчанию используется значение «no»;
  • @trial_percent – (актуально только для FB2-книг, у pdf-книг задается по листам в другом запросе) размер фрагмента книги в процентах, доступный читателю для бесплатного ознакомления перед покупкой. Доступные значения: целое число от 8 до 20 включительно. Значение по умолчанию: 25%;
  • @preview_length – размер фрагмента аудио книги в секундах, доступный читателю для бесплатного ознакомления перед покупкой. По умолчанию это 10% от начала первого mp3 файла книги, но не более 300 секунд. Актуально только для книг, у которых указан тип @type=audio;
  • @rss – url для rss подкаста, работает только при создании подкаста, при редактировании игнорируется
  • @podcast_complete – yes/no при значении yes считается что подкаст завершен, новые выпуски не будут добавляться
  • @valid_till – дата индивидуального окончания прав на данную книгу в формате «ГГГГ-ММ-ДД». При наступлении указанной даты книга автоматически полностью снимется с продажи. Также с помощью этого атрибута можно принудительно снять книгу с продажи, передав в нём текущую дату;
  • @keep_on_sale – атрибут, указывающий, что книга должна остаться в продаже. Принимает значение =1. Если параметр не передан, то при обновлении данных книги, она будет снята с продажи;
  • title-info/genre* – перечень жанров книги. Допустимые значения приведены в главе «жанры ЛитРес» в атрибутах @token. Для каждой книги должен быть определен хотя бы один такой жанр. Жанров может быть от одного до четырех;
  • title-info/master_genre –  мастер-жанр книги. Именно этот жанр будет приписан книге для случаев когда учитывается только один жанр. Он может быть одним из перечисленных в <genre>, а может быть дополнительным к ним. То есть всего книге можно с мастер-жанром присвоить максимум пять жанров;
  • title-info/annotation* – аннотация к книге. Должен содержать один или несколько абзацев или списков, каждый из которых должен быть обрамлен тегами <p></p>,<ul></ul>,<ol></ol>, элемент списка - <li></li>. Стили <b></b><i></i><u></u><sub></sub><sup></sup>. Пустые абзацы не допускаются. Размещение ссылок в аннотации не допускается (warning) (при попытке сервер вернет ошибку 102201 – см. Коды ошибок);
  • title-info/title-relations/related-title – список логических связей с другими книгами, добавленными ранее через API. Например, если книга является второй в серии, то можно создать связь с первой книгой (предыдущим выпуском). Атрибуты:
    • @uuid* – уникальный идентификатор логически связанной книги. Такая книга должна быть заранее создана партнером, но не обязательно размещена в продажу;
    • @relation* – тип связи между книгами. Допустимые значения:
      • previous – предыдущий выпуск;
      • next – следующий выпуск;
      • translated_from – перевод с;
      • translated – перевод;
      • collected – сборник;
      • part – часть;
      • reedition – переиздание;
      • sequel – продолжение;
      • prequel – предыстория;
      • another_type – другой тип книги, например аудиоверсия для текстовой;
      • auto_speech – создана авточтецом;
      • auto_speech_paid – cоздана авточтецом на продажу.
  • title-info/item-relations/person* – список персон, связанных с книгой. Важно, чтобы к книге была привязана хотя бы одна персона (автор, составитель или кто-то еще). Атрибуты:
    • @uuid* – уникальный идентификатор персоны. Такая персона должна быть заранее создана партнером;
    • @relation* – роль персоны по отношению к книге. Допустимые значения:
      • author – автор;
      • translator – переводчик;
      • illustrator – художник;
      • compiler – составитель;
      • editor – редактор;
      • narrator – чтец;
      • coauthor – соавтор.

    • @license_end – [разрешено только системным роботам].

  • title-info/item-series/related-serie – список серий, в которых размещается книга. Если в запросе не передан этот тег, то серии, присвоенные книге ранее, не будут изменены. Атрибуты:
    • @uuid* – уникальный идентификатор серии. Такая серия должна быть заранее создана партнером;
    • @number – порядковый номер книги в серии (целое положительное число). Следует указывать, если есть порядковая нумерация книг в серии. И, если вы добавляете, например, сначала 3-й выпуск номера журнала, а потом планируете добавить первые два, то необходимо сразу указывать корректную нумерацию. Издательские серии, например, «учебники высшей школы», как правило, идут без номера серии (но при желании можно и указать).

Дополнительно в узле item-series можно передать необязательный параметр keep_old=1. Он определяет, что переданный в этом запросе список серий нужно добавить к уже имеющимся сериям, в которых размещается книга. Если параметр не передан явным образом (а по умолчанию keep_old=0) и при этом передан пустой тег item-series, то в результате выполнения запроса все ранее присвоенные серии, в которых размещается книга, будут удалены.

  • title-info/art_tags/tag – список тегов (ключевых слов) книги. Атрибуты:
    • @uuid* – уникальный идентификатор ключевого слова. Допустимые значения рассмотрены в главе «теги ЛитРес»;
  • title-info/lang* – язык, на котором написана книга (двухбуквенный код в нижнем регистре в формате ISO). Допустимые значения:
    • ru – Русский;
    • uk – Украинский;
    • en – Английский;
    • de – Немецкий;
    • fr – Французский;
    • ab – Абхазский;
    • az – Азербайджанский;
    • ay – Аймара;
    • sq – Албанский;
    • ar – Арабский;
    • hy – Армянский;
    • as – Ассамский;
    • af – Африкаанс;
    • ts – Банту;
    • eu – Баскский;
    • ba – Башкирский;
    • be – Белорусский;
    • bn – Бенгальский;
    • my – Бирманский;
    • bh – Бихарский;
    • bg – Болгарский;
    • br – Бретонский;
    • cy – Валлийский;
    • hu – Венгерский;
    • wo – Волоф;
    • vi – Вьетнамский;
    • gd – Гаэльский;
    • nl – Голландский;
    • el – Греческий;
    • ka – Грузинский;
    • gn – Гуарани;
    • da – Датский;
    • gr – Древнегреческий;
    • iw – Древнееврейский;
    • dr – Древнерусский;
    • zu – Зулу;
    • he – Иврит;
    • yi – Идиш;
    • in – Индонезийский;
    • ia – Интерлингва;
    • ga – Ирландский;
    • is – Исландский;
    • es – Испанский;
    • it – Итальянский;
    • kk – Казахский;
    • kn – Каннада;
    • ca – Каталанский;
    • ks – Кашмири;
    • qu – Кечуа;
    • ky – Киргизский;
    • zh – Китайский;
    • ko – Корейский;
    • kw – Корнский;
    • co – Корсиканский;
    • ku – Курдский;
    • km – Кхмерский;
    • xh – Кхоса;
    • la – Латинский;
    • lv – Латышский;
    • lt – Литовский;
    • mk – Македонский;
    • mg – Малагасийский;
    • ms – Малайский;
    • mt – Мальтийский;
    • mi – Маори;
    • mr – Маратхи;
    • mo – Молдавский;
    • mn – Монгольский;
    • na – Науру;
    • ne – Непали;
    • no – Норвежский;
    • pa – Панджаби;
    • fa – Персидский;
    • pl – Польский;
    • pt – Португальский;
    • ps – Пушту;
    • rm – Ретороманский;
    • ro – Румынский;
    • rn – Рунди;
    • sm – Самоанский;
    • sa – Санскрит;
    • sr – Сербский;
    • si – Сингальский;
    • sd – Синдхи;
    • sk – Словацкий;
    • sl – Словенский;
    • so – Сомали;
    • st – Сото;
    • sw – Суахили;
    • su – Сунданский;
    • tl – Тагальский;
    • tg – Таджикский;
    • th – Тайский;
    • ta – Тамильский;
    • tt – Татарский;
    • te – Телугу;
    • bo – Тибетский;
    • tr – Турецкий;
    • tk – Туркменский;
    • uz – Узбекский;
    • ug – Уйгурский;
    • ur – Урду;
    • fo – Фарерский;
    • fj – Фиджи;
    • fi – Финский;
    • fy – Фризский;
    • ha – Хауса;
    • hi – Хинди;
    • hr – Хорватскосербский;
    • cs – Чешский;
    • sv – Шведский;
    • sn – Шона;
    • eo – Эсперанто;
    • et – Эстонский;
    • jv – Яванский;
    • ja – Японский;
  • title-info/src-lang – язык, с которого было переведено данное произведение (язык оригинала) – двухбуквенный код в нижнем регистре в формате ISO. Важно: оставьте это поле пустым, если книга не переводилась и язык оригинала совпадает с языком, на котором написана книга;
  • title-info/udc – перечень УДК-индексов книги. У книги может быть несколько индексов и каждый из них записывается в отдельном теге title-info/udc. Важно, чтобы в значении индекса отсутствовал префикс «УДК». Примеры корректных индексов:
    • 656.11;
    • 656.072:338.47;
    • 001(470);
    • 070(571.54)(091);

    • [32 + 338](470);

    • 364(571.53/.54)(091)(075.8);
    • 340.15(47+57)(075.8);

    • [574 + 502/504](075.8);

    • 94(100)«654»(075.8).
  • title-info/bbk – перечень ББК-индексов книги. У книги может быть несколько индексов и каждый из них записывается в отдельном теге title-info/bbk. Важно, чтобы в значении индекса отсутствовал префикс «ББК». Примеры корректных индексов:
    • 72;
    • 39.311;
    • 60.9я73;
    • 63.3(0)5я73;
    • 28.080я73 + 20.18я73;
    • 66.2(2Рос) + 65.9(2Рос).

Проверить корректность (валидность) XML-документа можно с помощью XSD-схемы query_samizdat.xsd.


8.1.4 XML для запроса полного или частичного обновления серий арта

Блок с обновлением серий для арта должен идти после блока /update_object/art_to_update.

Пример XML для запроса полного обновления серий у арта:

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
  <update_art_serie uuid="d35c0003-b0b6-43e5-8cb9-a5eda3775a66">
    <serie uuid="9b9bbdad-22f2-455d-bfe2-73d8f35d340b" number="2" />
    <serie uuid="3a51685a-81a0-11e7-8e4c-0cc47a52085c" number="3" />
  </update_art_serie>  
</update_object>

Пример XML для запроса частичного обновления серий у арта (для этого добавляется атрибут action):

<?xml version="1.0" encoding="UTF-8"?>
<update_object>
  <update_art_serie uuid="d35c0003-b0b6-43e5-8cb9-a5eda3775a66">
    <serie action="add" uuid="9b9bbdad-22f2-455d-bfe2-73d8f35d340b" number="2" />
    <serie action="remove" uuid="3a51685a-81a0-11e7-8e4c-0cc47a52085c" />
  </update_art_serie>  
</update_object>

Атрибут /update_object/update_art_serie:

  • @uuid - уникальный идентификатор книги.

Атрибут /update_object/update_art_serie/serie:

  • @uuid - уникальный идентификатор серии.
  • @action - действие над серией арта. Атрибут необязательный. Возможные значения: add, remove.
  • @number - можно задать/изменить номер книги в серии. Атрибут необязательный.


Важно

В /update_object/update_art_serie/serie либо вообще не указывается атрибут action для серий и тогда у арта все серии обновляются на переданный в запросе список. Либо указывается атрибут action у всех тэгов /update_object/update_art_serie/serie и тогда будет частичное обновление только переданных серий.



8.2 Ответ сервера

Пример возвращаемого XML:

<update_object_result>
	<updated_object result="error" timestamp="2015-05-27T18:20:30+03:00" error_message="Failed to add relation with art uuid = '33b19c47-7369-4702-8d8b-f98fedf05798': no ownership or art doesn't exist" uuid="63c38eb5-c0f1-4cae-b170-0bfa812e5c5f" error_code="102014"/>
</update_object_result>

В ответе каждый создаваемый или редактируемый элемент (серия, персона, книга) представлен тегами update_object_result/updated_object со следующим содержимым:

  • @result* – в случае успешной обработки элемента (серии, персоны, книги) этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса на сервере;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок»;
  • @uuid* – идентификатор создаваемого/редактируемого элемента.

9 Загрузка файла FB2 (FB3), EPUB и отправка книги на модерацию

9.1 Запрос на загрузку файла FB2 (FB3) и отправку книги на модерацию

Для FB2-файлов используется URL: https://sp.litres.ru/partner_fb2_upload/.
Для FB3-файлов используется URL: https://sp.litres.ru/partner_fb3_upload/.

(warning) Параллельная загрузка объектов от одного робота не поддерживается. Загружайте объекты по одному экземпляру.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • uuid* – уникальный идентификатор загружаемой книги;
  • file* – в данном параметре необходимо передать содержимое файла книги в ZIP-архиве. К загружаемым файлам предъявляются требования:
    • кодировка текста в файле: UTF-8;
    • допустимые символы в тексте файла: диапазоны допустимых символов;
    • книга в FB2-формате должна соответствовать схеме FictionBook2.2;
    • не допускаются к использованию следующие конструкции:
      • table – теги таблиц недопустимы. Все таблицы должны быть вставлены в книгу в виде изображений;
      • stylesheet – использование стилей недопустимо;
    • все внутренние сноски и ссылки внутри книги должны иметь актуальные точки привязки;
    • размер конечного файла в ZIP-архиве: не более 30 МБ;
    • в книге не должно быть оглавления (оно будет формироваться автоматически из заголовков);
    • все изображения в книге должны быть в форматах JPEG или PNG в цветовой схеме RGB с разрешением каждого файла не более 2 мегапиксела (длина × ширина ≤ 2 000 000 px). Рекомендуемый размер: 600-1000 px по длинной стороне. При этом все изображения в книге обязательно должны быть использованы;
    • в загружаемом файле может содержаться обложка книги. Но если она не задана, то на стороне ЛитРес она будет сгенерирована автоматически. Требования к обложке:
      • расширение файла: JPG;
      • цветовая схема: RGB;
      • минимальный размер бо́льшей стороны обложки: 1500 px, например 1000×1500 px;
      • в качестве обложки допустимо использовать только лицевую сторону книги без каких-либо дополнительных эффектов (например, 3D и т. п.);
      • рекомендуемое (но не обязательное) соотношение сторон: 5×7 (W×H);
    • для FB2-книг можете воспользоваться более подробными рекомендациями по оформлению и вёрстке «Советы для верстальщиков»;

    • для создания FB3-книг можно пользоваться специальным редактором http://fb3edit.org/. (warning) Рекомендуется заполнять все поля описания, чтобы избежать далее проблем с модерацией и релизом.

  • keep_on_sale – необязательный атрибут, указывающий, что книга должна остаться в продаже. Принимает значение =1. Если параметр не передан, то при обновлении FB2/FB3 файлов, книга будет снята с продажи;
  • file_checksum – необязательный атрибут, определяющий необходимость проверки FB2/FB3-файла на целостность. Принимает значение sha256 от файла (например, считается линукс-утилитой «sha256sum»), в нижнем регистре.

Пример содержимого FB2-файла:

<FictionBook xmlns="http://www.gribuser.ru/xml/fictionbook/2.0" xmlns:l="http://www.w3.org/1999/xlink">
 <description>
  <title-info>
   <genre>poetry</genre>
   <author>
    <first-name>Владимир</first-name>
    <middle-name>Владимирович</middle-name>
    <last-name>Маяковский</last-name>
    <id>dce719b0-2a83-102a-9ae1-2dfe723fe7c7</id>
   </author>
   <book-title>Тучкины штучки</book-title>
   <annotation>
    <p>«Плыли по◦небу тучки.</p>
    <p>Тучек◦– четыре штучки:</p>
    <p>от первой до◦третьей◦– люди,</p>
    <p>четвёртая была◦– верблюдик…»</p>
   </annotation>
   <date></date>
   <lang>ru</lang>
   <sequence name="Хрестоматии для начальной школы">
    <sequence name="Большая хрестоматия для начальной школы">
     <sequence name="Современная русская литература"/>
    </sequence>
   </sequence>
  </title-info>
  <document-info>
   <author>
    <nickname>MCat78</nickname>
   </author>
   <program-used>FictionBook Editor Release 2.6.6</program-used>
   <date value="2012-10-09">09 October 2012</date>
   <src-url>http://www.litres.ru/pages/biblio_book/?art=4235585</src-url>
   <src-ocr>Текст предоставлен издательством</src-ocr>
   <id>aa9720a5-12f6-11e2-86b3-b737ee03444a</id>
   <version>1.0</version>
   <history>
    <p>v 1.0 – создание fb2 – (MCat78)</p>
   </history>
  </document-info>
  <publish-info>
   <book-name>Большая хрестоматия для начальной школы</book-name>
   <publisher>Эксмо</publisher>
   <city>Москва</city>
   <year>2012</year>
   <isbn>978-5-699-56619-8</isbn>
   <sequence name="Для школьников и учеников начальных классов"/>
  </publish-info>
 </description>
 <body>
  <title>
   <p>Владимир Владимирович Маяковский</p>
   <p>Тучкины штучки</p>
  </title>
  <section>
   <poem>
    <stanza>
     <v>Плыли по◦небу тучки.</v>
     <v>Тучек◦– четыре штучки:</v>
     <v>от первой до◦третьей◦– люди,</v>
     <v>четвёртая была◦– верблюдик,</v>
     <v>К ним, любопытством объятая,</v>
     <v>по дороге пристала пятая,</v>
     <v>от неё в◦небосинем лоне</v>
     <v>разбежались за◦слоником слоник.</v>
     <v>И, не◦знаю, спугнула шестая ли,</v>
     <v>тучки взяли все◦– и◦растаяли.</v>
     <v>И следом за◦ними, гонясь и</v>
     <v>сжирав,</v>
     <v>солнце погналось◦—</v>
     <v>жёлтый жираф.</v>
    </stanza>
   </poem>
  </section>
 </body>
</FictionBook>

С примерами FB3-файлов можно ознакомиться по ссылке: https://github.com/gribuser/FB3/tree/master/Examples.

Данные в теге description FB2-книги

Параметры «XML запроса создания/редактирования описания к книге», из которого можно взять эти данные

Описание

title-info/genre

title-info/genre

Перечень жанров книги

title-info/author

title-info/item-relations/person/@uuid

Автор книги, @id которого должен совпадать с уникальным идентификатором персоны автора

title-info/book-title

@name

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

title-info/annotation

title-info/annotation

Аннотация к книге

title-info/keywords

title-info/art_tags/tag

Ключевые слова (UUID этих тегов приведены в title-info/art_tags/tag, но в FB2-книге должны быть перечислены текстовые описания тегов)

title-info/date

@date_written_s

Дата написания книги

title-info/lang

title-info/lang

Язык, на котором написана книга

title-info/src-lang

title-info/src-lang

Язык, на котором был написан оригинал произведения

title-info/translator

title-info/item-relations/person/@uuid

Перечень переводчиков книги, @id которых должны совпадать с уникальными идентификаторами переводчиков

title-info/sequence

title-info/item-series/related-serie

Список серий, в которых размещается книга

document-info/id

@uuid

Уникальный идентификатор книги

publish-info/publisher

@publisher

Полное название издательства, опубликовавшего книгу

publish-info/isbn

@isbn

ISBN книги

Протестировать запросы загрузки можно с помощью тестового файла. Пример тестового файла для FB2-книги SP_LitRes_partner_fb2_upload.html. Для FB3-книги нужно заменить action на https://sp.litres.ru/partner_fb3_upload/ и заголовок, соответственно.

9.2 Ответ сервера

Пример возвращаемого XML при загрузке FB2-файла:

<update_object_result result="ok" timestamp="2015-05-26T13:52:52+03:00" file_id="12736028"/>

В ответе в update_object_result содержатся следующие атрибуты:

  • @result* – в случае успешной обработки элемента (серии, персоны, книги) этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса на сервере;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок»;
  • @file_id – уникальный целочисленный номер файла. В дальнейшем вы сможете посмотреть перечень всех «привязанных» к книге файлов в запросе объектов, изменивших свое состояние (partner_update_log).

Пример возвращаемого XML при загрузке FB3-файла:

<update_object_result result="ok" timestamp="2015-05-26T13:52:52+03:00"/>

При загрузке FB3-файла в ответе в update_object_result содержатся все те же атрибуты, что и при загрузке FB2-файла за исключением атрибута @file_id.

Учитывайте, что успешное выполнение этого запроса запускает на стороне ЛитРес процедуру «релиза» загруженного файла (создание файлов книги в разных форматах). И до окончания процесса релиза изменять описание или сам файл книги нельзя: при попытке обновления данных API будет выдавать сообщение об ошибке.

9.3 Запрос статуса релиза загруженного файла книги

Файл книги проходит обработку в системе, проходит «релиз»: создаются файлы для бесплатного отрывка, создаются файлы для онлайн читалок, файлы альтернативных форматов и т.д. Когда файл книги успешно проходит релиз, он поступает на модерацию.
Релиз может завершиться с ошибкой, в этом случае книга не поступит на модерацию.
Арт может не содержаться в релизной таблице, но обычно в течение нескольких недель после попытки (с любым исходом) релиза арт в ней присутствует.

Узнать статус релиза можно запросом: https://sp.litres.ru/partner_release_status/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • uuid* – уникальный идентификатор загружаемой книги (один или несколько – до 100 штук);

В ответе для каждой указанной книги будет элемент release_status содержащий следующие атрибуты:

  • @status* – waiting, processing, ok, error, not found;
  • @timestamp* – дата и время обработки запроса на сервере;
  • @file_id* – уникальный целочисленный номер файла;
  • @uuid* – уникальный идентификатор книги;
  • @error_message – техническое сообщение системы об ошибке (в случае, если status="error");
  • @requested, @started, @finished – время постановки в очередь, начала и завершения обработки (если не NULL).

9.4 Загрузка файла EPUB-книги

EPUB-книги являются отдельным типом книг. В отличие от fb2/fb3 книг для них не производится генерация файлов книг других типов (pdf, text  и т.д.), читатель может получать только epub-тип.

Для EPUB-файлов используется URL: https://sp.litres.ru/partner_epub_upload/.

(warning) Параллельная загрузка объектов от одного робота не поддерживается. Загружайте объекты по одному экземпляру.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • uuid* – уникальный идентификатор загружаемой книги;
  • file* – в данном параметре необходимо передать содержимое файла книги в формате epub. Названия файлов внутри epub-архива должны быть только на латинице. Файл должен проходить проверку epubcheck. Проверка проходит по правилам EPUB version 2.0.1
  • book_type  - необязательный атрибут, значение epuborig при загрузке основного файла книги (по умолчанию), epubtrial при отдельной загрузке триальной версии;
  • do_trial  - необязательный атрибут, 1 или 0 (по умолчанию 0), указание сделать ли триальную версию при загрузке основного файла книги;
  • keep_on_sale – необязательный атрибут, указывающий, что книга должна остаться в продаже. Принимает значение =1. Если параметр не передан, то при обновлении FB2/FB3 файлов, книга будет снята с продажи;
  • file_checksum – необязательный атрибут, определяющий необходимость проверки epub-файла на целостность. Принимает значение sha256 от файла (например, считается линукс-утилитой «sha256sum»),  значение параметра передается в нижнем регистре.

Ответ аналогичен fb2 см. 9.2


10 Загрузка PDF-файлов книги на FTP

Файл книги в PDF-формате может иметь достаточно большие размеры. Поэтому для их передачи используется особая процедура загрузки.
Для начала книгу необходимо закачать по FTP на специальный сервер ЛитРес (адрес, логин и пароль сообщаются партнеру при заключении договора). На этом сервере загруженный файл хранится несколько часов. За это время нужно успеть выполнить запрос на модерацию PDF-книги (partner_object_update).

Требования к PDF-файлу книги:

  • все страницы книги должны находиться в одном PDF файле.Рекомендуется, что бы на одной странице PDF документа была отдельная страница книги, а не разворот;
  • PDF файл должен быть оптимизирован по размеру. Для чтения книги в электронном виде не требуется такое высокое качество, как для полиграфии. Поэтому размер PDF файла нужно уменьшать настолько, чтобы его можно было быстро скачать через мобильный интернет и при этом читаемость текста и качество картинок осталась на должном уровне;
  • название PDF файла должно состоять только из английских букв, арабских цифр и символов нижнего подчёркивания «_». Пробелы запрещены! Рекомендуется задавать «человекочитаемые» названия, т. к. конечные пользователи скачают файл книги именно с этим названием.

11 Загрузка обложек для PDF-книг, аудио-книг, epub-книг

В случае с книгами в формате FB2 обложка берется из содержимого FB2-файла. А для PDF-книг обложку необходимо загружать отдельно. Если её не загрузить, то книга будет вообще без обложки (автогенерация обложек для PDF не предусмотрена).
Требования к файлу обложки аналогичны требованиям для FB2-обложек и рассмотрены ранее в запросе загрузки FB2 книг.

Также этим запросом можно изменить обложку ранее загруженной fb2-книги.

11.1 Запрос на загрузку обложки для PDF-книги

Используется следующий URL: https://sp.litres.ru/partner_cover_upload/.

(warning) Параллельная загрузка объектов от одного робота не поддерживается. Загружайте объекты по одному экземпляру.
 Здесь и далее под роботом ЛитРес понимается скрипт-обработчик, выполняющий действия по добавлению, изменению, удалению книги, ее атрибутов (жанров, серий, описания, цены и т. д.) и правообладателей на стороне партнера.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • uuid* – уникальный идентификатор загружаемой книги;
  • file* – в данном параметре необходимо передать JPEG-файл обложки;
  • file_checksum – необязательный атрибут, определяющий необходимость проверки файла обложки на целостность. Принимает значение sha256 от файла (например, считается линукс-утилитой «sha256sum»), в нижнем регистре.

Протестировать запросы загрузки файлов обложек можно с помощью тестового файла SP_LitRes_partner_cover_upload.html.

11.2 Ответ сервера

Пример возвращаемого XML:

<update_object_result result="error" timestamp="2015-05-26T16:34:28+03:00" error_message="Only images in JPEG format are allowed but 'test.pdf' was given" error_code="102039"/>

В ответе в update_object_result содержатся следующие атрибуты:

  • @result* – в случае успешной обработки элемента (серии, персоны, книги) этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса на сервере;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

12 Отправка PDF книги на модерацию

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

12.1 Запрос на модерацию PDF-книги

Для отправки PDF-книги на модерацию используется тот же запрос, что и для редактирования серий,авторов и книг: https://sp.litres.ru/partner_object_update/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • request* – в данном параметре необходимо передать XML-документ следующего содержания:

    <?xml version="1.0" encoding="UTF-8"?>
<update_object>
  <pdf_to_upload name="MoskovskyKomsomolec_215_2014.pdf" sha="123ab..22123" preview_pages="1-4,7-8,15" uuid="63c38eb5-c0f1-4cae-b170-0bfa812e5c5f" />
</update_object>

    где:

    • @name* – название файла PDF-книги, предварительно загруженной на FTP;
    • @sha* – хеш SHA-256 от содержимого файла книги (важно: FTP протокол старый), в нижнем регистре;
    • @preview_pages* – перечень страниц (или диапазонов страниц), которые должны войти в файл предварительного просмотра, доступного читателю перед покупкой книги. Рекомендуется включать в него не более 20% книги. Пример: preview_pages="1-4,7-8,15";
    • @uuid* – уникальный идентификатор книги.

Проверить корректность (валидность) XML-документа можно с помощью XSD-схемы query_samizdat.xsd, а протестировать сам запрос отправки PDF-книги на модерацию можно с помощью тестового файла SP_LitRes_partner_object_update.html.

12.2 Ответ сервера

Пример возвращаемого XML:

<update_object_result>
   <updated_object result="ok" timestamp="2015-09-11T18:21:57+03:00" file_id="14651742" preview_id="14651749" uuid="fa7d41d5-54df-50fb-9234-dcd857a50674" />
</update_object_result>

В ответе содержится тег update_object_result/updated_object со следующим содержимым:

  • @result* – в случае успешной обработки запроса этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса на сервере;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок»;
  • @file_id – уникальный целочисленный номер файла с полной версией PDF-книги. В дальнейшем вы сможете посмотреть перечень всех «привязанных» к книге файлов в запросе объектов, изменивших свое состояние (partner_update_log);
  • @preview_id – уникальный целочисленный номер файла с фрагментом PDF-книги. В дальнейшем вы сможете посмотреть перечень всех «привязанных» к книге файлов в запросе объектов, изменивших свое состояние (partner_update_log);
  • @uuid – идентификатор книги.

Учитывайте, что успешное выполнение этого запроса запускает на стороне ЛитРес процедуру «релиза» PDF-книги (создание демо-файла с отрывком книги, генерация изображений для мобильных приложений и пр.). И до окончания процесса релиза изменять описание к книге или повторно отправлять её на модерацию нельзя: в таком случае API будет выдавать сообщение об ошибке.

13 Загрузка файлов аудио книги на FTP

Для передачи файла книги в аудио формате используется такая же процедура загрузки, как и с книгами в формате PDF.
Для начала книгу необходимо закачать по FTP на специальный сервер ЛитРес (адрес, логин и пароль сообщаются партнеру при заключении договора). На этом сервере загруженный файл хранится несколько часов. За это время нужно успеть выполнить запрос на модерацию аудио-книги (partner_object_update).

Требования к файлам аудио книги:

  • все файлы аудио книги должны находиться в одном zip-архиве и должны быть пронумерованы по-порядку (например, *_01.mp3, *_02.mp3, *_03.mp3);
  • названия файлов аудио книги должны состоять только из английских букв, арабских цифр и символов нижнего подчёркивания «_». Пробелы запрещены! Рекомендуется задавать «человекочитаемые» названия, т. к. конечные пользователи скачают файл книги именно с этим названием;
  • если в архиве не содержится файл с именем «sample.*», то ознакомительный фрагмент будет сформирован автоматически из файла книги, который является первым по нумерации (10% файла от начала, но по длительности не более 300 секунд).

14 Загрузка обложек для аудио книг

Для аудио книг обложку необходимо загружать отдельно. Если её не загрузить, то книга будет без обложки (автоматическая генерация не предусмотрена). Загрузка обложек для аудио книг аналогична загрузке обложек для PDF-книг. Требования к файлу обложки аудио книги аналогичны требованиям для FB2-обложек и рассмотрены ранее в запросе загрузки FB2 книг.

15 Отправка аудио книги на модерацию

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

15.1 Запрос на модерацию аудио книги

Для отправки аудио книги на модерацию используется тот же запрос, что и для редактирования серий, авторов и книг: https://sp.litres.ru/partner_object_update/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • request* – в данном параметре необходимо передать XML-документ следующего содержания:

    <?xml version="1.0" encoding="UTF-8"?>
<update_object>
  <audio_to_upload name="strannyi_zaichik.mp3" preview_length="90" sha=«123ab..22123» uuid=«63c41eb5-c0f1-4cae-b170-0bfa812e5c5f» />
</update_object>

    где:

    • @name* – название файла аудио книги, предварительно загруженной на FTP;
    • @sha* – хеш SHA-256 от содержимого файла книги (важно: FTP протокол старый);
    • @uuid* – уникальный идентификатор книги;
    • @preview_length – размер фрагмента аудио книги в секундах, доступный читателю для бесплатного ознакомления перед покупкой. По умолчанию это 10% от начала первого mp3 файла книги, но не более 300 секунд.

Проверить корректность (валидность) XML-документа можно с помощью XSD-схемы query_samizdat.xsd, а протестировать сам запрос отправки аудио книги на модерацию можно с помощью тестового файла SP_LitRes_partner_object_update.html.

15.2 Ответ сервера

Пример возвращаемого XML:

<update_object_result>
   <updated_object result="ok" timestamp="2015-09-11T18:21:57+03:00" uuid="fa7d41d5-54df-50fb-9234-dcd857a50674" />
</update_object_result>

В ответе содержится тег update_object_result/updated_object со следующим содержимым:

  • @result* – в случае успешной обработки запроса этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса на сервере;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок»;
  • @uuid – идентификатор книги.

Учитывайте, что успешное выполнение этого запроса запускает на стороне ЛитРес процедуру «релиза» аудио книги (создание демо-файла с отрывком книги, генерация изображений для мобильных приложений и пр.). И до окончания процесса релиза изменять описание к книге или повторно отправлять её на модерацию нельзя: в таком случае API будет выдавать сообщение об ошибке.

16 Проверка статуса книги, персоны или серии

После отправки книги на модерацию рекомендуется с некоторой периодичностью проверять, изменился ли статус книги или нет. Для этого используется универсальный запрос, который позволяет получить информацию об изменениях всех объектов, созданных партнером. Причем можно задавать различные критерии выборки информации: за определенный промежуток времени и/или среди конкретных объектов.
Если вы используете данный API в своем сервисе самиздата, то имейте в виду, что описание книги, персон и серий может незначительно меняться модераторами и редакторами ЛитРес, поэтому рекомендуется периодически (желательно не реже 1 раза в час) обновлять информацию в своей базе в соответствии с данными из приведенного далее запроса.

16.1 Запрос на перечень объектов, изменивших свое состояние

Используется следующий URL: https://sp.litres.ru/partner_update_log/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – серверное (московское) время в формате «2014-11-07T16:21:02+03:00»;

  • checkpoint* – время в формате ISO (например, 2015-09-30T12:09:39+03:00), начиная с которого требуется получить информацию по измененным объектам;
  • uuid – уникальный идентификатор объекта. Если он задан, то в ответе будут данные только по этому объекту.

Протестировать запрос проверки объектов, изменивших свое состояние, можно с помощью тестового файла SP_LitRes_partner_update_log.html.

16.2 Ответ сервера

Пример возвращаемого XML:

<partner_update_log timestamp="2015-05-26T19:19:26+03:00">
  <updated-art status="processed" available="0" message="Файл успешно поставлен в очередь на релиз" release_file="12736028" uuid="63c38eb5-c0f1-4cae-b170-0bfa812e5c5f" id="9827348" name="Двести возможно лучших рецептов" type="fb2" owner="9351135" last_update="2017-07-14 19:17:50" valid_till="2099-12-31" date_written_s="2012" date_written_d="2012-01-01" adult="12" price="14.99" isbn="9785170642281" adult_cover="1" adult_annotation="1" date_translate_s="2014" date_translate_d="2014-01-03" trial_percent="8" url="/petr-sergeevich-antonov/dvesti-vozmozhno-luchshih-receptov/">
    <annotation>
      <p>
      Замечательные рецепты на все случаи жизни. Одна из лучших книг в своем серии. Убедительно, ярко, вкусно!
      </p>
    </annotation>
    <lang>ru</lang>
    <src-lang>en</src-lang>
    <title-relations/>
    <item-relations>
      <person uuid="45a54cbd-a311-11e4-bbe7-002590591ed2" relation="agent"/>
      <person uuid="97a64a78-2ba5-4d6d-b0cb-1e0718794bf3" relation="author"/>
    </item-relations>
    <item-series/>
    <art_tags>
      <tag uuid="61799487-5b5b-11e4-96e2-0025905a06ea"/>
    </art_tags>
    <coverpage>
      <image type="jpg" cover_url="/static/bookimages/08/42/01/08420106.bin.dir/08420106.cover.jpg"/>
    </coverpage>
    <item-files>
      <file id="12736023" sent_by="9352347" size="480940" time="2015-05-26 13:52:42"/>
      <file id="12736028" sent_by="101" size="474024" time="2015-05-26 13:52:47"/>
    </item-files>
    <udc>656.11</udc>
    <udc>[32 + 338](470)</udc>
    <bbk>60.9я73</bbk>
    <bbk>66.2(2Рос) + 65.9(2Рос)</bbk>
  </updated-art>
  <updated-person uuid="97a64a78-2ba5-4d6d-b0cb-1e0718794bf3" status="processed" alphabet="И" first_name="Петр 255 символов" last_name="Иванофф" auto_sklon="1" full_name="Петр 255 символов Иванофф" inverse_full_name="Иванофф Петр 255 символов" last_update="2017-07-14 19:17:50" published_photo="/static/author/123.jpg"/>
  <update-serie uuid="9b9bbdad-22f2-455d-bfe2-73d8f35d340b" name="Название серии" last_update="2017-07-14 19:17:50">
    <text_descr_source>
      <hidden>Подробное описание серии</hidden>
    </text_descr_source>
  </update-serie>
</partner_update_log>

Корневой элемент partner_update_log имеет атрибут @timestamp, содержащий текущее серверное время (с точностью до секунды), до которого (не включительно) вы сейчас получили обновления. Для получения непрерывного потока обновлений это значение следует сохранять и при следующем запросе передавать в параметре checkpoint.

В partner_update_log хранится список объектов, изменивших свое состояние. Возможные объекты и их содержимое:

  • updated-art – содержимое этого тега полностью совпадает с запросом на добавление/редактирование описания к книге (partner_object_update). Дополнительно он содержит следующие значения:
    • @status – текущий статус модерации. Основной атрибут, который необходимо отслеживать после отправки запроса на модерацию. Для успешного прохождения модерации и размещения в продажу книги необходимо, чтобы все связанные с ней персоны и серии также прошли модерацию. Возможные значения:
      • received – первоначальный статус;
      • processed – в процессе обработки;
      • approved – одобрен;
      • declined – отклонен (см. @message);
    • @message – если в процессе модерации книга была отклонена (status="declined"), то в этом атрибуте выводится сообщение о возникшей ошибке или проблеме;
    • @publisher_code – внутренний издательский код книги. Длина до 100 символов.
    • @available – доступность книги для продажи на ресурсах/площадках ЛитРес. Значения:
      • -1 – карточка книги скрыта;
      • 0 – книга не доступна для продажи;
      • 1 – книга доступна и есть в продаже/бесплатной раздаче;
      • 2 – книга скоро поступит в продажу, дата неизвестна;
      • 6 – книга скоро поступит в продажу, дата известна;

Таким образом, как только @status изменит значение на «approved», а @available на «1», то это означает, что книга успешно размещена в продажу на площадках ЛитРеса. Посмотреть книгу на сайте ЛитРес можно по ссылке, сформированной с использованием UUID, например: http://www.litres.ru/search_by_id/?id=aa55bb28-fb43-102b-99a2-0288a49f2f10.

    • @release_file – уникальный целочисленный номер файла, который в текущий момент является актуальной версией книги («релизом» или кандидатом в релиз). Перечень всех файлов, которые отправлялись на модерацию и привязаны к текущей книге, приведены в тегах item-files/file (см. ниже);
    • item-relations/person/@relation="agent" – у каждой книги всегда будет присутствовать одна служебная персона с типом «agent». Для партнера эта персона не существенна;
    • coverpage/image – путь к загруженной обложке книги на сайтах ЛитРес. Например, для формирования полного адреса можно подставить URL: https://www.litres.ru. Примечание: актуальные данные в этом узле появляются только после размещения книги в продажу (@available="1");
    • item-files/file – перечень всех версий файла книги, связанных с текущей книгой (актуально для FB2-книг и аудио книг). Атрибуты:
      • @id – уникальный целочисленный номер файла (в @release_file приведен номер одного из этих файлов, являющийся в текущий момент актуальным «релизом»);
      • @sent_by – идентификатор партнера, отправившего данный файл на сервер ЛитРес. В основном здесь будет содержаться ваш идентификатор партнера (partner), а все остальные значения означают, что файл был загружен сотрудниками или роботами ЛитРес;
      • @size – размер файла в байтах;
      • @filename – наименование файла;
      • @time – время в формате «2014-11-07T16:21:02+03:00», когда файл был загружен в базу ЛитРес;
    • @last_update – дата и время последнего изменения объекта в формате «ГГГГ-ММ-ДД ЧЧ:ММ:СС»;
  • updated-person – содержимое этого тега полностью совпадает с запросом на добавление/редактирование персоны (partner_object_update). Дополнительно он содержит следующие атрибуты:
    • @status – текущий статус модерации. Значения совпадают с аналогичным атрибутом в объектах updated-art:
      • received – первоначальный статус;
      • processed – в процессе обработки;
      • approved – одобрен;
      • declined – отклонен;
    • @published_photo – путь к фотографии персоны на сайтах ЛитРес. Например, для формирования полного адреса можно подставить URL: https://www.litres.ru;
    • @local_person_name – массив локализации, содержащий фамилию и имя, а также описание, на разных языках. Если существуют кроме ru. Если есть только для ru, то этого элемента нет;
    • @last_update – дата и время последнего изменения объекта в формате «ГГГГ-ММ-ДД ЧЧ:ММ:СС»;
  • update-serie – содержимое этого тега полностью совпадает с запросом на добавление/редактирование серии (partner_object_update), за исключением того, что подробное описание серии вынесено в тег update-serie/text_descr_source/hidden. Также данный тег содержит дополнительный атрибут @last_update – дата и время последнего изменения объекта в формате «ГГГГ-ММ-ДД ЧЧ:ММ:СС».

17 Изменение цены продаваемой книги

Если книга уже размещена в продажу на ресурсах/площадках ЛитРес, то партнер может изменять её цену без прохождения повторной модерации.

17.1 Запрос на изменение цены продаваемой книги

Используется следующий URL: https://sp.litres.ru/partner_art_price_change/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • uuid* – уникальный идентификатор книги, цену которой мы хотим изменить;
  • price* – новая цена книги (используйте корректную сетку цен).

Протестировать запрос изменения цены можно с помощью тестового файла SP_LitRes_partner_art_price_change.html.

17.2 Ответ сервера

Пример возвращаемого XML:

<update_object_result result="ok" timestamp="2015-05-27T16:32:36+03:00"/>

В ответе в update_object_result содержатся следующие атрибуты:

  • @result* – в случае успешного изменения цены этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

18 Изменение правообладателя продаваемой книги

Описанный метод помогает сменить правообладателя для книги, не меняя при этом её статус «в продаже».

18.1 Запрос на изменение правообладателя

Используется следующий URL https://sp.litres.ru/partner_art_owner_change/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого запроса:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • uuid* – уникальный идентификатор книги, правообладателя которой мы хотим изменить;

  • owner* – новый правообладатель книги.

18.2 Ответ сервера

Пример возвращаемого XML:

<update_object_result result="ok" timestamp="2015-05-27T16:32:36+03:00"/>

В ответе в update_object_result содержатся следующие атрибуты:

  • @result* – в случае успешного изменения правообладателя этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

19 Удаление связи между роботом ЛитРес и книгой/персоной/серией

Описанный метод помогает удалить привязку робота ЛитРес к книге/персоне/серии. При этом у книги по прежнему останется статус «в продаже».

19.1 Запрос на удаление связи между роботом ЛитРес и продаваемой книгой

Используется следующий URL https://sp.litres.ru/partner_object_forget/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • uuid* – уникальный идентификатор объекта, который мы хотим отвязать от робота;
  • type – art / person / serie – тип объекта который мы хотим отвязать. По умолчанию – art.

19.2 Ответ сервера

Пример возвращаемого XML:

<update_object_result result="ok" timestamp="2015-05-27T16:32:36+03:00"/>

В ответе в update_object_result содержатся следующие атрибуты:

  • @result* – в случае успешного удаления робота, этот атрибут имеет значение ok, иначе – error;
  • @timestamp* – дата и время обработки запроса;
  • @error_message – текстовое описание ошибки на английском языке (в случае, если result="error");
  • @error_code – код ошибки (в случае, если result="error"). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

20 Снятие книги с продажи

Если необходимо снять книгу с продажи со всех площадок ЛитРес, выполните запрос на обновление книги (partner_object_update), указав в атрибуте индивидуального окончания прав (@valid_till) текущую дату в формате ГГГГ-ММ-ДД. Таким образом книга исчезнет из всех каталогов ЛитРес, но сохранится у пользователей, уже купивших данную книгу. В дальнейшем данную книгу можно будет вновь вернуть в продажу, указав корректный @valid_till и повторно пройдя модерацию.
Также имейте в виду, что книга автоматически снимается с продажи и отправляется на повторную модерацию каждый раз, когда меняется какая-либо связанная с ней информация: описание, файл, автор, серия и пр. Поэтому если вам необходимо изменить только лишь цену продаваемой книги, используйте запрос на обновление книги (partner_object_update).

21 Получение статистики

Партнер может просматривать и выгружать в XML статистику покупок, просмотров и онлайн-чтения на специальной странице правообладателя на сайте ЛитРес. Адрес этой страницы сообщается партнеру при заключении договора.
Помимо этого партнер может выгружать статистику через API: как в режиме реального времени (запрос на получение статистики в режиме реального времени), так и за закрытые отчетные периоды (запрос на получение статистики за закрытый отчетный период). Имейте в виду, что для «не закрытых» отчетных периодов показания статистики могут незначительно меняться.

21.1 Запрос на получение статистики в режиме реального времени

Используется следующий URL: https://sp.litres.ru/partner_stats/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • time_from – дата и время в формате «ГГГГ-ММ-ДД ЧЧ:ММ:CC», начиная с которого необходимо получить статистику. Передаваемое значение не может отставать от текущего серверного (московского) времени больше чем на 24 часа. Если в запросе передан данный параметр, то параметры from и to должны в запросе отсутствовать;
  • from – дата в формате «ГГГГ-ММ-ДД», начиная с которой необходимо получить статистику;
  • to – дата в формате «ГГГГ-ММ-ДД», до которой (включительно) необходимо получить статистику;
  • add_free – если этот опциональный параметр передан и равен 1, то выдается специальный отчет по розданным бесплатно книгам с площадок самого Литрес (веб-площадки, мобильные приложения, приложения для устройств и т.д.). Как бесплатно так и за деньги. При этом продажи с партнерских площадок не выдаются.
  • owner - выдать отчет только по одному правообладателю (может быть полезно, если робот обслуживает нескольких правообладателей), опциональный параметр.
  • stat_by_date - выдача статистики с группировкой по датам, опциональный параметр (в разработке).

Запрос позволяет выгружать статистику в трех режимах:

  1. с заданного времени (с точностью до секунды) до текущего момента. При этом заданное время не должно отличаться от текущего более чем на сутки. Используемый параметр: time_from;

    Примечание: в ответе сервер дополнительно возвращает точное серверное время, используя которое можно организовать непрерывную череду запросов для сбора статистики в режиме реального времени.

  2. с конкретной даты до текущего момента. Используемый параметр: from;

  3. с конкретной даты до конкретной даты. Используемые параметры: from и to.

Протестировать запрос можно с помощью тестового файла SP_LitRes_partner_stats.html.

21.2 Ответ сервера

Пример возвращаемого XML в случае ошибки:

<update_object_result result="error" timestamp="2015-06-19T18:56:19+03:00" error_message="SHA verification error - timestamp expired" error_code="102029"/>

В ответе в update_object_result содержатся следующие атрибуты:

  • @result – при ошибке имеет значение error;
  • @timestamp – дата и время обработки запроса;
  • @error_message – текстовое описание ошибки на английском языке;
  • @error_code – код ошибки. Перечень всех кодов с описанием см. в разделе «Коды ошибок».

Пример возвращаемого XML в случае успешной обработки запроса:

<partner_stats>
	<art authors="Павел Котиков" id="7222172" uuid="97a64a78-2ba5-4d6d-b0cb-1e0718794bf3" name="Наследие">
		<stat-channelgroup hits="0" hits_amount="0" sales="7" id="2" sales_amount="59.15" name="ЛитРес"/>
		<stat-channelgroup hits="0" hits_amount="0" sales="2" id="25" sales_amount="359.15" name="Bookmate"/>
	</art>	
	<art authors="Олег Максов" id="9363358" uuid="63c38eb5-c0f1-4cae-b170-0bfa812e5c5f" name="Избранный">
		<stat-channelgroup hits="1" hits_amount="0.03" sales="0" id="1" sales_amount="0" name="Прочее"/>
	</art>
	<period is_final="false" start="2015-06-18 19:44:52" end="2015-06-19 18:44:58"/>
</partner_stats>

Пример возвращаемого XML в случае успешной обработки запроса с параметром stat_by_date (в разработке):

<partner_stats>
	<user_info show_prorata="1" report_currency="RUB"/>
	<date value="2022-01-30">
		<art uuid="b17fb12c-5664-11ec-ab26-441ea1508474" series="Метод Тайной Комнаты" name="Путешествие из долгов к миллионам" authors="Михаил Павлов" id="66865293">
			<stat-channelgroup hits="0" name="Продажи по маскам" sales_amount="506.47" hits_amount="0" id="10000" sales="4"/>
		</art>
		<art id="59666592" authors="Михаил Павлов" name="Помоги любви найти тебя. Метод Тайной Комнаты" series="Метод Тайной Комнаты" uuid="7e2e80c7-fc21-11ea-a60e-0cc47a520475">
			<stat-channelgroup name="Продажи по маскам" hits="0" sales_amount="63.28" hits_amount="0" id="10000" sales="1"/>
		</art>
	</date>
	<date value="2022-01-31">
		<art series="Метод Тайной Комнаты" name="Помоги любви найти тебя. Метод Тайной Комнаты" uuid="0d2a566c-21c1-462f-a039-bb8f91d481b2" authors="Михаил Павлов" id="44222804">
			<stat-channelgroup prorata_list_summ="2" sales="1" id="10000" hits_amount="0" sales_amount="93.16" hits="0" name="Продажи по маскам" prorata_amount="113.48"/>
		</art>
		<art name="Путешествие из долгов к миллионам" series="Метод Тайной Комнаты" uuid="f8d283e5-5da5-11ec-ab26-441ea1508474" id="66931483" authors="Михаил Павлов">
			<stat-channelgroup hits_amount="0" prorata_amount="52.51" sales_amount="223.52" name="Продажи по маскам" hits="0" sales="3" prorata_list_summ="5" id="10000"/>
		</art>
	</date>
	<period is_final="true" end="2022-01-31" start="2022-01-30"/>
</partner_stats>

В ответе в partner_stats содержится перечень всех проданных/прочитанных/бесплатно взятых книг (art), а также данные о периоде, за который выдана данная статистика (period).

Каждая книга art содержит следующие данные:

  • @authors – перечень авторов книги через запятую;
  • @id – внутренний идентификатор книги на сервере ЛитРес. Его можно использовать для формирования ссылки на книгу в магазине ЛитРес: http://litres.ru/pages/biblio_book/?art=9368246;
  • @uuid – уникальный идентификатор книги;
  • @name – название книги;
  • в узлах stat-channelgroup перечислены «каналы продаж», на которых книга была куплена, прочитана или получена бесплатно. Т. к. книги продаются не только на сайтах и приложениях ЛитРес, но и на партнерских ресурсах, то для комфортного анализа статистики каждый из них выделен в отдельный канал. Примеры каналов: ресурсы ЛитРес, Google, МВидео, Связной, Bookmate и т. п. Атрибуты каналов:
    • @id – уникальный идентификатора канала продаж;
    • @name – название канала продаж;
    • @sales – количество проданных (или выданных бесплатно) экземпляров книги;
    • @sales_amount – сумма в рублях, зачисленная на счет партнера за покупки книги через данный канал;
    • @hits – целое число. Количество авторских листов (с округлением в бо́льшую сторону), прочитанных в режиме онлайн-чтения. В подсчете авторских листов участвует только «платная» часть книги – чтение ознакомительного фрагмента здесь не отражено;
    • @hits_amount – сумма в рублях, зачисленная на счет партнера за онлайн-чтение книги через данный канал.

Атрибуты узла period:

  • @is_final – возможные значения:
    • true – статистика за выгруженный период актуальна, окончательна и изменяться не будет. Партнер может использовать представленные данные для проведения внутренних финансовых расчетов;
    • false – статистика за выгруженные даты относится к «не закрытому» отчетному периоду и может незначительно меняться. Рекомендуется использовать представленную информацию только для ознакомительных целей;
  • @start – если в запросе передан параметр time_from, то в @start содержится дата и время в формате «ГГГГ-ММ-ДД ЧЧ:ММ:CC», начиная с которого выведена информация по статистике. Если в запросе переданы параметры from и/или to, то в @start содержится только дата в формате «ГГГГ-ММ-ДД»;
  • @end – если в запросе передан параметр time_from, то в @end содержится дата и время в формате «ГГГГ-ММ-ДД ЧЧ:ММ:CC», до которого (не включительно) выведена информация по статистике. Это значение удобно использовать в последующем запросе к API (в параметре time_from) для непрерывного сбора статистики.Если в запросе переданы параметры from и/или to, то в @end содержится только дата в формате «ГГГГ-ММ-ДД».

21.3 Запрос на получение статистики за закрытый отчетный период

Отчетным периодом является месяц. Данный запрос позволяет партнеру получить окончательную статистику по любому из прошедших и «закрытых» месяцев.

Используется следующий URL: https://sp.litres.ru/partner_final_stats/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • y* – год в формате «ГГГГ»;
  • m* – месяц в формате «ММ»;
  • owner – выдать отчет только по одному правообладателю (может быть полезно, если робот обслуживает нескольких правообладателей), опциональный параметр.

Протестировать запрос можно с помощью тестового файла SP_LitRes_partner_final_stats.html.

21.4 Ответ сервера

Формат ответа полностью совпадает с ответом на запрос partner_stats.

22 Получение данных о статусе связи робота и книги/персоны/серии

Партнер может просматривать и выгружать в XML данные о статусе привязки робота к книге/персоне/серии на сайте ЛитРес. 

22.1 Запрос на получение данных о статусе связи робота и книги/персоны/серии

Используется следующий URL: https://sp.litres.ru/partner_events/.

Параметры запроса (обязательные параметры отмечены красной звездочкой):

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

  • sha* – хеш SHA-256, формируемый индивидуально для каждого из запросов:

    $sha=Digest::SHA::sha256_hex($timestamp.':'.$secret_key.':'.$partner)

  • timestamp* – московское время в формате «2014-11-07T16:21:02+03:00»;

  • time_from – дата и время в формате «ГГГГ-ММ-ДД ЧЧ:ММ:CC», начиная с которого необходимо получить данные о статусе привязки робота к объекту. Передаваемое значение не может отставать от текущего серверного (московского) времени больше чем на 24 часа. Если в запросе передан данный параметр, то параметры from и to должны в запросе отсутствовать;
  • from – дата в формате «ГГГГ-ММ-ДД», начиная с которой необходимо получить данные о статусе привязки робота к объекту;
  • to – дата в формате «ГГГГ-ММ-ДД», до которой (включительно) необходимо получить данные о статусе привязки робота к объекту;

Запрос позволяет выгружать данные в трех режимах:

  1. с заданного времени (с точностью до секунды) до текущего момента. При этом заданное время не должно отличаться от текущего более чем на сутки. Используемый параметр: time_from;

    Примечание: в ответе сервер дополнительно возвращает точное серверное время, используя которое можно организовать непрерывную череду запросов для сбора данных в режиме реального времени.

  2. с конкретной даты до текущего момента. Используемый параметр: from;

  3. с конкретной даты до конкретной даты. Используемые параметры: from и to.

22.2 Ответ сервера

Пример возвращаемого XML в случае ошибки:

<update_object_result result="error" timestamp="2020-03-10T12:45:21+03:00" error_message="SHA verification error - timestamp expired" error_code="102029"/>

В ответе в update_object_result содержатся следующие атрибуты:

  • @result* – при ошибке имеет значение error;
  • @timestamp* – дата и время обработки запроса;
  • @error_message – текстовое описание ошибки на английском языке;
  • @error_code – код ошибки. Перечень всех кодов с описанием см. в разделе «Коды ошибок».

Пример возвращаемого XML в случае успешной обработки запроса:

<partner_events timestamp="2020-03-10T12:45:21+03:00">
	<event type="link" object_type="person" object_id="3952472" object_uuid="78ecf724-fc53-11e3-871d-0025905a0812" event_date="2020-01-22T17:35:49+03:00"/>
	<event type="link" object_type="serie" object_id="627" object_uuid="619ca63a-5b5b-11e4-96e2-0025905a06ea" event_date="2020-01-22T17:42:36+03:00"/>
	<event type="unlink" object_type="art" object_id="25761301" object_uuid="1d3a0fb0-4c77-4952-a33d-4c9fd433e68b" event_date="2020-03-10T16:53:13+03:00"/>
	<event type="link" object_type="art" object_id="25761282" object_uuid="5c4775b2-57c8-11ea-8be9-3a5c218e6655" event_date="2020-03-10T16:55:03+03:00"/>
</partner_events>

Корневой элемент partner_events имеет атрибут @timestamp, содержащий текущее время сервера.
В ответе в partner_events содержится перечень событий с данными о статусе связи робота и книги/персоны/серии. Каждое событие представлено элементом event со следующим содержимым:

  • @type* – тип события, в результате которого произошло изменение статуса привязки робота к объекту. Возможные значения:
    • link – робот был привязан к объекту. Такое событие возникает на этапе создания или редактирования объекта с использованием запроса partner_object_update или вручную;
    • unlink – робот отвязан от объекта. Причем не важно убрали связь вручную либо с помощью запроса partner_object_forget;
  • @object_type* – тип объекта, для которого произошла смена статуса привязки к роботу. Может принимать следующие значения:
    • art – книга;
    • person – персона;
    • serie – серия;
  • @object_id* – внутренний идентификатор объекта на сервере ЛитРес. В зависимости от типа объекта, указанного в @object_type, это может быть идентификатор книги, персоны или серии соответственно;
  • @object_uuid* – уникальный идентификатор объекта на сервере ЛитРес. В зависимости от типа объекта, указанного в @object_type, это может быть идентификатор книги, персоны или серии соответственно;
  • @event_date* – дата и время события, в результате которого произошло изменение статуса привязки робота к объекту. Возвращается в формате «2014-11-07T16:21:02+03:00».

23 Коды ошибок

  • 102001 – попытка обновить «чужую» персону, которая не была создана партнёром;
  • 102002 – обновление персоны: не хватает данных о склонениях имени;
  • 102003 – обновление персоны: не хватает данных о полном имени персоны;
  • 102004 – обновление персоны: нет данных о URL, с которого необходимо загружать фотографию;
  • 102005 – обновление персоны, не удалось загрузить фотографию;
  • 102006 – обновление персоны: не хватает данных об имени, либо отчестве, либо фамилии;
  • 102007 – ошибка создания новой персоны;
  • 102008 – ошибка обновления персоны;
  • 102009 – ошибка обновления описания персоны;
  • 102010 – обновление серии: не передано название;
  • 102011 – попытка обновить не принадлежащую партнёру серию;
  • 102012 – попытка обновить не принадлежащее партнёру произведение;
  • 102013 – обновление произведения: передан невалидный UUID;
  • 102014 – обновление произведения: попытка связать произведение с другим, которое не принадлежит партнёру;
  • 102015 – обновление произведения: попытка добавить более одного агента;<todo>Удалить эту ошибку по факту изменения логики. Добавить новые ошибки, связанные с отсутствием или некорректностью параметра @owner;
  • 102016 – обновление произведения: попытка связать произведение с персоной, которая не создана партнёром;
  • 102017 – обновление произведения: попытка включить произведение в серию, которая не принадлежит партнёру;
  • 102018 – ошибка при обновлении произведения;
  • 102019 – ошибка при создании произведения;
  • 102020 – обновление произведения: ошибка при задании жанров;
  • 102021 – обновление произведения: попытка присвоить несуществующий тег;
  • 102022 – попытка загрузить PDF для книги, которая не принадлежит партнёру;
  • 102023 – загрузка PDF: файл не найден;
  • 102024 – загрузка PDF: неверная сумма SHA-256 файла;
  • 102025 – загрузка PDF: ошибка добавления файла к произведению;
  • 102026 – передан невалидный timestamp;
  • 102027 – проверка валидности запроса: не удалось получить сведения о самом партнёре;
  • 102028 – партнёр с переданным идентификатором (partner) не существует;
  • 102029 – неверная подпись;
  • 102030 – ошибка повторного использования timestamp. Для каждого из запросов используйте новый timestamp;
  • 102031 – не передан запрос;
  • 102032 – невалидный XML в запросе, либо несоответствующий схеме. Подробне см. в @error_message;
  • 102033 – произведение, для которого обновляется цена, не принадлежит партнёру;
  • 102034 – попытка загрузить FB2 для произведения, которое не принадлежит партнёру;
  • 102035 – загрузка FB2: не найден файл. Убедитесь, что FB2-файл обернут в ZIP-архив и передается методом POST через переменную file c типом содержимого «multipart/form-data»;
  • 102036 – ошибка загрузки FB2. См. подробное описание ошибки в @error_message;
  • 102037 – в запросе на получение обновлённых произведений неверно передан checkpoint;
  • 102038 – неверные данные в запросе на получение обновлённых произведений;
  • 102039 – при загрузке обложки передано не JPEG изображение;
  • 102040 – загрузка обложки: в параметре file передан НЕ файл;
  • 102041 – попытка загрузить обложку для произведения, которое не принадлежит партнёру;
  • 102042 – ошибка загрузки обложки;
  • 102043 – в запросе статистики (partner_stats) не переданы параметры «time_from», «from» или «to». Допустимы следующие комбинации этих параметров:
    • только «time_from»;
    • только «from»;
    • только «from» и «to»;
  • 102044 – некорректный формат параметров «from» и/или «to» в запросе статистики (partner_stats). Укажите даты в формате «ГГГГ-ММ-ДД»;
  • 102045 – в запросе статистики (partner_stats) одновременно переданы параметры «time_from», «from» и «to», хотя в запросе допустимы только следующие комбинации этих параметров:
    • только «time_from»;
    • только «from»;
    • только «from» и «to»;
  • 102046 – некорректный формат параметра «time_from» в запросе статистики (partner_stats). Укажите время в формате «ГГГГ-ММ-ДД ЧЧ:ММ:CC»;
  • 102047 – некорректное значение параметра «time_from» в запросе статистики (partner_stats). Допустимое значение должно быть в промежутке последних суток (24 часа от текущего московского времени);
  • 102048 – некорректный формат параметров «y» и/или «m» в запросе статистики (partner_final_stats). Год должен быть в формате «ГГГГ», а месяц (m) – «ММ»;
  • 102049 – в запросе статистики (partner_final_stats) указан не закрытый отчетный период (даты закрытия периодов уточняйте у менеджеров ЛитРес). Выберите другой месяц или воспользуйтесь запросом статистики по не закрытому периоду (partner_stats);
  • 102050 – в запросе редактирования карточки книги (partner_object_update) указан некорректный идентификатор правообладателя (art_to_update/@owner), определяющий набор ресурсов (сайтов, мобильных приложений и пр.), на которых будет размещаться книга;
  • 102053 – в запросе изменения описания книги (partner_object_update) в параметре request отсутствует или указан неверно уникальный идентификатор правообладателя партнера (update_object/art_to_update/@owner);
  • 102054 – ошибка eval при смене правообладателя;
  • 102055 – правообладатель недоступен данному роботу;
  • 102056 – произведение, для которого меняется правообладатель, не принадлежит партнёру;
  • 102057 – агент, привязанный к произведению, не доступен данному роботу;

  • 102058 – Unknown type '$ObjectType' – неизвестный тип объекта;

  • 102059 – Object with uuid '$UUID' and type '$ObjectType' does not exist or was not created by you – объект с таким uuid и типом не существует или был создан не Вами;

  • 102060 – General Samizdat API error – ошибка API Самиздат;

  • 102062 – присланный на загрузку файл имеет нулевой размер
  • 102101 – ошибка eval при обновлении персоны. Обратитесь к разработчику;
  • 102102 – ошибка eval при обновлении серии. Обратитесь к разработчику;
  • 102103 – ошибка eval при обновлении произведения. Обратитесь к разработчику;
  • 102104 – ошибка eval при загрузке файла PDF. Обратитесь к разработчику;
  • 102105 – ошибка eval при проверке валидности запроса. Обратитесь к разработчику;
  • 102106 – ошибка eval при изменении цены произведения. Обратитесь к разработчику;
  • 102107 – ошибка eval при получении списка тэгов. Обратитесь к разработчику;
  • 102108 – ошибка eval при загрузке FB2. Обратитесь к разработчику;
  • 102109 – ошибка eval при запросе обновлённых произведений. Обратитесь к разработчику;
  • 102110 – ошибка eval при загрузке обложки. Обратитесь к разработчику;
  • 102111 – ошибка приведения заголовка в соответствие с базой;
  • 102112 - непредвиденная ошибка на сервере;
  • 102114 - не найден арт по UUID, либо этот арт не принадлежит этому партнеру;
  • 102115 – в запросе создания/редактирования описания к книге указано не уникальное название произведения (@name). Измените название или проверьте правильность UUID;
  • 102116 – при запросе создания/редактирования персоны превышен лимит на количество не уникальных полных имен персоны (@full_name). Система позволяет создать только 5 одинаковых полных имен. Измените полное имя или проверьте правильность UUID;
  • 102117 – в запросе создания/редактирования серии указано не уникальное название серии (@name). Измените название или проверьте правильность UUID;
  • 102118 – ошибка eval при загрузке статистики (partner_stats). Обратитесь к разработчику;
  • 102119 – ошибка eval при загрузке статистики (partner_final_stats). Обратитесь к разработчику;

  • 102123 – в запросе данных о статусе привязки робота к объекту (partner_events) не переданы параметры «time_from», «from» или «to». Допустимы следующие комбинации этих параметров:

    • только «time_from»;

    • только «from» и «to»;

    • только «from»;

  • 102124 – некорректный формат параметров «from» и/или «to» в запросе данных о статусе привязки робота к объекту (partner_events). Укажите даты в формате «ГГГГ-ММ-ДД»;

  • 102125 – в запросе данных о статусе привязки робота к объекту (partner_events) одновременно переданы параметры «time_from», «from» и «to», хотя в запросе допустимы только следующие комбинации этих параметров:

    • только «time_from»;

    • только «from»;

    • только «from» и «to»;

  • 102126 – некорректный формат параметра «time_from» в запросе данных о статусе привязки робота к объекту (partner_events). Укажите время в формате «ГГГГ-ММ-ДД ЧЧ:ММ:CC»;

  • 102127 – некорректное значение параметра «time_from» в запросе данных о статусе привязки робота к объекту (partner_events). Допустимое значение должно быть в промежутке последних суток (24 часа от текущего московского времени);

  • 102128 – неизвестная ошибка про выполнении запроса данных о статусе привязки робота к объекту (partner_events). Обратитесь к разработчику;
  • 102130 – ошибка при загрузке FB3: книга не найдена или не принадлежит партнёру;
  • 102131 – не найден файл FB3;
  • 102132 – ошибка копирования FB3 во временное хранилище;
  • 102133 – внутренняя ошибка конфигурации SVN;
  • 102134 – ошибка постановки FB3 в релиз;
  • 102135 – ошибка eval при загрузке FB3;
  • 102136 – «черновиком» может быть только книга в формате fb2;
  • 102137 – параметр update_period разрешен только для «черновиков»;
  • 102200 – description не может содержать ссылки;
  • 102201 – annotation не может содержать ссылки;
  • 102202 – загрузка FB2, FB3, Cover: не совпадает SHA256 файла.
  • 102210 – попытка загрузить аудио архив для книги, которая не принадлежит партнёру;
  • 102211 – загрузка аудио файлов: файл не найден;
  • 102212 – загрузка аудио файлов: неверная сумма SHA-256 файла;
  • 102213 – загрузка аудио файлов: неправильное расширение файла, принимается mp3 файл или zip архив с mp3 файлами;
  • 102215 – указанная книга не является аудио книгой, вы не можете добавить к ней mp3-файл.
  • 102216 - вы больше не можете редактировать описание этой персоны, свяжитесь с АПО чтобы внести изменения. Вы по прежнему можете привязывать книги к этой персоне.
  • 102217 - значения атрибутов персоны некорректны;
  • 102218 - серия либо не принадлежит этому партнёру, либо не найдена по этому UUID;
  • 102219 - не у всех тэгов update_art_serie/serie указан атрибут action. либо атрибут action должен быть у всех тэгов serie, либо ни у одного;
  • 102220 - неверный формат art_id - должен быть цифровой;
  • 102221 - art_id отсутствует в базе;
  • 102222 - неверній формат valid_till - должен быть ISO-формат ( "2015-05-27T18:20:30+03:00");