Термины

API

Набор HTTP-методов, через которые партнер авторизуется, создает купоны и получает их состояния.

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

Купон, по которому еще ожидается расчетный результат. Его можно получить через:

GET /api/partner/coupons/active

Азиатский рынок

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

Bearer JWT

Подписанный токен клиентского аккаунта, полученный через /api/partner/login.

Передается:

Authorization: Bearer <token>

JWT определяет владельца купонов. Административный токен для клиентских методов не подходит.

Callback

HTTP POST, который Система расчета купонов SportAPI отправляет на URL партнера при изменении расчетного состояния.

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

Callback secret

Секретная фраза, которую менеджер создает при подключении callback. Используется как ключ HMAC-SHA256 и хранится только на сервере партнера.

Cashout

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

Текущая функция находится в разработке, полностью не протестирована и не предназначена для production. Доступный экспериментальный метод не продает купон и не изменяет баланс.

`batchId`

Идентификатор конкретной версии пакета callback.

повторная доставка одного пакета имеет тот же batchId;
новое расчетное состояние получает новый batchId;
это не ID купона и не ID ставки.

Используется для дедупликации доставки.

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

Баланс партнера внутри Системы расчета купонов SportAPI.

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

`body`

Поле общей оболочки API, содержащее результат операции или дополнительные данные ошибки.

Тип зависит от endpoint: объект, массив, строка или null.

`calculate_coef`

Итоговый расчетный коэффициент всего купона. До финального расчета полной модели равен null.

В callback называется calculate_coefficient.

`calc_coef`

Расчетный множитель отдельной ставки:

выигрыш — исходный коэффициент;
проигрыш — 0;
возврат или push — 1;
половинный проигрыш — 0.5;
половинный выигрыш — (coef + 1) / 2.

В callback поле ставки называется calculate_coefficient.

`calculate_date`

Время расчета купона или ставки в Unix-миллисекундах.

До расчета равно null. Значение 0 для нерассчитанного объекта не используется.

`code`

Общий результат бизнес-операции:

1 — успех;
0 — ошибка.

HTTP 200 с code = 0 не является успешной бизнес-операцией.

`coupon_code`

Публичный код купона, обычно состоящий из 12 цифр:

000000000272

Хранится строкой вместе с ведущими нулями. Используется как основной ключ связи с системой партнера.

`coupon_type`

Тип купона:

1 — ординар;
2 — экспресс.

`error_code`

Числовая машиночитаемая причина бизнес-ошибки. Используется в программной логике вместо сравнения текста error_message.

HMAC-SHA256

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

Передается:

X-Coupon-Signature: sha256=<hex>

HTTP endpoint

URL, принимающий определенный HTTP-метод. Клиентские endpoint предоставляет SportAPI, а callback endpoint создает партнер.

Idempotency / идемпотентность

Свойство обработки, при котором повтор одного события не повторяет бизнес-эффект.

Например, повторный callback с тем же batchId не должен создавать второе начисление.

Финансовая идемпотентность дополнительно защищает от повторного результата, полученного через разные источники — callback и polling.

Inbox

Внутренняя надежная очередь партнера для сохранения входящих callback до дальнейшей бизнес-обработки.

JWT

См. Bearer JWT.

`lang`

Двухбуквенный код языка названий в купоне.

Поддерживается около 50 языков. Язык фиксируется при создании; получить существующий купон в другом переводе сейчас нельзя.

`line`

Прематч-линия: исходы событий до их начала.

В указателе и модели:

line_type = line
is_live = false

`live`

Линия события, которое уже идет.

В указателе и модели:

line_type = live
is_live = true

`mode`

Правило обработки изменившегося коэффициента:

reject — отклонить;
accept — принять по правилу mode_type.

`mode_type`

Направление изменения коэффициента, которое можно принять при mode = accept:

1 — только повышение;
2 — только понижение;
3 — любое изменение.

`multi`

Правило формирования купонов из list_bets:

false — один общий ординар или экспресс;
true — отдельный ординар для каждого элемента.

При multi = true сумма amount применяется отдельно к каждому созданному купону.

Outbox

Надежная внутренняя очередь исходящих callback в Системе расчета купонов SportAPI.

Partner / партнер

Компания или система, которая принимает ставки конечных пользователей и подключается к API SportAPI.

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

Polling

Периодический запрос состояний купонов через клиентский API.

Может использоваться:

без callback;
как резервная сверка при callback;
для восстановления после сбоя.

Push

Результат с расчетным множителем 1, используемый при равном результате. Статус ставки — 23.

Push отдельной ставки не увеличивает и не обнуляет коэффициент экспресса.

`rate`

Параметр исхода, например значение тотала или форы. Если параметр не требуется, обычно передается 0.

`raw_pointer`

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

`real_win`

Фактическая выплата после расчета купона. Используется партнером для финального начисления.

В callback называется realWin.

Не путать с potential_win.

Recalculate / перерасчет

Новый расчет ранее рассчитанного результата.

Во время ожидания:

купон имеет статус 15;
соответствующая ставка имеет статус 4.

Статус 15 не является финальным.

Settlement / расчет

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

`settlement_reason_code`

Стабильный машиночитаемый код причины расчета или возврата отдельной ставки. Может использоваться для аналитики и программной логики. Набор значений расширяемый.

`settlement_reason`

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

Sub-event / саб-событие

Связанная часть основного матча: тайм, период, сет, угловые, фолы и другие зависимые события.

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

`status`

Числовое состояние объекта.

Купон и ставка имеют разные справочники статусов. Значение нужно интерпретировать по уровню объекта.

Событие

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

Идентифицируется полем game_id.

Ставка

Один принятый исход внутри купона.

В полной модели имеет events_data[].id, а в callback — строковый events_data[].uuid.

Группа ставок / рынок

Набор связанных исходов, например:

исход матча;
тотал;
фора;
обе команды забьют.

Идентифицируется bet_group_id.

Исход

Конкретный выбор внутри группы ставок, например «Победа первой команды» или «Тотал больше 2.5».

Идентифицируется bet_id.

Конечный пользователь

Пользователь системы партнера, который формирует корзину и подтверждает ставку.

SportAPI не управляет его аккаунтом и балансом.

Коэффициент

Числовое значение, участвующее в расчете возможной выплаты.

На уровне купона:

original_coef — при создании;
coef — текущее отображаемое значение;
calculate_coef — итоговое расчетное значение.

Корзина ставок

Предварительный выбор пользователя до подтверждения API.

Корзина не является принятым купоном. Принятый купон сохраняется только после ответа создания с code = 1.

Купон

Принятая ставка или набор ставок с общими:

coupon_code;
суммой amount;
статусом;
расчетной выплатой.

Ординар

Купон с одной ставкой. Имеет coupon_type = 1.

Экспресс

Один купон с несколькими ставками на разные матчи. Имеет coupon_type = 2.

В одном экспрессе допускается не более 15 событий.

Половинный выигрыш

Статус ставки 21. Расчетный множитель:

(coef + 1) / 2

Половинный проигрыш

Статус ставки 22. Расчетный множитель:

0.5

Потенциальная выплата

Поле potential_win: возможная выплата, рассчитанная при создании купона.

Не используется как фактическое начисление после расчета.

Указатель ставки

Строка, однозначно описывающая выбранный исход:

line_type#game_id#group_id#type_id#rate#coefficient[#player_id]

Берется из спортивной линии и передается без изменений.

Возврат

Результат ставки с расчетным множителем 1.

Статус ставки — 3. Если весь купон возвращен, статус купона — 8.

Финансовая операция

Изменение баланса. В интеграции существуют два разных уровня:

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

Операции в системе партнера должны быть идемпотентными, чтобы повторный callback или polling не изменил пользовательский баланс второй раз.

Следующий раздел: «История изменений».