La solicitud de sesión

Su servidor abre un juego para un jugador con POST /v1/sessions. La llamada es de servidor a servidor: la clave va en el encabezado X-API-Key, y el navegador nunca llama a la 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" } }

Los campos obligatorios son playerId, currency, mode y exactamente uno de publicId o universalId. El identificador del jugador tiene de 1 a 64 caracteres ASCII imprimibles y nombra a un jugador de su propio sistema: WGC no crea ningún jugador, porque la billetera se queda en su casino. La moneda es un código de 3 a 8 letras, y el modo es real o demo. Los campos opcionales fijan el idioma, la dirección de retorno, la plataforma (escritorio o móvil), el país del jugador, su propio número de sesión y, para los juegos que los aceptan, el RTP y los límites de apuesta.

Qué trae la respuesta

url es el enlace de lanzamiento, sessionId es el número de la sesión tal como lo verá su casino, y expiresAt es la hora hasta la cual funciona un enlace sin abrir. Guarde el identificador de sesión: es el número con el que consulta la sesión más adelante y el número que aparece en los informes. Anotarlo en sus registros junto con el jugador y el juego le permite encontrar la sesión de inmediato en una solicitud de soporte.

Abra el enlace en el navegador del jugador

El enlace es una dirección propia de WGC y debe abrirse en el navegador del jugador, redirigiendo la página a él o colocándolo en un frame. No lo pida desde su servidor. El enlace registra el dispositivo que lo abre, y una petición desde su servidor se registraría como la apertura del jugador. Por eso su servidor solo recibe el enlace y se lo entrega al jugador; abrirlo es tarea del navegador.

Cuánto vive el enlace

  • Un enlace que ningún navegador ha abierto funciona durante 5 minutos. Para abrirlo más tarde, pida uno nuevo con una nueva solicitud de sesión.
  • Una vez que el navegador del jugador lo abrió, el enlace vive mientras el jugador siga jugando, es decir, mientras sigan llegando llamadas de billetera.
  • Después de que se cierra la sesión, el enlace responde con una página clara y el estado 410. Para volver a jugar, el juego se abre otra vez desde su lobby con una nueva solicitud de sesión. Si el jugador guardó un enlace viejo, verá la misma página; no es un error, sino una señal clara de que la sesión terminó.

Coloque el enlace en un frame

El enlace puede colocarse en un <iframe> con allow="fullscreen; autoplay". No añada un atributo sandbox a menos que lleve al menos allow-scripts allow-same-origin allow-popups, porque un sandbox más estricto impide que el juego funcione. En algunos juegos el enlace funciona una sola vez: una recarga en una pestaña nueva es una segunda apertura. Cuando eso ocurra, repita la solicitud de sesión y abra el enlace nuevo, que es la misma sesión con una dirección de juego nueva. Si un juego queda vacío en su frame pero se abre en una pestaña nueva, escriba al soporte en vivo indicando el juego y su dominio.

La dirección de retorno y el idioma

returnUrl devuelve al jugador a su lobby cuando termina el juego. Sin ella, WGC muestra una página neutra. No todos los juegos aceptan una dirección de retorno, y el lobby dentro del juego no funciona en todos los estudios, así que ofrezca a los jugadores una salida del frame en su propia página.

El idioma es un código ISO 639-1. Se admite una región como pt-BR y la región se corta. Un código de país enviado en lugar de un idioma se reemplaza, de modo que ua pasa a ser uk. Un código desconocido vuelve al inglés, y el juego nunca se rechaza por el idioma. Lo que el juego muestra realmente depende del estudio; por eso no lea que se muestre un idioma como una promesa y compruebe usted mismo las combinaciones de idioma importantes.

Una sesión abierta por jugador y juego

Mientras una sesión está abierta, una segunda solicitud para el mismo jugador, juego, moneda y modo devuelve esa sesión y el mismo enlace de lanzamiento. Dos aperturas en el mismo instante, como un doble clic, responden ambas con la misma sesión, y si la primera todavía no tiene enlace, la otra responde try_later. Otro jugador, otra moneda u otro modo es otra sesión. Cuando la sesión se cierra, la siguiente apertura crea una nueva.

El encabezado opcional Idempotency-Key, válido durante 24 horas, hace segura una solicitud repetida: la misma clave y el mismo cuerpo devuelven la misma respuesta sin una nueva llamada al estudio, y un cuerpo distinto es invalid_request. Una clave no renueva un enlace vencido: después de expiresAt, abra la sesión con una clave nueva. Estas dos reglas juntas evitan que un doble clic o un reintento de red generen sesiones duplicadas para el jugador.

Rechazos que debe esperar

error.codeHTTPQué hacer
unauthorized401Revise la clave.
invalid_request400Corrija el campo que nombra el mensaje. También se rechaza un demo abierto con una clave de producción.
not_found404El juego no existe, no está asignado a su cuenta o no tiene precio para ella. No sondee.
currency_not_granted400La moneda no está asignada a su cuenta.
balance_required402Una sesión real necesita dinero en la cuenta. Recargue, o abra un demo con una clave de prueba.
country_restricted403El estudio prohíbe el juego en el país del jugador. Ofrezca otro juego.
rate_limited429Espere los segundos indicados en Retry-After.
try_later409La apertura anterior con esta clave sigue en curso. Reintente en un segundo.
busy503WGC está bajo carga; reintente después de Retry-After.

Bifurque solo por error.code; el mensaje es para las personas. Defina de antemano, para cada rechazo, un texto corto para el jugador y el código que guardará en su propio registro, de modo que un rechazo no deje al jugador con dudas y sea rastreable para su equipo. Un juego que no está disponible en alguna moneda queda marcado en el catálogo, y un lanzamiento en esa moneda se rechaza mientras las demás monedas siguen funcionando. Un lanzamiento real necesita fondos en su cuenta comercial: el saldo más el límite de crédito debe ser mayor que cero, mientras que un lanzamiento demo no mueve dinero. La apertura de sesiones está limitada por clave, y el valor predeterminado es 600 por minuto.

Leer una sesión más adelante

Su servidor puede leer una sesión por su número con GET /v1/sessions/{sessionId}, que muestra su estado, la moneda, el modo y los totales, o encontrar sus sesiones por su propio número con GET /v1/sessions?casinoSessionId=. Solo se ven las sesiones de su cuenta. En las solicitudes de soporte, cite el identificador de sesión, el número de solicitud y la hora en UTC. Para lo que ocurre dentro de una ronda, vea el flujo de la ronda, y para las repeticiones, el artículo sobre idempotencia.

Vea la descripción general de la API de casino, los pasos de integración, el modo demo y de prueba y la página de billetera seamless para las llamadas que siguen al lanzamiento.