Аннотация

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

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

1. Просмотр доступных для партнера серий (типов) купонов:
   coupapi_get_available_series.
2. Выпуск заданного числа купонов определенной серии:
   coupapi_issue_coupones.
3. Регистрация даты продажи купона:
   API для работы партнеров с купонами ЛитРес (АПИ)#coupapi_coupone_sold.
4. Просмотр статуса определенного купона:
   coupapi_get_coupone_info.
5. Просмотр списка выпущенных купонов, которые не были активированы потребителями:
   coupapi_get_coupones.
6. Просмотр списка использованных купонов:
   coupapi_get_coupones_history.

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

1. После заключения договора партнер получает от ЛитРес индивидуальные ключи, которые будут использоваться при формировании запросов к API:
   • partner — идентификатор партнера. Например: «51221432»;
   • secret_key — секретный ключ партнера. Например: «password».
2. Работа с API сервера ЛитРес для любой программы-клиента строится по схеме запрос-ответ: клиент формирует и передает запрос, а сервер в ответ возвращает документ с JSON-ответом.
3. Все запросы к API осуществляются по методу POST.
4. Во всех запросах к API передаются параметры partner, sha и timestamp:
   • partner — идентификатор партнера;

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

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

     где:

     • $timestamp — московское время в формате «2014-11-07T16:21:02+03:00». Каждое значение timestamp можно использовать только один раз раз, причем оно не может отличаться от серверного (московского) времени более чем на 300 секунд в обе стороны;
     • $secret_key — секретный ключ партнера;
     • $partner — идентификатор партнера;
   • timestamp — московское время в формате, аналогичному $timestamp'у из параметра sha.
5. Все ответы сервера передаются в формате JSON.
6. В ответах, отдаваемых сервером ЛитРес, помимо описанного в документации содержимого, могут размещаться, добавляться и удаляться неограниченные и нерегламентированные элементы. Программное обеспечение на стороне партнера должно корректно обрабатывать подобные ситуации и игнорировать неизвестные ему элементы.

Просмотр всех доступных серий (типов) купонов

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

Запрос списка доступных серий купонов

Адрес запроса: https://www.litres.ru/coupapi_get_available_series/.
Параметры запроса (обязательные параметры выделены красным):

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

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

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

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

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

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

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

{
  "success":1,
  "pager":{"rows":"2","pages":1},
  "series":[
    {
      "id":"27815",
      "message_body":"Благодарим за активацию купона",
      "message_subject":"Вы активировали купон",
      "collection":null,
      "discount":"0.00",
      "art_override":"0",
      "description":"Описание серии купонов",
      "amount":"1",
      "discount_days":"0",
      "nominal":"0.00",
      "price":"0.00",
      "class":"4875",
      "expires":"2022-06-08T16:28:34+03:00"
    },
    {
      ...
    }
  ]
}

Пример ответа сервера в случае ошибки:

{
  "success":0,
  "error_message":"Partner not found - 249915141",
  "error_code":103001
}

Элементы в ответе, значимые для партнера:

• success — в случае успешного выполнения запроса этот элемент имеет значение 1, иначе — 0;
• pager/rows — общее количество серий купонов, доступных партнеру;
• series — список серий купонов. Данные из описания серий:
  • id — идентификатор серии. Это значение используется в запросе на выпуск купонов (coupapi_issue_coupones);
  • message_body — тело письма, отправляемого пользователю ЛитРес после активации купона данной серии;
  • message_subject — тема письма, отправляемого пользователю ЛитРес после активации купона данной серии;
  • collection — идентификатор набора книг на который по купону предоставляется скидка;
  • discount — размер скидки в десятых (если по купону предоставляется скидка);
  • art_override — если конечный пользователь может получить по купону произвольную книгу, то этот элемент имеет значение 1. Если только какую-то определенную, заданную в настройках серии, то — 0;
  • description — текстовое описание серии купонов;
  • amount — общее количество уже выпущенных купонов данной серии;
  • discount_days — продолжительность действия скидки, предоставляемой конечному пользователю по купону;
  • nominal — номинал купона в рублях, зачисляемый на счет пользователя после активации купона;
  • price — реальная стоимость купона в рублях;
  • class — служебный идентификатор класса/серии купонов;
  • expires — дата прекращение действия серии и всех её купонов. После наступления данной даты партнер не сможет выпускать новые купоны, а пользователи не смогут активировать старые;
• error_message — текстовое описание ошибки на английском языке (в случае, если "success":0);
• error_code — код ошибки (в случае, если "success":0). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

Получение (выпуск) купонов

Запрос на получение купонов выбранной серии (от 1 до 100 шт.). Если необходимо выпустить больше, чем 100 купонов, выполните несколько однотипных запросов подряд.

Запрос на выпуск новых купонов

Адрес запроса: https://www.litres.ru/coupapi_issue_coupones/.
Параметры запроса (обязательные параметры выделены красным):

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

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

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

• timestamp — московское (серверное) время в формате «2014-11-07T16:21:02+03:00»;
• serie — идентификатор серии (см. параметр id в запросе просмотра серий купонов);
• num — количество выпускаемых купонов. Можно указать целое число от 1 до 100 шт. Если необходимо выпустить больше, чем 100 купонов, выполните несколько однотипных запросов подряд;

• uuid — один или несколько уникальных идентификаторов книг, которые необходимо «привязать» к выпускаемым купонам (данная возможность доступна ограниченному списку партнеров). Перечисление идентификаторов идет через символ «|», например:

  uuid=656b0d97-3e97-4e56-92a0-993634ff1e9e|96c42450-7d7c-4a04-929f-a89f68abbe64

  Если к купону этой серии по умолчанию были «привязаны» другие книги, то происходит переопределение этого списка книг (старые книги заменяются новыми);

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

  bonus_uuid=656b0d97-3e97-4e56-92a0-993634ff1e9e|96c42450-7d7c-4a04-929f-a89f68abbe64

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

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

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

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

{
  "success":1,
  "coupones":[
    {
      "id":"180192888",
      "code":"8490139451465376"
    },
    {
      "id":"180192883",
      "code":"4902827566515272"
    }
  ]
}

• success — в случае успешного выполнения запроса этот элемент имеет значение 1, иначе — 0;
• coupones — список выпущенных купонов. Данные из описания купонов:
  • id — идентификатор купона (конечным пользователям его показывать НЕ нужно);
  • code — код купона. Этот код партнер передает конечному пользователю для последующей активации на сайте ЛитРес. Например, пользователь может активировать код через индивидуальный «лендинг» партнера https://www.litres.ru/?vtb24 или на обычной странице активации купонов https://www.litres.ru/pages/put_money_on_account/?descr=18. Также этот код используется в запросе на просмотр статуса купона (coupapi_get_coupone_info);
• error_message — текстовое описание ошибки на английском языке (в случае, если "success":0);
• error_code — код ошибки (в случае, если "success":0). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

Регистрация даты продажи купона

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

Запрос на регистрацию даты купона

Адрес запроса: https://www.litres.ru/coupone_sold/.

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

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

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

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

• serie — номер серии в рамках которой регистрируется продажа купона;
• coupone — номер купона по которому регистрируется продажа;
• date_sold — дата продажи купона в формате формате «2014-11-07T16:21:02+03:00».

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

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

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

{
	"success":1,
		"coupones":{
			"7862453545440465":{
				"serie":104574,
				"date_sold":"2019-04-17T12:30:56+00:00",
				"id":15
		}
	}
}

Элементы в ответе:

• success — в случае успешного выполнения запроса этот элемент имеет значение 1, иначе — 0;
• id — идентификатор купона;
• coupone — номер купона, по которому зарегистрирована продажа;
• serie — номер серии, в рамках которой регистрируется продажа;
• date_sold — дата продажи купона в формате формате «2014-11-07T16:21:02+03:00»;
• error_message — текстовое описание ошибки на английском языке (в случае, если "success":0);
• error_code — код ошибки (в случае, если "success":0). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

Просмотр статуса определенного купона

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

Запрос статуса купона, выданного ранее партнеру

Адрес запроса: https://www.litres.ru/coupapi_get_coupone_info/.
Параметры запроса (обязательные параметры выделены красным):

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

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

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

• timestamp — московское (серверное) время в формате «2014-11-07T16:21:02+03:00»;
• coupone — код купона (см. параметр code в запросе получения купонов).

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

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

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

{
  "success":1,
  "id":"180045072",
  "serie":"27820",
  "spent":"2015-06-10T16:15:01+03:00"
}

Элементы в ответе:

• success — в случае успешного выполнения запроса этот элемент имеет значение 1, иначе — 0;
• id — идентификатор купона;
• serie — идентификатор серии;
• spent — если код купона был активирован, то в данном значении содержится дата и время активации в формате «2014-11-07T16:21:02+03:00». Если купон еще не был активирован, то элемент spent в ответе сервера отсутствует;
• bonus_arts — список служебных идентификаторов ЛитРес, обозначающих номера прикрепленных к купону книг для бесплатной бонусной выдачи (добавляются при выпуске купонов с помощью параметра bonus_uuid);
• error_message — текстовое описание ошибки на английском языке (в случае, если "success":0);
• error_code — код ошибки (в случае, если "success":0). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

Просмотр всех выпущенных, но не использованных купонов

Этот запрос позволяет посмотреть информацию по всем купонам, которые были выпущены, но не активированы на стороне ЛитРес.

Запрос списка не использованных купонов

Адрес запроса: https://www.litres.ru/coupapi_get_coupones/.
Параметры запроса (обязательные параметры выделены красным):

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

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

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

• timestamp — московское (серверное) время в формате «2014-11-07T16:21:02+03:00»;
• pagenum — номер «страницы» с результатами (целое положительное число). По умолчанию имеет значение 1. Т.к. у партнера может быть большое число не активированных купонов, то для снижения нагрузки на сервер API данный запрос возвращает информацию не более, чем о 1000 купонов. И если, например, существует 3500 не активированных купонов, то для просмотра всех данных необходимо выполнить последовательно четыре запроса, указав в pagenum «1», «2», «3» и «4».

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

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

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

{
  "success":1,
  "coupones":{
    "7691824940512282":{
      "id":"180045072",
      "serie":"27820",
      "expires":"2022-06-08T16:28:20+03:00",
      "arts":["118369"]
    },
    "8493039891468376":{
      "id":"180192888",
      "serie":"27815",
      "expires":"2022-06-08T16:28:34+03:00"
    },
    ...
  },
  "pager":{
    "rows":"3210",
    "pages":4
  }
}

Элементы в ответе:

• success — в случае успешного выполнения запроса этот элемент имеет значение 1, иначе — 0;
• coupones — список выпущенных, но не активированных купонов. Данные из описания купонов:
  • id — идентификатор купона;
  • serie — идентификатор серии, к которой принадлежит купон;
  • expires — дата прекращение действия купона. После наступления данной даты пользователь не сможет активировать код купона;
  • arts — список служебных идентификаторов ЛитРес, обозначающих номера прикрепленных к купону книг;
• pager/rows — общее количество не активированных купонов (если это значение больше 1000, то для просмотра данных по всем купонам партнеру необходимо передать несколько запросов с указанием «страниц» в параметре pagenum;
• pager/pages — общее количество «страниц» с результатами текущего запроса;
• error_message — текстовое описание ошибки на английском языке (в случае, если "success":0);
• error_code — код ошибки (в случае, если "success":0). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

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

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

Запрос списка использованных купонов

Адрес запроса: https://www.litres.ru/coupapi_get_coupones_history/.
Параметры запроса (обязательные параметры выделены красным):

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

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

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

• timestamp — московское (серверное) время в формате «2014-11-07T16:21:02+03:00»;
• from — левая временна́я граница для поиска по дате активации купона (формат «2014-11-07T16:21:02+03:00»);
• to — правая временна́я граница для поиска по дате активации купона (формат «2014-11-07T16:21:02+03:00»);
• pagenum — номер «страницы» с результатами (целое положительное число). По умолчанию имеет значение 1. Т.к. у партнера может быть большое число активированных купонов, то для снижения нагрузки на сервер API данный запрос возвращает информацию не более, чем о 1000 купонов. И если, например, существует 3500 активированных купонов, то для просмотра всех данных необходимо выполнить последовательно четыре запроса, указав в pagenum «1», «2», «3» и «4».

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

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

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

{
  "success":1,
  "coupones":{
    "7691824940517871":{
      "id":"180045072",
      "spent":"2015-06-10T16:15:01+03:00"
    },
    "8493039891465375":{
      "id":"180192888",
      "spent":"2015-06-10T16:24:23+03:00"
    }
  },
  "pager":{
    "rows":"2",
    "pages":1
  }
}

Элементы в ответе:

• success — в случае успешного выполнения запроса этот элемент имеет значение 1, иначе — 0;
• coupones — список активированных купонов. Для каждого купона корневым ключем является его код активации. Данные из описания купонов:
  • id — идентификатор купона;
  • spent — дата и время активации купона в формате «2014-11-07T16:21:02+03:00»;
• pager/rows — общее количество активированных купонов (если это значение больше 1000, то для просмотра данных по всем купонам партнеру необходимо передать несколько запросов с указанием «страниц» в параметре pagenum;
• pager/pages — общее количество «страниц» с результатами текущего запроса;
• error_message — текстовое описание ошибки на английском языке (в случае, если "success":0);
• error_code — код ошибки (в случае, если "success":0). Перечень всех кодов с описанием см. в разделе «Коды ошибок».

Удаление выпущенных ранее купонов

С помощью этого запроса можно удалить ранее выпущенные купоны. В одном запросе до 100 штук. Серии, к которым принадлежат купоны, должны иметь разрешение на такое действие со стороны партнера.

Запрос удаления купонов, выданных ранее партнеру

Адрес запроса: https://www.litres.ru/coupapi_remove_coupones/.
Параметры запроса (обязательные параметры выделены красным):

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

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

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

• timestamp — московское (серверное) время в формате «2014-11-07T16:21:02+03:00»;
• coupone — код купона (см. параметр code в запросе получения купонов). В одном запросе может быть до 100 параметров coupone.

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

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

{
  "success":1,
  "removed":7,
  "forbidden": [ 
       {"id":"18092341", "code":"9921348123984123"},
       {"id":"12426654", "code":"9345948123984123"},
   ],
   "spent": [
       {"id":"18092341", "code":"9921348123984123",
         "spent":"2015-06-10T16:24:23+03:00"},
       {"id":"18296541", "code":"992864435639",
         "spent":"2016-03-11T16:24:23+03:00"}
   ],
}

Элементы в ответе:

• success — в случае успешного выполнения запроса этот элемент имеет значение 1, иначе — 0; обработка считается успешной, если удален хотя бы один купон;
• removed — количество удаленных купонов;
• id — идентификатор купона, если "id":"" - купон с таким кодом не найден;
• code — код купона;
• error_message — текстовое описание ошибки на английском языке (в случае, если "success":0);
• error_code — код ошибки (в случае, если "success":0). Перечень всех кодов с описанием см. в разделе «Коды ошибок»;
• forbidden - список купонов из запроса, для которых операция запрещена;
• spent - список купонов из запроса, которые уже были активированы пользователем и не могут быть удалены. В атрибутах объектов активированных купонов spent содержится дата и время активации в формате «2014-11-07T16:21:02+03:00».

Коды ошибок