Sección 05

Endpoints del Aggregator

Lista de juegos, apertura y cierre de sesiones, y consulta de rondas.

Endpoints del Aggregator#

Estos son los endpoints que tu plataforma llama a AIC: listar juegos, abrir un juego para un jugador, cerrar la sesión de juego y consultar el detalle de una ronda. Los endpoints protegidos requieren el token Bearer JWT (ver Configuración de la conexión).

Obtener lista de juegos#

Devuelve los juegos habilitados para tu proyecto.

POST{{URL_AGG}}/games/getGameList

AuthBearer JWT requerido

Ejemplo de solicitud

curl -X POST "{{URL_AGG}}/games/getGameList" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "projectId": "projectId"
  }'

Body de la solicitud

Parámetro	Tipo	Requerido	Descripción
projectId	string	Sí	Project ID de tu proyecto.

Respuesta exitosa (extracto)

{
  "statusCode": 200,
  "data": [
    {
      "id": "clmgj4mer000fawnho0gyt7ma",
      "gameId": "clmgj4mer000fawnho0gyt7ma",
      "name": "Roman",
      "imageUrl": "https://res.cloudinary.com/.../clmgj4mer000fawnho0gyt7ma.png",
      "gameCategoryCat": {
        "id": "cl8z582jm0000vu1keo4slqp3",
        "name": "Slots",
        "code": "sm"
      },
      "gameModel": "SEAMLESS",
      "supplierName": "AIC Games",
      "enabled": true,
      "gameAggregatorStatusCat": "Enabled"
    }
  ],
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Campos relevantes por juego

Parámetro	Tipo	Descripción
gameId	string	Identificador del juego. Es el valor que envías en enterGame y el que recibirás en las llamadas de wallet.
name	string	Nombre comercial del juego.
imageUrl	string	Imagen del juego para tu lobby.
gameCategoryCat	object	Categoría del juego (nombre y código).
gameModel	string	Modalidad de wallet del juego: SEAMLESS o TRANSFER.
supplierName	string	Nombre comercial del proveedor o marca del juego.
enabled	boolean	Indica si el juego está habilitado para tu proyecto.

Nota

La respuesta incluye campos adicionales de uso interno; basa tu integración solo en los campos documentados en esta tabla.

Abrir un juego#

Abre una sesión de juego para un jugador y devuelve la URL de lanzamiento.

POST{{URL_AGG}}/games/enterGame

AuthBearer JWT requerido

Ejemplo de solicitud

curl -X POST "{{URL_AGG}}/games/enterGame" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "gameId": "clmgj4mer000fawnho0gyt7ma",
    "playerName": "casinoPlayer123",
    "projectId": "projectId",
    "token": "playerSessionToken",
    "language": "es",
    "device": "desktop"
  }'

Respuesta exitosa

{
  "statusCode": 200,
  "data": {
    "url": "https://provider.example.com/launch?session=..."
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Respuesta con error

{
  "statusCode": 200,
  "data": "GAME_DISABLED",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Parámetros del body

Parámetro	Tipo	Requerido	Descripción
gameId	string	Sí	Identificador del juego (obtenido en la lista de juegos).
playerName	string	Sí	Identificador del jugador en tu plataforma. Ver reglas en Flujos por modalidad.
projectId	string	Sí	Project ID de tu proyecto.
token	string	Sí	Token de sesión del jugador generado por tu plataforma, único por sesión de juego. AIC te lo devolverá como token_room en cada llamada de wallet para que identifiques la sesión.
language	string	No	Idioma del juego (por ejemplo es, en, pt). Se aplica si el proveedor lo soporta.
device	string	No	Tipo de dispositivo: desktop o mobile. Se aplica si el proveedor lo soporta.

Respuesta

Éxito: data.url contiene la URL de lanzamiento del juego. Algunos proveedores devuelven data.html, un documento que debes incrustar en lugar de redirigir.
Errores: el juego no se pudo abrir en cualquiera de estos casos:

Respuesta	Significado
HTTP 401 o 402 con `No games available`	Tu proyecto no está habilitado o no tiene juegos disponibles.
HTTP 200 con `data` = `No games available`	El juego no está disponible para tu proyecto.
HTTP 200 con `data` = `GAME_DISABLED`	El juego está deshabilitado.
HTTP 200 con `data` = `Not a valid supplier`	El proveedor del juego no está disponible para tu proyecto.
HTTP 400 con `An error has occurred in enterGame`	No se pudo abrir el juego (por ejemplo, un `gameId` inexistente).

Importante

Lanza el juego solo si la respuesta es HTTP 200 y data es un objeto con url (o html). Cualquier otra respuesta significa que el juego no se abrió.

Cerrar la sesión de juego#

Cierra la sesión de juego del jugador. Es obligatorio en los juegos Transfer: es la llamada que hace que el balance regrese a tu plataforma (ver Flujos por modalidad).

POST{{URL_AGG}}/games/logout-game/:projectId

AuthBearer JWT requerido

Ejemplo de solicitud

curl -X POST "{{URL_AGG}}/games/logout-game/:projectId" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "playerName": "casinoPlayer123"
  }'

Respuesta exitosa

{
  "statusCode": 200,
  "data": {
    "status": "success",
    "message": "user logged out successfully"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Parámetro de URL

Parámetro	Tipo	Requerido	Descripción
projectId	string	Sí	Project ID de tu proyecto.

Parámetros del body

Parámetro	Tipo	Requerido	Descripción
playerName	string	Sí	Identificador del jugador cuya sesión se cierra.

La sesión se busca solo dentro de tu proyecto. Si el playerName no tiene sesión abierta en tu proyecto, la respuesta es HTTP 200 con data = { "status": "error", "message": "GAME_ROOM_NOT_FOUND" } y no se cierra ninguna sesión.

Nota

En los juegos Transfer, el balance resultante no viaja en esta respuesta: AIC lo acredita en tu plataforma mediante la llamada add-win a tu API.

Obtener ronda jugada#

Consulta el detalle de una ronda. Útil para conciliación y atención de incidencias.

GET{{URL_AGG}}/games/:merchantName/round-played/:idTransaction

AuthBearer JWT requerido

Ejemplo de solicitud

curl "{{URL_AGG}}/games/:merchantName/round-played/:idTransaction" \
  -H "Authorization: Bearer <token>"

Respuesta exitosa

{
  "data": {
    "id": "9db6be09-7afa-4a30-b388-66ffa1f2f191",
    "playerName": "casinoPlayer123",
    "amountBet": 90,
    "amountWin": 100,
    "balanceAfterBet": 10,
    "balanceAfterWin": 110,
    "idTransaction": "9db6be09-7afa-4a30-b388-66ffa1f2f190",
    "token_room": "playerSessionToken",
    "gameId": "clmgj4mer000fawnho0gyt7ma",
    "timestamp": "1723644383536",
    "movements": [
      {
        "movementId": "3f2a9c4e-7b1d-5e8a-9c2f-1a6b4d8e0f73",
        "type": "add-bet",
        "amount": 90,
        "idTransaction": "9db6be09-7afa-4a30-b388-66ffa1f2f190",
        "createdAt": "2026-11-02T15:39:12.104Z"
      },
      {
        "movementId": "b7d40e19-2c8f-5a6e-8d13-5f9c0a2e7b46",
        "type": "add-win",
        "amount": 100,
        "idTransaction": "9db6be09-7afa-4a30-b388-66ffa1f2f191",
        "createdAt": "2026-11-02T15:39:14.587Z"
      }
    ]
  },
  "status": {
    "code": "0",
    "message": "Success",
    "datetime": "2026-10-20T21:07:03.930Z"
  }
}

Respuesta con error

{
  "data": null,
  "status": {
    "code": 404,
    "message": "Transaction not found",
    "datetime": "2026-10-20T15:34:40.304Z"
  }
}

Parámetros de URL

Parámetro	Tipo	Requerido	Descripción
merchantName	string	Sí	Merchant Name de tu proyecto.
idTransaction	string	Sí	idTransaction que recibiste en la llamada de wallet (add-bet o add-win) de esa ronda.

Errores

Merchant Name inexistente: HTTP 400 con CUSTOMER_NOT_FOUND.
Transacción no encontrada: HTTP 200 con status.code 404.
Transacción que no pertenece a tu proyecto: HTTP 200 con status.code 409.

Campos de respuesta

Parámetro	Tipo	Descripción
id	string	Id de la transacción.
playerName	string	Identificador del jugador.
amountBet	number	Cantidad apostada.
amountWin	number	Cantidad ganada (0 si no hay ganancia).
balanceAfterBet	number	Balance después de la apuesta.
balanceAfterWin	number	Balance después de la ganancia (null si no hay ganancia).
idTransaction	string	Identificador de la transacción.
timestamp	string	Timestamp de la ronda en milisegundos (Epoch Unix).
token_room	string	Token de la sesión de juego asociada.
gameId	string	Identificador del juego.
movements	array	Movimientos de saldo de la ronda, en orden. Cada uno trae movementId, type (add-bet, add-win o rollback), amount, idTransaction y createdAt.