Спортивная аналитика и AI-диалоги для вашего бизнеса

Авторизация и повторы

Базовый URL — https://sportexa.online/api/partner/v1. Отправляйте запросы со своего сервера с заголовками Authorization: Bearer <token> и Accept: application/json. Для JSON-запросов укажите Content-Type: application/json. Храните партнёрский ключ на сервере.

Для создания сессии и отправки действия передавайте Idempotency-Key длиной до 128 символов. Генерируйте уникальный ключ для каждого хода в пределах партнёрского аккаунта. При сетевом сбое повторите тот же запрос с тем же ключом.

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

Создать сессию

POST /sessions запускает разбор предстоящего матча из лиг, подключённых для вашего аккаунта. Подставьте доступный ID вместо условного 12345.

curl https://sportexa.online/api/partner/v1/sessions \
  -H "Authorization: Bearer ${SPORTEXA_PARTNER_TOKEN}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: open-42-001' \
  -d '{"external_user_id":"customer-42","match_id":12345,"locale":"ru"}'

• external_user_id — стабильный идентификатор пользователя вашей площадки, строка до 128 символов. Используйте внутренний ID вместо имени или email.
• match_id — положительное целое число. Вместо него можно передать match_query с полными названиями обоих участников, например «Оренбург — Спартак», до 200 символов.
• locale — язык ответа и кнопок, ru или en.
• bookmaker_id — необязательный положительный ID из каталога Sportexa. Настройка вашего аккаунта имеет приоритет.

Готовый результат возвращается с HTTP 200. Пример структуры ответа ниже.

{
  "session_id": "00000000-0000-4000-8000-000000000001",
  "operation_id": "00000000-0000-4000-8000-000000000002",
  "status": "ready",
  "answer_id": "00000000-0000-4000-8000-000000000002",
  "answer": "Краткий разбор матча.",
  "actions": [{"id": "why", "label": "Почему?"}]
}

Продолжить диалог

POST /sessions/{session_id}/messages принимает answer_id из последнего ответа и action_id из его массива actions. Отображайте кнопки по label и обновляйте их после каждого готового ответа. В примере why должно быть среди доступных действий.

curl "https://sportexa.online/api/partner/v1/sessions/${SESSION_ID}/messages" \
  -H "Authorization: Bearer ${SPORTEXA_PARTNER_TOKEN}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: followup-42-001' \
  -d "{\"answer_id\":\"${ANSWER_ID}\",\"action_id\":\"why\"}"

Проверить состояние операции

Обычный режим возвращает разбор синхронно. Пока ход ещё обрабатывается, API возвращает HTTP 202 с status: processing, session_id и operation_id. Запрашивайте GET /sessions/{session_id}/operations/{operation_id} с тем же ключом Bearer, пока ответ обрабатывается. Остановите опрос после 200 или терминальной ошибки. ИИ-режим с асинхронной обработкой доступен только по отдельному согласованию в рамках пилота. Режим задаётся для аккаунта.

Ошибки

• 401 — ключ отсутствует, недействителен или отозван.
• 404 match_not_found — матч недоступен или не найден среди подключённых событий.
• 409 match_ambiguous — выберите match_id из массива candidates и отправьте новый запрос.
• 409 action_unavailable — действие больше не доступно. Используйте кнопки последнего готового ответа.
• 409 idempotency_conflict — этот ключ уже связан с другим запросом.
• 422 — проверьте поля запроса.
• 429 — лимит запросов. Соблюдайте Retry-After, если он возвращён.
• 503 — операция завершилась ошибкой или разбор временно недоступен.

Получите токен виджета на сервере

Отправьте POST /api/partner/v1/widget-tokens с партнёрским ключом. Используйте поля создания сессии и добавьте origin страницы встраивания. Он должен совпадать с согласованным адресом площадки по схеме, домену и порту. Определяйте external_user_id по сессии пользователя на своём сервере.

curl https://sportexa.online/api/partner/v1/widget-tokens \
  -H "Authorization: Bearer ${SPORTEXA_PARTNER_TOKEN}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"external_user_id":"customer-42","match_id":12345,"locale":"ru","origin":"https://partner.example"}'

Ответ HTTP 201 содержит token и expires_at. Передайте в браузер только токен виджета. Он действует один час и привязан к пользователю, матчу и origin.

Подключите скрипт на странице матча

В примере widgetToken — токен, полученный от вашего сервера. Передайте тот же язык, что и при выдаче токена.

<script src="https://sportexa.online/sportexa-widget.js"></script>
<script>
  const widget = window.SportexaWidget.mount({ token: widgetToken, locale: 'ru' });
</script>

Разбор запускается по нажатию кнопки в виджете. Для другого матча вызовите widget.destroy() перед повторным подключением и запросите новый токен. После истечения токена запросите новый, чтобы открыть новый чат. Если сайт ограничивает CSP, разрешите https://sportexa.online в script-src и frame-src.