Интеграция

Соглашения

Запросы и ответы#

• Серверные вызовы — POST с Content-Type: application/json и телом-JSON-объектом. Тела application/x-www-form-urlencoded тоже разбираются, но контракт — JSON. Всегда передавайте один из этих двух типов содержимого: при любом другом, например text/plain, тело не разбирается как JSON и вызов завершается ошибкой (обычно UNAUTHORIZED, так как partner не найден).
• Тело ограничено 128 КиБ (131072 байта). Слишком большое тело отклоняет веб-сервер: HTTP 413 и HTML-страница, до API запрос не доходит, поэтому JSON-конверта ошибки нет. Некорректный JSON, а также отсутствующий или неподдерживаемый тип содержимого (например, application/xml) дают HTTP 400 REQUEST_FAILED, а не INVALID_REQUEST.
• Успешные ответы содержат "status": "ok" и поля результата.
• Ошибки имеют вид {"status":"error","message":"<CODE>"}, HTTP-статус зависит от кода. message — всегда код в верхнем регистре; см. справочник ошибок. Сбой без публичного кода — REQUEST_FAILED.
• Ответы отправляются с Cache-Control: no-store: кэшируйте публичный каталог у себя.
• Публичные GET endpoints тоже возвращают JSON (Каталог). На запрос с неверным HTTP-методом или неизвестным путём API отвечает HTTP 404 и JSON другого вида, {"message":"Route GET:/nope not found","error":"Not Found","statusCode":404}, а не конвертом ошибки.

Идемпотентность#

POST /playGame.do и POST /gameActions.do принимают необязательный заголовок Idempotency-Key: от 1 до 128 печатных ASCII-символов (без пробелов). Некорректный ключ даёт HTTP 400 INVALID_IDEMPOTENCY_KEY.

• Область действия. Ключ действует в пределах вашего проекта и endpoint (/playGame.do и /gameActions.do хранят ключи раздельно). В /gameActions.do один и тот же ключ для двух разных значений method — конфликт. /playerRtp.do заголовок не использует.
• Повтор запроса с тем же ключом и тем же телом возвращает первый ответ, не выполняя работу заново. Поле api_key в сравнении не участвует.
• Тот же ключ с другим телом даёт IDEMPOTENCY_CONFLICT: HTTP 400 в /playGame.do, HTTP 409 в /gameActions.do.
• Методы report_* заголовок игнорируют (они только читают). freespins_create и outcome_schedule дополнительно защищены external_id (DUPLICATE_EXTERNAL_ID).
• Без заголовка вызов выполняется каждый раз (запуск без ключа считается новым запуском).

Лимиты запросов#

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

• Квота — «ведро токенов»: целую минуту вызовов можно отправить пачкой, токены возвращаются непрерывно. POST /playerRtp.do и публичные GET endpoints не ограничиваются.
• Ведро выбирается по полю partner тела до проверки ключа: вызовы с известным partner и неверным ключом тоже расходуют квоту, а 429 может прийти раньше 401. Счётчики хранятся в памяти процесса сервера и обнуляются при его перезапуске.
• При превышении квоты ответ — HTTP 429 RATE_LIMITED, ничего не выполняется. Учтённые ответы содержат X-RateLimit-Limit (например, 600/min); разрешённые — ещё и X-RateLimit-Remaining; отказ содержит Retry-After в целых секундах (не менее 1).
• Значения окружения — в rateLimits в GET /capabilities; более высокие можно согласовать с менеджером.

HTTP/1.1 429 Too Many Requests
Retry-After: 7
X-RateLimit-Limit: 600/min
content-type: application/json

{"status":"error","message":"RATE_LIMITED"}

При 429 подождите Retry-After секунд и повторите с тем же Idempotency-Key. Не опрашивайте отчёты: листайте report_rounds через cursor, а report_ggr и report_reconciliation вызывайте раз за период. Колбэки платформы к вам в эти квоты не входят.

Суммы#

У всех валют два знака после запятой (Валюты). Суммы точные: разбирайте их десятичным типом, а не числом с плавающей точкой.

Допускается не более двух знаков после запятой и не более 13 цифр до точки; ведущие нули запрещены. Платформа отправляет суммы колбэков JSON-числами ровно с двумя знаками (1.50, а не 1.5). Некоторые информационные поля meta (nominal_bet, total_win внутри meta.freespins, multiplier) — обычные числа без дополнения нулями. Подпись считайте и проверяйте по исходным байтам тела, а не по пересериализованному JSON (Подпись колбэков).

Даты и время#

• expires_at, created_at, finished_at и подобные поля — ISO 8601. Когда вы отправляете expires_at, в нём должна быть зона (Z или +02:00), например 2027-02-01T12:00:00Z.
• Колбэки кошелька содержат Unix-время в секундах (meta.time, timestamp).

Идентификаторы#

Неизвестные поля#

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

Таймауты и повторы с вашей стороны#

Используйте клиентский таймаут около 10 секунд; при таймауте или 5xx повторите вызов с тем же Idempotency-Key. 4xx — окончательный ответ: сначала исправьте запрос.