AG GAMELa API de slots, a tu manera.
Español
Contactar

AG GAME · Slots API V5.0.0

Documentación de Game API para la integración de Slots de AG GAME

Esta documentación de API de slots ofrece la referencia pública de AG GAME Slots API V5.0.0. Use la referencia para revisar la firma, el inicio de juego, los flujos de monedero, los registros de transacciones y el tratamiento de errores; después, siga el proceso de integración para confirmar acceso y materiales de prueba específicos del proyecto.

Resumen de la API y alcance de acceso

Referencia pública y materiales controlados del proyecto

Esta página explica el propósito del protocolo público actual. La URL base real, las credenciales, las restricciones completas de campos, la lista final de callbacks y la configuración de producción se confirman por proyecto mediante la integración controlada.

Referencia de la Slots API

Preparación para pruebas y producción

Materiales requeridos y próximos pasos

Prepare el alcance del proyecto, la arquitectura de monedero y los materiales de prueba; después, use el proceso de integración para confirmar entornos, responsabilidades y condiciones verificables de lanzamiento.

Iniciar el proceso de integración · Hablar sobre acceso de prueba

Autenticación y firma

Cabeceras comunes

CabeceraTipoObligatorioDescripción
X-MERCHANT-CODEstringObligatorioCódigo de comercio asignado a la plataforma
X-TIMESTAMPstringObligatorioMarca de tiempo de la solicitud
X-NONCEstringObligatorioCadena aleatoria usada en cada solicitud
X-SIGNstringObligatorioFirma de la solicitud generada con HmacSHA256
X-CONTENT-PROCESSING-TYPEstringObligatorioTipo de procesamiento de contenido indicado según la configuración de integración

Cadena de firma

Serialice el cuerpo JSON final. Concatene los valores en el orden indicado, sin separadores, y calcule HMAC-SHA256 con la clave de firma. Envíe el resultado en X-SIGN. Los bytes firmados deben coincidir exactamente con los enviados; reformatear JSON puede producir C10004.

merchantCode + timestamp + nonce + signType + body
import { createHmac } from "node:crypto";
const signType = "HmacSHA256";
const body = JSON.stringify(requestBody);
const signingText = merchantCode + timestamp + nonce + signType + body;
const signature = createHmac("sha256", secretKey)
  .update(signingText, "utf8")
  .digest("hex");

Respuesta común

El resultado de negocio se obtiene mediante code. El estado HTTP por sí solo no confirma el resultado de una transacción.

CampoTipoDescripción
codestringCódigo de resultado de negocio
msgstringMensaje de resultado
successbooleanIndicador de éxito en el ejemplo
dataobjectDatos de respuesta de la operación
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {}
}

Catálogo de 17 capacidades públicas

Catálogo de juegos y sesiones

  • POST /game/v5/providers

    Listar proveedores de juegos

  • POST /game/v5/categories

    Listar categorías de juegos

  • POST /game/v5/games

    Listar juegos con paginación

  • POST /game/v5/game/url

    Crear una sesión para jugador y obtener una URL de inicio

  • POST /game/v5/player/force/logout

    Forzar el cierre de una sesión de juego

Callbacks de monedero único

  • POST {MERCHANT-URL}/wallet/balance

    Consultar el saldo de monedero de un jugador

  • POST {MERCHANT-URL}/player/info

    Consultar información de jugador

  • POST {MERCHANT-URL}/wallet/bet

    Recibir una notificación de apuesta

  • POST {MERCHANT-URL}/wallet/win

    Recibir una notificación de liquidación o liquidación de apuesta

  • POST {MERCHANT-URL}/wallet/cancel

    Recibir una notificación de cancelación de pedido

Monedero de transferencia

  • POST /game/v5/cash/deposit

    Transferir fondos a un monedero de juego de jugador

  • POST /game/v5/cash/withdraw

    Transferir fondos desde un monedero de juego de jugador

  • POST /game/v5/cash/balance

    Consultar el saldo de monedero de juego de un jugador

  • POST /game/v5/cash/transaction

    Listar registros de transacciones de monedero con paginación

  • POST {CONTROLLED-PATH:FUND-RECOVERY}

    Recuperar todos los fondos de un monedero de juego mediante una operación controlada

Registros y comercio

  • POST /game/v5/game/record

    Listar registros de juego con paginación

  • POST {CONTROLLED-PATH:MERCHANT-CONFIGURATION}

    Consultar configuración de comercio e información de monedero mediante una operación controlada

POST/game/v5/game/urlCrear sesión de juego

Crea una sesión de juego para un jugador específico y devuelve una URL que puede iniciar el juego.

Autenticación: encabezados comunes de solicitudContent-Type: application/json

Campos de la solicitud

CampoTipoObligatorioDescripción
reqTraceIdstringObligatorioIdentificador único de solicitud; no se puede reutilizar
gameCodestringObligatorioCódigo de juego
playerIdstringObligatorioIdentificador único de jugador en el lado del comercio
currencyCodestringObligatorioCódigo de moneda del monedero
languagestringObligatorioIdioma de la interfaz del juego
terminalTypestringOpcionalTipo de terminal: PHONE o PC; PHONE de forma predeterminada
returnUrlstringOpcionalURL de retorno después de que el jugador salga del juego
ipAddressstringObligatorioDirección IPv4 o IPv6 del jugador
subMerchantCodestringOpcionalCódigo de subcomercio; no puede contener guion bajo
nickNamestringOpcionalApodo del jugador
avatarUrlstringOpcionalURL de avatar del jugador
Solicitud
{
  "reqTraceId": "trace-demo-001",
  "gameCode": "{game-code}",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "language": "en",
  "terminalType": "PC",
  "returnUrl": "https://{merchant-host}/lobby",
  "ipAddress": "192.0.2.10"
}
Respuesta
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameCode": "{game-code}",
    "playerId": "player-demo-001",
    "gameUrl": "https://{game-launch-host}/session/{token}",
    "expireTime": "2026-08-08T10:30:00Z"
  }
}

Campos de respuesta

CampoTipoDevueltoDescripción
data.gameCodestringObligatorioCódigo de juego
data.playerIdstringObligatorioIdentificador de jugador
data.gameUrlstringObligatorioURL de inicio del juego
data.expireTimestringOpcionalHora de caducidad de la sesión

POST{MERCHANT-URL}/wallet/winCallback de liquidación de monedero

En modo de monedero único, la plataforma envía una notificación de pago o de liquidación de apuesta al monedero del comercio. El comercio debe procesar la transacción de forma idempotente y devolver el saldo resultante en la respuesta.

Dirección: plataforma → comercioTipo: win / bet_win

Campos de la solicitud

CampoTipoObligatorioDescripción
reqTraceIdstringObligatorioIdentificador único de solicitud
playerIdstringObligatorioIdentificador único de jugador en el lado del comercio
currencyCodestringObligatorioCódigo de moneda del monedero
gameCodestringObligatorioCódigo de juego
transactionIdstringObligatorioIdentificador único de transacción de plataforma
roundIdstringObligatorioIdentificador único de ronda de juego
betIdstringObligatorioIdentificador de apuesta relacionada
betAmountstringObligatorioImporte de apuesta para esta transacción
winAmountstringObligatorioImporte de pago para esta transacción
isFreebooleanObligatorioIndica si el registro fue generado por un juego gratuito
isEndbooleanObligatorioIndica si la ronda de juego actual ha terminado
betTimestringObligatorioHora de apuesta
settledTimestringObligatorioHora de liquidación
typestringObligatorioTipo de notificación: win o bet_win
Solicitud de callback
{
  "reqTraceId": "trace-demo-002",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "gameCode": "{game-code}",
  "transactionId": "txn-demo-002",
  "roundId": "round-demo-001",
  "betId": "bet-demo-001",
  "betAmount": "10.00",
  "winAmount": "18.50",
  "isFree": false,
  "isEnd": true,
  "betTime": "2026-08-08T10:00:00Z",
  "settledTime": "2026-08-08T10:00:08Z",
  "type": "bet_win"
}
Respuesta del comercio
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "merchantBetId": "merchant-bet-demo-001",
    "balance": "108.50"
  }
}

POST/game/v5/cash/depositTransferir fondos al monedero de juego

En modo de monedero de transferencia, transfiere el importe indicado desde el sistema del comercio al monedero de juego de un jugador.

Esquema de monedero: monedero de transferenciaClave de transacción: merchantTransactionId

Campos de la solicitud

CampoTipoObligatorioDescripción
reqTraceIdstringObligatorioIdentificador único de solicitud usado para el seguimiento de solicitudes
playerIdstringObligatorioIdentificador único de jugador en el lado del comercio
currencyCodestringObligatorioCódigo de moneda del monedero
amountstringObligatorioImporte de transferencia
merchantTransactionIdstringObligatorioIdentificador único de transacción del comercio usado para conciliación
Solicitud
{
  "reqTraceId": "trace-demo-003",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "amount": "100.00",
  "merchantTransactionId": "merchant-txn-demo-001"
}
Respuesta
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "balance": "100.00"
  }
}
Conciliación de transacciones

Genere un merchantTransactionId único para cada transferencia y conserve la solicitud y el resultado de negocio para poder conciliar el estado final mediante el endpoint de consulta de transacciones.

POST/game/v5/game/recordConsultar registros de juego

Consulta los registros de apuestas y pagos de un jugador por rango de tiempo con paginación.

Campos de la solicitud

CampoTipoObligatorioDescripción
reqTraceIdstringObligatorioIdentificador único de solicitud
pageNumintegerObligatorioNúmero de página
pageSizeintegerObligatorioRegistros por página
reqData.startTimestringObligatorioHora inicial de consulta
reqData.endTimestringObligatorioHora final de consulta
sortstringOpcionalOrden de clasificación
Solicitud
{
  "reqTraceId": "trace-demo-004",
  "pageNum": 1,
  "pageSize": 50,
  "reqData": {
    "startTime": "2026-08-08T00:00:00Z",
    "endTime": "2026-08-08T23:59:59Z"
  },
  "sort": "DESC"
}
Respuesta
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameRecordList": [{
      "orderNo": "order-demo-001",
      "playerId": "player-demo-001",
      "betAmount": "10.00",
      "winAmount": "18.50",
      "betTime": "2026-08-08T10:00:00Z",
      "winTime": "2026-08-08T10:00:08Z",
      "gameCode": "{game-code}",
      "currencyCode": "{currency-code}",
      "roundId": "round-demo-001"
    }]
  }
}

Códigos de error

CódigoMensajeAcción
C10000Solicitud completada correctamenteSolicitud completada correctamente
C10001Excepción de servicio baseExcepción de servicio base
C10002Error de parámetro de solicitudRevise campos de solicitud y tipos de datos
C10003Encabezado de solicitud no válidoRevise los cinco encabezados comunes
C10004Error de firmaRevise orden de firma, clave y cuerpo original de solicitud
C20001Falta código de comercioRevise el código de comercio
G10001Excepción de servicio de juegoExcepción de servicio de juego
G20001ID de jugador vacíoProporcione playerId
G20002Falta ID de juegoRevise el código de juego
G20003Juego sin conexiónEl juego está sin conexión o no está disponible
G30001Sesión de juego de jugador caducadaCree una nueva sesión de juego
G30002Saldo de comercio insuficienteEl saldo del comercio es insuficiente
G30003Saldo de jugador insuficienteEl saldo del jugador es insuficiente
G40001Excepción de servicio de tercerosExcepción de servicio de terceros

Preguntas técnicas

¿Cómo genera AG API una firma de solicitud?

Serialice el cuerpo final de la solicitud como body y concatene merchantCode + timestamp + nonce + signType + body en ese orden y sin separadores. signType se fija como HmacSHA256. Calcule HMAC-SHA256 con la clave de firma y coloque el resultado en X-SIGN. El body usado para la firma debe ser exactamente igual al cuerpo enviado.

¿Por qué se devuelve C10004?

C10004 indica un fallo de verificación de firma. Primero revise el código de comercio, timestamp, nonce, clave de firma y el tipo fijo HmacSHA256. Después confirme que el middleware no ha serializado de nuevo la cadena JSON firmada, cambiado el orden de campos ni los espacios. Conserve reqTraceId y la hora de solicitud para diagnóstico, pero nunca registre la clave de firma.

¿Cuál es la diferencia entre monedero único y monedero de transferencia?

En modo de monedero único, el comercio mantiene el saldo del jugador y la plataforma colabora con el monedero del comercio mediante callbacks de saldo, apuesta y liquidación. En modo de monedero de transferencia, el comercio llama a endpoints como /game/v5/cash/deposit y /game/v5/cash/withdraw para mover fondos entre su sistema y el monedero de juego del jugador. El esquema utilizado depende de la configuración de integración del comercio y no debe mezclarse en el mismo flujo de transacción.

¿Cómo deben manejarse los callbacks repetidos de monedero?

El comercio debe usar transactionId como base de idempotencia para transacciones de callback. Cuando llegue la misma transacción de nuevo, devuelva el resultado de procesamiento y el saldo ya confirmados; no la debite ni la acredite otra vez. Conserve la solicitud, el resultado de negocio y el saldo final para conciliación. La necesidad de /wallet/bet y /wallet/cancel queda sujeta a la lista final de callbacks del comercio.

¿Puede reintentarse directamente una solicitud de transferencia después de un tiempo de espera?

No cree una transacción nueva ni repita la transferencia mientras se desconozca el resultado. Primero use el merchantTransactionId original para llamar a /game/v5/cash/transaction y consultar el resultado; luego decida si debe reenviar según el acuerdo técnico final. Esto evita la contabilización duplicada cuando la primera solicitud tuvo éxito pero su respuesta se perdió en la red.

¿Para qué se usan reqTraceId y merchantTransactionId?

reqTraceId es el identificador de seguimiento único de cada solicitud. Se usa para asociar registros de llamadas y diagnosticar una solicitud; debe generarse y registrarse para cada solicitud incluso durante reintentos. merchantTransactionId es el identificador único de transacción del lado del comercio, usado para conciliación de transferencias, consultas de resultado y para evitar procesar repetidamente la misma transacción de negocio. Tienen finalidades distintas y no se sustituyen.

¿Cómo se crea una sesión de juego de jugador?

Obtenga un gameCode disponible del catálogo de juegos, prepare identificador de jugador, moneda, idioma y dirección IP, y luego llame a /game/v5/game/url con los encabezados comunes de solicitud. Una respuesta correcta devuelve gameUrl y puede devolver expireTime; el cliente debe abrir la URL mientras la sesión sea válida.

¿Cómo se consultan los registros de juego de un jugador?

Llame a /game/v5/game/record con pageNum, pageSize y el rango reqData.startTime y reqData.endTime; sort puede enviarse si se necesita. Lea los registros de orden, jugador, importe de apuesta, pago, código de juego y ronda desde gameRecordList en la respuesta, y continúe la consulta página por página.

Comprobaciones antes de producción

Separe entornos de pruebas y producción. Mantenga las claves en el servidor, fuera de navegador, registros y chat. Pruebe tiempos de espera, solicitudes repetidas, cancelaciones y conciliación con identificadores de transacción. Confirme la configuración de producción y las operaciones controladas con el equipo de integración.

Iniciar el proceso de integración

AG GAME

Hablemos de su proyecto

Contáctenos
TelegramWhatsApp