Справочник endpoint

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

/api/partner/**

Базовый URL тестового или production-окружения предоставляет менеджер. В документации используется условный адрес:

https://coupon-api.example.com

Полный адрес метода формируется так:

{BASE_URL}{PATH}

Например:

https://coupon-api.example.com/api/partner/coupons/active

Рекомендуемый API

Общие заголовки

Для защищенного запроса:

Authorization: Bearer <token>
Accept: application/json

Для запроса с JSON-телом также передавайте:

Content-Type: application/json

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

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

GET /api/partner/health

Авторизация и параметры не требуются.

Ответ:

{
  "code": 1,
  "body": "ok",
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 1,
  "path": "/api/partner/health"
}

Метод проверяет доступность HTTP API, но не подтверждает правильность логина, JWT или данных конкретного купона.

Авторизация

POST /api/partner/login

Тело:

{
  "username": "<username>",
  "password": "<password>"
}

Поле login поддерживается как совместимый алиас username.

Основной результат:

body.token

Токен передается в остальных защищенных методах как Bearer JWT.

Бизнес-ошибки входа возвращаются с HTTP 200 и code = 0:

Подробнее: «Авторизация».

Создание купона

POST /api/partner/coupons/place

При code = 1 API атомарно создает все купоны и списывает их общую сумму с баланса клиентского аккаунта. При multi = false списывается один amount, при multi = true — amount за каждый созданный ординар. Недостаточный баланс возвращает 507; частичные купоны не создаются.

Основные поля JSON:

Успешно созданные купоны:

body.coupons[]

Даже при создании одного купона coupons является массивом.

Подробнее: «Создание купона».

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

GET /api/partner/coupons/get?coupon_code={coupon_code}

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

coupon_code

Совместимые имена:

code
coupon_id
bet_code

Купон возвращается непосредственно в:

body

Если купон отсутствует или принадлежит другому партнеру:

error_code = 471

Подробнее: «Получение одного купона».

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

POST /api/partner/coupons/results

Метод имеет два взаимоисключающих режима.

По кодам:

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

Не более 100 кодов в одном запросе.

По периоду создания:

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

Один интервал не может превышать 24 часа.

Результат:

body.query_type = "ids" или "time"
body.coupons[]

Подробнее: «Получение купонов списком и по периоду».

Недавно рассчитанные купоны

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

time:

• необязательный;
• по умолчанию равен 5 минутам;
• при значении <= 0 заменяется на 5;
• ограничивается максимумом 120 минут.

Отбор выполняется по времени окончательного расчета, а не создания.

Результат — массив полных моделей непосредственно в:

body[]

Подробнее: «Активные и недавно рассчитанные купоны».

Активные купоны

GET /api/partner/coupons/active

Параметры не требуются.

Результат — массив полных моделей непосредственно в:

body[]

Пустой массив является успешным результатом.

Подробнее: «Активные и недавно рассчитанные купоны».

Баланс клиентского аккаунта

GET /api/partner/balance

Сам метод GET /api/partner/balance только читает баланс и не выполняет пополнение или списание. Успешное создание купона через POST /api/partner/coupons/place списывает средства с этого баланса.

GET /api/partner/balance HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Accept: application/json

Ответ:

{
  "code": 1,
  "body": {
    "balance": 100
  },
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 3,
  "path": "/api/partner/balance"
}

Это баланс авторизованного клиентского аккаунта в Системе расчета купонов SportAPI. Метод не управляет балансами конечных пользователей партнера.

Не путайте два баланса:

• клиентский баланс SportAPI автоматически изменяется при создании купонов;
• баланс конечного пользователя находится в системе партнера и управляется самим партнером.

Callback партнера

Callback не является входящим endpoint SportAPI. Это HTTP endpoint, который создает и размещает партнер.

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

{
  "callback_url": "https://partner.example.com/api/coupon-result"
}

После расчетного изменения Система расчета купонов SportAPI отправляет:

POST {callback_url}
Content-Type: application/json
X-Coupon-Signature: sha256=<hex_hmac_sha256>

JWT в callback не передается. Подлинность проверяется по HMAC-подписи.

Callback необязателен. Для его подключения партнер сообщает менеджеру о своем решении, после чего менеджер включает функцию и создает секретную фразу.

Подробнее:

• «Callback результатов»;
• «Проверка подписи callback».

Форма успешного результата

Не путайте расположение купонов:

Проверка результата

Для нового API:

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

HTTP 200 сам по себе не подтверждает успешную бизнес-операцию.

Подробнее: «Формат ответа API».

Совместимые алиасы нового формата

Эти маршруты сохраняются для совместимости, но не рекомендуются для новой интеграции:

Маршрут /api/v3/partner/bet/list относится к старому контракту списка и не является алиасом нового /coupons/results.

Старые маршруты

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

Старые и новые маршруты могут возвращать разные структуры данных и коды ошибок.

Подробнее:

• «Переход со старого API»;
• «Совместимые старые маршруты».

Cashout

Текущий экспериментальный маршрут:

GET /coupons/cashout?coupon_code={coupon_code}

Статус:

• находится в разработке;
• полностью не протестирован;
• не имеет нового маршрута /api/partner/**;
• не рекомендуется для production.

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

Подробнее: «Cashout».

Завершающий слеш

Для перечисленных маршрутов допускается завершающий /:

/api/partner/coupons/active
/api/partner/coupons/active/

В одной интеграции рекомендуется использовать единый формат URL.

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

• Новый код использует /api/partner/**.
• Базовый URL получен у менеджера.
• Защищенные запросы передают Bearer JWT.
• JSON-запросы передают Content-Type: application/json.
• Проверяются HTTP-код и поле code.
• Форма body определяется по конкретному методу.
• coupon_code хранится строкой.
• Callback endpoint принадлежит партнеру и проверяет HMAC.
• Старые маршруты не смешиваются с новой моделью ответа.
• Cashout не используется в production.

Следующий раздел: «Формат ответа API».