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

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

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

POST /v1/promotion/statistics/

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

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

Если на продукт в один и тот же период времени действует несколько промоакций, то:

Покупатель получит скидку только от одной из них. Скидки не суммируются
Примение промоакции будет учтено:
- Для промоакции, скидка из которой была применена к продукту
- Для других промоакций (подробнее смотрите далее), которые подходили под условия применения, но не были применены

При этом:

Статус заказа не учитывается (то есть заказ может быть неоплачен/оплачен/удален)
Применение учитывается по продуктам в заказе. Например, если в заказе два продукта, и к каждому из них была применена скидка, то это учитывается, как два применения промоакции
Количество единиц продукта в заказе не учитывается. Например, если в заказе 5 шт одного и того же продукта, или 1 шт, и к ним была применена промоакция, то это учитывается, как одно применение
Если тип промоакции был изменен, то применения не обнуляются. Например, если тип промоакции был изменен с coupon на discount, то в статистике будет информация и о применении промокодов, и о применении скидок

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

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

Параметры заголовка

content-type

required

MIME-тип данных

Должен быть равен "application/json".

AuthorizationJWT

required

Авторизационный токен

Формат значения: Bearer [token]
Вместо [token] подставьте значение token, полученное в ответ на запрос к Authentication API

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

string

required

Идентификатор промоакции
Вы можете получить его в ответ на запросы:

Пример запроса

{
 "id": 12345
}

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

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

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

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

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

promotion_uses

number

required

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

Будет равно 0, если промоакция не была применена.

coupons

array [objects]

Данные о применении промокодов
Массив возвращается в ответе в случае, если промоакция имеет тип coupon или к ней ранее были привязаны промокоды, которые были применены.

Содержит массив со списком промокдов, который включает:

Все промокоды, которые на текущий момент принадлежат промоакции, и статистику их применения. Если какой-либо промокод еще не был применен, то он будет присутствовать в ответе с количеством применений равным 0
Все промокоды, которые ранее принадлежали промоакции, были применены, но затем были удалены из промоакции. Обратите внимание, эта ситуация также возможна, если тип промоакции был изменен с coupon на discount. Если какой-либо промокод принадлежал промоакции, но не был применен, то он не будет присутствовать в ответе

coupons / [object]

coupon_code

string

required

Промокод

coupons / [object]

coupon_code

string

required

Тип промокода на момент применения

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

one-time - в этом случае один и тот же промокод может быть применен только к продуктам одного заказа. При управлении промоакцией через портал данный тип промокодов называется "disposable"
reusable - в этом случае один и тот же промокод может быть применен к продуктам нескольких заказов

coupons / [object]

coupon_uses

number

required

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

coupons / [object]

coupon_id

number

required

Идентификатор промокода

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

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

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

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

Справочник 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	Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
110	JSON is not valid.	Структура параметров запроса невалидна. Проверьте параметры в теле запроса на соответствие формату JSON.
111	Invalid data format (Content-type).	Неправильный заголовок запроса. Content-type должен быть равен application/json.
11000	No access to promotion management. Please contact technical support.	При обработке не смогли однозначно определить настройки вашего аккаунта. Обратитесь в службу поддержки.
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
11010	Invalid field value: [наименование параметра]	Запрос не валиден, например, не заполнен обязательный параметр, передано неверное название параметра, тип или формат значения параметра неверны. В том числе ошибка будет возвращена, если в параметре передано null, и этот вариант значения не указан как допустимый.

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

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

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

Error	Message	Описание
11200	Promotion not found: [id промоакции]	Запрос не может быть выполнен. Промоакция с переданным id не найдена или у вас нет доступа к ней. В ошибке будут передан идентификаторы промоакции, не прошедший проверку.

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

errors

array [objects]

required

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

errors / [error object]

error

number

required

Код ошибки.

errors / [error object]

message

string

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

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

{
 "errors": [{
   "error": 11200,
   "message": "Promotion not found: 123"
  }
 ]
}