Получение купонов списком и по периоду

Один метод позволяет получить:

известные купоны по списку coupon_code;
купоны, созданные в заданный период.

Эти режимы взаимоисключающие: в одном запросе нужно выбрать только один из них.

Метод

POST /api/partner/coupons/results

Запрос требует:

Authorization: Bearer <token>
Content-Type: application/json

Выбор режима

Режим	Поля запроса	Для чего использовать
По кодам	`coupon_ids`	Получить актуальное состояние конкретных известных купонов.
По периоду	`start_date` и `end_date`	Получить купоны, созданные в определенном временном интервале.

Нельзя передавать coupon_ids одновременно с start_date или end_date.

При неверном наборе параметров API возвращает бизнес-ошибку 1002.

Режим 1. Получение по кодам

Передайте массив coupon_ids:

POST /api/partner/coupons/results HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "coupon_ids": [
    "000000000272",
    "000000000273"
  ]
}

Параметры

Поле	Тип	Обязательное	Описание
`coupon_ids`	array[string]	Да	Коды купонов, которые нужно получить.

В одном запросе можно передать не более 100 кодов.

Храните и передавайте каждый coupon_code как строку, чтобы сохранить ведущие нули:

{
  "coupon_ids": [
    "000000000272"
  ]
}

Особенности результата

При обработке списка API:

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

Поэтому нельзя сопоставлять элементы запроса и ответа по индексу:

coupon_ids[0] ↛ body.coupons[0]

Всегда находите и обновляйте купон по его coupon_code.

Если нужно проверить больше 100 купонов, разделите список на несколько запросов.

Пример cURL

BASE_URL="https://coupon-api.example.com"
TOKEN="<jwt-token>"

curl --request POST \
  --url "$BASE_URL/api/partner/coupons/results" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "coupon_ids": [
      "000000000272",
      "000000000273"
    ]
  }'

Фактический BASE_URL партнер получает у менеджера.

Режим 2. Получение по периоду создания

Передайте обе границы периода:

POST /api/partner/coupons/results HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "start_date": 1784880000000,
  "end_date": 1784966400000
}

Параметры

Поле	Тип	Обязательное	Описание
`start_date`	integer	Да	Начало периода создания, Unix-миллисекунды.
`end_date`	integer	Да	Конец периода создания, Unix-миллисекунды.

Правила:

нужно передать обе даты;
end_date должен быть больше start_date;
интервал не может превышать 24 часа;
значения передаются в миллисекундах, а не в секундах.

Пример интервала ровно 24 часа:

start_date = 1784880000000
end_date   = 1784966400000
difference = 86 400 000 ms

Чтобы запросить более длительный период, разделите его на последовательные интервалы продолжительностью не более 24 часов.

Отбор выполняется по времени создания

Метод сравнивает период с полем создания купона, а не с датой его расчета.

Например:

купон создан:   20 июля
купон рассчитан: 22 июля

Запрос периода создания за 22 июля такой купон не вернет. Чтобы найти результаты, появившиеся за последнее время, используйте GET /api/partner/coupons/calculated.

Поиск по периоду создания подходит для:

восстановления купонов, созданных во время сбоя;
сверки истории за известный день или интервал;
выборки купонов, если их коды не были сохранены локально.

Успешный ответ

В обоих режимах ответ имеет одинаковую структуру:

{
  "code": 1,
  "body": {
    "query_type": "ids",
    "coupons": [
      {
        "coupon_code": "000000000272",
        "amount": 10,
        "potential_win": 18.5,
        "real_win": 18.5,
        "original_coef": 1.85,
        "calculate_coef": 1.85,
        "status": 2,
        "calculate_date": 1784973600000,
        "coupon_type": 1,
        "events_count": 1,
        "events_data": [
          {
            "id": 84521,
            "game_id": 737779544,
            "bet_id": 1,
            "bet_name": "Победа первой команды",
            "status": 1,
            "coef": 1.85,
            "calc_coef": 1.85,
            "calculate_date": 1784973600000,
            "calculate_score": "2:1",
            "settlement_reason_code": "AUTOMATIC_SETTLEMENT",
            "settlement_reason": "Calculated automatically"
          }
        ]
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "date": 1784973600100,
  "time_ms": 8,
  "path": "/api/partner/coupons/results"
}

body.coupons — массив полных актуальных моделей купонов. Каждый купон содержит массив events_data со ставками внутри него.

Пример сокращен до основных полей. Полная структура описана на странице «Модель купона и ставки».

Поле `query_type`

Поле показывает, какой режим запроса был обработан:

Значение	Режим
`ids`	Поиск по `coupon_ids`.
`time`	Поиск по `start_date` и `end_date`.

Не отправляйте query_type в запросе: API формирует его в ответе.

Пустой результат

Успешный запрос может вернуть пустой массив:

{
  "code": 1,
  "body": {
    "query_type": "ids",
    "coupons": []
  },
  "error_code": null,
  "error_message": null
}

Это не ошибка.

Для режима ids пустой массив означает, что среди переданных кодов нет купонов, доступных текущему клиентскому аккаунту.

Для режима time он означает, что в заданном периоде создания нет доступных купонов.

Ошибка параметров

При неверном наборе параметров API возвращает:

{
  "code": 0,
  "body": null,
  "error_code": 1002,
  "error_message": "<описание ошибки параметров>",
  "date": 1784970000000,
  "time_ms": 4,
  "path": "/api/partner/coupons/results"
}

Ошибка 1002 возможна, например, если:

переданы coupon_ids и даты одновременно;
передана только одна граница периода;
интервал дат неположительный;
интервал превышает 24 часа;
набор параметров не позволяет определить режим запроса.

Текст error_message может уточнять конкретную причину. В программной логике ориентируйтесь прежде всего на error_code.

Проверка успешности

Как и в других методах нового API, HTTP 200 сам по себе не означает успешную бизнес-операцию:

HTTP 2xx и code = 1 → запрос выполнен, обработать body.coupons
HTTP 2xx и code = 0 → бизнес-ошибка, проверить error_code
HTTP 401 → JWT отсутствует, неверен или истек
HTTP 403 → токен не имеет необходимого доступа
HTTP 5xx → временная серверная ошибка

Обрабатывайте весь массив body.coupons, а не только первый элемент.

Как сохранять результат

Рекомендуемый алгоритм:

проверить HTTP-код и code;
проверить body.query_type;
перебрать весь массив body.coupons;
найти локальную запись по coupon_code;
обновить общие данные купона;
обновить ставки по сочетанию coupon_code + events_data[].id;
выполнить финансовое действие только для еще не обработанного расчетного состояния.

Повторное получение купона не означает новую ставку. Запросы по кодам, по периоду, polling и callback могут возвращать разные актуальные снимки одного coupon_code.

Отличие от получения одного купона

Один купон	Несколько купонов
`GET /api/partner/coupons/get`	`POST /api/partner/coupons/results`
Код передается в query-параметре	Коды или период передаются в JSON
Купон находится непосредственно в `body`	Купоны находятся в `body.coupons`
Неизвестный код возвращает ошибку `471`	Неизвестные коды пропускаются

Если нужно получить только один известный купон и явно обработать его отсутствие, используйте «Получение одного купона».

Связь с polling

Режим coupon_ids подходит для восстановления известных купонов после длительной недоступности.

Режим дат не является поиском по времени расчета. Для регулярного получения недавних результатов используйте:

GET /api/partner/coupons/calculated?time={minutes}

Практическая схема с перекрывающимися окнами описана на странице «Резервный polling».

Примечание о старом API

Ранее для получения купонов за период использовался:

GET /coupons/list

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

В новом API используйте POST /api/partner/coupons/results. Подробный список изменений приведен в разделе «Переход со старого API».

Контрольный список

Используется POST /api/partner/coupons/results.
Передается Bearer JWT и Content-Type: application/json.
Выбран только один режим запроса.
В coupon_ids передается не более 100 кодов.
Коды купонов хранятся строками.
Для периода передаются обе даты в Unix-миллисекундах.
Интервал периода положительный и не превышает 24 часа.
Учитывается, что период относится ко времени создания.
Результаты сопоставляются по coupon_code, а не по позиции.
Пустой массив обрабатывается как успешный результат.
Обрабатывается весь массив body.coupons и все events_data.
Финансовые операции остаются идемпотентными.

Следующий раздел: «Активные и недавно рассчитанные купоны».

Получение купонов списком и по периоду

Метод

Выбор режима

Режим 1. Получение по кодам

Параметры

Особенности результата

Пример cURL

Режим 2. Получение по периоду создания

Параметры

Отбор выполняется по времени создания

Успешный ответ

Поле query_type

Пустой результат

Ошибка параметров

Проверка успешности

Как сохранять результат

Отличие от получения одного купона

Связь с polling

Примечание о старом API

Контрольный список

Поле `query_type`