[GET] Получение списка продуктов

GET /v1/product

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

limit
number
Количество продуктов в ответе
Если не передано, то в ответе будут возвращены все найденные продукты.
offset
number
Количество продуктов, на которое нужно сдвинуть результат
  • Если не передано или равно 0, то в ответе будут возвращены все продукты
  • Если указать, например, 10, то в ответе вернется список продуктов начиная с 11-ого продукта из числа найденных
search_string
string
Строка для поиска
Если передано, то в ответе будут возвращены продукты, у которых найдено вхождение значения строки хотя бы в одном из параметров: Обратите внимание, локализованные значения аналогичных полей, которые передаются в localization_values, не участвуют в поиске.

Не менее 3 символов.
exclude_renew_ar_products
number
Исключение дочерних продуктов из ответа
Исключает из ответа продукты, которые соответствуют всем перечисленным условиям:
  • Продукт является дочерним по отношению к другому продукту. То есть идентификатор найденного продукта присутствует в параметре renew_settings.product_id_for_renew другого продукта (родительского)
  • У родительского продукта включена подписка с автоматическим продлением (AR), то есть renew_settings.renew_ar.enable:true
  • Найденный продукт не является одновременно родительским продуктом и продлевающим его дочерним продуктом
Посмотрите примеры использования.

Варианты значения:
  • 1 - дочерние продукты исключаются из ответа, кроме ситуаций, когда родительский продукт продлевается сам на себя
  • 0 - дочерние продукты не исключаются из ответа.
Если не передано, то дочерние продукты не исключаются из ответа

При использовании двух фильтров: search_string и exclude_renew_ar_products = 1, в ответе будут возвращены:
  • Родительские продукты, у которых найдено вхождение переданной в search_string строки
  • Родительские продукты, у которых нет вхождения из переданной в search_string строки, но к продукту привязан хотя бы один дочерний продукт, в котором вхождение есть
exclude_zero_price_products
number
Исключение продуктов с нулевой ценой из ответа
Например, исключение продуктов с бесплатным пробным периодом, подарков, продуктов, у которых не заданна цена.

Варианты значения:
  • 1 - продукты с нулевой ценой исключаются из ответа
  • 0 - продукты с нулевой ценой не исключаются из ответа
Если не передано, то продукты с нулевой ценой не исключаются из ответа.
sale_currency
string
Поиск продуктов по валюте продажи
Если передано, то в ответе будут возвращены продукты, которые доступны для продажи хотя бы в одной из переданных валют. Обратите внимание, если цены продукта заданы в базовой валюте (common price, ценовые модели One price, Volume pricing), то он считается доступным для продажи во всех валютах, разрешенных договором.
  • Формат: sale_currency[]=[валюта продажи], где [валюта продажи] – это код валюты в формате ISO 4217 alpha-3, 3 символа, варианты значений см. в справочнике. Например: sale_currency[]=USD
  • В запросе может быть передано несколько параметров sale_currency с разными валютами продажи, в этом случае они разделяются &. Например: sale_currency[]=USD&sale_currency[]=EUR
Посмотрите дополнительные примеры работы поиска по валюте продажи.
sort_by_update_date
string
Сортировка результов по дате обновления
Позволяет вам отсортировать продукты в результатах поиска по дате и времени последнего обновления.

Варианты значений:
  • desc - сортировка по убыванию дат обновления (от большей даты к меньшей), например: 01.01.2022 00:00:00 > 01.01.2022 00:00:00
  • asc - сортировка по возрастанию дат обновления (от меньшей даты к большей), например: 01.01.2022 00:00:00 > 01.01.2022 00:00:00
Если не передано, то список продуктов в результате будет отсортирован по убыванию id продуктов, например, 100 > 99.
AuthorizationJWT
required
Авторизационный токен.
  • Формат значения: Bearer [token]
  • Вместо [token] подставьте значение token, полученное в ответ на запрос к Authentication API.
  • /v1/product
    Все доступные продукты. Список отсортирован по убыванию id продуктов
  • /v1/product?search_string=test
    Все доступные продукты, у которых строка "test" присутствует хотя бы в одном из полей, перечисленных в описании параметра search_string. Список отсортирован по убыванию id продуктов
  • /v1/product?exclude_renew_ar_products=1
    Все доступные продукты, за исключением дочерних продуктов для продления AR подписки. Список отсортирован по убыванию id продуктов
  • /v1/product?sale_currency[]=USD&sale_currency[]=EUR
    Все доступные продукты, у которых разрешена продажа хотя бы в одной из валют: USD, EUR
  • /v1/product?limit=10
    Первые 10 найденных продуктов. Список отсортирован по id продуктов
  • /v1/product?limit=10&offset=5
    10 продуктов, начиная с 6 по 15. Список отсортирован по id продуктов
  • /v1/product?offset=5
    Все продукты, начиная с 6 из найденных. Список отсортирован по id продуктов
  • /v1/product?sort_by_update_date=desc
    Все доступные продукты. Список отсортирован по убыванию даты обновления продуктов (update_date)
  • Для продукта 001 выключена подписка с автоматическим продлением (AR):
    "renew_settings": {
     "renew_ar": {
      "enable": false
     },
     "renew_pmr": false,
     "renew_email": false
    }
    
  • В ответ на запрос /v1/product?exclude_renew_ar_products=1 вернется продукт 001
  • Для продукта 002 включена подписка с автоматическим продлением (AR). Продукт 002 используется для создания подписки и ее продления (то есть одновременно является родительским и дочерним для себя):
    "renew_settings": {
     "product_id_for_renew": [002],
     "renew_ar": {
      "enable": true
     }
    }
    
  • В ответ на запрос /v1/product?exclude_renew_ar_products=1 вернется продукт 002, так как применяется исключение - продукт продлевается сам на себя
  • Для продукта 003 включена подписка с автоматическим продлением (AR). Продукт 003 является родительским, то есть инициирует создание подписки. Для продления подписки используется продукт 004
    "renew_settings": "renew_settings": {
     "product_id_for_renew": [004,004],
     "renew_ar": {
      "enable": true
     }
    }
    
  • В ответ на запрос /v1/product?exclude_renew_ar_products=1 вернется продукт 003. Продукт 004 отсутствует в ответе, так как является дочерним
  • Для продукта 006 выключена подписка с автоматическим продлением (AR), но включена PMR подписка. Продукт 006 является родительским, то есть инициирует создание подписки. Для продления подписки используется продукт 007
    "renew_settings": {
     "product_id_for_renew": [007, 007],
     "renew_ar": {
      "enable": false
     },
     "renew_pmr": true
    }
    
  • В ответ на запрос /v1/product?exclude_renew_ar_products=1 вернутся продукты 006 и 007, так как подписки AR выключены и исключение дочерних продуктов не применяется

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

  • Продукт 001 – имеет индивидуальные цены в валютах продажи: AUD, CAD
  • Продукт 002 – имеет одну цену в базовой валюте продажи: EUR, таким образом этот продукт доступен для продажи во всех валютах в соответствии с вашим договором

Валюты, доступные по договору: USD, EUR, AUD, CAD, GBP, NZD

Параметры в запросе

Продукты в ответе

sale_currency[]=AUD

001, 002

sale_currency[]=EUR

002

sale_currency[]=USD

002

sale_currency[]=AUD&sale_currency[]=USD

001, 002

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

При успешной обработке запроса вы получите код ответа сервера HTTP/1.1 200 OK. В теле ответа будет передан список найденных продуктов в формате JSON.

count_all
number
required
Количество найденных продуктов
limit
number
required
Количество продуктов в ответе
offset
string
required
Сдвиг
Позиция продукта, со следующей за которой возвращены продукты в ответе.
product_ids
array [numbers]
required
Идентификаторы найденных продуктов
По умолчанию, если сортировка не задана параметром sort_by_update_date, то id в списке отсортированы от большего номера к меньшему. Массив может вернуться пустым, если продукты не найдены, например:
  • Нет созданных продуктов
  • В запросе задан сдвиг (offset) больше доступного числа продуктов (count_all)
{
 "count_all": 51,
 "limit": 51,
 "offset": 0,
 "product_ids": [
  444841127,
  444652444,
  666435276
 ]
}
{
 "count_all": 0,
 "limit": 0,
 "offset": 0,
 "product_ids": []
}
{
 "count_all": 108,
 "limit": 0,
 "offset": 150,
 "product_ids": []
}

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

Код ответа сервера Описание
HTTP/1.1 400 Bad Request Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.).
В теле ответа будет передан дополнительный код ошибки (один или несколько).
HTTP/1.1 401 Unauthorized Неуспешная аутентификация.
В теле ответа будет передан дополнительный код ошибки (один или несколько). 
HTTP/1.1 404 Not found Неверный URL запроса. Проверьте адрес запроса.
HTTP/1.1 500 Request Error Ошибка на стороне сервера. Повторите запрос позднее или обратитесь в службу поддержки.
Error Message Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
1025 Failed to identify settings for obtaining product list. Please contact technical support. При обработке не смогли однозначно определить настройки вашего аккаунта. Обратитесь в службу поддержки.
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
1200 Search is executed if string has at least three characters in it.

В запросе передан параметр search_string, но его значение меньше 3 символов.

1210 Invalid field value: [наименование параметра]

Запрос не валиден, например, передано неверное название параметра, тип или формат значения параметра неверны.
В том числе ошибка будет возвращена, если:

  • В параметре передано null, и этот вариант значения не указан как допустимый.
  • Передан параметр sort_by_update_date и его значение не совпадает с одним из возможных вариантов.
1220 Failed to generate a response for product [id]. Please contact technical support.

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

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

errors
array [objects]
required
Список ошибок
errors / [error object]
/
error
number
required
Код ошибки
errors / [error object]
/
message
string
Описание ошибки
{
 "errors": [{
   "error": 1200,
   "message": "Search is executed if string has at least three characters in it."
  }
 ]
}