| Версия документа | 1.0 |
|---|---|
| Дата последнего обновления | декабрь 2017 г. |
| Адрес постоянного размещения | https://docs.litres.ru/x/HgUT |
Введение
Большинство реферальных партнеров, работающих с «ЛитРес» , не занимаются приемом и обслуживанием платежей. Поэтому оплата покупок производится на стороне «ЛитРес». Если партнер заинтересован в проведении платежей через собственные биллинговые системы, то ему необходимо регистрировать покупки в «ЛитРес» с использованием описанного далее API.
Для начала работы с API партнеру необходимо получить от «ЛитРес» номер партнера, секретный ключ и домен для регистрации продаж (для тестовых регистраций используйте домен http://yabktest.litres.ru). Важно отметить, что секретный ключ для регистрации продаж отличается от секретного ключа, который используется при получении каталога и цен через интерфейс «Get_Fresh_Book» (документация: Интерфейс подключения партнеров к книжному магазину «ЛитРес»).
Общий алгоритм
- Партнер через интерфейс Get_Fresh_Book загружает каталог книг и предоставляет его пользователю.
- Пользователь на стороне партнера выбирает книгу и начинает оформлять покупку.
- (опционально) Партнер через данный API оформляет резерв, проверяя актуальность цены и валидность указанного пользователем e-mail.
- Партнер производит расчеты и оформление покупки. И после успешной оплаты регистрирует продажу в «ЛитРес» через данный API.
- (опционально) После регистрации продажи партнер предоставляет пользователю URL, по которому тот сможет перейти на «ЛитРес» в раздел «Мои книги» с одновременной авторизацией.
Предварительный резерв
Запрос к серверу
Пример запроса на оформление резерва:
Обратите внимание, что в примере указан тестовый домен.
Параметры (обязательные параметры отмечены звездочкой):
- lfrom* – номер партнера;
- reserve* – в этом запросе параметр должен всегда иметь значение «reserve»;
- user* – цифро-буквенный идентификатор пользователя на стороне партнера;
- price* – цена, по которой будет регистрироваться продажа. Она не может быть меньше текущей цены «ЛитРес» (если указать меньше, то она исправится автоматически);
- art* – UUID приобретаемой книги;
sha* – SHA-подпись, формируемая из идентификатора пользователя, UUID книги и секретного ключа партнера.
Пример формирования sha в синтаксисе Perlsha=Digest::SHA::sha256_hex($user.':'.$art.':'.$Key)
- mail* – e-mail пользователя.
Ответ сервера
<response status="0" reserve-id="71348" message="OK" reserve-price="119.90" userid="2232" />
- status – статус ответа. Если значение «0», то запрос обработан успешно;
- reserve-id – номер резерва;
- message – сообщение по статусу ответа. Если значение «OK», то запрос обработан успешно;
- reserve-price – текущая розничная цена «ЛитРес» , не ниже которой и будут произведены все расчеты;
- userid – внутренний номер пользователя на стороне «ЛитРес» (используется только для отладки). Если по указанному в запросе e-mail в «ЛитРес» отсутствует учетная запись, то в ответе не будет userid.
Резерв сохраняется 15 минут. Даже если за это время арт будет снят с продажи на «ЛитРес», то все равно по этому номеру резерва он может быть продан.
Далее по этому резерву можно окончательно зарегистрировать продажу, указав номер резерва.
Одна из причин делать резерв перед оформлением продажи – получить актуальную розничную цену арта, а также проверить пользовательский e-mail на «валидность с точки зрения «ЛитРес».
Регистрация продажи (с номером резерва или без него)
Запрос к серверу
Пример запроса на регистрацию продажи:
Обратите внимание, что в примере указан тестовый домен.
Параметры (обязательные параметры отмечены звездочкой):
- lfrom* – номер партнера;
- reserve – номер резерва, полученный в описанном ранее запросе (reserve-id). Не обязательный параметр;
- mail* – e-mail пользователя. E-mail должен быть валидным, иначе продажа не зарегистрируется. Учитывая, что «валидность» email понятие несколько расплывчатое из-за различных реализаций стандарта, рекомендуется проверять e-mail «с точки зрения «ЛитРес» с помощью запроса резерва. Тогда на этапе регистрации покупки никаких проблем не возникнет;
- user* – цифро-буквенный идентификатор пользователя на стороне партнера;
- price* – цена, по которой происходит регистрация продажи. Она не может быть меньше текущей цены «ЛитРес» (если указать меньше, то она исправится автоматически);
- art* – UUID приобретаемой книги;
sha* – SHA-подпись, формируемая из идентификатора пользователя, UUID книги и секретного ключа партнера.
Пример формирования sha в синтаксисе Perlsha=Digest::SHA::sha256_hex($user.':'.$art.':'.$Key)
Ответ сервера
<response status="0" order-id="310133434" message="OK" userid="2232" otsid="22sdfs222" />
status – статус ответа. Если значение «0», то запрос обработан успешно;
order-id – номер заказа;
message – сообщение по статусу ответа. Если значение «OK», то запрос обработан успешно;
userid – внутренний номер пользователя на стороне «ЛитРес» (используется только для отладки);
otsid – действующий в течение 15 минут одноразовый ключ инициации сессии на «ЛитРес». Значение этого ключа может быть использовано для предоставления пользователю ссылки вида http://www.litres.ru/pages/my_books/?otsid=22sdfasdf. По этой ссылке пользователь сможет перейти в раздел «Мои книги» на сайте «ЛитРес» с одновременной авторизацией.