Обзор API

API приема и расчета ставок позволяет партнеру передавать выбранные пользователями спортивные ставки в Систему расчета купонов SportAPI (далее — Система расчета), получать подтверждение их приема и узнавать результат после завершения события.

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

Для кого предназначен API

API подходит системам, которые уже получают спортивную линию и хотят передавать ставки на централизованный расчет, например:

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

Для создания купона партнеру потребуется указатель выбранного исхода из спортивной линии. Формат указателя описан в разделе «Указатель ставки».

Основные понятия

Термин	Значение
Исход	Вариант результата, который выбрал пользователь, например победа первой команды или тотал больше 2,5.
Ставка	Один выбранный исход с зафиксированным коэффициентом.
Купон	Запись, которая объединяет одну или несколько ставок и содержит общую сумму ставки.
Ординар	Купон с одной ставкой.
Экспресс	Купон с несколькими ставками. Итог зависит от расчета всех входящих ставок.
`coupon_code`	Публичный уникальный код созданного купона. По нему партнер связывает данные Системы расчета со своей системой.
Расчет	Определение результата ставки и итогового состояния купона: выигрыш, проигрыш, возврат или другой расчетный результат.

Как проходит обработка купона

Авторизация
→ выбор исхода из спортивной линии
→ создание купона
→ проверка актуальности ставок
→ сохранение coupon_code
→ расчет ставок
→ получение результата

1. Авторизация

Партнер входит в клиентский API по логину и паролю и получает JWT. Этот токен нужно передавать во всех защищенных запросах.

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

2. Выбор исхода

Пользователь выбирает исход в интерфейсе партнера. Вместе с исходом партнер получает из Sport Line API идентификаторы события, группы ставок, типа исхода, параметр ставки и текущий коэффициент.

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

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

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

POST /api/partner/coupons/place

Перед сохранением Система расчета проверяет каждый исход по актуальной линии:

существует ли событие и выбранный исход;
доступен ли исход для приема;
не изменился ли коэффициент;
можно ли объединить выбранные ставки в один купон.

Если проверка пройдена, API атомарно создает купон, списывает его сумму с баланса клиентского аккаунта SportAPI и возвращает данные. При multi = true списывается сумма каждого созданного ординара. Если общей суммы недостаточно, API возвращает 507, не создает частичных купонов и не изменяет баланс.

Клиентский баланс SportAPI не является балансом конечного пользователя: пользовательский кошелек партнер ведет и изменяет самостоятельно.

До успешного ответа содержимое корзины партнера является только предварительным выбором пользователя. Сохранять его как принятый купон нельзя: запись принятого купона создается только по данным body.coupons после ответа с code = 1.

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

4. Сохранение данных купона

После успешного создания API возвращает общие данные купона и массив events_data с подробной информацией по всем ставкам внутри него.

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

coupon_code следует хранить как строку, потому что код может начинаться с нулей.

5. Расчет

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

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

Подробнее: «Жизненный цикл расчета».

6. Получение результата

Партнер может получать результаты двумя способами.

Способ	Как работает	Когда использовать
Запросы к API	Система партнера самостоятельно запрашивает один купон, список купонов, активные или недавно рассчитанные купоны.	Как основной вариант без callback либо для периодической сверки.
Callback	Система расчета отправляет партнеру подписанный HTTP-запрос после изменения расчетного состояния.	Для автоматического получения результатов без постоянного опроса API.

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

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

Подробнее:

Что нужно получить перед подключением

Менеджер предоставляет партнеру:

базовый URL клиентского API;
логин;
пароль;
при подключении callback — секретную фразу для проверки подписи.

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

Важные правила

Используйте рекомендуемые маршруты /api/partner/**.
Передавайте клиентский JWT в каждом защищенном запросе.
Сохраняйте coupon_code как строку и не удаляйте ведущие нули.
Проверяйте поле code в JSON-ответе. Бизнес-ошибка может прийти с HTTP 200.
Все даты и время передаются как Unix timestamp в миллисекундах.
Суммы, коэффициенты и выплаты передаются как десятичные числа без фиксированного количества знаков после запятой.
Партнер самостоятельно определяет правила округления и отображения числовых значений.
Получить можно только купоны, принадлежащие клиенту из JWT.

Подробнее: «Общие правила API».

Если вы используете старый API

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

Все изменения маршрутов, запросов, ответов, ошибок и клиентской логики собраны в одном документе: «Переход со старого API».

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