Общие правила API

На этой странице собраны правила, общие для всех методов Системы расчета купонов SportAPI. Описание конкретных полей и бизнес-ошибок приводится на страницах соответствующих методов.

Базовый URL

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

https://coupon-api.example.com

Добавляйте путь метода к полученному базовому URL:

{BASE_URL}/api/partner/coupons/active

Рекомендуется хранить базовый URL без завершающего /. API допускает завершающий / в пути метода, но в одной интеграции лучше использовать единый формат.

Формат запросов

API принимает и возвращает JSON в кодировке UTF-8.

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

Accept: application/json
Content-Type: application/json

Для защищенных методов дополнительно требуется клиентский JWT:

Authorization: Bearer <client_token>

Не передавайте токен в URL или query-параметрах. Подробные правила получения и использования JWT описаны в разделе «Авторизация».

Общая структура ответа

Новые методы возвращают ответ в общей оболочке:

{
  "code": 1,
  "body": {},
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 12,
  "path": "/api/partner/coupons/get"
}

Содержимое body не имеет единого типа для всех методов. Это может быть объект, массив, строка или null. Всегда ориентируйтесь на описание конкретного метода.

Как определить успешность операции

Проверяйте не только HTTP-код, но и поле code:

Бизнес-ошибка обычно возвращается с HTTP 200, поэтому проверка только HTTP-статуса может привести к ошибочному учету купона как принятого.

Пример бизнес-ошибки:

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

Не повторяйте автоматически запрос создания купона после неопределенной сетевой или серверной ошибки, пока не исключена возможность, что первый запрос уже был обработан. Иначе один выбор пользователя может привести к созданию нескольких купонов.

Даты и время

Все даты и время в клиентском API передаются как Unix timestamp в миллисекундах, если для конкретного поля прямо не указано иное.

Пример:

{
  "date": 1784970000000,
  "event_date": 1784977200000,
  "calculate_date": null
}

• date — дата создания объекта или формирования ответа в зависимости от контекста;
• event_date — запланированное время начала спортивного события;
• calculate_date — время расчета купона или ставки.

До расчета calculate_date имеет значение null. Значение 0 для нерассчитанного купона или исхода не используется.

Не путайте миллисекунды с секундами: timestamp в миллисекундах обычно содержит 13 цифр.

Десятичные числа

Суммы, коэффициенты и выплаты передаются как JSON-числа без фиксированного количества знаков после запятой:

{
  "amount": 10,
  "coef": 1.85,
  "potential_win": 18.5
}

Значения 10, 10.0 и 10.00 не следует считать разными суммами. Интеграция не должна зависеть от текстового количества знаков после запятой.

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

Значения null, отсутствующие поля и пустые строки

Эти значения имеют разный смысл:

• null — поле присутствует, но значение пока отсутствует или неприменимо;
• отсутствующее поле — параметр не передан либо поле не входит в конкретный формат ответа;
• "" — передана пустая строка.

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

Например, для callback_url значения null и "" означают, что callback для создаваемого купона отправляться не будет. Если партнер не использует callback, он также может передать в этом поле основной домен своего сайта. Для числовых, логических и обязательных полей пустая строка не является заменой null.

Язык названий

Поле lang задает язык названий спорта, турнира, команд, группы ставок и исхода в данных купона.

• передавайте двухбуквенный код языка;
• API поддерживает около 50 языков;
• регистрируйте и отправляйте один согласованный код для каждого купона;
• язык фиксируется при создании: получить существующий купон на другом языке сейчас нельзя;
• полный список языков в этой документации не публикуется.

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

Поддержка нескольких вариантов перевода одного купона находится в разработке.

Код купона

coupon_code — публичный номер купона. Он обычно содержит 12 цифр:

{
  "coupon_code": "000000000272"
}

Храните и передавайте coupon_code как строку:

• ведущие нули являются частью кода;
• преобразование в число может превратить "000000000272" в 272;
• coupon_code не равен внутреннему ID записи в базе данных;
• используйте его для связи купона в SportAPI с записью в системе партнера.

Новые методы получения купона принимают несколько совместимых названий query-параметра, но для новой интеграции рекомендуется использовать каноническое имя coupon_code.

Доступ к данным

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

API возвращает только данные аккаунта, которому принадлежит токен. При запросе чужого купона система не раскрывает его существование и отвечает так же, как для неизвестного кода.

Совместимость

Основная документация описывает новые методы /api/partner/**. Старые методы пока продолжают поддерживаться, но могут отличаться:

• набором полей в общей оболочке ответа;
• кодами ошибок;
• расположением данных внутри body;
• правилами HTTP-статусов;
• форматом отдельных параметров.

Не смешивайте старый и новый контракты в одном обработчике без явной проверки маршрута. Для перехода существующей интеграции используйте самостоятельное руководство «Переход со старого API».

При чтении JSON не полагайтесь на порядок полей и допускайте появление новых необязательных полей в будущих совместимых обновлениях.

Следующий раздел: «Указатель ставки».