Получение одного купона

Метод возвращает текущее состояние одного купона вместе со всеми ставками внутри него.

Используйте его, когда нужно:

• открыть карточку купона;
• проверить, завершен ли расчет;
• получить фактическую выплату;
• восстановить полную информацию после callback;
• проверить конкретный купон при расхождении данных.

Метод

GET /api/partner/coupons/get

Запрос требует действующий Bearer JWT клиентского аккаунта:

Authorization: Bearer <token>

Параметр купона

Рекомендуемый параметр:

Пример:

/api/partner/coupons/get?coupon_code=000000000272

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

• code;
• coupon_id;
• bet_code.

Для новой интеграции всегда используйте coupon_code: это основное и наиболее понятное имя поля во всех методах API.

Передавайте только один параметр с кодом купона.

Ведущие нули

coupon_code нужно хранить и передавать как строку:

{
  "coupon_code": "000000000272"
}

Так ведущие нули не потеряются при сохранении или передаче данных.

Новый API умеет дополнить короткое числовое значение нулями слева до 12 знаков:

272 → 000000000272

Тем не менее рекомендуется всегда передавать полный 12-значный код. Это исключает неоднозначность в базе партнера, логах и запросах между внутренними сервисами.

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

HTTP:

GET /api/partner/coupons/get?coupon_code=000000000272 HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Accept: application/json

cURL:

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

curl --request GET \
  --url "$BASE_URL/api/partner/coupons/get?coupon_code=$COUPON_CODE" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $TOKEN"

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

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

Метод возвращает купон непосредственно в body:

{
  "code": 1,
  "body": {
    "coupon_code": "000000000272",
    "amount": 10,
    "win": 18.5,
    "potential_win": 18.5,
    "real_win": 18.5,
    "coef": 1.85,
    "original_coef": 1.85,
    "calculate_coef": 1.85,
    "has_return": false,
    "date": 1784970000000,
    "status": 2,
    "asian": false,
    "calculate_date": 1784973600000,
    "coupon_type": 1,
    "events_count": 1,
    "events_data": [
      {
        "id": 84521,
        "game_id": 737779544,
        "main_game_id": null,
        "is_sub_game": false,
        "parent_game_id": null,
        "sub_game_key": null,
        "raw_pointer": "line#737779544#1#1#0#1.85",
        "line_type": "line",
        "is_live": false,
        "bet_group_id": 1,
        "bet_group_name": "Исход матча",
        "bet_id": 1,
        "bet_name": "Победа первой команды",
        "sport_id": 1,
        "sport_name": "Футбол",
        "tournament_id": 45821,
        "tournament": "Национальная лига",
        "event_date": 1784971800000,
        "status": 1,
        "opp1": "Команда A",
        "opp2": "Команда B",
        "coef": 1.85,
        "calc_coef": 1.85,
        "calculate_date": 1784973600000,
        "calculate_score": "2:1",
        "settlement_reason_code": "AUTOMATIC_SETTLEMENT",
        "settlement_reason": "Calculated automatically",
        "rate": "0"
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "date": 1784973600100,
  "time_ms": 6,
  "path": "/api/partner/coupons/get"
}

В объекте body находятся:

• общие данные купона;
• сумма и значения выигрыша;
• исходный и расчетный коэффициенты;
• статус и даты;
• тип купона и количество ставок;
• events_data со всеми ставками купона.

Каждая ставка в events_data содержит собственный внутренний id, данные события и исхода, коэффициенты, статус расчета, даты и счет.

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

Важно. В этом методе body является объектом одного купона. Здесь нет массива body.coupons. Массив используется при создании купонов и в методах группового получения.

Как определить состояние

Основные поля для проверки:

Сразу после создания купон обычно содержит:

{
  "status": 0,
  "real_win": null,
  "calculate_coef": null,
  "calculate_date": null
}

null означает, что итоговое значение еще не сформировано. Для нерассчитанного купона calculate_date не принимает значение 0.

Финальными статусами купона являются:

• 2 — выигрыш;
• 4 — проигрыш;
• 8 — возврат.

Статусы 0 и 15 не являются финальными. При статусе 15 купон возвращен на перерасчет, поэтому нужно ожидать нового результата.

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

Полные правила описаны в разделе «Статусы и расчет выплаты».

Купон и ставки имеют разные статусы

Поле body.status относится ко всему купону, а body.events_data[].status — к отдельной ставке.

Таблицы статусов купона и ставки различаются, поэтому коды нельзя интерпретировать без учета объекта. Примеры возможных сочетаний:

Выигравший ординар:
status купона = 2
status ставки = 1

Проигравший ординар:
status купона = 4
status ставки = 2

Купон возвращен на перерасчет:
status купона = 15
status ставки = 4

Всегда интерпретируйте status в контексте объекта, в котором находится поле.

Идентификаторы

Не путайте идентификаторы:

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

coupon_code + events_data[].id

game_id и bet_id могут встречаться в разных купонах и не заменяют внутренний ID принятой ставки.

В callback внутренний ID ставки передается в поле events_data[].uuid как строка.

Купон не найден

Если купон не существует или принадлежит другому партнеру, API возвращает одинаковую бизнес-ошибку:

{
  "code": 0,
  "body": null,
  "error_code": 471,
  "error_message": "Coupon not found",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/coupons/get"
}

Одинаковый ответ не раскрывает, существует ли такой код у другого партнера.

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

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

Не ограничивайтесь проверкой HTTP 200.

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

При error_code = 471 не создавайте пустой купон и не заменяйте сохраненную карточку пустыми данными. Сначала проверьте переданный coupon_code и принадлежность JWT нужному клиентскому аккаунту.

Совместимые маршруты

Новый маршрут имеет алиас с тем же новым форматом:

GET /api/v3/partner/bet/get?coupon_code=000000000272

Для новой интеграции рекомендуется использовать канонический маршрут:

GET /api/partner/coupons/get?coupon_code=000000000272

В старом API использовался:

GET /coupons/get?coupon_code=000000000272

Старый маршрут пока поддерживается, но возвращает прежний формат ответа и требует код ровно из 12 цифр. При неверном коде он возвращает error_code = 560, а если купон не найден — error_code = 561.

Полное сравнение контрактов находится в разделе «Переход со старого API».

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

• Используется GET /api/partner/coupons/get.
• Передается действующий Bearer JWT.
• Параметр называется coupon_code.
• Код хранится строкой вместе с ведущими нулями.
• Успех проверяется по code = 1.
• Купон читается из объекта body, а не из body.coupons.
• Обрабатываются данные купона и весь массив events_data.
• Статусы купона и ставки интерпретируются отдельно.
• Для выплаты используется финальное значение real_win.
• Статус 15 не считается окончательным.
• Ошибка 471 обрабатывается как отсутствие доступного купона.

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