Public : Интерфейс подключения партнеров к книжному магазину «ЛитРес»

Created by Кристина Курашова, last modified by Илья Барышев on Aug 17, 2021
Версия документа1.105
Дата последнего обновления01 июня 2020 г.
Адрес постоянного размещенияhttps://docs.litres.ru/x/goh8

Аннотация
ЛитРес предлагает партнерам возможность легально торговать электронным контентом несколькими способами:

  1. Схема №1: полностью самостоятельно. При этом партнер оперативно получает от нас список новинок (см. 1. Интерфейс получения списка обновлений), файлы книг (см. 2. Интерфейс получения файла книги) и отдает нам статистику продаж (см. 3. Интерфейс отдачи статистики продаж партнерами). Схема работает только для электронных текстов – мультимедиа-контент (аудиокниги и др.) на условиях этой схемы недоступен. Учтите, что список произведений, допускающих полную передачу, ограничен. Фактически, от трети до половины ассортимента будут вам недоступны при данной схеме.
  2. Схема №2: с каталогом на стороне партнера, но с отдачей файлов с сервера ЛитРес. При этом партнер должен подключиться к нашему списку новинок (см. 1. Интерфейс получения списка обновлений) и системе уведомлений (см. 4. Интерфейс уведомлений ЛитРес о партнерских продажах). Биллинг работает на стороне партнера, а партнер безналом расплачивается с ЛитРес. Подключение по этой схеме допускает продажу мультимедиа-контента.
  3. Схема №3: с каталогом на стороне ЛитРес. При этом партнер должен только разработать дизайн или готовый набор xslt для нашего «движка», а все прочие работы выполняются на нашей стороне. Партнер при этом занимается исключительно раскруткой своей площадки за определенный процент от продаж. При данном подходе весь каталог ЛитРес, включая мультимедиа-контент, автоматически доступен партнеру.

Содержание

Общие замечания по работе партнеров

  • Этот документ описывает исключительно техническую сторону взаимодействия между ЛитРес и партнерами. Юридические, организационные и договорные вопросы решаются отдельно. Например, из того, что некий способ подключения существует, не следует, что вы сможете им воспользоваться. Для обсуждения условий партнерского подключения обращайтесь на litres@litres.ru.
  • Взаимодействие партнера с ЛитРес подразумевает, что ЛитРес не только оперативно отдает партнеру контент, но и автоматически уведомляет партнера о необходимости удалить или обновить контент. Если партнер своевременно не выполнит запрошенные процедуры удаления/обновления, он будет самостоятельно отвечать перед правообладателями. Продажа произведений, права на которые были отозваны, является пиратством.

Общая информация по сервисам ЛитРес для партнеров

  • Все текстовые данные передаются и обрабатываются в кодировке UTF-8. В том числе это касается вычисления SHA.
  • При взаимодействиях используется протокол HTTPS. При всех запросах к серверам ЛитРес методы GET и POST взаимозаменяемы, поддерживается HTTP 1.1.
  • Дата и время, при отдаче в XML или при передаче на сервер в виде параметров запроса, всегда подразумеваются в формате ISO (2008-10-08 13:29:51) и соответствуют московскому времени.
  • Для всех дробных чисел (к примеру, для цен) в качестве разделителя дробной части используется точка. Число 15,50 является некорректным, а 15.50 и 15.5 являются корректными.
  • Все цены указываются в рублях, любые конвертации при работе партнера с другими валютами должны осуществляться на стороне партнера предпочтительно по курсу Центробанка РФ с отклонениями в пределах 5%.
  • В XML, помимо описанного в документации содержимого, может размещаться, добавляться и удаляться неограниченное и нерегламентированное содержание – узлы, текст и атрибуты. Софт на стороне партнера должен корректно отбрасывать и обрабатывать ситуации, при которых, например, в документации описана структура <a b="c"><d/></a>, а фактически возвращается <a b="c" y="x" s="z"><i/><d/><m>text</m></a>. Атрибуты и параметры, которые вас интересуют, останутся по прежнему адресу a/@b и a/d, это мы гарантируем, но дополнительное содержимое может (и будет) появляться и пропадать. Будьте к этому готовы.

1 Интерфейс получения списка обновлений

Для получения списка обновлений используется URL:
https://partnersdnld.litres.ru/get_fresh_book/
Этот интерфейс возвращает как, собственно, новые книги, так и книги, статус которых был изменен. В частности, книга может обновиться, что должно привести к ее автоматическому обновлению на площадке партнера. Подобным образом книга может из продаваемой стать непродаваемой – при этом партнер обязан немедленно прекратить продажи этой книги (старые покупатели могут по-прежнему иметь доступ к своим оплаченным копиям). Книга может получить новую цену, новую аннотацию и т. д. – любые поля могут обновиться и партнер должен обновить их на своей площадке.
Обновления следует извлекать не чаще одного раза в десять минут и не реже одного раза в три часа. Рекомендуемая частота обновлений – один раз в 15 минут. Слишком редкие обновления ведут к проблемам с продажей «непродаваемых» книг. Особенно болезненно отзываются задержки, если ответ сервера ЛитРес на уведомление о продаже для партнеров с «витриной на стороне партнера» (схема №2) игнорируется партнерским ПО. При этом продажа считается совершенной, несмотря на отказ ЛитРес ее регистрировать (см. 4. Интерфейс уведомлений ЛитРес о партнерских продажах), что ведет к невозможности скачать оплаченный файл.
Запрос списка обновлений (особенно при выборке за большой период, например при начальной загрузке) занимает на стороне ЛитРес достаточно много времени, поэтому следует подготовить скрипт к работе с таймаутом до двадцати (warning) минут и исключить повторные запросы до того, как будет получен ответ на первый запрос. 
Протестировать процесс загрузки списка обновлений, а также разобраться в принципах формирования запросов к API вы можете с помощью тестового файла https://www.litres.ru/static/get_fresh_book_tester.html (см. исходный код этой страницы).

1.1 Формат запроса

Параметры запроса (все параметры являются обязательными, если не обозначено обратное):

  • checkpoint – время в формате ISO (например, 2017-12-06 19:35:39), с которого следует забирать новинки. Вы получите список новинок со временем большим или равным checkpoint и меньшим /fb-updates/@timestamp (см. описание XML ниже). Если вы хотите получать непрерывную ленту новинок, сохраняйте отданный вам сервером /fb-updates/@timestamp и в следующий раз используйте его в качестве checkpoint;
  • place – ID партнера. Обычно это четырехбуквенный код, который выдается партнеру при заключении договора (см. 8. Данные, предоставляемые партнеру);
  • type – тип запрашиваемого контента, необязательный параметр. По-умолчанию подразумевается type=0. Возможные значения:
    • 0 – электронные тексты/книги;
    • 1 – аудиокниги;
    • 4 – PDF-книги;
    • 11 – Книги на английском языке (Adobe DRM protected);
    • 22 – Подкаст;
    • 23 – Выпуски подкаста, которому передается атрибут updated-book/podcast c id соответствующего Подкаста с type=22 ;
    • all – все типы произведений, кроме type=22 и 23. При этом клиент должен ожидать, что ему будут выданы произведения, тип которых ему не известен.
  • uuid – параметр позволяет выдать информацию только по книге с конкретным ID, необязательный параметр. См. ниже про updated-book/@external_id – уникальный идентификатор книги. Параметр uuid предназначен для ручной проверки книг и его работа в будущем не гарантируется и учитывается вместе с checkpoint. Если вам нужно гарантированно получить XML на произведение, используйте checkpoint «2005-01-01» в сочетании с указанием uuid;

  • endpoint – конец периода, за который запрашивается информация. Необязательный параметр. Рекомендуется использовать при получении базы обновлений за большие периоды. (При полчении базы обновлений на слабые машины ограничивайте запросы месячными периодами, так вы сможете избежать обработки гигантского XML, за несколько проходов обработав все произведения.) Формат времени аналогично параметру checkpoint. Параметр endpoint предназначен для единовременной работы с книгами;

    Получение полной базы каталога

    Для получения полной базы (при первоначальной загрузке) используйте период загрузки каталога равный году максимум, т.е. в первом запросе используем checkpoint «2013-01-01 00:00:00» и endpoint «2014-01-01 00:00:00»

  • moreplaces (актуально только для партнеров с несколькими площадками) – названия площадок, перечисленных через запятую, на которых необходимо проверить доступность книг. Например: «PRTN,TEST». Результат будет размещен в узлах /fb-updates/updated-book/other-place;

  • timestamp – текущий UNIX-таймстамп, время в секундах с 00:00:00 UTC 1 января, 1970. Обязательный параметр;

    Программисты Windows! Проверьте свои таймстампы на https://www.timestampgenerator.com/. Обратите внимание, что вычислять таймстамп из местного времени нельзя! Таймстамп считается по UTC и без сдвига летнего/зимнего времени. В Википедии есть множество подробностей по теории таймстампа, а также есть огромное количество исходников для любого языка, от Perl до PL/SQL.

    sha – подпись запроса. Формируется как: sha256_hex (timestamp.':'.secret_key.':'.checkpoint) – обратите внимание на разделяющие параметры двоеточия. Параметры для расчета sha-подписи будут использоваться в том виде, как были переданы в запросе, secret_key – секретный ключ для уведомлений, который передается партнеру при подключении (см. 8. Данные, передаваемые при подключении партнера). Обязательный параметр.
    Если у вас проблемы с формированием корректного SHA можете воспользоваться следующей командой для консоли unix:

    perl -e '\
$TimeStamp = 1323780017;\
$Key="<secretkey>";\
$CheckPoint="2013-11-25 00:00:00";\
use Digest::SHA;\
print "\n\nGood SHA is: ".Digest::SHA::sha256_hex("$TimeStamp:$Key:$CheckPoint")."\n";'

Пример корректного запроса списка новинок (не забудьте изменить checkpoint, timestamp и sha на актуальные значения):
https://partnersdnld.litres.ru/get_fresh_book/?checkpoint=2015-10-08%2000:00:00&place=TEST&timestamp=1444248000&sha=4a44dc15364204a80fe80e9039455cc1608281820fe2b24f1e5233ade6af1dd5

1.2 Формат ответа сервера

Новинки выдаются в виде XML. Помимо описанных ниже узлов и атрибутов, в выдаваемом XML могут быть любые дополнительные данные, которые партнерам следует игнорировать.
Корневой элемент всегда fb-updates. И в корневом элементе всегда есть атрибут timestamp. Пример пустого ответа (если обновлений нет) выглядит так:
<fb-updates timestamp="2008-10-08 14:34:05"/>

В /fb-updates/@timestamp передается серверное время (с точностью до секунды), до которого (не включительно) вы сейчас получаете новинки. Для получения непрерывного потока обновлений это значение следует сохранять и при следующем запросе передавать в параметре checkpoint (см. 1.1. Формат запроса). 

Каждая новинка передается партнеру в виде узла /fb-updates/updated-book. 

Пример выдачи с двумя новинками и одной удаленной книгой
<fb-updates xmlns:l="https://www.w3.org/1999/xlink" timestamp="2018-04-19 11:33:14">
	<updated-book id="32498526" created="2018-04-18 16:35:49" last_release="2018-04-18 16:35:49" updated="2018-04-18 16:35:49" valid_till="2018-12-31" valid_from="2013-01-01" size="579411" sent_by_name="nvcvet@gmail.com" sent_by_id="9351951" must_import="0" options="0" price="0.90" you_can_sell="0" allow_read="0" allow_sell="0" has_trial="0" allow_full_free="0" public_domain="0" show_card="0" contract_author="9339265" contract_title="АСТ" subject_id="44580" external_id="b4854f32-430a-11e8-9a05-0cc47a52085c" cover="jpg" type="0" adult="16" file_parts="6" available="-1" available_date="2018-04-18 16:18:02" copyright_read_online="1" contract_ends="2018-12-31" udk="821.111-312.4" art_cover="jpg" lvl="2" sell_open="0" can_preorder="0" litex="1" chars="46369" images="1" drm="0" publisher="АСТ" date_written_s="1969" date_written_d="1969-01-01" lang="ru" src_lang="en" cover_h="1960" cover_w="1400" art_cover_w="1400" art_cover_h="1960" lang3="rus" src_lang3="eng" status="approved" rating="6030" url="" inapp_price="0.90">
		<files>
			<file size="579409" type="fb2.zip"/>
			<file size="51846" type="html"/>
			<file size="583471" type="html.zip"/>
			<file size="47604" type="txt"/>
			<file size="20832" type="txt.zip"/>
			<file size="623059" type="rtf.zip"/>
			<file size="663336" type="a4.pdf"/>
			<file size="708752" type="a6.pdf"/>
			<file size="447161" type="mobi.prc"/>
			<file size="1474324" type="epub"/>
			<file size="590189" type="ios.epub"/>
			<file size="578047" type="fb3"/>
		</files>
		<book-title title="Наследство Боксдейла"/>
		<annotation>
			<p>
			«– Видишь ли, мой дорогой Адам, – мягко объяснял каноник, прохаживаясь с главным суперинтендентом Дэлглишем под вязами возле своего пасторского дома, – как бы нам ни было кстати это наследство, оно не принесет мне радости, если моя приемная бабушка Элли получила в свое время эти деньги недостойным способом.
			</p>
			<p>
			Каноник имел в виду, что они с женой не смогут воспользоваться пятьюдесятью тысячами фунтов, оставленными им его приемной бабушкой Элли, если шестьдесят семь лет назад она отравила своего престарелого мужа мышьяком, чтобы получить их. Поскольку в 1902 году это обвинение было снято с тетушки Элли судом, который, по мнению ее хемпширских соседей, в качестве публичного зрелища мог состязаться с церемонией коронации, щепетильность каноника казалась не совсем уместной…»
			</p>
		</annotation>
		<authors>
			<author id="dc3b5610-2a80-102a-9ae1-2dfe723fe7c7">
				<subject_id>44580</subject_id>
				<url>fillis-dzheyms/</url>
				<first-name>Филлис Дороти</first-name>
				<middle-name/>
				<last-name>Джеймс</last-name>
				<full-name-rodit>Филлис Дороти Джеймс</full-name-rodit>
				<lvl>2</lvl>
				<relation>0</relation>
			</author>
			<author id="e4f1d9b0-2a80-102a-9ae1-2dfe723fe7c7">
				<subject_id>44696</subject_id>
				<url>i-doronina/</url>
				<first-name>Ирина</first-name>
				<middle-name>Яковлевна</middle-name>
				<last-name>Доронина</last-name>
				<full-name-rodit>Ирины Дорониной</full-name-rodit>
				<lvl>1</lvl>
				<relation>1</relation>
			</author>
			<author id="c9a05514-1ce6-11e2-86b3-b737ee03444a">
				<subject_id>2835185</subject_id>
				<url>raznoe-4/</url>
				<first-name>Литагент</first-name>
				<middle-name/>
				<last-name>АСТ</last-name>
				<full-name-rodit/>
				<lvl>2</lvl>
				<relation>2</relation>
			</author>
		</authors>
		<genres>
			<genre title="зарубежные детективы" id="5219" bisac="FIC022000" master="1"/>
			<genre title="классические детективы" id="5261" bisac="FIC022000"/>
		</genres>
		<relations>
			<related uuid="BA8F3184-9049-4EAF-A47B-9D711D9135DC" relation="6" type="0"/>
		</relations>
		<copyrights>
			<copyright id="9339265" title="АСТ" percent="100.00"/>
		</copyrights>
		<livelib livelib_id="1001260109" rating="7.263" avg_mark="3.8246" count_readers="2271" widget_url="book/1100906/ratingbutton2015.png" widget_url2="book/1100906/ratingbuttonwhite.png" mark_1="2" mark_2="5" mark_3="48" mark_4="78" mark_5="885"/>
	</updated-book>
	<updated-book id="32523047" created="2018-04-19 09:14:23" last_release="2018-04-19 09:14:23" updated="2018-04-19 09:14:23" valid_till="2021-11-01" valid_from="2016-11-01" size="5653231" sent_by_name="sabanova" sent_by_id="9355626" must_import="0" options="68" price="5.99" you_can_sell="0" allow_read="0" allow_sell="0" has_trial="0" allow_full_free="0" public_domain="0" show_card="64" contract_author="9356032" contract_title="Эксмо" subject_id="44790" external_id="0a6e477f-4398-11e8-aa6b-0cc47a520474" cover="jpg" type="1" adult="0" file_parts="0" available="-1" available_date="2018-04-19 09:11:16" copyright_read_online="0" contract_ends="2021-02-12" art_cover="jpg" lvl="4" sell_open="0" can_preorder="0" litex="0" chars="4368" drm="0" publisher="" lang="ru" cover_h="1500" cover_w="1071" art_cover_w="1071" art_cover_h="1500" lang3="rus" status="approved" url="" inapp_price="5.99">
		<files>
			<group value="Ознакомительный фрагмент. MP3" group_id="1">
				<file id="37754271" size="5653231" filename="Sample.mp3" seconds="4368" mime_type="audio/mpeg" file_description="MP3"/>
			</group>
			<group value="Стандартное качество. MP3" group_id="5">
				<file id="37754255" size="5669432" filename="01.mp3" seconds="354" mime_type="audio/mpeg" file_description="MP3"/>
				<file id="37754231" size="14099251" filename="02.mp3" seconds="880" mime_type="audio/mpeg" file_description="MP3"/>
				<file id="37754263" size="11474467" filename="03.mp3" seconds="716" mime_type="audio/mpeg" file_description="MP3"/>
				<file id="37754215" size="5472573" filename="04.mp3" seconds="341" mime_type="audio/mpeg" file_description="MP3"/>
				<file id="37754239" size="24781451" filename="05.mp3" seconds="1548" mime_type="audio/mpeg" file_description="MP3"/>
				<file id="37754247" size="8470594" filename="06.mp3" seconds="529" mime_type="audio/mpeg" file_description="MP3"/>
			</group>
			<group value="Мобильная версия. MP4" group_id="19">
				<file id="37754223" size="31707503" filename="Sovetnik_Po_Kulture.m4b" seconds="4366" mime_type="audio/m4b" file_description="M4B-файл"/>
			</group>
		</files>
		<book-title title="Советник по культуре"/>
		<annotation>
			<p>
			Николай Стверцов прибыл на планету Ниона в качестве советника по культуре посольства Земной Федерации. Он должен сыграть важную роль в межгалактическом проекте «Восхождение». Проект призван помочь пяти расам Нионы достичь более высокого уровня развития. Но, узнав о страшной тайне изготовления шейота, который является главным предметом экспорта с отсталой планеты, Стверцов начинает сомневаться в правильности политики Земной Федерации на Нионе…
			</p>
		</annotation>
		<authors>
			<author id="ea92d3b4-2a80-102a-9ae1-2dfe723fe7c7">
				<subject_id>44790</subject_id>
				<url>aleksey-kalugin/</url>
				<first-name>Алексей</first-name>
				<middle-name>Александрович</middle-name>
				<last-name>Калугин</last-name>
				<full-name-rodit>Алексея Калугина</full-name-rodit>
				<lvl>4</lvl>
				<relation>0</relation>
				<exid>1-00000025829</exid>
			</author>
			<author id="556f2637-8bde-11e6-9c73-0cc47a1952f2">
				<subject_id>10117645</subject_id>
				<url>audioagent-litres-chtec-pablik/</url>
				<first-name>Аудиоагент</first-name>
				<middle-name/>
				<last-name>ЛитРес Чтец</last-name>
				<full-name-rodit>Аудиоагента ЛитРес Чтец</full-name-rodit>
				<lvl>1</lvl>
				<relation>2</relation>
			</author>
			<author id="a4d115a3-a4f2-11e6-a11d-0cc47a5203ba">
				<subject_id>10389074</subject_id>
				<url>raznoe-10389074/</url>
				<first-name>Аудиоагент</first-name>
				<middle-name/>
				<last-name>1 редакция-прямой договор</last-name>
				<full-name-rodit/>
				<lvl>1</lvl>
				<relation>2</relation>
			</author>
			<author id="f703f2a3-24cc-11e7-b088-0cc47a52085c">
				<subject_id>11119920</subject_id>
				<url>dumanskiy-andrey/</url>
				<first-name>Андрей</first-name>
				<middle-name/>
				<last-name>Думанский</last-name>
				<full-name-rodit>Думанского Андрея</full-name-rodit>
				<lvl>1</lvl>
				<relation>2</relation>
			</author>
			<author id="f703f2a3-24cc-11e7-b088-0cc47a52085c">
				<subject_id>11119920</subject_id>
				<url>dumanskiy-andrey/</url>
				<first-name>Андрей</first-name>
				<middle-name/>
				<last-name>Думанский</last-name>
				<full-name-rodit>Думанского Андрея</full-name-rodit>
				<lvl>1</lvl>
				<relation>6</relation>
			</author>
		</authors>
		<genres>
			<genre title="научная фантастика" id="5073" bisac="FIC028020"/>
			<genre title="социальная фантастика" id="5078" bisac="FIC028000"/>
		</genres>
		<relations>
			<related uuid="76316fbc-2c44-102b-839c-b3fddb510218" relation="8" type="0"/>
		</relations>
		<copyrights>
			<copyright id="9354189" title="ЛитРес: чтец" percent="26.00"/>
			<copyright id="9354794" title="Эксмо" percent="50.00"/>
			<copyright id="9356032" title="Думанский Андрей" percent="100.00"/>
		</copyrights>
	</updated-book>
	<removed-book id="24261892" uid="fc3ba230-4753-11e7-b2fb-0cc47a52085c" removed="2018-04-19 10:34:13"/>
</fb-updates>

Содержимое узла updated-book, существенное для партнеров:

  • updated-book/@id – уникальный ID книги в системе. Необходим при извлечении обложки, ознакомительных фрагментов. В отличие от updated-book/@external_id уникален в рамках одной сущности (например, может быть книга с ID=12345, а может быть автор с ID=12345);
  • updated-book/@you_can_sell – параметр, определяющий право партнера размешать книгу в продажу на своей площадке. Имеет значение больше нуля, если вы можете размещать у себя книгу, и 0 – если не можете. Обратите внимание, что значение может меняться в любую сторону и партнерский магазин должен руководствоваться именно данным атрибутом. Так, если книга, которая находится у вас в продаже, раньше имела атрибут you_can_sell больше нуля, а теперь выдает вам you_can_sell="0", вы должны немедленно снять книгу с продажи. Карточка книги может при этом оставаться, так как сама книга при этом остается в системе, но это не означает, что она когда либо вернется обратно в продажу. Партнерам, не осуществляющим продажи, следует руководствоваться этим же атрибутом и размещать или удалять книги в соответствии с ним;

  • updated-book/@available – глобальный параметр, определяющий доступность книги на ресурсах ЛитРес. (warning) Обратите внимание, какое-либо значение available не гарантирует доступность книги к продаже!!! Партнерам в первую очередь нужно ориентироваться на значение параметра you_can_sell, и размещать книги на своих площадках, только если you_can_sell имеет значение больше нуля. Параметр available может принимать следующие значения:

    • -1 – книга скрыта на ресурсах ЛитРес. При этом параметр you_can_sell всегда будет равен 0. Такие книги запрещено размещать в продажу на площадках партнера;

    • 0 – книга отсутствует в продаже на ресурсах ЛитРес. При этом параметр you_can_sell всегда будет равен 0. Такие книги запрещено размещать в продажу на площадках партнера;

    • 1 – книга доступна к продаже на ресурсах ЛитРес;

    • 2 – книга скоро поступит в продажу на ресурсах ЛитРес (точная дата неизвестна);

    • 6 –  книга скоро поступит в продажу на ресурсах ЛитРес (точная дата известна);
  • updated-book/@available_date – дата поступления книги в продажу на ресурсах ЛитРес. Значение имеет смысл, если available=6. Может отсутствовать;
  • updated-book/@last_release – время размещения последней версии файла. При изменении last_release партнерам, размещающим файлы на своем сервере, следует запросить у нас новый файл;
  • updated-book/@updated – время последнего обновления по книге. Меняется при обновлении текста, обложки, прав на продажу, смене цены и т. п.;
  • updated-book/@size – размер ZIP-файла с книгой (в байтах);
  • updated-book/@adult – возрастные ограничения на книгу (в годах). Значение 0 обозначает, что ограничения отсутствуют;
  • updated-book/@price – продажная стоимость книги на ЛитРес на данный момент. Партнеру следует быть готовым к тому, что цена с течением времени будет изменяться. Цена носит рекомендательный характер, но если партнер продает книгу дешевле цены ЛитРес, с ЛитРес он всё равно будет рассчитываться исходя из указанной здесь цены, доплачивая разницу из своих средств. Поэтому к обновлению цены следует относиться внимательно;
  • updated-book/@inapp_price – стоимость InApp'а в рублях. Партнеру следует учитывать эту стоимость, если планируется для покупки книги перенаправлять пользователя в приложение ЛитРес на платформе iOS;
  • updated-book/@external_id – уникальный ID книги. Используется для глобальной идентификации произведений, в частности, при запросе у ЛитРес файла с текстом (см. 2.1. Формат запроса), уведомлениях о продаже (см. 4.1. Формат запроса-уведомления от партнера о продаже) и многих других местах. external_id – строковая переменная, не более 50 знаков. Должен всегда обрабатываться и передаваться серверу ЛитРес в нижнем регистре (это критично при вычислении SHA);
  • updated-book/@cover – строковое значение, являющееся признаком наличия у книги обложки. Если строка пустая – обложки нет. Если строка не пустая, то она указывает на формат оригинальной обложки (jpg или png). Обложки фиксированных размеров всегда имеют формат jpg (см. 5. Получение обложек ЛитРес);
  • updated-book/@file_parts – количество фрагментов при онлайн-чтении (целочисленное значение);
  • updated-book/@wap_parts – количество фрагментов при мобильном онлайн-чтении (целочисленное значение);
  • updated-book/@contract_ends – примерная дата окончания контракта на произведение;
  • updated-book/@type – тип произведения. Возможные значения:
    • 0 – текст;
    • 1 – аудиокнига;
    • 4 – PDF-книга;
    • 11 – книга на английском языке (Adobe DRM protected).
  • updated-book/@chars – в зависимости от типа произведения, в данном значении содержится различная информация:
    • тип 0 – количество символов в книге (включая пробелы);
    • тип 1 – общая длительность аудиокниги (в секундах);
    • тип 4 – количество страниц в PDF-книге;
  • updated-book/@isbn – один или несколько ISBN книги;
  • updated-book/@date_written_s – дата написания произведения (строковое значение в свободной форме. Но обычно тут хранится год написания книги в формате ГГГГ);
  • updated-book/@date_written_d – дата написания произведения в формате ГГГГ-ММ-ДД;
  • updated-book/@images – (актуально для произведений с типом 0) – количество изображений в произведении, включая обложку. Например, если у произведения с типом 0 в этом параметре указано значение «2», то это означает, что в самой книге есть только одна иллюстрация;
  • updated-book/authors – раздел, в котором описываются все авторы, переводчики, художники, чтецы и другие лица, принявшие участие при создании произведения. Для каждого лица выделяется отдельный подраздел updated-book/authors/author со списком его параметров:
    • @id – уникальный автора (художника, чтеца и т. п.);
    • url – относительный URL на страницу автора. Например, этот путь можно подставить к своему домену: www.litres.ru/<строковое значение из данного параметра>;
    • first-name – имя автора;
    • last-name – фамилия автора;
    • full-name-rodit – имя и фамилия автора в родительном падеже;
    • lvl – уровень автора, субъективно выставляемый редакторами ЛитРес и отражающий степень известности/интересности автора. Параметр может принимать целые значение от 1 до 5 (5 – наиболее известные авторы);
    • relation – параметр, определяющий тип лица, принявшего участие при создании данного произведения. Возможные значения:
      • 0 – автор;
      • 1 – переводчик;
      • 2 – агент;
      • 3 – художник;
      • 4 – составитель;
      • 5 – пересказчик;
      • 6 – чтец;
      • 7 – исполнитель;
      • 8 – производитель;
      • 9 – редактор;
      • 10 – актер;
      • 11 – режиссер;
      • 15 – продюсер;
      • 19 – композитор;
      • 23 – звукорежиссер;
      • 27 – сценарист.
  • updated-book/genres – раздел, в котором описываются все жанры данного произведения. Каждый жанр представлен отдельным узлом updated-book/genres/genre со следующими параметрами:
  • updated-book/sequences – раздел, в котором описываются все серии книги. Для каждой серии выделяется отдельный подраздел updated-book/authors/sequences/sequence со списком параметров:
    • @name – название серии;
    • @number – порядковый номер данной книги в серии (опционально);
    • @uuid – уникальный идентификатор серии.

Список серий может иметь древовидную/сложенную структуру. В таком случае книга привязывается к крайним «листам» дерева, например к updated-book/authors/sequences/sequence/sequence/@uuid.

  • updated-book/book-title/@title – название книги;
  • updated-book/book-title/@subtitle – подзаголовок (уточнение) к названию книги;
  • updated-book/annotation – текст аннотации произведения, разбитый на абзацы тегами <p>…</p>;
  • updated-book/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 – Японский.
  • updated-book/src_lang – язык исходного оригинала произведения (двухбуквенный код в нижнем регистре в формате ISO). Например, если книга – это Шекспировский «Гамлет» на русском языке, то в src_lang будет «en», а в lang – «ru»;
  • updated-book/files/group/ – (актуально для контента с типом 1, 4) – список мультимедиа-файлов, связанных с данным произведением. Файлы сгруппированы по типу «кодирования» (updated-book/files/group/@value). Каждому типу соответствует свой @group_id. Для одного произведения может быть несколько альтернативных форм. Например, книга может быть в двух вариантах: «Стандартное качество. MP3, 192 Kbps» и «Мобильная версия. MP4, 16 Kbps». Обе группы файлов дублируют одно и то же содержание, но предоставляют его в разных форматах. Блок updated-book/files/group/@value может содержать следующие значения с соответствующим group_id:

    • Для контента с типом 1 (аудиокниги):

      • 1 – ознакомительный фрагмент. MP3, 128 Kbps;
      • 2 – копия оригинального диска. MP3-файлы в самораспаковывающемся RAR-архиве;
      • 3 – стандартное качество. MP3, 128 Kbps;
      • 4 – мобильная версия. MP4, 16 Kbps;
      • 5 – стандартное качество. MP3, 192 Kbps;
      • 6 – мобильная версия. MP4, 32 Kbps;
      • 7 – стандартное качество. MP3, 64 Kbps;
      • 8 – дополнительные материалы;
      • 19 – мобильная версия. MP4, 64 Kbps;
      • 20 – MP3 файлы в zip архиве.

    • Для контента с типом 4 (PDF):

      • 9 – ознакомительный фрагмент pdf;
      • 10 – PDF-книга;
      • 11 – обложка в PDF (PoD);
      • 15 – дополнительные материалы.

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

    • @id – численный ID файла. При скачивании мультимедиа-файлов пользователем (см. 4.6. Скачивание мультимедиа-контента (все типы, кроме 0 и 11)) этот ID передается серверу ЛитРес;
    • @size – размер файла (в байтах);
    • @filename – рекомендуемое имя файла;
    • @seconds – длительность (имеет смысл для таких файлов, как mp3);
    • @mime_type – тип контента. Возможные значения:
      • audio/mpeg – MP3-файл;
      • audio/x-pn-realaudio – файл Real Audio;
      • audio/wav – WAV-файл;
      • audio/x-ms-wma – WMA-файл;
      • audio/m4b – M4B-файл;
      • application/zip – ZIP-файл;
      • application/x-rar-compressed – RAR-файл;
      • application/pdf – PDF-файл.
        (warning) Важно понимать, что список типов контента может расширяться и необходимо корректно обрабатывать все незнакомые значения.
    • @file_description – краткое описание типа файла;
  • updated-book/files/file – (актуально для контента с типом 0 и 11) – список типов файлов с указанием размера файла, содержащего электронный текст книги. Для каждого типа файла указывается:
    • @type – тип файла.
      Возможные значения для контента типа 0:
      • fb2.zip;
      • rtf.zip;
      • a6.pdf;
      • a4.pdf;
      • html.zip;
      • txt.zip;
      • rtf.zip;
      • doc.prc.zip;
      • rb;
      • epub;
      • mobi.prc;
      • txt;
      • isilo3.pdb;
      • lit;
      • ios.epub;

Возможные значения для контента типа 11:

      • epub;
      • a4.pdf;
    • @size – размер файла в байтах (не указывается для типа 11);
  • updated-book/@contract_author, updated-book/@contract_title – числовой ID и текстовое имя правообладателя по данному тексту. Если updated-book/@contract_title отсутствует, значит правообладателем является автор. Партнер может указывать имя правообладателя на своем сайте, чтобы повысить для пользователей и авторов прозрачность системы;

  • updated-book/@copyrights – детализация по правообладателям:

    • copyrights_title – название правообладателя (значение соответствует параметру contract_title);

    • copyrights_id – числовой ID правообладателя (значение соответствует параметру contract_author);

    • ownership rate – процент участия данного правообладателя в книге;

  • updated-book/@rating – рейтинг книги, выставляемый на основе нескольких показателей (на основе объема продаж книги в течение года, популярности автора книги, оценок пользователей и др.) и отражающий реальную популярность книги среди пользователей ЛитРес. Параметр может принимать целые значение от 0 до ∞ (чем больше значение – тем популярнее книга). Параметр может отсутствовать в выдаче. Например, если книга новая и еще ни разу не продавалась;

  • updated-book/@relations – ID книг, связанных с ID, по которому передается информация, тип их связи и тип связанной книги. Возможные значения типов связи (relations) потенциально интересные партнеру:

    • 5 – сборник;

    • 6 – часть;

    • 7 – переиздание;

    • 8 – другой носитель;

  • updated-book/@livelib – текущий рейтинг книги на ресурсе LiveLib. Партнер может дополнительно указывать этот рейтинг на своем сайте, чтобы показать популярность книги. Параметр может отсутствовать в выдаче. Содержит следующие атрибуты, потенциально интересные партнеру:

    • rating – рейтинг книги в списке «Топ-100» LiveLib;

    • avg_mark – средняя оценка книги по 5-балльной шкале. Дробное число, в качестве разделителя используется точка. Например, «4.123»;

    • count_readers – количество пользователей, прочитавших книгу. Число;

    • widget_url – ссылка на виджет рейтинга книги;

    • widget_url2 – ссылка на виджет рейтинга книги с подписью «LiveLib» под виджетом;

    • mark_1 – количество пользователей, поставивших книге оценку «1». Число;

    • mark_2 – количество пользователей, поставивших книге оценку «2». Число;

    • mark_3 – количество пользователей, поставивших книге оценку «3». Число;

    • mark_4 – количество пользователей, поставивших книге оценку «4». Число;

    • mark_5 – количество пользователей, поставивших книге оценку «5». Число;

  • updated-book/other-place – информация о доступности книги на заданной площадке (см. параметр запроса moreplaces в 1.1. Формат запроса). Таких узлов в ответе может быть несколько: в зависимости от количества площадок, указанных в запросе. Каждый узел содержит атрибуты:

    • @place – название площадки, переданной в запросе в параметре moreplaces;

    • @you_can_sell – разрешение на размещение книги в продажу на площадке, указанной в параметре @place. Возможные значения:

      • 1 – партнер может размещать и продавать эту книгу на площадке, указанной в параметре @place;

      • 0 – партнеру запрещено размещать эту книгу на площадке, указанной в параметре @place.

Помимо информации о новинках, в ответе сервера может содержаться набор команд на удаление книг с площадок партнера – removed-book. Книги на удаление идентифицируются по идентификатору, который указан в атрибуте removed-book/@uuid и должны быть полностью удалены из системы партнера (если они там присутствуют). В том числе и из корзин уже купивших книгу пользователей.

Инструкции removed-book могут иметь атрибут @uid_new, где хранится новый ID для удаленной книги. В этом случае речь идет не об удалении, а о замещении книги. И партнер для уже оплативших книгу пользователей может заменить старую книгу на новую (на стороне ЛитРес покупки замещаются). Запись о старой книге в любом случае должна быть удалена.

2 Интерфейс получения файла книги

Для получения файла книги используется URL:
https://partnersdnld.litres.ru/get_the_book/

2.1 Формат запроса

Данный URL принимает запросы с параметрами, которые будут указаны ниже. В ответ отдается ZIP-архив с fb2-файлом (для электронной книги) или файл другого формата (если заполнено поле file). 

Параметры запроса (параметры book, sha, place являются обязательными):

  • book – fb2-ID книги (извлекается из updated-book/@external_id, подробности см. в 1.2. Формат ответа сервера). Обязательный параметр;

  • sha – подпись запроса. На Perl ключ генерируется следующим образом: 

    Digest::SHA::sha256_hex("$Art:$Key")

    , где $Key – ваш секретный ключ для скачивания, предоставляется партнерам при подключении (см. 8. Данные, передаваемые при подключении партнера). Обратите внимание, что в $Art ожидается ID книги в нижнем регистре. Обязательный параметр;

    place – ID партнера, обычно это четырехбуквенный код (см. 8. Данные, передаваемые при подключении партнера). Обязательный параметр;
  • type – необязательный атрибут, указывает формат, в котором требуется вернуть файл электронной книги. По умолчанию считается fb2.zip, допустимые значения:
    • fb2.zip;
    • rtf.zip;
    • a6.pdf;
    • a4.pdf;
    • html.zip;
    • txt.zip;
    • rtf.zip;
    • doc.prc.zip;
    • rb;
    • epub;
    • mobi.prc;
    • txt;
    • isilo3.pdb;
    • lit;
    • ios.epub;
  • file – ID файла из updated-book/files/group/file/@id (см. 1.2. Формат ответа сервера). Необязательный параметр, используемый для получения PDF и аудио файлов (type в этом случае заполнять не требуется). Если параметр не передан, то в выдачу попадут файлы формата fb2.zip и производные от него.

2.2 Формат ответа сервера

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

3 Интерфейс отдачи статистики продаж партнерами

Партнеры обязаны предоставлять ЛитРес оперативную статистику (задержка уведомлений о продажах не более суток) по продажам произведений. Для получения статистики партнерами, подключенными по схеме №1, используется http-запрос с нашего сервера на сервер партнера (об отчете при схеме подключения №2 см. 4.1. Формат запроса-уведомления от партнера о продаже).

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

3.1 Формат запроса к серверу партнера

URL отдачи статистики партнер сообщает нам при подключении (см. 8. Данные предоставляемые партнером).

HTTP-сервер на указанном URL должен обрабатывать GET запросы со следующими параметрами:

  • checkpoint – время, с точностью до секунды, начиная с которого (включительно) следует отдавать список покупок. Предполагается, что сервер партнера вернет покупки по [настоящий момент минус одна секунда];

  • sha – подпись запроса. Формируется вычислением sha от значения, полученного после конкатенации значения checkpoint и секретного ключа. На Perl ключ генерируется следующим образом: 

    Digest::SHA::sha256_hex($CheckPoint.$Key)

    , где $Key – секретный ключ, предоставляется ЛитРес'у партнером при подключении (см. 8. Данные, предоставляемые партнеру).

ЛитРес будет обращаться к URL'у отдачи статистики ежечасно. Ожидается, что при подстановке в каждый следующий запрос параметра litres-partner-sales/@timestamp в качестве checkpoint, партнер будет отдавать непрерывную и полную статистику. Без пропусков (обязательно) и без повторов (желательно).

Пример Perl-кода для корректной выборки новых продаж, исключающей повторы и пропуски
my $CheckPoint=$query->param('checkpoint');

my $NowSth=$dbh->prepare("SELECT now()");
$NowSth->execute();
my $EndPoint=$NowSth->fetchrow();

my $GetSalesSth=$dbh->prepare("
	SELECT fb2_id as `item-id`, price, time, id as `pay-id`
	from sales
	where time >= ? and time < ?
");

$GetSalesSth->execute($CheckPoint,$EndPoint);

print '<litres-partner-sales partner="PRT" timestamp="'.$EndPoint.'">'.	FetchQueryXML($GetSalesSth).'</litres-partner-sales>';

3.2 Формат ответа сервера партнера

Сервер партнера в ответ на запрос ЛитРес должен отдавать XML, где корневой элемент имеет имя litres-partner-sales.

Пример ответа сервера партнера
<litres-partner-sales checkpoint="2008-09-01 18:00" partner="IMOB" timestamp="2008-10-08 17:12">
	<sale item-id="236C2AF7-38AB-41C4-AE10-F592EDE67F75" price="10.00" time="2008-09-01 18:45" pay-id="566" currency="RUR"/>
	<sale item-id="8A7F4723-9F7B-4C97-BF17-130DAB87519A" price="17.00" time="2008-09-01 19:08" pay-id="567" currency="RUR"/>
	<sale item-id="03D9D905-3387-4B04-94F5-BEF119059D13" price="3.00" time="2008-09-02 08:50" pay-id="568" currency="RUR"/>
</litres-partner-sales>

Обязательное содержимое тега litres-partner-sales:

  • litres-partner-sales/@timestamp – серверное время, до которого (не включительно) вы отдаете полный список продаж;
  • litres-partner-sales/@partner – ID партнера (см. 8. Данные, предоставляемые партнеру);
  • litres-partner-sales/sale – описание одной продажи партнером. Должно иметь следующие атрибуты:
    • @item-id – fb2-ID книги (см. 1.2. Формат ответа сервера, updated-book/@external_id);
    • @price – цена, за которую была продана книга;
    • @time – время в формате ISO, в которое была завершена продажа;
    • @pay-id – уникальный ID платежа в системе партнера, который позволит избежать повторного учета платежей;
    • @currency – код валюты. Допускаются значения EUR, USD, GBP, AUD, CAD, RUR, NZD. Необязательный атрибут. По умолчанию считается равным RUR (российский рубль), а любые значения, отличные от рубля, следует явно оговаривать при подключении к системе ЛитРес.

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

4 Интерфейс уведомлений ЛитРес о партнерских продажах

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

  1. Партнеры выделяют доменное имя, которое будет использоваться для отдачи файлов (см. 8. Данные предоставляемые партнером). Например, партнер, имеющий витрину www.bobook.ru, может выделить домен dnlbook.bobook.ru для скачивания книг. Этот домен перенаправляется на сервер ЛитРес. Имя этого домена необходимо сообщить при подключении к сервису.
  2. Партнер, в процессе продажи (а не после ее завершения!) книги своему пользователю, отправляет на сервер ЛитРес уведомление (см. 4.1. Формат запроса-уведомления от партнера о продаже) и получает ответ (см. 4.2. Формат ответа сервера на запрос-уведомление). После того (и только после того!), как ЛитРес вернул статус «успех», партнер завершает продажу книги пользователю. Если ЛитРес отказывается регистрировать продажу, партнер обязан незамедлительно прервать продажу книги пользователю (warning). Если уведомление прошло успешно, продажа необратимо регистрируется в нашей системе и становится мгновенно доступна правообладателям.
  3. Книга, продажа которой зарегистрирована на ЛитРес, доступна пользователю для скачивания по специальному URL. Ссылка на скачивание книг включает SHA-подпись покупателя (см. 4.3. Формат URL на скачивание книг для пользователей партнера) и направляется партнером на выбранный при подключении домен (см. пункт 1 выше). В случае, если покупка не была зарегистрирована сервером ЛитРес, либо ссылка составлена неверно (неправильный SHA), клиент перенаправляется (с 302-м кодом HTTP) на страницу ошибки (см. 8. Данные предоставляемые партнером), указанную партнером при регистрации;
  4. ЛитРес гарантирует обслуживание до 20-и скачиваний любой книги в любом формате каждым клиентом. Клики клиентов партнера, исчерпавших свой лимит скачивания, перенаправляются (302-й код HTTP) на указанную партнером страницу. Счетчик уже совершенных скачиваний хранится на сервере ЛитРес и уменьшается на 1 ежемесячно (предоставляя максимум 32 закачки в год). Докачка и повторные скачивания в течение минуты не наращивают счетчик скачиваний. Желательно, чтобы партнер самостоятельно вел счетчик обращений и заблаговременно уведомлял своих клиентов о приближении к лимиту скачиваний.

Уведомления о продажах партнера считаются достоверными данными по продажам и используются ЛитРес для отчета перед правообладателями. Предоставление партнером статистики согласно разделу 3 для работающих по схеме №2 партнеров не требуется.

4.1 Формат запроса-уведомления от партнера о продаже

Для уведомления о том, что один из пользователей партнера приобрел книгу и ему следует разрешить скачивание, партнер сразу после продажи отправляет HTTP-запрос на специальный URL (на зарегистрированном для него в ЛитРес домене согласно разделу 8. Данные предоставляемые партнером), например: https://dnlbook.bobook.ru/partner_user_purchases_a_book/.

При этом партнер передает следующие параметры:

  • user – обязательный параметр. ID покупателя в системе партнера. Далее он используется при формировании URL на скачивание. Целое положительное число, не более 4294967295. Если в запросе также передается параметр lfrom, то значение user может быть строкой длиной до 128 символов;
  • art – обязательный параметр. FB2-ID книги в нижнем регистре, которую пользователь приобрел (см. updated-book/@external_id в разделе 1.2. Формат ответа сервера);

  • sha – обязательный параметр. Подпись запроса SHA256. На Perl ключ генерируется следующим образом:

    Digest::SHA::sha256_hex("$User:$Art:$Key")

    , где $Key – секретный ключ для уведомлений партнеру при подключении (см. 8. Данные, передаваемые при подключении партнера). Обратите внимание, что в $art ожидается ID книги в нижнем регистре;

  • price – обязательный параметр. Цена, по которой партнер продал книгу. В случае, если эта цена оказывается ниже цены ЛитРес, для взаиморасчетов все равно будет использоваться цена ЛитРес. Партнер должен добросовестно указывать свою выручку с продажи. Допустим, книга стоит на ЛитРес 10 рублей. Партнер продает эту книгу за SMS, отправка SMS обходится пользователю в 50 рублей, из которых партнер получает 20 рублей. При этом партнер должен отчитаться о продаже книги за 20 рублей;
  • mail – e-mail адрес покупателя. Является обязательным параметром за исключением того случая, когда параметр reserve=reserve (см. ниже). В таком случае параметр mail является лишь желательным и позволяет провести валидацию e-mail адреса на стороне ЛитРес;
  • reserve – необязательный параметр. Признак двухэтапного заказа, работы с резервированием. При указании параметра reserve=reserve сервер ЛитРес не осуществит покупку для клиента, вместо этого будет проверена доступность товара и произведено его резервирование. В ответе сервера будет передан ID резерва. Если в параметре reserve передано число, считается что это ID резерва и этот резерв проводится, как покупка (все остальные параметры так же должны быть переданы и соответствовать данным в резерве). Время резервирования – 15 минут. Зарезервированный товар гарантированно будет проведен как продажа даже в случае, если за это время он был снят с продажи и по состоянию на текущий момент уже недоступен;
  • lfrom – необязательный параметр. Номер реферала. Партнеру может быть выдан номер реферала для регистрации продажи не на сайте партнера, а на ЛитРес. В этом случае lfrom нужно указывать в обязательном порядке, а параметр user в этом случае может быть строковым идентификатором длиной до 128 символов.

4.2 Формат ответа сервера на запрос-уведомление

Сервер ЛитРес выдаёт в ответ на запрос-уведомление результат операции в виде XML. Варианты ответа:

  • <response status="0" reserve-id="333333" message="OK" reserve-price="89.90"/> – резервирование успешно. В атрибуте reserve-id передается ID резерва, а в reserve-price – справочная рублевая цена ЛитРес на эту книгу на момент оформления резерва;
  • <response status="0" order-id="333333" message="OK"/> – продажа успешно зарегистрирована, в order-id внутренний ID покупки ЛитРес;
  • <response status="код_ошибки" message="текстовое_сообщение"/> – произошла ошибка; дается её краткое описание. В этом случае ссылка на скачивание данной книги будет «невалидной», а продажа не регистрируется. Возможны следующие коды ошибок:
    • 1001 – неправильный SHA;
    • 1002 – неправильный ID книги;
    • 1003 – книга уже куплена (для POD-книг не возвращается);
    • 1004 – книга недоступна для продажи.

Обратите внимание, что ответ за запрос-уведомление может быть «ошибка», а не только «ок». При этом не нужно списывать с клиента средства – книгу он скачать все равно не сможет! Если вы обновляете каталог своевременно, вероятность отказа в регистрации продажи невелика, но она не равна нулю. Так же возможен нештатный ответ, например, http-ошибка 500 или 503, наш сервис тоже, случается, недоступен. Ни в коем случае не списывайте с клиента средства до того, как получили ответ «ок» на уведомление о продаже!

4.3 Формат URL на скачивание книг для пользователей партнера

4.4 Скачивание текстовых книг (тип 0)

Для скачивания текстовой книги с сервера ЛитРес партнер формирует URL согласно следующим правилам:

  • HTTP-запрос с доменом, оговоренном сторонами, и указывающим на сервер ЛитРес (см. 8. Данные предоставляемые партнером) (например, https://dnlbook.bobook.ru/).
  • После доменного имени следует обязательная часть URL: /get_litres_file/ (например, https://dnlbook.bobook.ru/get_litres_file/).

  • Затем следует текущий UNIX-таймстамп: время в секундах с 00:00:00 UTC 1 января, 1970. Ссылка считается валидной, если таймстамп не отстал от текущего времени более чем на 12 часов. Ссылки с устаревшим таймстампом не обрабатываются. (например, https://dnlbook.bobook.ru/get_litres_file/1223476707/). Для понижения чувствительности URL к рассинхронизации времени между сервером партнера и ЛитРес, рекомендуем брать таймстамп, просроченный на 60 секунд.

    Программисты Windows! Проверьте свои таймстампы на https://www.timestampgenerator.com/. Обратите внимание, что вычислять таймстамп из местного времени нельзя! Таймстамп считается по UTC и без сдвига летнего/зимнего времени. В Википедии есть множество подробностей по теории таймстампа, а также есть огромное количество исходников для любого языка, от Perl до PL/SQL.

  • Затем следует ID пользователя (например, https://dnlbook.bobook.ru/get_litres_file/1223476707/666/).

  • Затем указывается fb2-ID книги в нижнем регистре. В ID могут встречаться недопустимые для URL символы, в этом случае URL следует «эскейпить». (например, https://dnlbook.bobook.ru/get_litres_file/1223476707/666/fb2-test-id-123).
  • Затем, через точку, указывается расширение, выбираемое в зависимости от запрошенного пользователем типа файла. Допускаются следующие расширения:
    • .fb2.zip – зипованный FB2;
    • .html.zip – зипованный HTML;
    • .txt.zip – зипованный TXT;
    • .rtf.zip – зипованный RTF;
    • .a4.pdf – PDF, оптимизированный для печати на A4;
    • .a6.pdf – PDF, оптимизированный для чтения на eBook;
    • .isilo3.pdb – формат для iSilo, мультиплатформенной старенькой читалки;
    • .doc.prc.zip – файл palm doc. Формат читает множество старых и не очень программ;
    • .lit – формат файлов читалки Microsoft Reader;
    • .rb – формат для устройства Rocket eBook и REB1100;
    • .epub – ePub, новый перспективный формат электронных книг, разработанный Adobe;

    • mobi.prc – файлы для моби-ридера. В данный момент особенно примечательны тем, что работают на Amazon Kindle, хотя для моби есть очень хорошие читалки для PalmOS, Windows Mobile и настольных компьютеров.
      (например, https://www.dnlbook.bobook.ru/get_litres_file/1223476707/666/fb2-test-id-123.fb2.zip).

  • В качестве GET или POST параметра к этой ссылке добавляется SHA-подпись. На Perl ключ генерируется следующим образом: 

    Digest::SHA::sha256_hex("$TimeStamp:$User:$Art:$Key")

    , где $Key – ваш секретный ключ для скачивания, предоставляется партнерам при подключении (см. 8. Данные, передаваемые при подключении партнера);
    (например, https://www.dnlbook.bobook.ru/get_litres_file/1223476707/666/fb2-test-id-123.fb2.zip?sha=4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce). Обратите внимание, что в $art ожидается ID книги в нижнем регистре.

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

perl -e '\
$TimeStamp = 1323780017;\
$User=5;\
$Art=lc("c4ca9de1-7457-102b-94c2-fc330996d25d");\
$Key="<secretkey>";\
use Digest::SHA;\
print "\n\nGood SHA is: ".Digest::SHA::sha256_hex("$TimeStamp:$User:$Art:$Key")."\n";'

4.5 Скачивание книг на английском языке Adobe DRM (тип 11)

Для скачивания книг на английском языке, защищенных технологией Adobe DRM (тип 11), партнер формирует URL идентично тому, как формируется URL для текстовых книг (тип 0), см. 1.1. Формат запроса. 
В ответ на запрос сервер ЛитРес отдает не сам файл, а HTTP-редирект со статусом 302 на уникальный URL, с которого и будет производиться скачивание файла лицензии URLLink.acsm (т. е., по сути, книги Adobe DRM).

Следует обратить особое внимание на следующее:

  • После уведомления партнером о продаже книги на английском языке Adobe DRM (partner_user_purchases_a_book), сервер ЛитРес формирует URL, на который будет производится HTTP-редирект (302). Формирование URL для Adobe DRM требует некоторого времени, поэтому рекомендуется между уведомлением о продаже и запросом на скачивание файла сделать паузу не менее 15 секунд;
  • Книга на английском языке Adobe DRM может быть скачана не более 3 раз.

4.6 Скачивание мультмедиа-контента (все типы, кроме 0 и 11)

Для скачивания мультимедиа-контента с сервера ЛитРес партнер формирует URL согласно следующим правилам:

4.7 Время жизни ссылок, число скачиваний

Партнерские ссылки остаются валидными в течение 12-и часов от указанного в них таймстампа. Скачивания пользователей теоретически «не лимитированы», то есть мы не запрещаем добросовестным пользователям скачивать купленную единожды книгу столько раз и в стольких форматах, в скольких им нужно. Однако, для предотвращения злоупотреблений существует фактическое ограничение на 11 повторных скачиваний, причем счетчик ежемесячно уменьшается на 2. При этом повторными скачиваниями не считаются:

  • Повторные скачивания текстовых книг в течение 3-х минут – с любого IP.
  • Повторные скачивания текстовых книг в течение 15-и минут из подсети, сформированной из пользовательского IP маской 255.255.255.0.
  • Повторные скачивания текстовых книг в течение одного часа с того же IP.
  • Повторные скачивания «не текстовых» книг в течение 8-и часов с любого IP.
  • Повторные скачивания «не текстовых» книг в течение 3-х дней из подсети, сформированной из пользовательского IP маской 255.255.255.0.
  • Повторные скачивания «не текстовых» книг в течение недели с того же IP.

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

4.8 Перенаправления пользователя при ошибках

Если пользователь обращается на URL скачивания книги, но при этом происходит ошибка, пользователь перенаправляется на указанный партнером URL (см. 8. Данные предоставляемые партнером) с сообщением об ошибке. При этом к URL добавляется параметр error, принимающий следующие значения:

  • sha – неверная подпись SHA;
  • unkownbook – книга с таким ID сейчас недоступна для скачивания;
  • not_purchased – книга не была продана данному пользователю;
  • not_ready_pending_acsm – URL для скачивания книги на английском языке Adobe DRM (тип 11), еще не готов. Он находится в процессе формирования.
  • downloads_overquote – превышен лимит скачиваний;
  • expired – ссылка содержит просроченный таймстамп (больше 12 часов);
  • internal – внутренняя ошибка сервиса ЛитРес.

Например, если партнер указал URL https://www.partner.ru/dnld_err/?err= (см. 8. Данные предоставляемые партнером) и произошла ошибка вычисления SHA, будет осуществлена переадресация на: https://www.partner.ru/dnld_err/?err=sha.

4.9 Тестирование интерфейса уведомлений

Для тестирования на площадке ЛитРес заведен партнер TEST, домен tester.litres.ru, а также секретный ключ 93w4jfhs8imksGo-oa3s85d6Akmkkbnsi9. Для этого тестового партнера всегда доступна книга 65830123-26b8-4b07-8098-c18229e5026e (Психология Искусства). 
Протестировать процесс загрузки списка обновлений, а также разобраться в принципах формирования запросов к API вы можете с помощью тестового файла https://www.litres.ru/static/get_fresh_book_tester.html. Затем вы можете скачать этот файл и изменить под свои задачи тестирования различных запросов. 

Примеры запросов к API:

5 Получение обложек ЛитРес

Для большинства (но не для всех!) книг имеются обложки. Дефолтная обложка обычно имеет ширину 250-300 px, но это не гарантированно, т. к. бывают более широкие или узкие обложки. Ссылку на изображение обложки партнер формирует согласно следующим правилам:

  • HTTPS запрос к ЛитРес (https://partnersdnld.litres.ru).

  • После доменного имени следует обязательная часть URL: /pub/c/ (https://partnersdnld.litres.ru/pub/c).

  • Затем следует указать желаемый формат обложки. Для дефолтной обложки это просто /cover (https://partnersdnld.litres.ru/pub/c/cover).

  • Также существуют версии обложки «фиксированных» размеров – 30, 37, 89, 95, 100, 120, 123, 185, 200, 250, 330 и 415 пикселей в ширину (высота пропорциональна) и 70, 120, 140, 190, 270, 400 и 1500 в высоту (ширина пропорциональна). Чтобы получить отформатированную в стандартный размер обложку, желаемый размер вместо /cover нужно подставить желаемый размер обложки в формате /cover_# (например, /cover_415.jpg – картинка шириной 415) и /cover_h# (например, /cover_h140 – картинка высотой 140). Для получения обложки максимальной высоты, нужно подставить значение /cover_max1500. Обратите внимание, обложки фиксированного размера всегда имеют формат jpg.

  • Затем следует подставить ID книги из списка новинок (fb-updates/updated-book/@id) и формат файла. Формат обложки может быть png или jpg. О формате следует узнавать из ленты обновлений, см. 1.2. Формат ответа сервера, updated-book/@cover;

  • Сформировать полный URL обложки, например: https://partnersdnld.litres.ru/pub/c/cover_h140/32544407.jpg.

6 Получение ознакомительных фрагментов книг

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

6.1 Ознакомительные фрагменты для текстовых книг

Для текстовых форматов (fb2.zip, fb3, ePub, rtf.zip, txt, txt.zip, a4.pdf, a6.pdf) ознакомительный фрагмент с сервера ЛитРес можно получить по ссылке вида: https://partnersdnld.litres.ru/pub/t/123456.fb2.zip, где 123456 – ID книги из атрибута updated-book/@id, a вместо fb2.zip можно поставить другое расширение.

Кроме того для некоторых текстовых форматов (см. перечень ниже в описании параметра format) возможно получение ознакомительного фрагмента без явного указания в конце фрагмента ссылки для покупки полной версии книги на сайте ЛитРес. Это может быть полезно партнерам, работающим по Схеме №2. Для этого используйте ссылку вида: https://litres.ru/gettrial/?art=123456&lfrom=1251428&format=fb2.zip&clean=1,

где:

  • art – уникальный ID книги, для которой должен быть получен ознакомительный фрагмент. Обязательный параметр. Соответствует атрибуту updated-book/@id (см. раздел 1.2. Формат ответа сервера);
  • lfrom – реферальный номер партнера. Обязательный параметр. Выдается партнеру для регистрации продаж, если они происходят напрямую с сайта ЛитРес (см. 8. Данные предоставляемые партнером);
  • format – указывается расширение ознакомительного фрагмента книги. Обязательный параметр. Допускаются следующие расширения:
    • fb2.zip – зипованный FB2;
    • txt.zip – зипованный TXT;
    • rtf.zip – зипованный RTF;
    • epub – ePub, новый перспективный формат электронных книг, разработанный Adobe;
  • clean – необязательный параметр. Если передать его со значением «1», то в конце ознакомительного фрагмента не будет ссылки для покупки полной версии книги на сайте ЛитРес.

6.2 Ознакомительные фрагменты для PDF-книг

Для всех PDF-книг доступны ознакомительные фрагменты. URL для ознакомительного фрагмента формируется как https://partnersdnld.litres.ru/get_pdf_trial/123456.pdf, где 123456 – ID книги из атрибута updated-book/@id (раздел 1.2. Формат ответа сервера). Фрагмент является PDF-файлом, обычно содержащим несколько первых страниц (например, может быть 25 страниц).

6.3 Ознакомительные фрагменты для аудио-книг

Для всех аудио-книг доступны ознакомительные фрагменты. URL для ознакомительного фрагмента формируется как https://partnersdnld.litres.ru/get_mp3_trial/123123.mp3, где 123123 – ID книги из атрибута updated-book/@id (раздел 1.2. Формат ответа сервера), ознакомительный фрагмент представлен mp3-файлом.

7. Получение дерева жанров ЛитРес

Полное дерево жанров постоянно находится по ссылке https://partnersdnld.litres.ru/genres_list_2/. Его желательно обновлять раз в две недели или при обнаружении книг с неизвестными жанрами. 
Дерево состоит из корневых жанров (type="root"), непосредственно в которых или в поджанрах (type="container") расположены конечные жанры (type="genre"). 
Книгам из каталога всегда присваиваются только конечные жанры из этого дерева (с атрибутом type="genre"). Но учитывайте, что жанровое дерево может изменяться и со временем, например, конечные жанры (type="genre") могут превратиться в поджанры (type="container").
Все элементы дерева имеют одинаковые атрибуты:

  • @id – уникальный ID жанра/поджанра;
  • @token – строковой ID жанра/поджанра;
  • @title – русское название жанра/поджанра.
  • @type – тип элемента дерева. Возможные значения:
    • root – корневой жанр;
    • container – поджанр, условно являющийся «папкой» для конечных жанров;
    • genre – конечный жанр.
Пример выдачи дерева жанров:
<genres>
  <genre id="5003" title="Бизнес-книги" type="root">
    <genre id="5049" title="Банковское дело" token="bankovskoe_delo" 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>
  </genre>
  <genre id="5013" title="Юмористическая литература" type="root">
    <genre id="5201" title="Анекдоты" token="anekdoty" type="genre"/>
    <genre id="5202" title="Зарубежный юмор" token="zarubezhnyy" type="genre"/>
  </genre>
</genres>

8. Данные, передаваемые при подключении партнера

Данные, предоставляемые партнеру

Параметр

Пример значения

Описание

ID партнера

TEST

Строковой ID партнера. Обычно представлен четырьмя символами. Используется при запросе обновлений (см. 1.1. Формат запроса). Также используется при скачивании файла партнером типа «магазин на стороне партнера» (см. 2.1. Формат запроса).
Выдается партнеру тех. службой ЛитРес при заключении договора.

Секретный ключ

93w4jfhs8imksGo-oa3s85d6Akmkkbnsi9

Секретный ключ, используемый для SHA-подписи и требуемый при авторизации запросов от партнера к ЛитРес (см. 2.1. Формат запроса, 3.1. Формат запроса к серверу партнера, 4.1. Формат запроса-уведомления от партнера о продаже, 4.3. Формат URL на скачивание книг для пользователей партнера), а также от ЛитРес к партнерам (см. 3.1. Формат запроса к серверу партнера). Выдается партнеру тех. службой ЛитРес при заключении договора.

Пароль для доступа к статистике

8rdj-WKj

Пароль для доступа к статистике по работе партнера на стороне ЛитРес. Используется стандартное имя пользователя Admin и этот пароль. Для доступа к статистике используется домен для скачивания (см. выше). Выдается партнеру тех. службой ЛитРес при заключении договора.

Данные предоставляемые партнером (необходимо предоставить ДО подключения)

Параметр

Пример значения

Описание

Домен для скачивания (только для партнеров по схеме №2)

dnld_book.partner.ru

Доменное имя, принадлежащее партнеру и имеющее перенаправление (через CNAME запись в DNS) на partnersdnld.litres.ru. Позволяет полностью скрыть от простого пользователя участие ЛитРес в транзакции – все операции происходят на домене партнера. Партнер выбирает домен и сообщает его ЛитРес. В дальнейшем большая часть транзакций осуществляется партнером на этом домене (см. 4. Интерфейс уведомлений ЛитРес о партнерских продажах). partnersdnld.litres.ru может резолвиться на несколько IP – это нормально.

URL для редиректа при ошибках (только для партнеров по схеме №2)

https://www.partner.ru/dnld_err/?err=

При ошибках скачивания клиента сервер ЛитРес будет отправлять редирект на этот URL с добавлением кода ошибки в конец (см. 4.5. Скачивание книг на английском языке Adobe DRM (тип 11)). Передается партнером в тех. службу ЛитРес.

URL отдачи статистики (только для партнеров по схеме №1)

https://www.partner.ru/litresstats.php

По данному URL ЛитРес будет обращаться с периодичностью ~раз в 30 минут для получения статистики продаж партнера (см. 3. Интерфейс отдачи статистики продаж партнерами).

E-mail для контактов по техническим вопросам

developer@partner.ru

На этот адрес будут отправлены рассылки с информацией о нововведениях, простоях и другая подобная техническая информация. Помимо e-mail приветствуется указания Telegram/Skype/ICQ.

E-mail для контактов по административным вопросам

manager@partner.ru

Информация по изменениям в условиях работы, по продлению договора и другим организационным вопросам будет адресоваться на указанный e-mail.