[GET] Получение списка промоакций

Softline CheckoutИнтеграцияPromotions API

Описание запроса

GET /v1/promotion

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

Данные для отправки запроса

Endpoints URL:
- Боевая среда: https://api.ecommerce.softline.com/v1/promotion
- Тестовая среда: https://api.ecommerce.softline.com.demoslweb.com/v1/promotion
Метод: GET
Авторизация: с помощью токена

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

limit

number

Количество промоакций, которое должно быть возвращено в ответе

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

offset

number

Количество промоакций, на которое нужно сдвинуть выдачу результатов

Если не передано или равно 0, то в ответе будут возвращены все промоакции
Если указать, например, 10, то в ответе вернется список промоакций начиная с 11-ой промоакции из числа найденных

status

number

Статус промоакции

Варианты значения:

1 - активна
0 - деактивирована

Если не передано, то в ответе вернутся промоакции во всех статусах.

expired

number

Завершение срока действия промоакции

Варианты значения:

1 - срок действия промоакции истек, дата и время окончания промоакции [date_to] > текущей даты и времени
0 - срок действия промоакции не завершен. Дата и время окончания промоакции [date_to] ≤ текущей даты и времени

Если не передано, то в ответе вернутся промоакции с любыми датами завершения.

search_string

string

Строка для поиска
Если передано, то в ответе будут возвращены промоакции, у которых найдено вхождение значения строки в названии промоакции (promotion_name).

Не менее 3 символов.

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/promotion
Все доступные промоакции. Список отсортирован по убыванию id промоакции
/v1/promotion?search_string=Черная%20пятница
Все доступные промоакции, у которых строка "Черная пятница" присутствует в названии промоакции (promotion_name)
/v1/promotion?expired=1
Все промоакции, у которых завершен срок действия
/v1/promotion?status=1&expired=0
Все активные промоакции, срок действия которых еще не завершен (или еще не наступил)
/v1/promotion?limit=10&offset=5&sort_by_update_date=desc
10 промоакций, начиная с 6, отсортированные по убыванию даты обновления

Ответ на запрос

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

Положительный ответ

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

Параметры в теле ответа

count_all

number

required

Количество найденных промоакций.

limit

number

required

Количество промоакций в ответе.

offset

string

required

Сдвиг.
Позиция промоакции, со следующей за которой возвращены промоакции в ответе.

ids

array [numbers]

required

Массив идентификаторов найденных промоакций.
По умолчанию, если сортировка не задана параметром sort_by_update_date, то id в списке отсортированы от большего номера к меньшему. Массив может вернуться пустым, если промоакции не найдены, например:

нет созданных промоакций,
в запросе задан сдвиг (offset) больше доступного числа промоакций (count_all).

Пример ответа: Промоакции найдены

{
 "count_all": 51,
 "limit": 51,
 "offset": 0,
 "ids": [
  444841127,
  444652444,
  666435276
 ]
}

Пример ответа: Не найдено промоакций, отвечающих условиям поиска

{
 "count_all": 0,
 "limit": 0,
 "offset": 0,
 "ids": []
}

Пример ответа: Не найдено промоакций, так как заданы неправильные условия поиска (offset>count_all)

{
 "count_all": 108,
 "limit": 0,
 "offset": 150,
 "ids": []
}

Ответ об ошибке

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

Справочник HTTP-кодов ответа сервера при ошибке

Код ответа сервера	Описание
HTTP/1.1 400 Bad Request	Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.). В теле ответа будет передан дополнительный код ошибки (один или несколько).
HTTP/1.1 401 Unauthorized	Неуспешная аутентификация. В теле ответа будет передан дополнительный код ошибки (один или несколько).
HTTP/1.1 404 Not found	Неверный URL запроса. Проверьте адрес запроса.
HTTP/1.1 500 Request Error	Ошибка на стороне сервера. Повторите запрос позднее или обратитесь в службу поддержки.

Справочник дополнительных кодов ошибок для HTTP 400

Error	Message	Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
11000	No access to promotion management. Please contact technical support.	При обработке не смогли однозначно определить настройки вашего аккаунта. Обратитесь в службу поддержки.
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
11010	Invalid field value: [наименование параметра]	Запрос не валиден, например, передано неверное название параметра, тип или формат значения параметра неверны. В том числе ошибка будет возвращена, если: В параметре передано null, и этот вариант значения не указан как допустимый. Передан параметр sort_by_update_date и его значение не совпадает с одним из возможных вариантов.
11100	Search is executed if string has at least three characters in it.	В запросе передан параметр search_string, но его значение меньше 3 символов.

Справочник дополнительных кодов ошибок для HTTP 401

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

Параметры в теле ответа

errors

array [objects]

required

Список ошибок.

errors / [error object]

error

number

required

Код ошибки.

errors / [error object]

message

string

Описание ошибки.

Пример ответа об ошибке

{
 "errors": [{
   "error": 11100,
   "message": "Search is executed if string has at least three characters in it."
  }
 ]
}