Вап. Ыываыва

Интерфейс работы сторонних программ с каталогом магазина "ЛитРес"

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

Дата последнего обновления: 16 февраля 2015 г.

Постоянный URL актуальной версии данного документа: http://www.litres.ru/static/CataLitResAPI.zip

Аннотация

"ЛитРес" предоставляет простой, основанный на HTTP и XML, API, позволяющий любой программе:

-- Получать список авторов и жанров, размещенных на сайте "ЛитРес";

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

-- Скачивать ознакомительные фрагменты книг;

-- Авторизоваться на сайте "ЛитРес" используя логин и пароль пользователя, действовать от имени этого пользователя;

-- Запрашивать состояние счета пользователя, покупать книги;

-- Скачивать с "ЛитРес" приобретенные пользователем книги в формате fb2;

-- Пополнять счет пользователя (потребуются функции браузера);

-- Манипулировать с корзиной на сервере;

-- Сохранять и получать закладки, заметки и выделения в тексте;

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

Важное замечание

Эта документация не предназначена для партнеров, разрабатывающих собственные магазины. API создано исключительно для разработчиков, создающих клиентское ПО для работы с каталогом ЛитРес. Если вы создаете партнерский магазин - не пользуйтесь этим API, оно предназначено не для вас!

Скачайте документацию по подключению партнеров со следующего URL:

http://www.litres.ru/static/get_fresh_book.zip

и сразу после этого сотрите читаемый сейчас файл. Использование функционала из этого API в работе партнерских магазинов категорически запрещено.

Содержание

Интерфейс работы сторонних программ с каталогом магазина "ЛитРес"

Партнерская программа для разработчиков

"ЛитРес" готов сотрудничать с любыми разработчиками на основании партнерских условий, описанных на сайте "ЛитРес" по адресу http://www.litres.ru/pages/cms/?page=635. Заявку на партнерство можно оформить через стандартный интерфейс по адресу http://www.litres.ru/pages/reader_partner/ (укажите в комментарии, что вы будете разрабатывать ПО, желательно предоставить дополнительную информацию).

Например, при подключении по схеме "10% за два дня" партнер получит на свой счет 10% от стоимости всех покупок пользователей через его ПО и еще 10% от суммы всех покупок, которые данный пользователь совершит вне его программы в следующие 48 часов после покупки.

О том, как регистрировать покупки пользователей на определенного партнера подробно смотрите раздел 10.1 (конкретно параметр lfrom в запросе на покупку).

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

-- Работа с API сервера "ЛитРес" для любой программы-клиента строится по схеме запрос-ответ: клиент формирует и передает запрос, сервер в ответ возвращает XML-документ с ответом;

-- Все запросы от клиентов к серверу "ЛитРес" осуществляются на сервер robot.litres.ru по протоколу HTTP (1.0, 1.1) или HTTPS, для передачи параметров используется метод POST. При формировании поисковых запросов следует кодировать строки запроса в UTF-8 (!);

-- Если не оговорено иное, все ответы сервера передаются в виде XML, сжатого по алгоритму gzip (о чем сообщает стандартный заголовок HTTP-ответа Content-Encoding: gzip);

-- XML в ответах сервера всегда имеет кодировку UTF-8 (о чем сообщает HTTP-заголовок Content-type: text/xml; charset=utf-8);

-- В некоторых случаях клиент может и/или должен подключиться к серверу по стандартному HTTP, в обход API, например, для получения файла обложки в формате JPEG. Такие случаи оговариваются особо;

-- В некоторых случаях следует использовать только HTTPS. Такие случаи оговариваются особо;

-- XML, отдаваемый сервером ЛитРес может быть шире (и будет шире, по мере развития функционала), чем описано в данной документации. Приложение должно штатно обрабатывать избыточные или незнакомые узлы и/или атрибуты в XML. Все изменения, разумеется, обратно совместимы и то, что вы ожидаете найти, вы найдете в XML в том же виде на том же месте.

Авторы любых программ, добросовестно использующие данный API, могут рассчитывать на техническую и информационную поддержку со стороны "ЛитРес". По техническим вопросам обращайтесь на admin@litres.ru, по коммерческим на partners@litres.ru.

-- Регистрация пользователя

-- Предостережение от повторных регистраций

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

Пользователю ВСЕГДА следует первым делом предоставить возможность ввести имеющийся у него логин/пароль, а при необходимости, предложить восстановить забытый пароль (см. 4.1). И только если пользователь совершенно точно не имеет рабочего логина/пароля и/или категорически не может их восстановить, следует инициировать регистрацию.

Альтернативный метод состоит в том, чтобы по умолчанию авторизовать пользователя со сгенерированными автоматически данными, а впоследствии позволить ему поменять логин/пароль и автоматически объединить аккаунты (см. 2) в случае возникновения конфликта (см. ошибкой 1 в 1.4). Такая, чуть боле сложная, реализация, позволит предоставить пользователям комфортный сервис и при этом не создаст болезненных проблем. Без объединения авторегистрация недопустима.

-- Запрос на регистрацию

Для регистрации нового пользователя используется URL

http://robot.litres.ru/pages/catalit_register_user/

Этот URL обрабатывает параметры:

-- new_login - логин, под которым пользователь хочет зарегистрироваться. Этот параметр является обязательным;

-- new_pwd1 - запрошенный пароль. Этот параметр является обязательным;

-- mail - e-mail пользователя. Это необязательный параметр, но если он не был указан (или является неверным), пользователь не сможет восстановить свой пароль (см. 4.1). Рекомендуется, по возможности, побуждать пользователя указывать его e-mail и/или информировать о рисках, связанных с отсутствием e-mail;

-- first_name - имя;

-- middle_name - отчество;

-- last_name - фамилия;

-- city - город;

-- phone - номер телефона;

-- www - адрес в интернет;

-- birth_day - дата рождения в ISO-виде 1999-12-21;

-- male - пол, может принимать значения m-мужчина, f-женщина.

Если в качестве логина (new_login) был указан e-mail и/или e-mail пользователя был указан в поле mail, то при регистрации новый пользователь:

-- Получает 10 книг бесплатно (видны в разделах "Мои покупки"/"Все мои покупки" http://www.litres.ru/pages/my_books/ сразу после регистрации), если при регистрации не был передан параметр no_present_books со значением 1;

-- Подписывается на уведомления по e-mail о новых произведениях авторов, книги которых он покупал.

-- Ответ сервера в случае успеха регистрации

<catalit-authorization-ok first-name="Пётр" last-name="Петров" middle-name="Васильевич" login="petro" mail="petrov@petrov.ru" www="www.site.go" phone="8-333-44-22-33" city="Богуслав" can-rebill="0" male="m" now="2014-10-01 15:27:12" account="0.00" account_full="0.00" bonus="0.00" sid="aa16067ed749a33263ebd687ad4b13c6" user-id="134200089" books-cnt="89958" authors-cnt="34707" biblio_user="0" birth_day="1970-10-12"/>

Ответ сервера при успешной регистрации аналогичен ответу при успешной авторизации (см. 5.3), но, в отличие от авторизации, на указанный пользователем e-mail (параметр mail, см. 1.2) высылается подтверждение регистрации.

Ответ сервера включает новый уникальный SID клиента (@sid), а также ID и все регистрационные данные пользователя (@user-id, @first-name, @last-name и т.д.) и статистические данные по количеству книг, авторов и пользователей.

@user-id (ID пользователя) используется для отслеживания рецензий пользователя (см. 12), а также для журнализации взаимодействия пользователя с новостями и уведомлениями (см. 24.2).

Также, если в запросе были заданы параметры app и (опционально) d, то в ответе сервера будет содержаться узел @not_read, в котором в виде целочисленного числа будет содержаться количество полученных, но не прочитанных пользователем новостей (пуш-уведомлений).

-- Ответ сервера в случае ошибки регистрации

Если при регистрации пользователя произошла ошибка (например, логин пользователя уже занят), сервер возвращает сообщение об ошибке:

<catalit-registration-failed error="1" coment="Login is in use"/>

В атрибуте @coment словами описывается смысл ошибки, возможные значения атрибута @error приведены ниже:

-- 1 - запрошенный логин уже занят;

-- 2 - логин не указан;

-- 3 - пароль не указан;

-- 4 - e-mail некорректный;

-- 5 - слишком много регистраций с этого IP, попробуйте немного позднее (10 минут должно быть достаточно);

-- 6 - e-mail уже принадлежит другому пользователю;

-- 7 - повтор пароля не совпадает с паролем;

-- 8 - некорректный номер телефона;

-- 9 - телефон уже принадлежит другому пользователю;

-- 100 - прочие ошибки.

-- Объединение аккаунтов

-- Общая логика объединения аккаунтов

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

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

В какой-то момент пользователь вспоминает, что у него уже есть учетная запись на ЛитРес и у него возникает потребность получить доступ ко всему принадлежащему ему контенту. В этот момент можно объединить аккаунты, в т. ч. "прозрачно" для пользователя, и он, просто введя уже существующие e-mail/пароль, получит вместо ошибки "такая учетная запись уже существует, переименование невозможно" нормально работающий объединенный аккаунт.

-- Запрос на объединение аккаунтов

Для обновления данных в профиле пользователя используется следующий URL:

http://robot.litres.ru/pages/catalit_unite_user/

Этот URL обрабатывает три параметра;

-- sid - SID, идентифицирующий текущего пользователя. Пользователь, идентифицированный этим SID, останется в системе;

-- user_login - логин присоединяемого (уничтожаемого) аккаунта;

-- user_passwd - пароль от присоединяемого (уничтожаемого) аккаунта.

-- Ответ сервера в случае успеха объединения

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

<catalit-unite-user-ok sid="12245bf68c3d5f2cb81374b6fe058ed7" user-id="333" first-name="Пётр" last-name="Петров" middle-name="Васильевич" mail="petrov@petrov.ru" www="www.site.go" phone="8-333-44-22-33" city="Богуслав" books-cnt="2245" authors-cnt="2245" users-cnt="2245" can-rebill="0"/>

-- Ответ сервера в случае ошибки объединения

<catalit-unite-user-failed error="1" coment="Bad login/pass combination"/>

В атрибуте @coment словами описывается смысл ошибки. Возможные значения атрибута @error приведены ниже:

-- 1 - логин/пароль для присоединяемого аккаунта не корректны;

-- 2 - пустой логин;

-- 3 - пустой пароль;

-- 4 - присоединяемый аккаунт пользователя не найден;

-- 5 - объединение аккаунта библиотекаря запрещено;

-- 6 - объединение невозможно;

-- 100 - произошла внутренняя ошибка сервера.

-- Обновление данных в профиле пользователя

-- Запрос на обновление данных

Для обновления данных в профиле пользователя используется следующий URL:

http://robot.litres.ru/pages/catalit_update_user/

Этот URL обрабатывает параметры полностью аналогично 1.2, за исключением того, что параметр new_pwd1 не является обязательным и если он опущен, пароль не изменяется. Если параметр не задан, то он сбрасывается.

-- sid - SID, идентифицирующий пользователя;

-- curpass - текущий пароль. При обновлении пароля и/или e-mail параметр является обязательным.

-- Ответ сервера в случае успеха обновления

<catalit-updateuser-ok/>

-- Ответ сервера в случае ошибки обновления профиля

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

<catalit-updateuser-failed error="1" coment="Login is in use"/>

-- Восстановление пароля

-- Общая логика восстановления пароля

В случае утери пользователем пароля можно инициировать его восстановление. На сервере "ЛитРес" пароли пользователей не хранятся в открытом виде, поэтому восстановление фактически означает генерацию нового пароля и высылку этого нового пароля пользователю на e-mail.

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

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

-- Запрос на восстановление пароля

Для инициации восстановления пароля используется следующий URL:

http://robot.litres.ru/pages/catalit_recover_pass/

Этот URL обрабатывает один параметр:

-- mail - e-mail, который пользователь указал при регистрации.

-- Ответ сервера в случае успешного запроса

<catalit-pass-recover-ok/>

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

-- Ответ сервера в случае ошибки

<catalit-pass-recover-failed error="1" coment="Mail unknown"/>

В атрибуте @coment словами описывается смысл ошибки. Возможные значения атрибута @error приведены ниже:

-- 1 - запрошенный e-mail ни у одного пользователя не зарегистрирован, инициация смены пароля не произведена;

-- 2 - e-mail не указан;

-- 100 - произошла внутренняя ошибка сервера.

-- Авторизация на сервере "ЛитРес"

-- Общая логика авторизации

Авторизация на сервере "ЛитРес" осуществляется открытой передачей логина и пароля. При успехе авторизации сервер в ответ возвращает SID - уникальную строку длинной до 32-х символов. Все последующие запросы к серверу могут включать параметр sid, при этом запрос будет сделан не от имени анонимного пользователя, а от имени пользователя, для которого был сформирован этот SID. Если запрос не предполагает авторизации, sid просто игнорируется, поэтому хорошей практикой является передача sid в любом запросе к серверу.

В случае если при использовании SID в запросе опознать пользователя не удалось, а запрос предполагает авторизацию, сервер вернет соответствующий XML (см. 5.4) вместо нормального ответа. В этом случае следует произвести повторную авторизацию.

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

-- Запрос на авторизацию

Для запроса на авторизацию используется следующий URL:

http://robot.litres.ru/pages/catalit_authorise/

Этот URL обрабатывает параметры:

-- sid - SID, валидность которого проверяется;

-- login - имя пользователя, под которым требуется авторизоваться;

-- pwd - пароль для авторизации;

-- skip_ip - не обязательный параметр, позволяющий получить сессию, не привязанную к конкретному IP. Этот метод авторизации менее безопасен;

При запросе на авторизацию с указанием старого SID сервер вначале проверяет, является ли данный SID валидным, и если является, параметры login и pwd игнорируются - сессия продляется и прежний SID возвращается клиенту. Если sid не был передан или не является валидным - сервер пытается авторизовать пользователя с переданными ему логином и паролем.

Дополнительно можно указать еще параметры app и d, с помощью которых можно в ответе сервера узнать, сколько непрочитанных новостей (пуш-уведомлений) есть у данного пользователя (описание см. в разделе 24):

-- app - не обязательный параметр, в котором указывается ID приложения (значение данного идентификатора для вашего приложения вы можете узнать у менеджера ЛитРес);

-- d - не обязательный параметр (целое положительное число от 1 до 32), в котором указывается количество дней, за которое необходимо посмотреть количество не прочитанных новостей. Если параметр не указан, то по умолчанию он имеет значение "30".

-- Ответ сервера в случае успеха авторизации

<catalit-authorization-ok sid="12245bf68c3d5f2cb81374b6fe058ed7" not_read="4" user-id="333" first-name="Пётр" last-name="Петров" middle-name="Васильевич" mail="petrov@petrov.ru" www="www.site.go" phone="8-333-44-22-33" city="Богуслав" account="55.20" books-cnt="2245" authors-cnt="2245" users-cnt="2245" can-rebill="0" birth_day="1970-10-12" male="m"/>

Ответ сервера при успешной авторизации включает новый уникальный SID клиента (@sid), а также ID и все регистрационные данные пользователя (@user-id, @first-name, @last-name и т.д.) и статистические данные по количеству книг, авторов и пользователей.

-- Ответ сервера в случае ошибки авторизации

Ответ сервера при ошибке авторизации:

<catalit-authorization-failed/>

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

-- Одноразовая авторизация

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

-- Запрос одноразового токена

Для запроса такого токена используется следующий URL:

http://robot.litres.ru/pages/catalit_get_onetime_sid/

Этот URL обрабатывает один параметр:

-- sid - SID пользователя, валидность которого проверяется.

-- Ответ сервера в случае успеха

<catalit_get_onetime_sid otsid="12245bf68c3d5f2cb81374b6fe058ed7"/>

Полученный одноразовый токен @otsid можно использовать для авторизации пользователя в системе.

-- Ответ сервера в случае неудачи

<catalit_get_onetime_sid-failed/>

-- Получение списка жанров в каталоге "ЛитРес"

-- Запрос дерева жанров

Для получения списка жанров "ЛитРес" используется следующий URL:

http://robot.litres.ru/pages/catalit_genres/

Этот URL обрабатывает параметры:

-- lang - обязательный параметр, двухбуквенный код языка в нижнем регистре в формате ISO, в котором требуется получить название жанра genre/@title;

-- search_types - необязательный параметр. Искать жанры с перечисленными типами контента. Значения по умолчанию 0, 4. Можно указать несколько типов контента (аналог - несколько чекбоксов html формы).

-- Ответ сервера

Возвращается древовидный XML с жанрами. Для каждого оконечного жанра отдается @id (положительное целое, ID) и @title. Не-оконечные жанры не имеют @id, только @title, и им в каталоге не сопоставлены книги - это просто контейнеры для оконечных жанров.

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

Используя возвращенный сервером @id жанра, можно запрашивать книги, принадлежащие этому жанру (см. 8.1, параметр genre).

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

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

<catalit-genres>

</genre>

</genre>

</catalit-genres>

-- Получение списка авторов в каталоге "ЛитРес"

-- Запрос списка авторов

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

http://robot.litres.ru/pages/catalit_persons/

Этот URL обрабатывает параметры:

-- person - UUID автора/переводчика/редактора/etc. Если автор с таким UUID есть, будет возвращен соответствующий XML. Допускается передача нескольких параметров person, будут выданы личные карточки по всем указанным авторам;

-- hub_id - внутренний ID автора/переводчика/редактора/etc. в каталоге "ЛитРес". Может быть передано несколько значений параметра, перечисленных через запятую;

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

-- search_last_name - поисковый запрос на фамилию автора. Поддерживаются плэйсхолдеры SQL (%_). Наиболее полезен, видимо, для алфавитного поиска по авторам, например можно сделать запрос `a%' или `аб%', чтобы получить список авторов, чья фамилия начинается на "А" и "Аб" соответственно;

-- rating - ненулевое значение в этом параметре указывает, что следует выбрать популярных авторов по рейтингам "ЛитРес". Возвращается 50 авторов. Прочие параметры поиска накладываются на этот список;

-- rating_period - необязательный параметр, при выборке популярных авторов по рейтингам "ЛитРес", указывает период. 2 (по умолчанию) - за неделю, 3 - за месяц, 4 - за год, 5 - за всё время.

-- search_types - искать авторов, имеющих контент перечисленных типов

0	Электронный текст
1	Аудиокнига
2	Мультимедиа-книга
3	Устройство для чтения
4	PDF-книга
5	Print-on-Demand-книга
6	База данных
7	Видео
8	Компьютерная игра
9	Софт
11	Книги Gardners (Adobe DRM)

Значение по умолчанию 0. Можно указать несколько типов контента (аналог - несколько чекбоксов html формы).

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

-- Ответ сервера

Сервер возвращает XML с информацией о найденных авторах:

<catalit-persons>

<title>

<main>Дарья Донцова</main>

</title>

<arts-count>178</arts-count>

<first-name>Дарья</first-name>

<middle-name/>

<last-name>Донцова</last-name>

<last-rodit>Донцовой</last-rodit>

<last-dateln>Донцовой</last-dateln>

<last-vinit>Донцову</last-vinit>

<last-tvorit>Донцовой</last-tvorit>

<last-predl>Донцовой</last-predl>

<full-rodit>Дарьи Донцовой</full-rodit>

<full-dateln>Дарье Донцовой</full-dateln>

<full-vinit>Дарью Донцову</full-vinit>

<full-tvorit>Дарьей Донцовой</full-tvorit>

<full-predl>Дарье Донцовой</full-predl>

<inverse-full-name>Донцова Дарья</inverse-full-name>

<text_descr_html>

Дарья Донцова уже несколько лет является королевой

<a href="/detektivy/ironicheskiy-detektiv/">иронического детектива</a>.

За свою писательскую деятельность она написала более ста двадцати

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

Все книги Дарьи Донцовой, написанные с 1999 по 2011 год, стали

бестселлерами.

</hidden>

</text_descr_html>

<photo>http://robot.litres.ru/static/authors/100/44336.jpg</photo>

<recenses-count>26</recenses-count>

</subject>

</catalit-persons>

Атрибут catalit-persons/subject/@id может быть использован при запросе книг данного автора (см. 8.1, параметр person).

Узел catalit-persons/subject/title/main дает полное имя автора в общепринятом написании, например многие авторы известны по фамилии и имени, без отчества.

Также передаются следующие данные:

-- first-name - имя;

-- middle-name - отчество;

-- last-name - фамилия автора;

-- last-rodit - фамилия автора (родительный падеж);

-- last-dateln - фамилия автора (дательный падеж);

-- last-vinit - фамилия автора (винительный падеж);

-- last-tvorit - фамилия автора (творительный падеж);

-- last-predl - фамилия автора (предложный падеж);

-- full-rodit - полное имя автора (родительный падеж);

-- full-dateln - полное имя автора (дательный падеж);

-- full-vinit - полное имя автора (винительный падеж);

-- full-tvorit - полное имя автора (творительный падеж);

-- full-predl - полное имя автора (предложный падеж);

-- inverse-full-name - полное имя автора в обратном порядке слов;

-- photo - ссылка на фотографию автора;

-- level - уровень автора; имеет цифровое целое значение от 0 до 9 и отражает степень известности/популярности данного автора (чем больше значение, тем более значим автор в литературном мире);

-- arts-count - количество доступных книг (тип книг задаётся в запросе через параметр search_types, значение по умолчанию "0" (ноль) - электронные книги);

-- recenses-count - количество отзывов об авторе.

-- Получение данных из каталога "ЛитРес"

-- Запрос на просмотр каталога

Для получения данных из каталога используется запрос на URL:

http://robot.litres.ru/pages/catalit_browser/

Этот URL обрабатывает параметры:

-- sid - указывает, от имени какого пользователя следует произвести запрос (учитывается при использовании параметров my, basket);

-- my - ненулевое значение в этом параметре указывает, что следует ограничить выборку уже приобретенными книгами. "Скрытые" книги при таком запросе не возвращаются, а содержимое всех остальных полок (см. параметр my_folder далее) - возвращается. При использовании этого параметра обязательно предоставить валидный SID (см. 5 и 1.3);

-- my_folder - ID пользовательской "папки", к которой принадлежат книги. Помимо полок имеющих ID (работа с полками описана в разделе 19) есть "спец-полка" 0, обозначающая "скрытые книги". Такие книги не отдаются на запрос полного списка моих книг "my", их список можно получить только явно сделав запрос к полке 0. Спец-полка "-1" это "книги, не лежащие ни на какой полке". Каждая книга может находиться только на одной полке (т.е. полки это полки, а не теги). При использовании параметра my_folder параметр my игнорируется, возвращаются только "мои книги" принадлежащие к указанной полке. При использовании этого параметра обязательно предоставить валидный SID (см. 5 и 1.3);

-- my_incremental - инкрементальная подгрузка "моих книг". Передавать следует время (в формате ISO, например, "2015-02-16 16:51:30"), начиная с которого необходимо подгрузить изменения. Отдает только книги, по которым было какое-то движение после указанного времени, в том числе книги, принадлежащие полке 0 (скрытые). Такой подход, в сочетании с атрибутом @in_folder (см. ниже), позволит инкрементально подгружать и скрывать книги в клиентском приложении;

-- basket - ненулевое значение в этом параметре указывает, что следует ограничить выборку книгами, находящимися в корзине. При использовании этого параметра обязательно предоставить валидный SID (см. 5 и 1.3);

-- in_gifts - ненулевое значение в этом параметре указывает, что следует ограничить выборку книгами, которые доступны по подписке (под подпиской здесь подразумевается "раздача слонов" - когда пользователь по акциям/купонам получает доступ к некоторой, заранее предопределенной, группе книг, часть из которых можно взять себе бесплатно);

-- collection - ID коллекции. Будут выданы только книги из указанной коллекции;

-- person - UUID автора/переводчика/редактора/etc. Будут выданы только книги, в которых этот автор числится одним из создателей (в любом качестве). Допускается передача нескольких значений UUID, разделенных запятой. При этом будут выданы все книги по всем указанным авторам. Если параметр не указан, отбор по автору не осуществляется. О способах получения UUID автора см. 7;

-- genre - ID жанра. Целое положительное число (о возможных значениях см. 6).
В запросе можно передать сразу несколько ID жанров, указав каждый из них в отдельном параметре genre. Пример запроса:
http://robot.litres.ru/pages/catalit_browser/?genre=6225&genre=6329&genre=6195&search_types=0;

-- lang - язык книги, двухбуквенный код в формате ISO;

-- search - поисковая строка. Поиск по названию, автору и названию серии. Поиск ведется по полному совпадению искомого фрагмента;

-- search_inside - не пустое значение указывает, что нужно дополнительно искать и в середине слова. Используется совместно с search;

-- search_types - искать в перечисленных типах контента:

0	Электронный текст
1	Аудиокнига
2	Мультимедиа-книга
3	Устройство для чтения
4	PDF-книга
5	Print-on-Demand-книга
6	База данных
7	Видео
8	Компьютерная игра
9	Софт
11	Книги Gardners (Adobe DRM)

Значение по умолчанию: "0". Можно указать несколько типов контента, перечислив значения через запятую (аналог - несколько чекбоксов html формы);

-- search_title - аналогично search, но ищет только по названию произведения и имени серии; аннотация игнорируется;

-- art - внутренний ID книги в каталоге "ЛитРес" (см. 8.2, catalit-fb2-books/fb2-book/@hub_id), аналогично параметру person может быть передано несколько значений параметра, перечисленных через запятую. При этом из каталога будут возвращены только книги с соответствующими внутренними ID (если есть);

-- uuid - уникальный ID книги (хранится в поле document-info/@id fb2-файла). Работает аналогично art, но при этом опирается не на внутренний ID книги в БД, а на универсальный ID книги;

-- search_person - аналогично search, но ищет только по имени (Ф.И.О.) автора;

-- rating - Выбирает книги соответственно рейтингам "ЛитРес". Возможные значения:

-- hot - горячие новинки;

-- with - книги, которые читают вместе с указанной в art или uuid (допускается только одна книга);

-- talk - список обсуждаемой литературы.

В этих случаях параметры поиска накладываются на полученный список;

-- linked_to - Выбирает книги, связанные с данной книгой. Если передан параметр linked, то следует также передать параметр art (с какой книгой искать связи) и type, который может принимать значения из таблицы:

1	Предыдущий выпуск
2	Следующий выпуск
3	Перевод с
4	Перевод
5	Сборник
6	Часть
7	Переиздание
8	Другой носитель
9	Неопределенная
10	Продолжение
11	Предыстория
12	Аксессуар
13	Подходит к
14	Другой цвет

-- rating_period - необязательный параметр. При выборке популярных книг по рейтингам "ЛитРес", указывает период.

-- 1 - за день;

-- 2 (по умолчанию) - за неделю;

-- 3 - за месяц;

-- 4 - за год.

-- min_person_rating - минимальный рейтинг автора. Например, в разделе новинок на сайте litres.ru выводятся книги, у которых рейтинг авторов больше или равен 6;

-- tag - тег, которым должны быть помечены книги (см. 8.2, catalit-fb2-books/fb2-book/art_tags/tag/@id);

-- sequence - ID серии для книги хранится в catalit-fb2-books/fb2-book/sequences/sequence/@id;

-- limit - ограничение на число возвращаемых книг. Работает аналогично инструкции limit в MySQL: limit состоит из двух чисел N,M (разделенных запятой). Если limit указан, возвращается M книг, начиная с книги N (у первой книги номер 0). При этом в ответе сервера присутствует атрибут catalit-fb2-books/@pages. Если limit не задан -- значение по умолчанию '0,200';

-- sort - сортировать выдачу явно указанным образом. Каждый режим сортировки имеет две версии - asc и desc (по возрастанию и по убыванию). Возможные значения:

time_asc time_desc	По времени поступления, затем по названию
title_asc title_desc	По названию
pop_asc pop_desc	По популярности, затем по времени поступления, затем по названию

Запрос с широким поиском вернет вам список произведений, который может оказаться весьма объемным. Будьте осторожны с пустыми поисковыми запросами, а на бедных ресурсами системах всегда используйте limit и организуйте доступ к данным постранично (см. атрибут catalit-fb2-books/@pages и catalit-fb2-books/@records в разделе 8.2).

-- Ответ сервера

Сервер возвращает XML со списком книг, подпадающих под запрошенную выборку. Пример возвращаемого XML:

<catalit-fb2-books now="2009-01-14 16:39:16" account="158.13" pages="5" records="11" not_read="4">

<fb2-book hub_id="165361" added="2009-01-14 16:37:59" base_price="29.63" price="28.99" updated="2009-01-14 16:37:59" chars="701266" images="1" zip_size="418054" has_trial="1" cover="http://robot.litres.ru/pages/show_cover/?file=132272&type=jpg" cover_ preview="http://robot.litres.ru/pages/show_cover/?file=132272&type=jpg" url="http://robot.litres.ru/pages/biblio_book/?art=165361" rating="9" type="0" drm="0" copyright="Эксмо" trial_id="198020" in_gifts="1" items_left="5" recenses="33" in_folder="-1">

<text_description>

<title-info>

<genre>child_sf</genre>

<genre>sf_fantasy</genre>

<first-name>Эдуард</first-name>

<last-name>Веркин</last-name>

</author>

<book-title>Кошки ходят поперек</book-title>

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

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

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

Там хранится самый последний дракон. Если кормить его мясом и поить кровью, из него получится убийца. Если яблоками и мюсли - вырастет друг. Но и в том и в другом случае дракон - пропуск в Страну Мечты. Которая существует на самом деле...

</annotation>

</coverpage>

</title-info>

<document-info>

<nickname>Jerald</nickname>

</author>

<program-used>doc2fb, FB Editor v2.0</program-used>

<src-url>http://robot.litres.ru/</src-url>

<src-ocr>Текст книги предоставлен издательством "Эксмо"</src-ocr>

v. 1.0 - создание fb2-документа из издательского текста - Jerald

</history>

</document-info>

<publish-info>

<book-name>Веркин Э. Кошки ходят поперек: Роман</book-name>

<publisher>Эксмо</publisher>

</publish-info>

</hidden>

</text_description>

<files>

</group>

</group>

</group>

</files>

<art_tags>

</art_tags>

</fb2-book>

</catalit-fb2-books>

Корневой элемент catalit-fb2-books имеет атрибут @now, содержащий текущее время сервера, и, если была проведена успешная авторизация, атрибут @account с состоянием счета пользователя (в рублях). При последующих запросах значение @now можно использовать в качестве чекпойнта, что гарантирует полноту получения новинок при минимальном трафике и расчетах. Атрибут @pages, если он присутствует, указывает, что ответ включает не все найденные записи и содержит число страниц в результатах выборки, а также будет присутствовать атрибут @records, содержащий общее число найденных записей.
Если присутствует атрибут @not_read (для этого в запросе должны быть заданы параметры app и, опционально, d), то в нем, в виде целочисленного числа, будет содержаться количество полученных, но не прочитанных пользователем новостных сообщенией (описание пуш-уведомлений см. в разделе 8.2).

Управление числом возвращаемых результатов и номером страницы осуществляется параметром limit (см. 8.1).

В catalit-fb2-books хранится список произведений, каждое представлено тегом fb2-book со следующим содержимым:

-- fb2-book/@hub_id - внутренний ID книги в библиотеке;

-- fb2-book/@added - время размещения книги в библиотеке;

-- fb2-book/@updated - время последнего обновления книги (мог меняться файл, могла измениться цена или еще что-то);

-- fb2-book/@base_price - цена (в рублях) на данную книгу без скидок;

-- fb2-book/@price - цена (в рублях) на данную книгу с учётом скидки, эта сумма списывается с пользователя при покупке. Если скидок на книгу нет, то @price = @base_price;

-- fb2-book/@chars - число символов в книге;

-- fb2-book/@images - число картинок в книге;

-- fb2-book/@zip_size - размер ZIP-файла с fb2, который будет отдан клиенту;

-- fb2-book/@has_trial - ненулевое значение указывает, что для этой книги можно скачать ознакомительный фрагмент (см. 11.1);

-- fb2-book/@user_cloud - признак книги загруженной пользователем; заполняется при действительном параметре запроса my. Возможные значения: 0 - не загружен пользователем, 1 - загружен пользователем;

-- fb2-book/@cover - URL файла обложки (полноразмерного) на сервере. Извлекается простым HTTP-запросом;

-- fb2-book/@cover_preview - URL унифицированного превью обложки в формате JPEG, имеющего фиксированную ширину в 89 пикселей. Извлекается простым HTTP-запросом;

-- fb2-book/@url - URL страницы книги в магазине "ЛитРес". На эту страницу можно отправить пользователя за дополнительной информацией; также эту страницу можно отобразить в программе-клиенте;

-- fb2-book/@rating - рейтинг произведения по десятибалльной шкале (0-10);

-- fb2-book/@type - тип контента. Возможные значения описаны в разделе 8.1, в описании параметра search_types;

-- fb2-book/@drm - наличие DRM (0 - нет, 1 - есть);

-- fb2-book/@copyright - наименование правообладателя;

-- fb2-book/@trial_id - для произведений не-текстового типа ID файла с ознакомительным фрагментом. Используется при получении ознакомительного фрагмента, см. 11.2;

-- fb2-book/@basket - признак, означающий наличие книги в корзине. Допустимые значения: 0 - книги нет в корзине, 1 - книга в корзине, 2 - книга отложена;

-- fb2-book/@in_gifts - признак доступности книги по подписке. Допустимые значения: 0 - книга недоступна по подписке, 1 - книга доступна по подписке (под подпиской здесь подразумевается "раздача слонов" - когда пользователь по акциям/купонам получает доступ к некоторой, заранее предопределенной, группе книг, часть из которых можно взять себе бесплатно);

-- fb2-book/@recenses - число рецензий на книгу;

-- fb2-book/@items_left - количество книг, которые можно приобрести по подписке ("раздаче слонов") из подписной коллекции, к которой относится данная книга;

-- text_description/hidden - содержимое узла FictionBook/description fb2-файла книги, подробно смотрите в описании формата. Наиболее интересны поля:

-- title-info/book-title - название книги;

-- title-info/annotation - аннотация книги;

-- title-info/sequence - серия, если книга серийная;

-- title-info/author - автор;

-- title-info/reader - чтец.

-- fb2-book/files - (актуально для контента с типом 1,2,4; типы рассмотрены в описании параметра search_types) - список мультимедиа-файлов, связанных с данным произведением. Файлы сгруппированы по типу "кодирования" (fb2-book/files/group/@value), для каждого произведения может быть несколько альтернативных форм. Например, для одной книги может быть две группы файлов: "Стандартное качество. MP3, 192 Kbps" и "Мобильная версия. MP4, 16 Kbps". Обе группы файлов дублируют одно и то же содержание, но при этом предоставляют его в разных форматах.
Название групп fb2-book/files/group/@value могут принимать следующие значения:

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

-- Ознакомительный фрагмент. MP3, 128 Kbps;

-- Копия оригинального диска. MP3-файлы в самораспаковывающемся RAR-архиве;

-- Стандартное качество. MP3, 128 Kbps;

-- Мобильная версия. MP4, 16 Kbps;

-- Стандартное качество. MP3, 192 Kbps;

-- Мобильная версия. MP4, 32 Kbps;

-- Стандартное качество. MP3, 64 Kbps;

-- Дополнительные материалы;

-- Мобильная версия. MP4, 64 Kbps;

-- MP3 файлы в zip архиве;

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

-- Ознакомительный фрагмент pdf;

-- PDF-книга;

-- Обложка в PDF (PoD);

-- Дополнительные материалы;

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

Для каждого файла из группы указывается:

-- @id - численный ID файла. При скачивании мультимедиа-файлов пользователем (см. 4.6) этот 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-файл:

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

-- @file_description - краткое описание типа файла;

-- fb2-book/files/file - (актуально для контента с типом 0 и 11; типы рассмотрены в описании параметра search_types) - список типов файлов с указанием размера файла, содержащего электронный текст книги. Для каждого типа файла указывается:

-- @type - тип файла.
Возможные значения для контента типа 0:

-- fb2.zip;

-- rtf.zip;

-- a6.pdf;

-- a4.pdf;

-- html.zip;

-- txt.zip;

-- rtf.zip;

-- doc.prc.zip;

-- rb;

-- epub;

-- mobi.prc;

-- txt;

-- lrf;

-- isilo3.pdb;

-- lit;

-- ios.epub;

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

-- epub;

-- a4.pdf;

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

-- @size - размер файла в байтах (не указывается для типа 11).

-- fb2-book/art_tags/tag - "теги" для данного произведения. Каждый тег имеет два атрибута:

-- @id - ID тега. В дальнейшем можно передавать его в качестве параметра tag в запрос (см. 8.1) на поиск книг, что позволит получить все книги, помеченные тегом;

-- @tag_title - текст тега;

-- fb2-book/@in_folder - ID папки, в которой находится данная книга (см. параметр my_folder в разделе 8.1 и весь раздел 19).

-- Получение списка книг из рекомендательного рейтинга "ЛитРес"

-- Запрос списка книг из рекомендательного рейтинга

Основываясь на данных о книгах, купленных, оцененных или просмотренных конкретным пользователем, а также на других специфических параметрах, на стороне "ЛитРес" происходит определение набора книг, которые могут быть интересны пользователю. Из этого набора и формируется индивидуальный рекомендательный рейтинг для каждого из пользователей.

Для получения списка рекомендованных книг используется следующий URL:

http://robot.litres.ru/pages/catalit_browser/?rating=posrednik

Этот URL обрабатывает параметры:

-- sid - (обязательный параметр) SID пользователя, для которого необходимо получить список рекомендованных книг;

-- app - (обязательный параметр) ID приложения, в котором планируется показывать рекомендуемые книги. Этот параметр выполняет роль "фильтра" и позволяет получать список только тех книг, которые совместимы с конкретным приложением. Например, если приложение поддерживает только FB2 и ePub книги, то в рекомендацию не попадут аудиокниги, книги с DRM-защитой и др.
Значение данного идентификатора для вашего приложения вы можете узнать у менеджера ЛитРес;

-- limit - ограничение на число возвращаемых книг. Работает аналогично инструкции limit в MySQL: limit состоит из двух чисел N,M (разделенных запятой). Если limit указан, возвращается M книг, начиная с книги N (у первой книги номер 0). Если limit не задан - значение по умолчанию '0,200'.

-- Ответ сервера

Сервер возвращает XML с информацией о книгах, рекомендуемых для указанного пользователя. Формат ответа полностью совпадает с ответом на запрос данных из каталога ЛитРес (см. 8.2).

-- Покупка книги

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

-- Запрос на приобретение книги

Запрос отправляется на следующий URL:

http://robot.litres.ru/pages/purchase_book/

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

-- sid - SID, идентифицирующий пользователя (см. 5);

-- art - ID книги, которую следует приобрести (см. 8.2, атрибут /fb2-book/@hub_id);

-- uuid - UUID книги (см. 8.2, атрибут /fb2-book/text_description/document-info/id);

-- lfrom - ID партнера (положительное целое), которому следует зачесть данную покупку. Данный ID выдается партнеру "ЛитРес" после подачи заявки на партнерство. Подробнее об условиях партнерской программы "ЛитРес" см. в разделе "Партнерская программа для разработчиков";

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

Параметры uuid и art являются взаимозаменяемыми.

Если параметр uuid пропущен, а art также пропущен (или равен нулю), возвращается сообщение об успешной покупке книги с ID=0 и состояние счета. Такой пустой запрос на покупку можно использовать для получения текущей информации о состоянии счета пользователя и о статусе SID (проверка, является ли он на данный момент валидным).

-- Ответ об успешной покупке книги

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

<catalit-purchase-ok account="110.02" art="165361"/>

В ответ включается текущее состояние счета пользователя @account и ID приобретенной книги @art.

-- Ошибка при покупке книги

Если произошла ошибка авторизации, будет возвращен стандартный код ошибки авторизации (см. 5).

Если по какой-либо другой причине покупка книги не удалась, клиенту возвращается статус ошибки:

<catalit-purchase-failed error="1" coment="Not enough money" account="110.02"/>

В атрибуте @coment словами описывается смысл ошибки. Возможные значения атрибута @error приведены ниже:

-- 1 - недостаточно средств на счете;

-- 2 - книга отсутствует в продаже;

-- 3 - книга уже куплена этим пользователем;

-- 4 - неверный идентификатор партнёра;

-- 100 - внутренняя ошибка сервера.

-- Получение купленного файла из каталога "ЛитРес"

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

-- Запрос на получение файла для книги типа 0 (fb2)

Запрос отправляется на следующий URL:

http://robot.litres.ru/pages/catalit_download_book/

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

-- sid - SID, идентифицирующий пользователя (см. 5);

-- art - ID книги, которую следует отдать (см. 8.2, атрибут /catalit-fb2-books/fb2-book/@hub_id);

-- uuid - UUID книги (см. 8.2, атрибут /catalit-fb2-books/fb2-book/text_description/hidden/document-info/id);

-- type - тип файла. Необязательный параметр, по умолчанию считается fb2.zip. Может принимать следующие значения:

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

-- .lrf - формат, который понимают Sony Reader-ы;

-- .mobi.prc - файлы для моби-ридера. В данный момент особенно примечательны тем, что работают на Amazon Kindle, хотя для моби есть очень хорошие читалки для PalmOS, Windows Mobile и настольных компьютеров.

Параметры uuid и art являются взаимозаменяемыми.

-- Запрос на получение файла для книг типов 1, 2, 4

Запрос отправляется на следующий URL:

http://robot.litres.ru/download_my_book/<art>/<file>.pdf?sid=SID

При этом следует передать обязательный параметр sid - SID, идентифицирующий пользователя (см. 5);

URL формируется с использованием ID книги и ID файла:

-- <art> - ID книги, которую следует отдать (см. 8.2, атрибут /catalit-fb2-books/fb2-book/@hub_id);

-- <file> - ID файла книги, которую следует отдать (см. 8.2, атрибут /catalit-fb2-books/fb2-book/files/group/file/@id).

Например, для книги с ID 555 можно скачать файл 777 по URL вида:

http://robot.litres.ru/download_my_book/555/777.pdf?sid=mycoolsid

Имейте в виду, что одной книге не текстового типа, например PDF-книге, может соответствовать несколько файлов (например, Volume1.pdf, Volume2.pdf), а для аудиокниг может присутствовать множество mp3-файлов и т.д.

Каждая группа внутри тега files имеет идентификатор group_id.

group_id	Описание	Тип книги
1	Ознакомительный фрагмент. MP3, 128 Kbps.	1
2	Копия оригинального диска. MP3-файлы в самораспаковывающемся RAR-архиве.	1
3	Стандартное качество. MP3, 128 Kbps.	1
4	Мобильная версия. MP4, 16 Kbps.	1
5	Стандартное качество. MP3, 192kbps.	1
6	Мобильная версия. MP4, 32 Kbps.	1
7	Стандартное качество. MP3, 64 Kbps.	1
8	Дополнительные материалы.	1
9	Ознакомительный фрагмент PDF.	4
10	PDF-книга.	4
11	Обложка в PDF (PoD).	4
12	PDF-файл.	5
13	Обложка в PDF (PoD).	5
14	Ознакомительный фрагмент PDF.	5
15	Дополнительные материалы.	4
16	Архив с игрой.	8
17	Скриншот.	8
18	Архив с базой данных.	6
19	Мобильная версия. MP4, 64 Kbps.	1

-- Отдача сервером файла книги

В случае успешной авторизации (см. 5) в ответ на запрос будет передан файл. При этом в заголовке будет указан тип содержимого, например application/zip для файла fb2. Так же передается поле Content-Disposition: attachment; filename="file-name.ext" с указанием рекомендованного имени файла для книги. Пример ответа сервера:

HTTP/1.0 200 OK

Server: nginx/0.6.29

Date: Thu, 15 Jan 2009 12:46:25 GMT

Content-Type: application/zip

Content-Length: 13095

Last-Modified: Wed, 04 Jun 2008 20:00:24 GMT

Content-Disposition: attachment; filename="Garrison_G._Kapitan_Bork.fb2.zip"

-- Ошибки при скачивании файла книги

При скачивании возможны ошибки. В этом случае сервер возвращает в заголовке тип содержимого, отличный от application/zip. При нефатальных ошибках сервера вам будет возвращен XML-код, содержащий дополнительную информацию об ошибке. Возможные варианты ответа сервера с информацией об ошибке:

<catalit-authorization-failed/>

Ошибка авторизации (об этой ошибке см. 5, особенно раздел 5.4)

<catalit-download-failed error="1" coment="Book not purchased"/>

<catalit-download-failed error="100" coment="File not found, internal error"/>

Ошибка скачивания книги. В поле @coment передается текстовое описание ошибки, в поле @error - код ошибки. Возможные численные ID ошибок:

-- 1 - попытка скачать книгу, которая не была приобретена данным читателем;

-- 2 - исчерпан лимит загрузок для данной книги;

-- 100 - внутренняя ошибка сервера.

Если тип содержимого ответа не соответствует ожидаемому и не text/xml, то это означает, что произошла внутренняя непредвиденная ошибка сервера и содержимое ответа неопределенно. В зависимости от типа запрошенного файла, корректные content-type для разных типов контента следующие:

0	zip application/zip fb2 text/xml html text/html rb application/x-rocketbook pdb chemical/x-pdb lit reader/x-lit pdf application/pdf
1	mp3 audio/mpeg m4b audio/m4b zip application/zip rar application/x-rar-compressed exe application/x-rar-compressed
2	zip application/zip rar application/x-rar-compressed exe application/x-rar-compressed
4	pdf application/pdf

-- Получение ознакомительного фрагмента

Для многих книг в каталоге доступна возможность скачивания ознакомительного фрагмента книги. Ознакомительный фрагмент предоставляется в виде валидного fb2-файла в zip-архиве. Обычно фрагмент составляет первые 25% текста всей книги (от начала и далее). Ознакомительный фрагмент включает обложку, все иллюстрации и сноски, относящиеся к фрагменту. Таким образом, технически это вполне полноценная книга.

О том, доступен ли для книги ознакомительный фрагмент, можно узнать из атрибута fb2-book/@has_trial (см. 8.2).

-- Запрос на получение ознакомительного фрагмента для книг типа 0 (fb2)

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

-- Дополнить нулями ID книги до получения 8-ми знаков вида XXYYZZNN (например, 00123456; нули дописываются перед ID);

-- Из полученного номера создать путь XX/YY/ZZ/XXYYZZNN.fb2.zip/ (например, 00/12/34/00123456.fb2.zip);

-- Добавить полученную строку к адресу http://robot.litres.ru/static/trials/

В данном случае, для книги с ID 123456 ознакомительный фрагмент будет доступен по адресу http://robot.litres.ru/static/trials/00/12/34/00123456.fb2.zip

-- Запрос на получение ознакомительного фрагмента для книг типов 1, 2, 4

Получить ознакомительный фрагмент можно по адресу:

http://robot.litres.ru/pages/download_prew/

Запрос принимает один обязательный параметр:

-- file - ID файла книги, которую следует отдать (см. 8.2, атрибут /fb2-book/@trial_id).

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

-- Отдача сервером ознакомительного файла для книги

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

HTTP/1.0 200 OK

Server: nginx/0.6.29

Date: Wed, 11 Feb 2009 15:16:40 GMT

Content-Type: application/zip

Content-Length: 80060

Last-Modified: Wed, 11 Feb 2009 15:15:29 GMT

Accept-Ranges: bytes

-- Работа с рецензиями

-- Запрос на получение рецензий

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

http://robot.litres.ru/pages/catalit_get_recenses/

При этом следует передать один из следующих параметров (любой из них на выбор):

-- art - ID книги, для которой нужно получить рецензии (см. 8.2, атрибут /fb2-book/@hub_id);

-- person - UUID автора, для которого нужно получить рецензии (см. 8.2, /catalit_persons/subject/@id);

-- sid - SID, идентифицирующий пользователя (см. 5). Влияет на адекватность атрибута recense/@already_voted, подробности см. ниже.

-- Ответ сервера

Сервер возвращает XML со списком рецензий, соответствующих указанному автору/книге. Пример возвращаемого XML:

<catalit-recenses>

<book-recenses>

<text_recense>

Книги замученных в фашистских застенках писателей меня всегда привлекали. Чем так они насолили гадам!? Не диверсанты и не шпионы, всего лишь писатели.

Когда прочитал первые Андреевские романы "Паутина" и "2048", то понял почему писатели так опасны.

Они пробуждают от инфантильного сна. А это страшное преступление против потребительского общества.

</hidden>

</text_recense>

</recense>

</book-recenses>

</catalit-recenses>

Каждая рецензия представлена тегом recense со следующим содержимым:

-- recense/@id - внутренний ID рецензиикниги в библиотеке;

-- recense/@added - дата добавления рецензиикниги в библиотеке;

-- recense/@login - логин пользователякниги в библиотеке;

-- recense/@user - внутренний ID пользователя (см. 5.3 о том, как узнать ID текущего пользователя и отличить свои рецензии)книги в библиотеке;

-- recense/@answer_to - ответ на рецензию - указан ID родительской рецензиикниги в библиотеке;

-- recense/@caption - заголовок рецензиикниги в библиотеке;

-- recense/@votes_good - число голосов "за" рецензию;

-- recense/@votes_bad - число голосов "против" рецензии;

-- recense/@already_voted - признак, который указывает, голосовал ли текущий пользователь за рецензию или нет (0 - не голосовал; 1 - голосовал). Данный признак будет адекватно работать только при указанном SID;

-- recense/text_recense/hidden - текст рецензии в виде HTMLкниги в библиотеке.

В случае отсутствия рецензий или неправильного идентификатора список рецензий пуст.

-- Добавление рецензии

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

-- Запрос на добавление рецензии

Запрос отправляется на следующий URL:

http://robot.litres.ru/pages/catalit_add_recense/

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

-- sid - SID, идентифицирующий пользователя (см. 5);

-- art - ID книги для которой добавляется рецензия (см. 8.2, атрибут /catalit-fb2-books/fb2-book/@hub_id). Допускается список из нескольких книг, разделённых ";";

-- author - UUID автора, для которого нужно добавить рецензию (см. 7.2, /catalit_persons/subject/@id). Рецензия может быть добавлена или на книгу или на автора;

-- caption - заголовок рецензии (необязательно);

-- message - текст рецензии;

-- nickname - имя, от которого создаётся рецензия (необязательно);

-- mail - e-mail пользователя. Это обязательный параметр при добавлении рецензии/отзыва.

-- Ответ сервера

В случае успеха возвращается ответ вида:

<catalit-add-recenses-ok/>

В случае ошибки авторизации:

<catalit-authorization-failed/>

Или:

<catalit-add-recenses-fail error="Текст сообщения об ошибке"/>

-- Оценка рецензии

Читатель может "оценить" любую рецензию как "годную" или "негодную" (см. реализацию на сайте и атрибуты recense/@votes* и recense/@already_voted в разделе 12.2). Отправлять оценку читатель может один раз, последующие голосования игнорируются, поэтому приложению не рекомендуется давать пользователю возможность голосовать повторно (см. recense/@already_voted выше).

-- Запрос на выставление оценки рецензии

Запрос отправляется на следующий URL:

http://robot.litres.ru/pages/catalit_vote_recense/

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

-- sid - SID, идентифицирующий пользователя (см. 5);

-- rec_id - ID рецензии, за которую пользователь голосует (см. 12.2, атрибут recense/@id);

-- is_good - оценка. Значение 1 считается голосом "за", значение 0 считается голосом "против".

-- Ответ сервера

В случае успеха возвращается ответ вида:

<catalit-vote-recenses-ok/>

В случае ошибки авторизации:

<catalit-authorization-failed/>

Или:

<catalit-vote-recenses-fail error="Текст сообщения об ошибке"/>

-- Оценка произведения пользователем

-- Оценка произведения

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

Для реализации этой возможности, необходимо отправить запрос на URL: http://robot.litres.ru/pages/catalit_vote/

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

-- sid - SID, идентифицирующий пользователя (см. 5);

-- mark - оценка пользователя, число (1-5);

-- art - ID книги, которой ставится оценка.

-- Ответ сервера

В случае успеха возвращается ответ вида:

<catalit-vote-ok/>

В случае ошибки авторизации:

<catalit-authorization-failed/>

Или:

<catalit-vote-fail error="Текст сообщения об ошибке"/>

Пользователь имеет право изменить свою оценку. Для этого нужно отправить запрос с новыми параметрами еще раз.

-- Пополнение счета

Список всех доступных способов оплаты представлен на сайте ЛитРеса под адресу: http://www.litres.ru/pages/put_money_on_account/ .

-- Пополнение счета платной SMS

-- Обзор оплаты с использованием SMS

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

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

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

-- Короткий номер. Некоторые операторы списывают деньги с абонента строго в зависимости от короткого номера: любая SMS (даже с некорректным текстом или пустая) на определенный номер будет стоить определенную сумму. Большинство Российских операторов работают именно так;

-- Префикс. Так как на одном коротком номере обычно оплачивается множество различных услуг и текст SMS состоит из двух частей - префикс и собственно текст SMS. При оплате товаров/услуг ЛитРес в префиксе обязательно будет текст типа "LTR", который дает знать оператору, что данная SMS оплачивает услуги ЛитРес, а не "мобильное порно" или что-либо еще. Префикс, помимо этого, может быть составным и включать пре-префикс, задающий сумму списания. Дело в том, что у некоторых операторов сумма списания со счета абонента определяется не коротким номером, а текстом SMS (так работают многие зарубежные операторы). В этом случае SMS может состоять из составного префикса "RR LTR", где RR указывает, что следует списать 50р., а LTR - что средства должны быть переданы компании ЛитРес;

-- Собственно, значимый текст. В случае с ЛитРес здесь должен передаваться ID пользователя (см. атрибут @user-id в разделе 5.3).

Например, для абонента российской сотовой сети "Биллайн" чтобы пополнить счет на сумму в 30р. следует отправить SMS на номер "1234" с текстом "LTR 686", где 686 - ID текущего пользователя на ЛитРес. А для абонента какой-нить "Лондонские сотовые сети" номер будет уже "4321", а текст SMS может выглядеть как "FM LTR 686". При этом для "Билалйна" на счет пользователя будет начислено 31р, а с него спишут 50р, а в Лондоне начислится 33.50р. и будет снят один фунт (к примеру), так как стоимость SMS дискретная и предопределена заранее.

-- Интерфейс получения информации о коротких номерах

Запрос отправляется на следующий URL:

http://robot.litres.ru/pages/sms_billing_publ_info/

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

<catalit-sms-payments-info>

</operator>

</operator>

</country>

</operator>

</operator>

</country>

</catalit-sms-payments-info>

, где:

-- /catalit-sms-payments-info/country - страна. Имеется буквенный ISO-код страны @country_code, по которому программа может сама попытаться опознать текущую страну на телефоне (к примеру);

-- /catalit-sms-payments-info/country/operator - оператор. В атрибут @caption заносится его видимое имя;

-- /catalit-sms-payments-info/country/operator/num - описание доступных для данного оператора коротких номеров. Узел num имеет следующие атрибуты:

-- @number - короткий номер, на который следует отправлять SMS;

-- @subprefix - дополнительный префикс. Может отсутствовать;

-- @prefix - основной префикс. Обычно здесь LTR, но полагаться на это не стоит;

-- @sum - сумма (в рублях), которая будет начислена на счет пользователя;

-- @cost - стоимость SMS для абонента у сотового оператора. Цена задается в денежной единице страны (/catalit-sms-payments-info/country/@money), либо денежная единица может быть указана отдельно для оператора (/catalit-sms-payments-info/country/operator/@money).

-- Пополнение счета в терминалах оплаты

Самым простым и доступным способом пополнить счет ЛитРес для жителя РФ является терминал оплаты. Реализация этого способа в приложении также является тривиальной: вы должны предоставить пользователю его ID и краткую инструкцию по навигации в самом терминале оплаты. Помимо систем оплаты, управляемых пользователем (такие как терминалы QIWI (Киви), существуют "терминалы", где оплату производит оператор. К числу таких терминалов относятся, к примеру, все салоны "МТС" и "Евросеть".

-- Кто принимает сегодня платежи в пользу ЛитРес

-- "МТС" - в любом салоне сотовой связи можно сказать оператору, что вы хотите пополнить счет в ЛитРес и назвать свой ID;

-- "Связной" - в любом салоне-магазине Связного вы можно пополнить счет ЛитРес;

-- Терминалы QIWI/ОСМП (http://www.qiwi.ru/, пример инструкции для терминалов есть на http://www.litres.ru/pages/put_money_on_account/?descr=25).

-- Что предъявлять пользователям

Вам необходимо показать пользователю его ID (см. 5.3, узел catalit-authorization-ok/@user-id). При отображении кода желательно визуально разбить его на разряды, чтобы облегчить считывание длинного числа человеком и его диктовку:

25686869	- неправильно (мелко, без деления на разряды, нечитаемый шрифт)
25'686'869	- правильно (крупно, с разделителями разрядов, контрастно)

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

http://www.litres.ru/pages/put_money_on_account/?descr=25

http://www.litres.ru/pages/put_money_on_account/?descr=35

http://www.litres.ru/pages/put_money_on_account/?descr=28

-- Пополнение счета кредитной картой

-- Общая логика работы с кредитными картами

Пополнение счета с кредитной карты допускает пополнение счета с непосредственным вводом данных карты. Помимо этого доступен "ребилл" (повторное списание произвольной суммы заказа с уже известной карты без какого-либо дополнительного ввода данных пользователем). Работа осуществляется с использованием протокола https; все параметры передаются на сервер процессинга в кодировке UTF-8.

Работа ведется асинхронно:

-- С сервера ЛитРес запрашивается URL для https-запроса и параметры этого запроса;

-- От пользователя получается вся необходимая информация (если это не "ребилл");

-- Посылается https-запрос на сервер карточного процессинга. Процессинг проверяет корректность введенных данных и возвращает "ок" (что не означает списание средств, но только факт приема транзакции "в обработку");

-- Приложение проверяет статус транзакции, периодически опрашивая сервер ЛитРес. Как правило, транзакция закрывается (либо мы получаем отказ) в течение 5-30 секунд;

-- После получения ответа от сервера ЛитРес о статусе транзакции пользователь уведомляется о результатах операции. Если транзакция не была закрыта (статус все еще pending, см. 14.4) в течение 5 минут, следует сообщить пользователю об ошибке.

-- Запрос у ЛитРес параметров карточного процессинга

Пополнение счета кредитной картой начинается с получения параметров https-подключения к процессинговому центру. Запрос отправляется на адрес

https://robot.litres.ru/pages/catalit_credit_card_init/

При этом следует передать три параметра:

-- sid - SID, идентифицирующий пользователя, обязательный параметр (см. 5);

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

-- operation - тип операции, может принимать значения auth и rebill. По умолчанию подразумевается auth, т.е. первичная оплата (пользователь должен будет ввести номер карты и другие реквизиты). rebill можно указывать пользователю, у которого были успешные операции по карте и возможен ребилл (см. атрибут @can-rebill в разделе 5.3);

-- preventrebill - необязательный параметр. Если передать его со значением 1, то система не сохранит данные платежа для ребилла.

-- Ответ ЛитРес с информацией о сервере карточного процессинга

Сервер ЛитРес отдаст информацию о том, что следует передавать в процессинг. Пример выдачи в случае успеха:

<catalit-paycard-processing>

<url>https://secure.payonlinesystem.com/payment/transaction/auth/</url>

<name>PayOnline</name>

<homepage>http://www.payonlinesystem.com/</homepage>

<TermUrl>http://robot.litres.ru/pages/catalit_credit_card_3ds_result/862703672/</TermUrl>

<param name="DedicatedChars">$param</param>

<param name="RussianText">Не забывайте делать URL-encode в UTF</param>

</catalit-paycard-processing>

Отдается узел catalit-paycard-processing, включающий следующие обязательные узлы:

-- url - https(!) адрес сервера, на который следует отправлять запрос. Приложение обязано должно проверить, что URL указывает именно на HTTPS ресурс (!). Для каждого обращения к оплате следует заново совершать этот запрос и заново получать URL. Повторное использование и вообще сохранение на стороне приложения URL платежного процессинга категорически запрещено!;

-- method - метод запроса. Может принимать значения POST или GET;

-- name - имя кредитного процессинга. Можно продемонстрировать пользователю вместе с доменом из URL;

-- homepage - домашняя страница кредитного процессинга;

-- order-id - ID заказа, к которому будет привязана данная транзакция. Далее этот ID приложение будет использовать при проверке, был ли данный запрос обработан и с каким результатом (см. 14.4). Это положительное целое число в диапазоне 1-4294967295;

-- TermUrl - (параметр используется при 3DS-авторизации; см. ниже.) - это URL страницы на сервере ЛитРес, которая умеет обрабатывать результат авторизации плательщика на сайте банка-эмитента и выдавать результат в виде веб-формы с "автосабмитом" на адрес платежной системы (для этого должен работать JS);

-- param - несколько узлов с параметрами, передаваемыми серверу. Узел может встречаться произвольное число раз. Каждый узел param включает обязательный атрибут @name - имя параметра, которое следует передать на сервер процессинга, и необязательный атрибут @substitute, указывающий, что данный параметр приложению следует заполнить самостоятельно, используя введенные пользователем данные. Если атрибут @substitute отсутствует, приложению следует транслировать содержимое узла на сервер процессинга (т.е. даже пустой параметр следует передать как пустой, а не пропустить, остальные передать, при необходимости кодируя в UTF-8). При запросе типа rebill параметров с атрибутом @substitute быть не должно. Приложение при этом просто транслирует запрос на процессинг-сервер.
Атрибут @substitute может принимать следующие значения:

-- name - имя владельца карты (в том виде, как оно написано на карте, например "vasily pupkin";

-- number - номер кредитной карты, 13-19 цифр, без пробелов и тире. Для обычной VISA будет 16 цифр, например "1111222233334444";

-- expires - дата истечения срока действия карты. Строка в формате MMYY - две цифры месяца и две цифры года, например "0915";

-- cvv - cvv-код карты (печатается на обратной стороне), например "123";

-- bank - наименование банка, выдавшего карту;

-- mail - e-mail пользователя карты, передаваемый в процессинговый центр, например admin@litres.ru;

-- phone - телефон пользователя карты;

-- country - страна плательщика, 2 символа из ISO-3166, например RU. Список стран и соответствующих им кодов доступен в формате XML по адресу http://robot.litres.ru/static/country-codes.xml

Перечисленные выше 8 параметров обязательно будут присутствовать, если тип запроса был auth. При этом, если не осуществить их передачу на сервер процессинга, то это приведет к ошибке. Поимо этого существует несколько параметров, которые могут отсутствовать даже в параметрах запроса auth, а могут присутствовать, в зависимости от текущих настроек безопасности. Приложению следует запрашивать их у пользователя и передавать на сервер только в том случае, если они присутствовали среди узлов param. Если сервер ЛитРес эти поля не потребовал, приложение их может не запрашивать у пользователя и точно не должно передавать на сервер. Ниже дан список возможных необязательных параметров:

-- city - город плательщика. Строка, максимальная длина - 50 символов;

-- address - адрес плательщика. Длина до 150 символов;

-- zip - только для указавших регион США - почтовый индекс;

-- state - только для указавших регион США - штат;

-- SecurityKey - (параметр используется при 3DS-авторизации; см. ниже.) -открытый ключ, подтверждающий целостность параметров запроса.

В случае ошибки авторизации:

<catalit-authorization-failed/>

Или при другой ошибке:

<catalit-paycard-processing-fail error="Текст сообщения об ошибке"/>

-- Действия приложения по формированию и отправке запроса на списание средств у клиента

После того, как от сервера ЛитРес получен ответ с параметрами обращения к процессингу, вы можете запросить у пользователя номер кредитной карты и все остальные параметры. При ненулевом значении атрибута @can-rebill (см. раздел 5.3) вы можете пропустить этот шаг и, начав с запроса типа rebill, сразу обратиться к серверу карточного процессинга. Если же в @can-rebill указано значение 0, то вы обязаны запросить данные у пользователя.

Важно: ни в коем случае параметры name, number, expires, cvv не могут и не должны сохраняться на стороне приложения. Остальные параметры, такие как e-mail или адрес, можно после первого ввода запоминать (хотя с учетом возможности "слепого" ребилла это едва ли имеет смысл).

После того, как все данные подготовлены, приложение отправляет HTTPS-запрос на сервер процессинга. На данный момент сервер процессинга возвращает plain-text строку, наличие в которой фрагмента вида "ErrorCode=555" (где 555 - код ошибки) указывает на ошибку. Если ErrorCode в ответе процессинга отсутствует - ошибки нет. Однако отсутствие ErrorCode не гарантирует отсутствие ошибок.

В случае, если ответе процессинга получен ErrorCode со значением "6001", то это означает, что плательщик должен пройти дополнительную 3DS-авторизацию на сайте банка-эмитента. Для этого необходимо перенаправить плательщика на сайт банка-эмитента, дождаться авторизации, а затем корректно завершить процесс списания средств на стороне мобильного приложения. Документацию по 3DS-авторизации, описывающую, куда именно необходимо перенаправлять пользователя и с какими параметрами, можно получить в поддержке платежной системы PayOnline (http://www.payonline.ru/feedback/) или в технической поддержке ЛитРес.

-- Запрос у сервера ЛитРес статуса заказа

См. "14.4 Проверка статуса операции на пополнение счета"

-- Удаление данных о ребиллах пользователя

Чтобы удалить данные о привязанных картах и ребиллах пользователя необходимо вызвать адрес

https://robot.litres.ru/pages/catalit_purge_rebills/

При этом следует передать обязательный параметр:

-- sid - SID, идентифицирующий пользователя, обязательный параметр (см. 5).

В случае успеха, система возвращает ответ:

<catalit-purge-rebills result="ok"/>

Это значит, что данные о ребиллах были успешно очищены.

Если произошла, ошибка система возвращает

<catalit-purge-rebills result="fail"/>

-- Проверка статуса операции на пополнение счета

Некоторые типы пополнения счета работают асинхронно. Приложение отправляет запрос на выполнение операции, а затем периодически обращается на сервер, чтобы проверить статус запрошенной операции. Асинхронно работает ребилл по кредитным картам (см. 14.3.1) и мобильная коммерция (см. 14.6). При инициализации асинхронных операций сервер возвращает приложению "тикет" и "ID заказа", используя которые приложение может проверять статус операции.

-- Запрос статуса операции

Для запроса статуса операции используется следующий URL:

http://robot.litres.ru/pages/catalit_payorder_check_state/

При этом следует передать единственный параметр:

-- order_id - номер заказа на пополнение счета, обязательный параметр (см. 12.5.2).

-- Ответ сервера

На этот запрос система возвращается ответ:

<catalit-payorder-processing-check order="555" state="failed" account="12.55"/>

Атрибут @order подтверждает номер запрошенного заказа, атрибут @state описывает его текущий статус, @account содержит информацию о текущем состоянии счета пользователя.

Атрибут @state может принимать следующие значения:

-- unknown - заказ не опознан, ошибка;

-- closed_ok - заказ успешно "закрыт", счет пополнен;

-- failed - заказ был отвергнут процессингом. К сожалению, деталей о причинах отказа процессинг нам не передает - просто ставит нас перед фактом;

-- pending - статус заказа пока не известен, процессинг еще не прислал ЛитРес уведомления об успехе или неуспехе транзакции;

-- @error-code - в случае возникновения ошибки на стороне процессинга, к ответу добавляется атрибут с кодом ошибки:

-- 1 - техническая проблема на стороне платежного сервиса. Возможно, что запрошенная операция пройдет успешно при отправке запроса спустя некоторое время;

-- 2 - провести платеж невозможно, плательщику стоит воспользоваться другим способом оплаты;

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

-- 4 - время жизни переданного ID .

Время жизни "тикета" на операцию - 45 минут. Если за это время пользователь не подтвердил платеж, повторный запрос на пополнение счета с указанного номера выполняться не будет (код ошибки 4).

-- Пополнение счета купоном/подарочной картой (активация купона/подарочной карты)

-- Запрос на активацию купона/подарочной карты

Запрос отправляется на следующий URL:

http://robot.litres.ru/pages/catalit_activate_coupone/

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

-- sid - SID, идентифицирующий пользователя, обязательный параметр (см. 5);

-- code - уникальный код купона/подарочной карты. Уникальный код купона является строкой из 16 цифр, например 1234567891234567. Как правило, если купоны распространяются в виде подарочных карт, уникальный код купона наносится на лицевую сторону подарочной карты в одну строку четырьмя группами по четыре цифры, аналогично номеру банковской карты, например 1234 5678 9123 4567.

-- Ответ сервера

В случае ошибки авторизации возвращается:

<catalit-authorization-failed/>

В случае ошибки активации купона, возвращается:

<catalit-activate-coupone-failed error="123" comment="Описание ошибки"/>

Где @error - код ошибки, а @comment - описание ошибки. Коды ошибок:

-- 1 - введён неверный код купона (неправильный формат купона, или купон уже был активирован);

-- 2 - код купона уже был использован (для особых серий, если купон уже был активирован);

-- 3 - активировать этот купон можно только после пополнения счета на сумму от ста рублей и выше;

-- 4 - время действия этого купона истекло, он просрочен и теперь его нельзя активировать;

-- 5 - пользователь уже активировал купон из этой серии, активация второго купона невозможна;

-- 6 - нельзя активировать купон для покупки абонемента: у пользователя уже оформлен абонемент. Оформление нового абонемента до окончания предыдущего невозможно.

В случае успешной активации купона возвращается:

<catalit-activate-coupone-ok account="146.22" coupone_class="143"/>

, где @account - текущий баланс пользователя, для которого активировался купон, а @coupone_class - класс купона.

-- Пополнение счета пользователя через систему мобильной коммерции

Данным способом пользователь может пополнить свой счет, со счета мобильного оператора (поддерживаются только российские операторы МТС, Билайн, МегаФон).

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

-- Отправка запроса на пополнение счета через мобильную коммерцию

Для начала процесса списания средств необходимо отправить запрос на следующий URL:

http://robot.litres.ru/pages/catalit_mcommerce_init/

При этом следует передать три обязательных параметра:

-- sid - SID, идентифицирующий пользователя, обязательный параметр (см. 5);

-- sum - сумма (в рублях), на которую необходимо пополнить счет и которая будет размещена на счету пользователя на ЛитРес. Сумма списания с мобильного счета пользователя может быть выше (см. @price, рассмотренный ниже). Сумма не может быть меньше 10 рублей или больше 3000 рублей. Целое число;

-- phone - телефонный номер пользователя без пробелов, спецсимволов и кода России (+7). Например, для номера +7(903)123-45-67 следует передать 9031234567.

-- Ответ сервера

В случае успеха возвращается:

<catalit-mcommerce-init order_id="12345678" state="success" price="95.14"/>

, где @order_id - номер заказа на пополнение счета, который нужно использовать для проверки статуса операции в дальнейшем (см. 14.4), а @price - сумма, которую реально спишут со счета абонента (включает комиссию оператора; эта сумма всегда больше или равна сумме заказа).

В случае ошибки возвращается:

<catalit-mcommerce-init state="failed" error="1"/>

, где @error = один из возможных номеров ошибок:

-- 1 - заказ или пользователь не найдены;

-- 2 - указан неправильный номер телефона;

-- 3 - указана недопустимая сумма;

-- 4 - таймаут платежей;

-- 5 - внутренняя ошибка.

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

-- Проверка списания средств с мобильного счета пользователя

См. "14.4 Проверка статуса операции на пополнение счета"

-- Пополнение счета пользователя другими способами

-- API покрывает лишь часть опций пополнения счета

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

-- URL с упрощенной страницей пополнения счета

"ЛитРес" гарантированно поддерживает работоспособность и актуальность всех методов пополнения счета при работе в любом стандартном веб-браузере на URL:

http://robot.litres.ru/pages/put_money_on_account/?sid=SID

В качестве SID используйте SID, полученный на этапе авторизации (см. 5).

Эта страничка содержит минимум оформления и должна адекватно отображаться и функционировать в любом, даже самом примитивном, веб-браузере. Некоторые методы оплаты, такие как WebMoney, предполагают авторизацию с использованием ключей и другие продвинутые возможности, но если вы используете хоть сколько-нибудь современный компонент веб-браузера, функции пополнения счета будут либо работать полноценно, либо работать достаточно хорошо, чтобы удовлетворить 90% пользователей и на 100% реализовать возможности системы.

-- Работа с корзиной

-- Управление состоянием книги в корзине

Для управления состоянием книги в корзине используется URL:

http://robot.litres.ru/pages/catalit_manage_basket/

Этот URL обрабатывает параметры:

-- sid - SID, идентифицирующий пользователя (см. 5);

-- hub_id - внутренний ID книги в библиотеке (см. 8.2, атрибут /fb2-book/@hub_id);

-- type - осуществляемая операция. Допустимые значения: 0 - удаление книги из корзины, 1 - добавление книги в корзину, 2 - добавление книги в отложенные.

-- Ответ сервера

В случае успеха возвращается ответ вида:

<catalit-basket-ok/>

В случае ошибки авторизации:

<catalit-authorization-failed/>

В случае другой ошибки:

<catalit-basket-error error="Текст сообщения об ошибке"/>

-- Работа с закладками/заметками

-- Общая информация о работе с заметками/закладками

Для работы с закладками используется XML-стандарт FictionNotes.

Схема для XML-файла с заметками/закладками доступна здесь: http://www.gribuser.ru/xml/fictionbook/2.0/markup/FictionNotes.xsd

Пример файла с заметками доступен здесь: http://www.gribuser.ru/xml/fictionbook/2.0/markup/markup_epample.xml

Документация по формату доступна здесь: http://www.gribuser.ru/xml/fictionbook/2.0/markup/FictionNotes/FictionNotes.html

Общая логика работы с закладками такова: приложение формирует описание "выделений", сделанных пользователем. Эти "описания" затем сохраняются на сервер и/или читаются с него. В соответствии с информацией о выделении приложение наносит на текст "отметки", рисует закладки и т.п.

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

Золото - хозяйке, серебро - слуге,

Медяки - ремесленной всякой мелюзге.

"Верно, - обрубил барон, нахлобучив шлем, -

Но хладное железо властвует над всем".

При этом сохраненное выделение должно содержать:

-- Указатель на начало выделения в исходном документе (в нашем вырожденном случае это point(/1/2.30) - второй узел, 30-й символ;

-- Указатель на конец выделения - point(/1/3.18);

-- Тип выделения (красный/зеленый/синий или 0/1/2);

-- Выделенный текст, а именно "мелюзге. "Верно, - обрубил";

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

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

Мы рекомендуем приложению использовать данный формат не только для работы с CataLit, но и для импорта/экспорта пользовательских заметок и закладок в файл, а также, по возможности, и для хранения данных о выделениях.

-- Получение закладок/заметок с сервера

Для запроса заметок клиент должен быть авторизован.

-- Запрос на получение закладок/заметок

Для загрузки заметок с сервера используется URL:

http://robot.litres.ru/pages/catalit_load_bookmarks/

Этот URL обрабатывает параметры:

-- uuid - уникальный ID книги (хранится в поле document-info/@id fb2-файла). Необязательный параметр;

-- art - внутренний ID книги в каталоге "ЛитРес" (см. 8.2, catalit-fb2-books/fb2-book/@hub_id). Необязательный параметр. Используется в качестве альтернативы параметру uuid и, соответственно, игнорируется в случае, если указан параметр uuid.

-- last_update - время, начиная с которого (включительно) следует подгрузить заметки. Полезно, если у пользователя "богатая" история - позволит загрузить только новые заметки, что ускорит работу и уменьшит трафик. Настоятельно рекомендуется использовать этот параметр при "обновлениях" заметок. Задаётся в формате xs:dateTime. Если не указан часовой пояс -- используется часовой пояс сервера (московское время). Необязательный параметр;

-- set_lock - параметр, при значении > 0 означающий, что после обновления данных будет осуществлена запись. "Блокировка" ставится на фиксированное время 20 минут либо до ближайшего запроса catalit_store_bookmarks (см. 16.3.1). Если передан параметр set_lock, в ответе сервера будет присутствовать атрибут FictionBookMarkup/@lock-id, содержащий одноразовый ID, значение которого используется сохранении данных на сервер (см. 16.3.1). В случае, если будет сделан новый запрос на блокировку, предыдущий выданный lock_id станет недействительным. Необязательный параметр;

-- search_types - необязательный параметр. Выдать заметки по контенту перечисленных типов. Значение по умолчанию пусто (нет ограничений по типу контента). Можно указать несколько значений тиков контента через запятую (аналог - несколько чекбоксов html формы). Возможные значения описаны в разделе 8.1 (описание параметра search_types). При этом указание uuid приводит к игнорированию параметра search_types;

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

Если uuid и search_types не указаны, сервер вернет ВСЕ пользовательские заметки. В дальнейшем клиентское приложение сможет разделить заметки по книгам, опираясь на атрибут Selection/@art-id (содержимое соответствует uuid).

-- Ответ, сервера содержащий закладки/заметки

Вот пример ответа сервера на запрос:

<FictionBookMarkup xmlns="http://www.gribuser.ru/xml/fictionbook/2.0/markup"

xmlns:fb="http://www.gribuser.ru/xml/fictionbook/2.0"

lock-id="bf43f954-256c-11e1-9474-102aa4b7a826">

<Selection id="a2ed9598-b375-11e0-2259-47117d41cf4b"

class="abc" title="Untitled" group="4"

selection="fb2#xpointer(point(/1/2/3/1/13.184)/range-to(point(/1/2/3/1/14.30)))"

art-id="a2ed9598-b375-11e0-9959-47117d41cf4b"

last-update="2011-05-30T09:30:10-06:00">

<Note>

I can't beleive <fb:emphasis>he</fb:emphasis> wrote this!

</Note>

<Extract original-location="fb2#xpointer(/1/2/3/1/13)"

selection="xpointer(point(here()/2.184)/range-to(point(here()/3.30)))"

selection-text="belied her air of confidence. Most pilots wouldn't accept an">

"You have a welcoming committee," I said.

She flashed her white teeth. Part Latin, or maybe African-American and white--whatever her heritage, I found her exotic pale almond eyes hypnotic. Only the slight tang of perspiration belied her air of confidence.

Most pilots wouldn't accept an <fb:strong>anonymous</fb:strong> customer who paid in cash. It wasn't that I lacked ethics or good sense, or that I'd knowingly do something illegal, but times were tough and work was hard to come by. Besides, risk never bothered me, especially when my survival depended on it.

The Zodiac bounced towards us without altering its course to avoid the swells. The girl's sphinx-like smile returned as she watched the boat approach. I lifted the side hatch to a gust of thick salt air.

</Extract>

</Selection>

</FictionBookMarkup>

Ответ сервера всегда соответствует схеме FictionNotes. Помимо штатного ответа сервер может вернуть стандартную ошибку авторизации. Также ответ может не содержать узлов Selection, что означает, что соответствующих запросу заметок на сервере нет.

-- Отправка закладок/заметок на сервер

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

Чтобы избежать коллизий и разрушения пользовательских данных, приложение должно перед записью данных на сервер осуществить "обновление" с параметром set_lock, и, если получены новые записи, учесть и сохранить их. При этом set_lock-запрос на любую книгу блокирует "общий" запрос, а "общий запрос" блокирует все запросы - и общие, и на конкретную книгу. После set_lock-запроса на получение данных успешный вызов catalit_store_bookmarks сбрасывает блокировку.

-- Запрос к серверу на сохранение заметок/закладок

Для загрузки заметок на сервер используется следующий URL:

http://robot.litres.ru/pages/catalit_store_bookmarks/

Этот URL обрабатывает параметры:

-- data - XML, соответствующий стандарту FictionNotes. Размер XML, переданного таким образом, не должен превышать 10 MB (10485760 байт). Рекомендуется использовать метод POST для этого запроса, т.к. сервер ЛитРес не пропустит GET-запрос большого размера. Обязательный параметр;

-- lock_id - ID блокировки, переданный сервером в запросе на загрузку заметок, описанном в разделе 16.2.1. Время жизни этого ID - 20 минут. После успешного использования в описываемом запросе catalit_store_bookmarks ID также теряет актуальность, т.е. его можно использовать один раз в течение часа после создания. Обязательный параметр;

-- uuid - уникальный ID книги (хранится в поле document-info/@id fb2-файла). Необязательный параметр. Если указан, перезаписываются только данные для данной книги, если параметр не задан, приложение перезаписывает ВСЕ заметки/закладки. Соответственно, передав uuid и пустой узел <FictionBookMarkup xmlns="http://www.gribuser.ru/xml/fictionbook/2.0/markup"/> вы удалите все заметки/закладки для соответствующей книги. Пустой <FictionBookMarkup xmlns="http://www.gribuser.ru/xml/fictionbook/2.0/markup"/> без uuid удалит с сервера вообще все заметки/закладки. Если параметр задан, ожидается, что в XML будут присутствовать только заметки/закладки для соответствующей книги, иное считается ошибкой;

-- Ответ сервера после сохранения закладок/заметок

В случае успешной обработки ответ сервера всегда:

<catalit-store-bookmarks-ok/>

Если пользователь не авторизован будет ответ стандартный ошибки авторизации:

<catalit-authorization-failed/>

В случае если произошла ошибка, сервер возвращает сообщение вида:

<catalit-store-bookmarks-failed error="1" comment="Invalid lock ID"/>

В атрибуте @comment словами описывается смысл ошибки, возможные значения атрибута @error приведены ниже:

-- 1 - переданный lock_id неправильный или уже устарел;

-- 2 - переданный в data XML неправильный (не соответствует требованию well-formed);

-- 3 - переданный в data XML невалидный (не соответствует схеме FictionNotes.xsd);

-- 4 - не задан lock_id;

-- 5 - размер data слишком велик;

-- 6 - переданный в data XML содержит некорректные данные;

-- 100 - прочие ошибки.

Узел <catalit-store-bookmarks-failed/> для ошибок 2 и 3 содержит узел <description/> с подробным описанием ошибки и указанием на проблемное место в переданном XML-документе.

-- Работа с коллекциями

-- Получение списка коллекций

-- Запрос на получение списка коллекций

Для загрузки заметок с сервера используется URL:

http://robot.litres.ru/pages/catalit_collections/

Этот URL обрабатывает один параметр:

-- my_active - при использовании этого параметра возвращается список активных подписных коллекций.

-- Ответ сервера со списком коллекций

Если пользователь не авторизован будет возвращена стандартная ошибка авторизации:

<catalit-authorization-failed/>

Если все хорошо, ответ будет примерно таким:

<catalit-collections>

<text_html>

<hidden>10 самых продаваемых книг жанра фантастика по результатам продаж ЛитРес за июнь. Все ли Вы их прочитали?</hidden>

</text_html>

</collection>

</catalit-collections>

Ответ содежит узлы catalit-collections/collection для каждой подходящей коллекции. Узлы collection имеют следующие артибуты:

-- @id - ID коллекции;

-- @name - название коллекции;

-- @items_left - число книг, доступных в данной подписной коллекции.

-- Получение краткого списка коллекций (с фильтрацией)

Чтобы получить полный список коллекций используется URL

http://robot.litres.ru/pages/catalit_collections_list/

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

-- id - идентификатор коллекции (целое число);

-- name - часть или полное название коллекции (строка);

-- limit - ограничение на число возвращаемых коллекций. Работает аналогично инструкции limit в MySQL: limit состоит из двух чисел N,M (разделенных запятой). Если limit указан, возвращается M коллекций, начиная с коллекции N (у первой коллекции номер 0). Если limit не задан, то значение по умолчанию '0,200'.

-- Ответ сервера

<catalit-collections-list count="2">

</catalit-collections-list>

Значение /catalit-collections-list/@count - общее количество коллекций без учета параметра limit.

Значения узла collection:

-- id - идентификатор коллекции;

-- name - название коллекции;

-- art_count - количество произведений в коллекции.

-- Получение книг по подписке

-- Запрос на получение книги по подписке

Книгу, доступную по подписке, можно получить, отправив запрос на URL:

http://robot.litres.ru/pages/catalit_get_collection_book/

Этот URL обрабатывает параметры:

-- uuid - уникальный ID книги (хранится в поле document-info/@id fb2-файла);

-- art - ID книги, которую следует приобрести (см. 8.2, атрибут /fb2-book/@hub_id).

Параметры uuid и art являются взаимозаменяемыми. Обязательно наличие одного из этих параметров.

-- Ответ сервера при получении книги по подписке

Если пользователь не авторизован будет возвращена стандартная ошибка авторизации:

<catalit-authorization-failed/>

В случае успешного получения книги по подписке будет возвращено сообщение вида:

<catalit-get-collection-book-ok/>

В случае ошибки будет возвращено сообщение вида:

<catalit-get-collection-book-failed comment="UUID not specified."/>

Атрибут @comment содержит описание ошибки.

В атрибуте @error содержится код ошибки. Возможные значения атрибута @error приведены ниже:

-- 1 - не задан параметр uuid;

-- 2 - не осталось доступных книг в этой подписной коллекции;

-- 100 - прочие ошибки.

-- Хранилище для произвольных данных из приложений

Доступно только авторизованным пользователям. Может использоваться для хранения на сервере настроек и предпочтений пользователя и синхронизации настроек между устройствами, для сбора статистики (ваша скорость чтения 500 знаков в минуту) и других целей. Не должно использоваться для работы с заметками/закладками/текущей позицией чтения - об этом см. раздел 16.

-- Сохранение данных

-- Запрос на сохранение данных

Для сохранения данных на сервер используется URL:

http://robot.litres.ru/pages/catalit_save user_data/

Этот URL обрабатывает параметры:

-- sid - идентификатор сессии;

-- key1 - имя параметра, часть 1 (не более 100 символов);

-- key2 - имя параметра, часть 2 (не более 100 символов);

-- value - целочисленное значение;

-- tag - дополнительная информация в текстовом формате (необязательный параметр, не более 1000 символов).

При сохранении данных фиксируется дата и время операции.

Если передано пустое значение value или параметр value отсутствует, то данные, с соответствующими ключами key1 и key2 будут удалены. Значение ключа может содержать SQL плэйсхолдер % на конце (и только на конце) для удаления нескольких записей, соответствующих маске. Знак % зарезервирован и не может входить в имя ключевого параметра, других ограничений на содержимое полей нет.

-- Ответ сервера на запрос на сохранение данных

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

<catalit_save_user_data_ok affected="100"/>

Атрибут @affected содержит информацию о количестве измененных (добавленных или удаленных) записей.

В противном случае возвращается:

<catalit_save_user_data_fail error="1" comment="incorrect name of"/>

Атрибут @comment содержит описание ошибки.

В атрибуте @error содержится код ошибки. Возможные значения атрибута @error приведены ниже:

-- 1 - некорректное имя ключа;

-- 2 - некорректное значение;

-- 3 - слишком длинное значение tag;

-- 4 - записей с таким ключом не обнаружено;

-- 100 - неизвестная ошибка.

-- Извлечение значений

Для извлечения данных с сервера используется URL:

http://robot.litres.ru/pages/catalit_get user_data/

Этот URL обрабатывает параметры:

-- sid - SID, идентифицирующий пользователя (см. 5);

-- updated_from, updated_to - время последнего обновления значения, с точностью до секунды. Время обновлений считается по серверному (Московскому) времени. Необязательные параметры;

-- key1 - имя параметра, часть 1;

-- key2 - имя параметра, часть 2.

Обязательно передать в запросе хотя бы один ключевой параметр - key1 или key2, можно передать оба. Значение ключа может содержать SQL плэйсхолдер % на конце (и только на конце) для выборки нескольких записей, соответствующих маске. Если знак % входит в имя ключевого параметра, его необходимо экранировать слэшем: \%.

Сервер возвращает данные в XML формате:

<catalit_user_data>

</catalit_user_data>

-- Работа с "пользовательскими папками"

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

-- Запрос на получение списка полок

Чтобы получить список полок пользователя следует отправить запрос на URL:

http://robot.litres.ru/pages/catalit_user_folders/

Этот URL обрабатывает единственный параметр: sid - идентификатор сессии.

Сервер возвращает данные в XML формате:

<catalit_user_folders>

</folder>

</catalit_user_folders>

-- Создание полки

Чтобы создать полку следует отправить запрос на URL:

http://robot.litres.ru/pages/catalit_create_user_folder/

Этот URL обрабатывает следующие параметры:

-- sid - SID, идентифицирующий пользователя (см. 5);

-- caption - имя для создаваемой полки.

В случае успеха сервер вернет XML:

<catalit-user-folders-create-ok id="56879"/>

Где @id это ID созданной полки.

В случае ошибки:

<catalit-user-folders-create-failed error="1" comment="Internal error"/>

-- Удаление полки

Чтобы удалить полку следует отправить запрос на URL:

http://robot.litres.ru/pages/catalit_drop_user_folder/

Этот URL обрабатывает следующие параметры:

-- sid - SID, идентифицирующий пользователя (см. 5);

-- folder - ID удаляемой полки.

В случае успеха сервер вернет XML:

<catalit-user-folders-drop-ok/>

Где @id это ID удаленной полки.

В случае наличия в папке вложенных подпапок:

<catalit-user-folders-drop-failed error="2" comment="Folder Contains Subfolders"/>

В случае неизвестной ошибки:

<catalit-user-folders-drop-failed error="3" comment="Internal error"/>

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

-- Помещение книги на полку

Чтобы получить список полок пользователя следует отправить запрос на URL:

http://robot.litres.ru/pages/catalit_put_book_to_folder/

Этот URL обрабатывает следующие параметры:

-- sid - SID, идентифицирующий пользователя (см. 5);

-- art - внутренний ID книги в каталоге "ЛитРес" (см. 8.2, catalit-fb2-books/fb2-book/@hub_id). Аналогично параметру person, в этот параметр может быть передано несколько экземпляров. При этом из каталога будут возвращены только книги с соответствующими внутренними ID (если есть);

-- uuid - уникальный ID книги (хранится в поле document-info/@id fb2-файла). Работает аналогично art, но при этом опирается не на внутренний ID книги в хабе, а на универсальный ID книги;

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

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

В случае успеха сервер вернет XML:

<catalit-put-book-to-folder-ok/>

В случае ошибки:

<catalit-put-book-to-folder-failed comment="bad params"/>

В атрибуте @comment словами описывается смысл ошибки, возможные значения атрибута:

-- bad params - переданы не все обязательные параметры;

-- bad folder - полка не найдена;

-- not in the basket - книга не найдена.

-- Получение книг, лежащих на полке

См. раздел 8.1, параметр my_folder.

-- Работа с подписками

-- Получение списка авторов, на которых подписан пользователь

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

http://robot.litres.ru/pages/catalit_author_subscr/

Для получения списка авторов необходимо указать параметр:

-- sid - SID, идентифицирующий пользователя (см. 5).

В результате возвращается XML вида:

<catalit_author_subscr>

</catalit_author_subscr>

Если пользователь не авторизован, то будет возвращена стандартная ошибка авторизации:

<catalit-authorization-failed/>

-- Изменение списка авторов

Для внесения изменений в список авторов, необходимо к параметрам запроса списка авторов (18.1) добавить один из параметров:

-- add_to_subscr - UUID автора, которого нужно добавить в подписку пользователя;

-- del_subscr - UUID автора, которого нужно удалить из подписки пользователя;

-- update_subscr - обновить подписку полностью. Значение параметра - список имен авторов. Разделитель - пара символов "||" или пара "\r\n".

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

-- Загрузка пользовательских файлов

-- Загрузка файлов

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

http://robot.litres.ru/pages/catalit_file_upload/

При этом необходимо указать следующие параметры:

-- sid - SID, идентифицирующий пользователя (см. 5);

-- upload_file - файл в формате fb2 или несколько файлов в этом формате, объединенных в zip архив (размером не более 30МБ). Представление аналогично представлению поля input type="file".

В результате возвращается XML вида

<catalit-files>

<catalit-file-upload-ok id="37"/>

<catalit-file-upload-ok id="38"/>

</catalit-files >

Если пользователь не авторизован будет возвращена стандартная ошибка авторизации:

<catalit-authorization-failed/>

-- Статус загрузки файлов

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

http://robot.litres.ru/pages/catalit_file_upload_state/

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

-- sid - SID, идентифицирующий пользователя (см. 5);

-- upload_id - ID загруженного файла (см. 21.1, атрибут @id узла catalit-file-upload-ok).

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

Пример XML ответа на запрос всех файлов пользователя:

<catalit-files>

<catalit-file-upload-state id="37" time="2013-08-28 12:35:24" orig_name="02.ZIP/Tolstoyi_L._Anna_KareninaI.fb2" status="wait" />

<catalit-file-upload-state id="38" time="2013-08-28 12:35:24" orig_name="02.ZIP/Panov_V._Ruchnoyi_Privod.fb2" status="wait" />

<catalit-file-upload-state id="39" time="2013-08-28 12:39:20" orig_name="03.ZIP/Panov_V._Ruchnoyi_Privod.fb2" status="ok" basket="256568" art="89546" />

</catalit-files >

В атрибуте @status передается статус загруженного файла:

-- wait - ожидание обработки;

-- release - проверка и обработка файла;

-- ok - обработка файла успешно завершена;

-- damaged - нарушение формата fb2; конвертация в другие форматы не производится;

-- error - поврежденный файл.

Для книг со статусом damaged и ok будет присутствовать атрибут @art, содержащий ID книги, который присвоен загруженному файлу (см. параметр art в 8.1).

При отсутствии файлов соответствующих запросу возвращается пустой список:

<catalit-files/>

Если пользователь не авторизован, то будет возвращена стандартная ошибка авторизации:

<catalit-authorization-failed/>

-- Работа с АБ-тестами

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

Для получения списка активных АБ-тестов используется URL:

http://robot.litres.ru/pages/catalit_abgroup_testsstate/

Этот URL обрабатывает один обязательный параметр:

-- sid - SID, идентифицирующий пользователя (см. 5).

Пример XML ответа на запрос активных АБ-тестов:

<catalit-ab-testing group="0" max-group="3">

<active-ab id="37/>

<active-ab id="38/>

<active-ab id="39/>

</catalit-ab-testing>

В атрибуте @group передается группа АБ-теста, соответствующая данному пользователю.

В атрибуте @max-group передается общее количество групп АБ-теста.

Узлы catalit-ab-testing/active-ab содержат информацию по всем активным АБ-тестам. При этом атрибут @id соответствует ID АБ-теста.

Если пользователь не авторизован будет возвращена стандартная ошибка авторизации:

<catalit-authorization-failed/>

-- Работа с рассылкой новостей и уведомлениями о подписках

-- Загрузка списка новостей и уведомлений о подписках

Для получения списка новостей и уведомлений о подписках (отправленных определённому пользователю в виде пуш-уведомлений) используется URL:

http://robot.litres.ru/pages/catalit_push_list/

Этот URL обрабатывает следующие параметры:

-- sid - (обязательный параметр) SID пользователя (см. 5), для которого необходимо получить список новостей и уведомлений;

-- app - (обязательный параметр) ID приложения, в котором планируется показывать загружаемые новости. Этот параметр выполняет роль "фильтра" и позволяет получать список только тех новостей, которые совместимы с конкретным приложением. Например, если приложение поддерживает только FB2 и ePub книги, то в список не попадут аудиокниги, книги с DRM-защитой и др.
Значение данного идентификатора для вашего приложения вы можете узнать у менеджера ЛитРес;

-- d - (обязательный параметр; целое положительное число от 1 до 32) количество дней, за которое необходимо загрузить свежие новости. Например, если параметр имеет значение "7", то в список попадут только те новости, которые пользователь получил за последнюю неделю;

-- old - не обязательный параметр.
Если он не указан, то в выдачу попадут только те новости, которые сформированы автоматически (рекомендательным сервисом ЛитРес или роботом отправки уведомлений). Если же параметр присутствует в запросе и имеет значение "1", то в выдачу дополнительно попадут ещё и новости, подготовленные и отправленные вручную сотрудниками отдела маркетинга ЛитРес.

Пример XML ответа на запрос без параметра "old" (список отсортирован по убыванию даты):

<catalit_push_inbox>

<push-message date="2014-08-18 14:00:00" ticket_id="718212210" type="b" internal_id="8206506" opened="0" special="0" text="Юрий Казаков "Двое в декабре"" spam_pack_id="1742517"/>

<push-message date="2014-08-18 00:00:00" ticket_id="716076126" type="b" internal_id="8216362" opened="0" special="0" text="Егор Чекрыгин "Странный приятель. Тайна Врат"" spam_pack_id="1742517"/>

<push-message date="2014-08-17 00:00:00" ticket_id="711824802" type="b" internal_id="8225173" opened="0" special="0" text="С. А. Матвеев "Быстрый английский. Грамматика в простых таблицах, правилах и формулах за 24 часа"" spam_pack_id="1742458"/>

</catalit_push_inbox>

Пример XML ответа на запрос с параметром "old=1":

<catalit_push_inbox>

<catalit_push_inbox_old>

<push-message date="2014-08-15 14:01:27" ticket_id="9676" type="c" internal_id="4556" opened="0" special="1" text="Фантастика Каменистого, провинциальные записки Бару, искусство учиться и другие новинки!" spam_pack_id="1742371"/>

<push-message date="2014-08-11 15:07:02" ticket_id="9671" type="b" internal_id="7632892" opened="0" special="1" text="Александра Маринина, "Ангелы на льду не выживают" - новая Каменская!" spam_pack_id="1742115"/>

<push-message date="2014-08-06 15:28:57" ticket_id="9657" type="c" internal_id="4477" opened="0" special="1" text="Новинка лауреата "Русского Букера", космическая фантастика Мартина и детективы Денниса Лихэйна!" spam_pack_id="1741564"/>

<push-message date="2014-08-01 18:01:46" ticket_id="9651" type="c" internal_id="4427" opened="0" special="1" text="День рождения Джоан Роулинг: читайте книги "мамы" Гарри Поттера"!" spam_pack_id="1741079"/>

<push-message date="2014-07-31 11:31:28" ticket_id="9636" type="c" internal_id="4431" opened="0" special="1" text="Легендарный "Ведьмак", гид по борьбе с прокрастинацией, эротические сказки Энн Райс и другие хиты!" spam_pack_id="1740593"/>

</catalit_push_inbox_old>

</catalit_push_inbox>

Ответ содержит узлы catalit_push_inbox/push-message для каждой новости, которая была сформирована автоматически. А те новости, которые были подготовлены вручную, находятся в узлах catalit_push_inbox/catalit_push_inbox_old/push-message.

Узлы push-message, в любом из случаев, имеют следующие артибуты:

-- @date - дата, когда было сформирована новость (пуш-уведомление);

-- @type - тип пуш-уведомления. Возможные значения:

-- a - новость об авторе;

-- b - новость о конкретном произведении (книге, аудиокниге);

-- c - новость о коллекции (подборке) произведений;

-- ad - новость со ссылкой на какой-то (возможно, что и сторонний) сайт.

-- @opened - статус, показывающий, была ли ранее открыта и прочитана данная новость (значение "1") или нет (значение "0");

-- @text - строковое значение, содержащее текст новости;

-- @ticket_id - ID пуш-уведомления;

-- @internal_id - ID сущности, например ID книги/автора/коллекции;

-- @spam_pack_id - ID номер спам-рассылки;

-- @special - данный узел зарезервирован, но не используется.

-- Передача на сервера ЛитРес информации о взаимодействии пользователей с новостями и уведомлениями

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

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

Для передачи такой информации используется URL:

http://robot.litres.ru/pages/fake/

Этот URL обрабатывает следующие параметры (все эти параметры обязательны):

-- id - ID номер спам-рассылки (рассмотрен в предыдущем разделе в узле push-message/@spam_pack_id);

-- action - данный параметр всегда должен иметь значение "user_spam";

-- event - возможные значения:

-- 1 - новость была удалена пользователем (вне зависимости: до прочтения или после);

-- 2 - новость была открыта (прочитана);

-- 3 - новость была доставлена до читателя (мобильное приложение получило информацию о доставке пуш-уведомления);

-- ticket - ID пуш-уведомления (рассмотрен в предыдущем разделе в узле push-message/@ticket_id);

-- user - ID пользователя (см. 5.3).

Примеры URL для трёх разных событий, которые необходимо обрабатывать:

-- Ваше приложение получило подтверждение о доставке пользователю пуш-уведомления:

http://robot.litres.ru/pages/fake/?id=174791&action=user_spam&event=3&ticket=75646241&user=1

-- Пользователь открыл (прочитал) новость:

http://robot.litres.ru/pages/fake/?id=174791&action=user_spam&event=2&ticket=75646241&user=1

-- Пользователь удалил новость (например, в новостной ленте приложения): http://robot.litres.ru/pages/fake/?id=174791&action=user_spam&event=1&ticket=75646241&user=1

На данный момент сервер ЛитРес разрешает до 7-и загрузок одной книги в месяц, причем счетчик совершенных загрузок уменьшается на 1 первого числа каждого месяца, что дает пользователю 7+12=19 закачек в год для каждой книги. Закачки с одного IP, совершенные за короткий промежуток времени (из-за докачки, повторной загрузке при ошибках и т.п.) при этом считаются одной закачкой и не ограничиваются.

Оставить комментарий © Copyright Вап (g467235@trbvm.com) Размещен: 27/03/2015, изменен: 27/03/2015. 325k. Статистика. Эссе: Лирика Скачать FB2		Ваша оценка:

Вап : другие произведения.

Ыываыва