Запрос сессии

Ваш сервер открывает игру для игрока вызовом POST /v1/sessions. Вызов идёт между серверами: ключ передаётся в заголовке X-API-Key, а браузер к API никогда не обращается.

POST /v1/sessions
{"publicId":"sweet-bonanza-1","playerId":"casino-side-player-42","currency":"USD","mode":"demo","language":"en"}
→ 200 { "ok": true, "requestId": "req_…", "data": { "url": "https://play.worldgamingconnect.com/play/Zk3p9xQ2vL8mTn4r", "sessionId": "cmgq3r8v40001l8xyz5k2abcd", "expiresAt": "2026-10-12T10:45:00.000Z" } }

Обязательные поля — playerId, currency, mode и ровно одно из publicId или universalId. Идентификатор игрока — от 1 до 64 печатаемых ASCII-символов, он называет игрока в вашей собственной системе: WGC не создаёт игроков, потому что кошелёк остаётся в вашем казино. Валюта — код из 3–8 букв, а режим — real или demo. Необязательные поля задают язык, адрес возврата, платформу (десктоп или мобильная), страну игрока, ваш собственный номер сессии и, для игр, которые их принимают, RTP и лимиты ставок.

Что приходит в ответе

url — ссылка запуска, sessionId — номер сессии так, как его увидит ваше казино, а expiresAt — время, до которого работает неоткрытая ссылка. Сохраните идентификатор сессии: это номер, по которому вы позже запрашиваете сессию, и номер, который стоит в отчётах. Если записать его в свои данные вместе с игроком и игрой, сессию легко найти сразу в обращении в поддержку.

Открывайте ссылку в браузере игрока

Ссылка — собственный адрес WGC, и открывать её нужно в браузере игрока: перенаправив на неё страницу или поместив во фрейм. Не запрашивайте её со своего сервера. Ссылка записывает устройство, которое её открывает, и запрос с вашего сервера записался бы как открытие игроком. Поэтому сервер только получает ссылку и передаёт её игроку, а открывает её браузер.

Сколько живёт ссылка

  • Ссылка, которую не открыл ни один браузер, работает 5 минут. Чтобы открыть её позже, запросите новую новым запросом сессии.
  • Когда браузер игрока её открыл, ссылка живёт, пока игрок продолжает играть, то есть пока приходят вызовы кошелька.
  • После закрытия сессии ссылка отвечает понятной страницей и статусом 410. Чтобы сыграть снова, игру открывают заново из вашего лобби новым запросом сессии. Если игрок сохранил старую ссылку, он увидит ту же страницу; это не ошибка, а ясный знак, что сессия закончилась.

Поместите ссылку во фрейм

Ссылку можно поместить в <iframe> с allow="fullscreen; autoplay". Не добавляйте атрибут sandbox, если он не содержит как минимум allow-scripts allow-same-origin allow-popups, потому что более строгая песочница не даёт игре работать. У некоторых игр ссылка одноразовая: обновление в новой вкладке — это второе открытие. В таком случае повторите запрос сессии и откройте новую ссылку: это та же сессия со свежим адресом игры. Если игра в вашем фрейме остаётся пустой, а в новой вкладке открывается, напишите в живую поддержку, указав игру и свой домен.

Адрес возврата и язык

returnUrl возвращает игрока в ваше лобби, когда игра заканчивается. Без него WGC показывает нейтральную страницу. Не каждая игра принимает адрес возврата, а лобби внутри игры работает не у всех студий, поэтому дайте игрокам собственный выход из фрейма на вашей странице.

Язык — код ISO 639-1. Регион вроде pt-BR допускается, и регион отбрасывается. Код страны, присланный вместо языка, заменяется: ua становится uk. Неизвестный код превращается в английский, и игра никогда не отклоняется из-за языка. Что игра покажет на самом деле, зависит от студии; поэтому не читайте показ языка как обещание и сами проверьте важные сочетания.

Одна открытая сессия на игрока и игру

Пока сессия открыта, второй запрос для того же игрока, игры, валюты и режима возвращает эту сессию и ту же ссылку запуска. Два открытия в один момент, например двойной клик, отвечают одной и той же сессией, а если у первого ещё нет ссылки, второе отвечает try_later. Другой игрок, валюта или режим — это другая сессия. Когда сессия закрыта, следующее открытие создаёт новую.

Необязательный заголовок Idempotency-Key, действующий 24 часа, делает повторный запрос безопасным: тот же ключ и то же тело возвращают тот же ответ без нового обращения к студии, а другое тело — invalid_request. Ключ не продлевает истёкшую ссылку: после expiresAt откройте сессию с новым ключом. Эти два правила вместе не дают двойному клику или сетевому повтору породить для игрока дубли сессий.

Какие отказы ожидать

error.codeHTTPЧто делать
unauthorized401Проверьте ключ.
invalid_request400Исправьте поле, названное в сообщении. Демо, открытое боевым ключом, тоже отклоняется.
not_found404Игры нет, она не выдана вашему аккаунту или для него нет цены. Не перебирайте.
currency_not_granted400Валюта не выдана вашему аккаунту.
balance_required402Настоящей сессии нужны деньги на аккаунте. Пополните или откройте демо тестовым ключом.
country_restricted403Студия запрещает игру в стране игрока. Предложите другую игру.
rate_limited429Подождите число секунд из Retry-After.
try_later409Предыдущее открытие с этим ключом ещё идёт. Повторите через секунду.
busy503У WGC высокая нагрузка; повторите после Retry-After.

Ветвитесь только по error.code; сообщение — для людей. Заранее определите для каждого отказа короткий текст для игрока и код, который вы запишете в свой журнал, чтобы отказ не оставлял игрока в неведении и был прослеживаем для вашей команды. Игра, недоступная в какой-то валюте, помечена в каталоге, и запуск в этой валюте отклоняется, пока остальные валюты работают. Настоящему запуску нужны средства на вашем коммерческом аккаунте: баланс плюс кредитный лимит должен быть больше нуля, а демо-запуск денег не двигает. Открытие сессий ограничено на ключ, по умолчанию 600 в минуту.

Прочитать сессию позже

Ваш сервер может прочитать сессию по номеру вызовом GET /v1/sessions/{sessionId}, который показывает её статус, валюту, режим и итоги, или найти свои сессии по собственному номеру вызовом GET /v1/sessions?casinoSessionId=. Видны только сессии вашего аккаунта. В обращениях в поддержку укажите идентификатор сессии, номер запроса и время в UTC. Что происходит внутри раунда, смотрите в потоке раунда, а о повторах — в статье про идемпотентность.

О вызовах, которые идут после запуска, см. обзор Casino API, шаги интеграции, демо и тестовый режим и страницу seamless-кошелька.