Ошибка при загрузке обложки литрес

Когда вы загружаете книгу в ЛитРес: Самиздат, создается ее карточка в разделе Мои книги. Именно в этой карточке в дальнейшем должны происходить все действия с книгой от момента загрузки до ее публикации. После публикации в карточке книги будет указана информация о стоимости и будут размещены ссылки на книгу в ЛитРес и MyBook (чтобы вы могли поделиться ссылкой с читателями).
ВНИМАНИЕ! Если вы хотите внести изменения или загрузить другой файл (например, после корректуры), не удаляйте карточку книги!
После удаления карточки восстановить книгу можно будет только через обращение в поддержку.

На карточке книги, которая находится в работе, отображаются:

• название книги;

• имя автора;

• обложка книги;

• статус книги;

• кнопки «Редактировать», «Читать», «Удалить».

ВНИМАНИЕ!

Название произведения, имя автора и обложка книги отображаются только после того, как вы заполните вкладку «Сведения о книге» в редакторе карточки книги.

Статусы карточки книги

• Статус «Загружено» присваивается книге сразу после загрузки и успешной конвертации. Чтобы опубликовать книгу, нажмите кнопку «Редактировать» и заполните сведения о книге, загрузите обложку и выберите тип публикации.

• Статус «Ошибка при загрузке» присваивается, если во время конвертации файла после загрузки произошла ошибка. Вы можете заполнить сведения о книге в редакторе карточки книги, но не можете опубликовать ее. Чтобы опубликовать эту книгу на ЛитРес, необходимо исправить исходный файл и заменить его, и только после этого отправить на проверку модераторам для публикации.

• Статус «Книга возвращена на доработку модератором» присваивается, если после отправки книги на проверку у модераторов возникли вопросы к заполнению сведений о книге или к ее содержанию. Причины, по которым книга была отклонена, указываются в комментариях в редакторе карточке книги. Чтобы увидеть комментарии, надо нажать на кнопку «Редактировать». Рекомендации по заполнению данных будут на баннере в верхней части страницы:

• Статус «Книга на модерации» присваивается после того, как вы отправите книгу на проверку. В этом статусе книга находится в очереди на модерацию. Если вам требуется внести правки в сведения о книге или заменить файл, нажмите на кнопку «Отозвать». После этого книга вернется в статус «Загружено», и вы сможете внести необходимые изменения.

• Статус «В обработке» присваивается, когда модератор взял вашу книгу на проверку. Вы не можете вносить изменения, пока модератор не закончит работу с книгой. После проверки книга будет опубликована на ЛитРес и партнерских площадках или возвращена на доработку.

• Статус «Опубликована» присваивается после того, как ваша книга успешно прошла проверку модераторов и опубликована в каталоге ЛитРес и на партнерских площадках (площадки зависят от выбранного пакета публикации). В карточке книги при этом отображается статус электронной книги и статус книги, опубликованной по технологии печать по требованию (см. Публикация печатной книги). В поле «Магазины» отображаются только ссылки на книгу в ЛитРес и MyBook. Вы можете внести изменения в опубликованную книгу, не снимая ее с публикации, нажав на кнопку «Редактировать».

• Статус «Снята с публикации» присваивается после того, как вы нажмете на кнопку «Снять с публикации». Это может понадобиться, если по какой-то причине вы не хотите, чтобы ваша книга была размещена на витрине ЛитРес и других партнерских площадках.

ВНИМАНИЕ!

Партнерские площадки обновляют информацию об опубликованных книгах по своему графику, поэтому после снятия книги с публикации на ЛитРес она может быть размещена на партнерских площадках до 1 месяца.

1 Аннотация

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

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" 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.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 для создания/редактирования персоны;
  • 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 должно быть заполнено обязательно .
  Если персона не имеет фамилии, а использует только псевдоним или имя – оно указывается именно в @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), картинка должна быть квадратной и иметь размер не менее 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>. Пустые абзацы не допускаются. Размещение ссылок в description не допускается  (при попытке сервер вернет ошибку 102200 – см. Коды ошибок). 

Пример:

<?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»;
• @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;
• @valid_till – дата индивидуального окончания прав на данную книгу в формате «ГГГГ-ММ-ДД». При наступлении указанной даты книга автоматически полностью снимется с продажи. Также с помощью этого атрибута можно принудительно снять книгу с продажи, передав в нём текущую дату;
• @keep_on_sale – атрибут, указывающий, что книга должна остаться в продаже. Принимает значение =1. Если параметр не передан, то при обновлении данных книги, она будет снята с продажи;
• title-info/genre* – перечень жанров книги. Допустимые значения приведены в главе «жанры ЛитРес» в атрибутах @token. Для каждой книги должен быть определен хотя бы один такой жанр;
• title-info/annotation* – аннотация к книге. Должен содержать один или несколько абзацев или списков, каждый из которых должен быть обрамлен тегами <p></p>,<ul></ul>,<ol></ol>, элемент списка — <li></li>. Стили <b></b><i></i><u></u>. Пустые абзацы не допускаются. Размещение ссылок в аннотации не допускается  (при попытке сервер вернет ошибку 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.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) и отправка книги на модерацию

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

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

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

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

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

• 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.

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

Протестировать запросы загрузки можно с помощью тестового файла. Пример тестового файла для 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).

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

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

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

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

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

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

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

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

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

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

• 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 – ошибка приведения заголовка в соответствие с базой;
• 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-файл.

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" 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.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 для создания/редактирования персоны;
  • 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 сначала создается только описание персоны (ФИО, дата рождения, фотография и пр.), а её роль (автор, переводчик и т. д.) указывается уже в запросе создания/редактирования описания к книге.

Пример 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 должно быть заполнено обязательно .
  Если персона не имеет фамилии, а использует только псевдоним или имя – оно указывается именно в @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), картинка должна быть квадратной и иметь размер не менее 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>. Пустые абзацы не допускаются. Размещение ссылок в description не допускается  (при попытке сервер вернет ошибку 102200 – см. Коды ошибок). 

Пример:

<?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»;
• @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;
• @valid_till – дата индивидуального окончания прав на данную книгу в формате «ГГГГ-ММ-ДД». При наступлении указанной даты книга автоматически полностью снимется с продажи. Также с помощью этого атрибута можно принудительно снять книгу с продажи, передав в нём текущую дату;
• @keep_on_sale – атрибут, указывающий, что книга должна остаться в продаже. Принимает значение =1. Если параметр не передан, то при обновлении данных книги, она будет снята с продажи;
• title-info/genre* – перечень жанров книги. Допустимые значения приведены в главе «жанры ЛитРес» в атрибутах @token. Для каждой книги должен быть определен хотя бы один такой жанр;
• title-info/annotation* – аннотация к книге. Должен содержать один или несколько абзацев или списков, каждый из которых должен быть обрамлен тегами <p></p>,<ul></ul>,<ol></ol>, элемент списка — <li></li>. Стили <b></b><i></i><u></u>. Пустые абзацы не допускаются. Размещение ссылок в аннотации не допускается  (при попытке сервер вернет ошибку 102201 – см. Коды ошибок);
• title-info/title-relations/related-title – список логических связей с другими книгами, добавленными ранее через API. Например, если книга является второй в серии, то можно создать связь с первой книгой (предыдущим выпуском). Атрибуты:
  • @uuid* – уникальный идентификатор логически связанной книги. Такая книга должна быть заранее создана партнером, но не обязательно размещена в продажу;
  • @relation* – тип связи между книгами. Допустимые значения:
    • previous – предыдущий выпуск;
    • next – следующий выпуск;
    • translated_from – перевод с;
    • translated – перевод;
    • collected – сборник;
    • part – часть;
    • reedition – переиздание;
    • sequel – продолжение;
    • prequel – предыстория.
• title-info/item-relations/person* – список персон, связанных с книгой. Важно, чтобы к книге была привязана хотя бы одна персона (автор, составитель или кто-то еще). Атрибуты:
  • @uuid* – уникальный идентификатор персоны. Такая персона должна быть заранее создана партнером;
  • @relation* – роль персоны по отношению к книге. Допустимые значения:
    • author – автор;
    • translator – переводчик;
    • illustrator – художник;
    • compiler – составитель;
    • editor – редактор;
    • narrator – чтец.

  • @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.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) и отправка книги на модерацию

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

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

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

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

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

• 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.

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

Протестировать запросы загрузки можно с помощью тестового файла. Пример тестового файла для 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).

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

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

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

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

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

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

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

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

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

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

• 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 — выдать отчет только по одному правообладателю (может быть полезно, если робот обслуживает нескольких правообладателей), опциональный параметр.

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

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>

В ответе в 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 – ошибка приведения заголовка в соответствие с базой;
• 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 — вы больше не можете редактировать описание этой персоны, свяжитесь с АПО чтобы внести изменения. Вы по прежнему можете привязывать книги к этой персоне.

1. «Всё знает только Сталин.»

(Фарид Киреев.

Курс лекций по истории СССР)

2. «Чтобы знать, надо учиться.»

(Иосиф Сталин.

Речь на VIII съезде ВЛКСМ)

В прошлом году я провел две «Беседки» на тему «Как издать электронную книгу».

Там я попытался рассказать об общих проблемах электронных публикаций и ответил на некоторые вопросы.

Но общность проблем и интерактивность материала слегка размыли суть вопроса.

В последнее время ко мне обращаются друзья с просьбой помочь советом по размещению книг на самой крупной русскоязычной торговой площадке Литрес.

Всплывающие слоганы «Один клик до книг!» являются мифом.

На самом нужен сто один.

В один клик не удается разместить произведение даже мне, работающему в направлении несколько лет и самостоятельно опубликовавшему (на данный момент) почти полсотни книг.

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

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

Подумав об этом, я решил более подробно описать процесс размещения книги на ресурсе Литрес.

В настоящий момент существуют 2 актуальные площадки для размещения электронных книг: Литрес и Ридеро.

(Остальные второстепенны или небесплатны.)

О плюсах и минусах каждой я уже говорил, сегодня коснусь только Литреса.

Эта площадка имеет максимальный охват партнеров (электронных магазинов) и – как следствие – с нее идет довольно приличное роялти.

Чтобы эффективно работать с Литресом, нужно знать как общие моменты, так и некоторые мелочи, которые выявляются лишь при достаточно интенсивной работе с книгами.

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

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

Но, надеюсь, части целого будут понятны.

I

Существуют 2 способа работы с Литресом: через менеджера и самостоятельно, по системе selfpub(самиздат).

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

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

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

Эта система мне кажется оптимальной.

Решив опубликовать книгу по системе «Самиздат», надо сразу определиться, на какой основе вы хотите ее размещать.

При бесплатном размещении книгу будут свободно скачивать со всех партнерских площадок. Такая публикация – это «раздарить воспоминания о бабушке в деревне». Кроме того, на обложку книги, идущей по бесплатной лицензии, ставится штамп «Самиздат», это вызывает мысль о низком уровне произведения.

(Самиздат ставится в тегах, но одно дело – тег, а другое – печать на обложке!)

Платное размещение требует заключения договора с Литресом и идентификацию автора. Для этого приходится предоставлять свои данные и фотографию с паспортом в руке. Многие боятся «засвечивать» реквизиты – в этом вопросе, конечно, каждый выбирает сам.

От себя скажу, что с Литресом сотрудничаю с 2006 года и никаких неприятностей не имел.

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

Ясное дело, что фото с читаемым паспортом н различимым лицом (хоть селфи, хоть зеркальные селфи, хоть сделанные кем-то другим) почти всегда достойны стенда «Их разыскивает милиция». Но отправив, даже вы их больше не увидите. Эти снимки будут лежать в материалах вашего аккаунта, их смотрит только юрист, причем один раз.

Фотографии для своей страницы на книжном ресурсе – это другое дело. Они ставятся через систему обратной связи, вы пишете письмо, вас просят прислать хорошее фото нужного формата. Тут уже, конечно, имеет смысл постараться, но сейчас разговор о другом.

После идентификации вы будете иметь право на получение роялти с продаж.

Процент указан в каждом типе лицензии, статистика по совокупности книг доступна с момента публикации, деньги можно вывести 1 раз в квартал (при достижении пороговой суммы 1 000 рублей) на банковскую карту, которую вы указываете перед выводом. Раньше все происходило мгновенно, сейчас Литрес передает заказ платежной системе SolarStaff и выплата занимает 3-4 дня. Впрочем, тонкости поймете сами, когда дело дойдет до вывода роялти.

Литрес удерживает налоги, но – насколько я знаю – отчислений в пенсионный фонд не делает, т.е. ваши приработки не выявляются.

Также отмечу, что идентификация происходит после публикации первой книги – перед тем, как будет выбран тип лицензии и установлена цена.

Так что утром – книга, вечером – договор, пора перейти к делу.

II

Итак, вы решили опубликовать книгу. С чего начать?

Здесь опять сталкиваемся с альтернативой (кажется, последней из всех).

Книга может быть чисто электронной или иметь печатную версию по системе on—demand(печать по требованию).

Что означает последнее, вероятно, знают все. Но я-таки поясню.

Печать по требованию – это не заказ тиража, а возможность любому покупателю заказать хоть 1 экземпляр в бумажном виде.

Такая система не требует авторских вложений, все оплачивает заказчик. Ясное дело, что 1 экземпляр своей книги можете заказать и вы сами – но она будет стоить дороже, чем при печати в тираже.

Раньше возможность печатной версии была доступна только при безлимитной лицензии – т.е. в случае, если вы отдаете Литресу эксклюзивные права и не можете опубликовать книгу где-то еще.

С недавнего времени печатный вариант стал доступен и при базовом пакете.

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

Просится вопрос: нужна ли печатная версия электронной книге?

Однозначно не могу – как говорили герои Довлатовской «Зоны», на этот счет существуют разные мнения.

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

(Несколько случаев, когда заказывали знакомые или герои мемуаров, не считаются.

Абстрактный читатель печать по требованию не использует.)

Но зато книге с печатной версии присваивается ISBN, вот он виден на сайте книги:

Подчеркну, что процедура бесплатна (если вы печатаете книгу в каком-то издательстве, то за номер с вас всегда возьмут дополнительные деньги, 1,5 – 2 тысячи с тиража.

Также печатная версия имеет на 4-й стороне обложки штрих-код:

(К сожалению, не могу продемонстрировать в физическом виде, потому что своих книг не заказывал.)

То есть, несмотря на «самиздатность», ваша книга будет иметь пристойный вид.

Однако при определенных плюсах есть и некоторые минусы.

Объективным является то, что чисто электронную книгу можно корректировать хоть каждый день.

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

Книга с печатной версией имеет 90-дневный «карантин» на перепост. При этом в личном кабинете вы будете видеть количество дней, оставшееся до возможности внесения изменений:

Субъективным минусом являются более строгие технические требования, предъявляемые к оформлению.

Их я освещу далее. В процессе рассказа буду всякий раз отмечать моменты, характерные для книги с печатной версией.

Повторю еще раз, что выбор в пользу чисто электронной или «полупечатной» книги остается за автором.

Его лучше сделать до начала процесса, чтобы избежать лишней работы потом.

Вот теперь наконец приступаем к чисто техническим вопросам.

III

Работа с книгой начинается с ее файла.

90% времени занимает его подготовка, в той же степени зависит успех процесса.

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

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

Работа по приведению никуда не годного текста в соответствующий вид довольно кропотлива. Это не верстка макета, а переформатирование файла — что, как правило, труднее.

Она стоит достаточно серьезных денег.

Самым близким друзьям я делаю все «за так», но ресурсы времени и здоровья небезграничны.

Все мы пишем, как привыкли.

И надо сказать, что привычки не всегда полезны

Несмотря на существование эргономичного офисного пакета, есть авторы, которые рвутся в открытый космос.

(Это я понял когда составлял сборник «Новые имена-4».

Кто-то прислал файлы .odt (WordPad), которые для перевода в человеческий формат требуют промежуточной конвертации через RichText(.rtf).

Кто-то прислал стихи в теле письма (формат .msg), из которого приходилось выкопировать текст в новый документ.

В общем, нет предела авторской… изобретательности.

Хотя есть простой MicrosoftOfficeWord, который является идеальной программой для работы писателя.)

Входной формат Литреса — .docx, т.е. файл Ворда версий начиная с 2007.

(Можно также сразу загрузить файл электронной книги, но этот вариант я не обсуждаю.

Электронные форматы – не рабочие, а выходные, в них никто не пишет.)

До 2007 Ворд по умолчанию сохранял тексты в формате .doc.

Эти форматы взаимно конвертируемы с помощью самого же Ворда.

Использование их зависит от версии установленного Офиса.

Лично я работаю в MSW2003, поскольку начиная с 2007 интерфейс имеет «ленточное» меню, неудобное для писателя, которому нужен минимум функций при максимальной скорости.

Ворд 2003 файлы .docxобрабатывает медленно, лучше оперировать с .doc, потом конвертировать.

При работе в Ворде 2007 проблем нет.

Иногда бывает, что вы сформировали файл книги в формате .docx, но появляется необходимость вставить фрагмент, написанный в ранней версии (.doc).

Этого делать нельзя.

Текст вольется в общий, вы не заметите разницы. Но при переводе в формат электронной книги вставка может исказиться.

Если вы хотите вставить в документ .docxкусок, созданный в предыдущей версии, то надо сначала перевести его в .docx(выделить нужное, создать новый документ, скопировать туда, потом сохранить как «Word 2007 Document») – и только после этого вставлять куда надо.

Итак, повторю еще раз.

Файл книги, которую вы загружаете на Литрес, должен иметь формат .docx — т.е. документ Ворд 2007 — иного интерфейс «не видит» при загрузке.

Но сам по себе файловый формат еще ничего не решает.

При некорректной структуре текст может быть не воспринят системой (возникает сообщение об ошибке конвертации).

Также может оказаться, что после конвертации книга примет некорректный вид и ее придется переделывать.

Чтобы не возникло сбоев, надо сразу готовить все как можно правильнее.

(Оговорюсь, что вопросы грамотности: ошибки орфографии и пунктуации, неправильные конструкции типа «…?», «!…» или «!,.», пробелы перед вопросительным и восклицательными знаками и пр. – я оставляю в стороне.

Это входит к компетенцию корректора и не имеет отношения к техническому сопровождению е-публикаций.)

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

Файл электронной книги представляет собой текстовый массив без разбивки на страницы: каждый е-ридер отображает их по-своему.

В тексте не допускается полужирный шрифт в больших объемах. На самом деле, даже если пропустит модератор, он выглядит тяжело.

Нельзя включать в Ворде опцию переноса слов: из-за отсутствия понятия «страница» в е-форматах разорванные слова окажутся посреди строк, это очень плохо.

Если в тексте есть ссылки (например, переводы иноязычных слов), то их надо оформлять через меню «Вставка – Ссылка – Сноска», в этом случае примечания всегда будут внизу страницы. При переводе в электронный формат они тоже отобразятся корректно.

«Кустарные» сноски типа ручной вставки в текст недопустимы.

Изначально текст должен иметь формат абзаца (Меню «Формат – Абзац») с выравниванием по ширине, отступом 1,25 см и одинарным интервалом:

Текст, отформатированный таким образом, правильно отображается на е-ридерах.

Если у вас установлен этот шаблон, то все нормально.

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

Процедура делается в несколько этапов.

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

Вот что надо сделать для перевода текста в правильный формат

1. Открыть меню «Выделить все – Очистить – Форматы»:

Все форматы пропадут, текст выключится влево.

После этого скопировать выделенное в буфер обмена.

2. Создать новый документ блокнота.

Многие не знают, как это сделать. Программа Блокнот (NotePad – не путать с WordPad!) находится в стандартных программах, открывается через меню «Пуск»:

3. Создав документ блокнота, вставить в него «очищенный» текст из Ворда, затем нажать в Блокноте «Выделить все – Копировать», создать новый файл Ворд и вставить туда.

В полученном тексте тоже выделить все, потом открыть меню «Формат – Абзац» и установить указанные параметры:

После этого установить шрифт Times New Roman и кегль 14 (лучше всего).

4. Если изначальный файл был совсем плох, в получившемся могут остаться лишние отступы в начале абзацев:

Их нужно удалить по всему тексту вручную.

5. Также в тексте могут быть разрывы строк внутри абзацев – неразличимые в оригинале, разбивающие абзацы после форматирования.

Их тоже придется удалить – и тоже вручную.

Текст как таковой будет иметь правильный формат, но работа над ним еще не окончена.

При очистке форматов исчезают сноски. В правильно отформатированный документ их нужно будет вставить заново.

Кроме того, если текст неоднороден по стилю (имеются цитаты, стихи, и т.д.), то неоднородности следует привести к единообразию с помощью инструмента «Копировать формат»:

То есть все цитаты должны выглядеть одинаково, все стихи – одинаково.

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

Уверен, вы утомились даже от описания самой процедуры.

А представьте, что вам надо привести в порядок книгу страниц на 150!

Надеюсь, станет понятно, почему такая работа стоит немало.

Конечно, невыровненный формат несмертелен.

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

Но на е-ридере ваша книга будет похожа на…

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

После того, как вы привели свою книгу к описанному выше формату, для электронной публикации она теоретически готова.

Но практически – не всегда.

IV

Не устаю повторять, файл е-бука представляет аморфный текстовый массив, который каждый е-ридер по-своему делит на страницы

Если книга не разбита на составляющие (части, главы и т.д.), то ее подготовка на самом деле закончена.

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

Для этого придется назначить стили заголовков.

Это делается через меню «Формат – Стили и форматирование».

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

Названия разделов, которые необходимо вывести в оглавление, должны иметь стиль «Заголовок».

Цифры 1-2-3 означают положение в иерархическом дереве, конкретный вид заголовка вы устанавливаете на свой вкус.

Можете дать его любым шрифтом (независимо от шрифта текста), любым кеглем, курсивом, полужирным, подчеркнутым, по центру или с выключкой влево-вправо, и т.д.

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

Не допускаются заголовки, набранные заглавными буквами, это смотрится утомительно.

При публикации чисто электронной книги к структуризации текста стоит относиться без фанатизма.

На е-ридере оглавление выносится вперед текста и позволяет при начале чтения открывать нужную главу.

В процессе е-ридер открывает книгу на той странице, где она была закрыта, поэтому оглавление некритично.

Бесспорно, что структуризация необходима для сборника рассказов, где каждое отдельное произведение самостоятельно.

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

При публикации книги с печатной версией все обстоит иначе.

Строгость требований к структуре обусловлена объективными факторами.

Печатная книга – это совокупность отдельных файлов в графическом формате .pdf(набор «диапозитивов», с которых идет печать в типографии).

Разбивка производится конвертером Литреса и если входной текст не структурирован, там появляются «висячие» заголовки разделов.

То есть номер главы может оказаться внизу одной страницы, а сама глава начнется на следующей. Это недопустимо.

Модератор этого не пропустит: вернет на доработку, снабдив ссылкой на скриншот.

Но устранить «висячий» заголовок правкой (добавлением или удалением строк, разбивкой абзацев и пр.) невозможно. Вы «развесите» один, «повиснет» другой, процесс не приведет к успеху.

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

Вот пример того, как это нужно делать.

Иерархия разделов видна через меню «Вид – Структура»:

Здесь «Книга» имеет стиль «Заголовок 1», «Часть» — «Заголовок 2», глава, обозначенная только номером – «Заголовок 3».

Заголовки в структуре помечаются контурным крестиком, их места в иерархии видны по величине отступа.

(Эта «ступенчатость» отображается только в режиме структуры!

В самом тексте заголовки стоят согласно оформлению.)

Если разделы имеют правильные стили заголовков, то проблем с печатной книгой не возникнет.

Но отмечу, что слишком глубокое структурирование нежелательно.

Процедура назначения несколько утомительна, но не в этом дело.

В рекомендациях Литреса сказано, что не рекомендуется использование заголовков глубже 4-го уровня.

На самом деле уже 3-й уровень не всегда корректно отображается в электронной книге.

(Я подчеркиваю значение этого факта потому, что Литрес – это электронная площадка и вид электронной книги приоритетен даже при наличии печатной версии!

Свои книги я перевел на лицензию с печатным вариантом исключительно ради того, чтобы иметь ISBN.

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

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

На Литресе книги покупают для чтения на е-ридерах, поэтому вид электронной версии должен быть безупречным!)

Оглавление электронной книги видно при публикации (я его покажу), иерархия различима по значкам: это контурные или заштрихованные кружки, квадраты и т.д.

Но надо сказать, что при конвертации входного файла часто возникает путаница, в которой – признаюсь честно – я не всегда могу разобраться.

Однажды я несколько дней мучился над книгой дневниковых записей, где содержание требовало разделения на годы, места, даты, персоналии… Добиться корректного оглавления е-бука мне не удалось, в конце концов я махнул рукой и оставил все как есть, рассудив, что желающий прочитает, а нежелающий и не посмотрит.

Иногда мне кажется, что конвертация текста на Литресе идет по стохастическим законам.

О чем-то подобном сорок с лишним лет назад говорил член нашего клуба, мой нынешний коллега, бывший учитель технического перевода с английского языка Владислав Леопольдович Левитин:

— Техника живет по своим законам. Возьми, к примеру, авиационный двигатель. Будет какой-нибудь патрубок прямым – не заведется. Сделай его изогнутым – заработает. А почему, никто не знает.

То же происходит с иерархией оглавления.

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

V

Ну что ж, вопросы подготовки файла книги освещены, теперь пора перейти к самой публикации.

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

Готовясь к написанию статьи, я делал снимки экрана и сейчас предлагаю пошагово проследить процесс от начала до конца.

Начать нужно с нажатия вот на эту кнопку в личном кабинете:

Если кабинета еще нет, он возникнет, едва вы приступите к публикации, зайдя в систему «Самиздат» как неизвестный автор.

Там она называется «Загрузить книгу или черновик».

Дальше все идет точно так же.

Что такое черновик?

Это интерактивная возможность писать книгу прямо на ресурсе.

Лично я считаю его вариантом блогерства, не имеющим отношения к литературной деятельности.

Такой не рассматриваю, деталей не знаю, касаться не буду.

Мы публикуем готовую книгу, а не черновик.

После нажатия появится окно загрузки:

Дальше надо перетащить мышью или нажать «Загрузить файл» и найти на компьютере папку с текстом.

После того, как выбран файл и нажато «Открыть» в системном окне, начнется загрузка, а на странице кабинета появится такая запись (если книга не первая, она будет в самом низу):

Сообщение о конвертации пульсирует, обложка появляется стандартная Литресовская (на данный момент это брызги прибоя), на нее не нужно обращать внимания.

Если все пошло криво, вверху страницы появится сообщение об ошибке конвертации на розовом фоне.

Придется возвратиться к разделу IIэтой статьи и заново форматировать файл.

Если все нормально, то вид записи изменится вот на такой:

Стандартная обложка исчезнет, кодовый номер книги (в данном случае 6194) останется.

На него не нужно обращать внимания, это промежуточный момент, отражающий регистрацию новой единицы на Литресе.

Теперь надо нажать кнопку «Редактировать»:

На дисплее появится карточка книги

Теперь начинается конкретный процесс публикации.

Меню в верхней части карточки имеет четыре закладки.

В принципе можно переключаться с одной на другую и обратно, это не влияет на результат.

Но при отсутствии опыта рекомендую действовать строго в том порядке, как я тут показываю.

Иначе где-нибудь что-нибудь пропустите, система начнет выдавать сообщения об ошибках, процесс пойдет по кругу и вы не найдете концов.

Первой открывается закладка «Сведения о книге».

Кнопка «Загрузить другой файл» вам понадобится при перепосте книги (или если придется править оглавление), сейчас она вам не нужна.

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

Оно должно соответствовать тому, которое будет на обложке:

Автора надо указать один раз, в следующих книгах он будет возникать автоматически.

Если при регистрации аккаунта вы укажете себя с отчеством, то возникнет альтернатива: автор с ФИО.

Рекомендую отчества не указывать: в литературном авторстве они выглядят непрофессионально.

Но, ясное дело, у каждого свой вкус.

Есть люди, которые даже на портале проза.ру не могут обойтись без ФИО.

Следующим этапом идет заполнение данных о книге:

Наиболее важным моментом является аннотация.

Вы видите, что, помимо содержательной части, я дал жанровое предупреждение и указал копирайты.

Это необязательно, но мне так удобнее.

В 2019 году на Литресе началась охота за нарушителями авторских прав, прежде всего во внешнем оформлении книг.

Если вы используете обложку из Литресовского набора, ни о чем беспокоиться не нужно.

Если вы делаете конструктором из своего фона, модератор попросит указать авторство снимка.

Как это делать в тех или иных случаях (фото скачано на бесплатном стоке, куплено на платном, и т.д.), я не знаю, поскольку интернетскими источниками не пользуюсь.

Это придется уточнить, написав в поддержку по обратной связи, вам ответят.

Сам я использую свои снимки. Если беру работу кого-то из друзей, указываю его (согласовав). Если фото из школьного или студенческого архива и я не имею понятия, кто его делал, то пишу «фото Петра Сидорова» — никто еще ни разу не привязался.

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

В случае, когда вы хотите опубликовать на Литресе книгу, где-то уже изданную, и использовать ту обложку, придется оговорить согласие издательства — тоже через обратную связь.

Издательству обычно все равно, но модератор потребует отписки.

Нюансы работы с аннотацией этим не исчерпываются.

Допустимый ее размер – 1000 символов, но текст такого объема, данный сплошным массивом, нечитаем.

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

У электронной книги это не имеет значения, аннотация может занять хоть всю 4-ю страницу обложки.

Печатная имеет штрих-код. Если он перекроет аннотацию, книгу вам вернут – то есть будьте готовы что-то изменить или сократить.

С аннотацией, я полагаю, все ясно.

Смотрите поля, которые выделены ниже.

Дата написания имеет формат ДД.ММ.ГГГГ.

Даже если вы публикуете книгу, написанную 10 лет назад и доведенную до новейшего релиза (что у меня бывает часто), лучше поставить текущую дату.

Иначе книга на вашей странице попадет в раздел «2010 год» и ее не станут читать, подумав, что она старая.

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

В поле «содержит — не содержит нецензурную брань» надо сказать правду. Если вы соврете, а брань есть, Литресовский автофильтр ее выявит и метку на книгу все равно поставят.

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

То есть, если указать «содержит», вручную рейтинг уже не меняется.

Разобравшись с этими полями, надо опуститься ниже и определить жанровую принадлежность.

Проще всего нажать «Показать все жанры», развернуть и выбрать по одному (до 3 позиций) жанры, к которым может быть отнесена ваша книга.

Жанры следует выбирать серьезно: согласно им читатель будет видеть книгу в разделах главной страницы Литреса.

Это делается вот так:

После жанров нужно установить теги для поиска в Интернете.

Максимальное количество тегов равно 5, «Самиздат» устанавливается автоматически: есть если вы указали все 5 тегов сами, то один заменится, причем неизвестно какой.

Поэтому стоит задать 4, тогда ничего не исчезнет.

Теги на Литресе устанавливаются иначе, чем здесь.

Вы не можете создать новый, можете лишь выбрать из имеющихся.

Процесс идет следующим образом.

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

Если ничего не открылось, значит, ваш тег отсутствует и его следует сформулировать как-то иначе.

По заполнении всех полей внизу вы увидите предложение:

Такие будут возникать на всех вкладках.

Если все нормально, как заполнены формы, надо нажать «Сохранить» и идти дальше.

(Если нет – исправить и сохранить.)

После завершения работы с первой вкладкой надо перейти на вторую:

На вкладке «Лицензия и цена» выбирается тип лицензии:

Как только вы нажмете «Выбрать», кнопка станет зеленой и в окошечке слева наверху можно поставить галочку «С печатной версией» — оно тоже позеленеет:

Далее надо определить цену.

На Литресе они имеют фиксированную сетку: открывается разворачивающийся список.

Выбирается цена электронной книги, цена печатной рассчитывается автоматически.

Какую цену поставить?

Это решать вам.

По своему опыту скажу, что слишком дорогие (дороже 200 рублей) и слишком дешевые (дешевле 90) не покупаются. Оптимальный интервал цен 109-176:

Дальше вы должны перейти на вкладку «Обложка».

Поскольку я работаю только со своими обложками, то показываю этот пример.

(Работа с шаблонами и фонами достаточно проста, надо нажимать «Изменить» и «Добавить» и выбирать из того, что предложено.)

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

Нажав окно «Своя обложка», надо найти ее на компьютере и загрузить:

После этого вы увидите обложку так, как она будет выглядеть.

Значки останутся на месте.

Они могут мешать: закрывать изобразительные элементы или текст, это плохо.

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

Положение обязательных значков в некоторой степени подлежит коррекции – хотя этого не описано в рекомендациях Литреса, приходится выяснять самому!

Если значки мешают, надо подняться к окну «Шаблоны» и нажать «Изменить»:

Что такое шаблоны?

По существу это инструмент конструктора обложек: он позволяет выбрать стиль плашки с надписью (именем автора и названием книги), которая накладывается на фон (ваш пустой или Литресовский из набора).

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

Вот посмотрите, как это открывается.

На плашки не нужно обращать внимания, просто переключайте вариант за вариантом и слева на большой картинке будете видеть положение значков:

Разнообразие, конечно, не очень большое, но значки удается сместить выше или ниже, это обычно помогает.

Вот как я перенес значки в описываемой книге, стало лучше, так они меньше мешают восприятию:

С 1-й страницей обложки мы разобрались.

Если книга чисто электронная, то можно идти на последнюю вкладку (сохранив изменения!).

Если вы допускаете электронный вариант, то нужно сделать еще три простых шага.

Сначала надо выбрать цвет текста и цвет фона:

Они устанавливаются автоматически по каким-то общим соображениям согласно гамме обложки, но мне такой вариант не нравится, я корректирую на свой вкус.

Цвет фона (по сути, цвет 4-й стороны обложки) лучше всего установить через печатный вариант. Это можно сделать бесступенчато, точно так же, как в Фотошопе:

Цвет текста выбирается по соответствующей кнопке, там тоже все просто.

Последним при подготовке вида печатной книги идет заполнение корешка.

Если книга имеет достаточную толщину (что зависит от количества страниц), на корешке появятся поля «Имя автора» и «Название»:

Их надо заполнить.

После этого еще раз посмотреть на обложку в целом.

Если все нормально, нужно сохранить изменения и перейти на последнюю вкладку «Публикация».

Там уже ничего не меняется, только проверяется.

Прежде всего надо нажать кнопку «Читать fb2», чтобы увидеть, как будет выглядеть ваша электронная книга для читателей:

Этой проверкой нельзя пренебрегать.

Как я уже говорил, конвертация в файл е-бука не всегда идет корректно.

Лучше сразу посмотреть, что получится, чем увидеть свою книгу в магазине и схватиться за голову.

(Что особенно актуально, если вы публикуетесь с печатной версией и вам будет установлен 90-дневный «карантин» на перепост.)

Сверху вы увидите аннотацию.

Она может исказиться и ее надо просмотреть.

Ниже идет оглавление.

То есть те отметки разделов, которые читатель будет нажимать на е-ридере для перехода.

Описываемая книга имеет простую неразветвленную структуру, тут все получилось корректно:

Оглавление нужно прочитать очень внимательно.

В спешке при форматировании файла можно пропустить назначение стиля какому-нибудь разделу, и в оглавлении за 4-й главой пойдет 6-я, а 5-я останется необозначенной.

Это, опять-таки, несмертельно.

Но оглавление – лицо книги, и если оно сделано с ошибками, то и к автору возникает соответствующее отношение.

Я не шучу.

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

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

При слишком сложной иерархии работа заставит вас вспомнить сказку про белого бычка.

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

Если с оглавлением все в порядке, советую просмотреть всю книгу до конца на предмет некорректностей в тексте.

Я уже говорил при конфликты разных версий Ворда при конвертации документа.

Когда я делал первые шаги в электронных публикациях, приходилось компоновать сборник из рассказов, набранных в разное время, а потом с изумлением обнаружить, что некоторые из них в е-буке отобразились жирным шрифтом от начала до конца.

Все это лучше исправить до публикации, чем после.

Можно посмотреть и вариант в формате .pdf.

Но «пдф» нужен только при печатной версии.

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

После этого остается нажать кнопку «Отправить на модерацию» и облегченно вздохнуть:

Теперь остается только ждать.

Модерация на Литресе нестабильна: иногда книги держат по 3 недели, иногда проверяют за 3 дня.

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

Посмотрите на эти книги в моем личном кабинете:

Обе находятся в работе, но «Тот самый снег» (после перепоста) стоит в очереди на модерацию, его можно отредактировать еще раз.

А «Маленький гарем» уже проверяется, его больше править нельзя.

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

Только халтурщик работает по схеме «написал – издал – забыл».

Даже повесть в 5 листов невозможно начать с нуля и довести до совершенства за 2 месяца.

Нормальный писатель работает непрерывно, но не спеша.

Написанное требует «отлеживания», а потом как минимум двух правок: содержательной и стилевой.

Вордовский формат – рабочий, он скрадывает погрешности.

Качественно оценить собственную книгу можно только в издательском или электронном формате.

Поэтому произведения стоит опубликовать, потом перечитать и поправить через 3 месяца – хотя бы один раз.

Литрес это позволяет сделать.

* * *

В этой статье я постарался помочь всем, кто хочет опубликовать свою электронную книгу, но еще не умеет это делать.

Ясно, что я не мог осветить все нюансы, дал общую схему.

На возникающие вопросы всегда готов ответить.

И желаю удачи всем!

Как разместить книгу на ЛитРес

Шаг 2. Загрузите файл в DOCX или FB2 (специальный формат для электронных книг).

Шаг 2. Загрузите файл в DOCX или FB2 (специальный формат для электронных книг).

Шаг 4. Выберите способ распространения книги. Уже знакомые нам тарифы + счетчик того самого роялти для каждого из вариантов.

Шаг 4. Выберите способ распространения книги. Уже знакомые нам тарифы + счетчик того самого роялти для каждого из вариантов.

Шаг 5. Загрузка или создание обложки.

Шаг 5. Загрузка или создание обложки.

Шаблонов не много, вариантов для фона — тоже. Если честно, то все они слишком уж простенькие.

Шаблонов не много, вариантов для фона — тоже. Если честно, то все они слишком уж простенькие.

Вот пример, собранный за одну минуту из фона и шаблона:

Вот пример, собранный за одну минуту из фона и шаблона:

Шаг 6. Финальная проверка и подготовка к публикации

Шаг 6. Финальная проверка и подготовка к публикации

После того, как книга загружена — она уходит на модерацию. Только после проверки (первая занимает в среднем 7 дней) она появится в продаже, либо будет возвращена на доработку.

После того, как книга загружена — она уходит на модерацию. Только после проверки (первая занимает в среднем 7 дней) она появится в продаже, либо будет возвращена на доработку.

Также сообщения о сбоях есть в городах:
Видное, Московская область; Симферополь, Республика Крым; Мурманск, Мурманская область; Кызыл, Тува; Рязань, Рязанская область; Екатеринбург, Свердловская область; Мама, Иркутская область; Уфа, Башкортостан.

Подсказки? Разочарования? Обсуждаем проблемы сервиса с другими посетителями сайта: