Conteúdo da documentação

Desenvolvedor / Referência pública da API

API da Plataforma Aberta de Jogos AG

V5.0.0

Integre os recursos da plataforma de jogos ao sistema existente por meio do catálogo, das sessões, dos callbacks de carteira única ou dos endpoints de carteira de transferência. Todos os endpoints da plataforma usam corpo JSON; os cabeçalhos comuns e as regras de assinatura se aplicam a cada solicitação.

Base URLhttps://{base-url}

Método da solicitaçãoPOST

Content-Typeapplication/json

Modelos de carteiraCarteira única / carteira de transferência

Referência pública, não um contrato completo de produção

Esta página publica o catálogo de endpoints, o método de assinatura, campos representativos e exemplos com dados fictícios para avaliação técnica. A URL base real, as credenciais, todas as restrições dos campos, a lista final de callbacks e a configuração de produção devem ser confirmadas pelo processo controlado de integração. Os exemplos não contêm credenciais utilizáveis; não envie dados reais de jogadores ou transações pelos canais públicos.

Mantenha as chaves apenas no servidor controlado

Separe as configurações de teste e produção. Nunca coloque a chave de assinatura no navegador, em pacotes do cliente, logs, chamados ou conversas. Os valores fictícios não servem para produção.

Exemplo mínimo de solicitação

O exemplo a seguir cria uma sessão de jogo. Antes de enviá-lo, calcule a assinatura a partir da string JSON final.

curl --request POST 'https://{base-url}/game/v5/game/url' \
  --header 'Content-Type: application/json' \
  --header 'X-MERCHANT-CODE: {merchant-code}' \
  --header 'X-TIMESTAMP: {timestamp}' \
  --header 'X-NONCE: {nonce}' \
  --header 'X-SIGN: {hmac-sha256-signature}' \
  --header 'X-CONTENT-PROCESSING-TYPE: {processing-type}' \
  --data-raw '{
    "reqTraceId": "trace-demo-001",
    "gameCode": "{game-code}",
    "playerId": "player-demo-001",
    "currencyCode": "{currency-code}",
    "language": "pt-BR",
    "terminalType": "PC",
    "returnUrl": "https://{merchant-host}/lobby",
    "ipAddress": "192.0.2.10"
  }'

Autenticação e assinatura

O tipo de assinatura é fixo como HmacSHA256, e os cabeçalhos comuns devem acompanhar cada solicitação.

Cabeçalhos comuns da solicitação

Header	Tipo	Obrigatório	Descrição
`X-MERCHANT-CODE`	string	Obrigatório	Código de comerciante atribuído à plataforma
`X-TIMESTAMP`	string	Obrigatório	Timestamp no momento da solicitação
`X-NONCE`	string	Obrigatório	String aleatória usada em cada solicitação
`X-SIGN`	string	Obrigatório	Assinatura da solicitação gerada com HmacSHA256
`X-CONTENT-PROCESSING-TYPE`	string	Obrigatório	Tipo de processamento do conteúdo enviado conforme a configuração da integração

String de assinatura

1
Serialize o corpo da solicitação como a string JSON final body.
2
Concatene os campos exatamente na ordem abaixo, sem separadores.
3
Use a chave de assinatura para executar HMAC-SHA256 e coloque o resultado em X-SIGN.

merchantCode + timestamp + nonce + signType + body

O corpo da solicitação deve ser idêntico byte a byte

O body usado na assinatura deve ser exatamente igual ao corpo realmente enviado. Reformatar o JSON, mudar a ordem dos campos ou os espaços antes do envio pode gerar C10004.

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");

Resposta comum

O resultado de negócio é retornado em code no corpo da resposta; não use apenas o status HTTP para determinar o resultado de uma transação.

Campo	Tipo	Descrição
`code`	string	Código do resultado de negócio
`msg`	string	Mensagem do resultado
`success`	boolean	Indicador de sucesso no exemplo de resposta
`data`	object	Dados retornados pelo endpoint

{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {}
}

Catálogo e endpoints típicos

Selecione o grupo de endpoints que corresponde à arquitetura da carteira do comerciante. Todos os endpoints da plataforma usam POST.

/

Catálogo de jogos e sessões

POST/game/v5/providers

Consultar fornecedores de jogos

POST/game/v5/categories

Consultar categorias de jogos

POST/game/v5/games

Consultar jogos com paginação

POST/game/v5/game/url

Criar uma sessão de jogo para o jogador e obter a URL de início

POST/game/v5/player/force/logout

Encerrar à força a sessão de jogo do jogador

Callbacks da carteira única

POST{MERCHANT-URL}/wallet/balance

Consultar o saldo da carteira do jogador

POST{MERCHANT-URL}/player/info

Consultar dados do jogador

POST{MERCHANT-URL}/wallet/bet

Receber notificação de aposta

POST{MERCHANT-URL}/wallet/win

Receber notificação de liquidação ou de aposta e liquidação

POST{MERCHANT-URL}/wallet/cancel

Receber notificação de cancelamento do pedido

Carteira de transferência

POST/game/v5/cash/deposit

Transferir saldo para a carteira de jogo do jogador

POST/game/v5/cash/withdraw

Retirar saldo da carteira de jogo do jogador

POST/game/v5/cash/balance

Consultar o saldo da carteira de jogo do jogador

POST/game/v5/cash/transaction

Consultar transações da carteira com paginação

POST/game/v5/cash/force/withdraw/all

Retirar à força todo o saldo da carteira de jogo do jogador

Registros e comerciante

POST/game/v5/game/record

Consultar registros dos jogos com paginação

POST/game/v5/merchant/info

Consultar a configuração atual do comerciante e os dados da carteira

Escopo dos callbacks de carteira única

A necessidade de o comerciante implementar /wallet/bete /wallet/cancel depende da configuração real da integração e do acordo técnico final. Confirme a lista de callbacks antes dos testes de integração.

POST`/game/v5/game/url`Criar sessão de jogo

Cria uma sessão de jogo para o jogador informado e retorna uma URL para iniciar o jogo.

Autenticação: cabeçalhos comuns da solicitaçãoContent-Type: application/json

Campos da solicitação

Campo	Tipo	Obrigatório	Descrição
`reqTraceId`	string	Obrigatório	Identificador único da solicitação; não pode ser reutilizado
`gameCode`	string	Obrigatório	Código do jogo
`playerId`	string	Obrigatório	Identificador único do jogador no sistema do comerciante
`currencyCode`	string	Obrigatório	Código da moeda da carteira
`language`	string	Obrigatório	Idioma da interface do jogo
`terminalType`	string	Opcional	Tipo de terminal: PHONE ou PC; o padrão é PHONE
`returnUrl`	string	Opcional	URL de retorno após o jogador sair do jogo
`ipAddress`	string	Obrigatório	Endereço IPv4 ou IPv6 do jogador
`subMerchantCode`	string	Opcional	Código do subcomerciante; não pode conter sublinhado
`nickName`	string	Opcional	Apelido do jogador
`avatarUrl`	string	Opcional	URL do avatar do jogador

                          {
  "reqTraceId": "trace-demo-001",
  "gameCode": "{game-code}",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "language": "pt-BR",
  "terminalType": "PC",
  "returnUrl": "https://{merchant-host}/lobby",
  "ipAddress": "192.0.2.10"
}

                          {
  "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"
  }
}

Dados da resposta

Campo	Tipo	Retornado	Descrição
`data.gameCode`	string	Obrigatório	Código do jogo
`data.playerId`	string	Obrigatório	Identificador do jogador
`data.gameUrl`	string	Obrigatório	URL de início do jogo
`data.expireTime`	string	Opcional	Horário de expiração da sessão

POST`{MERCHANT-URL}/wallet/win`Callback de liquidação da carteira

No modelo de carteira única, a plataforma envia à carteira do comerciante uma notificação de prêmio ou de aposta e liquidação. O comerciante deve processar a transação de forma idempotente e devolver o saldo resultante na resposta.

Direção: plataforma → comercianteTipo: win / bet_win

Campos da solicitação

Campo	Tipo	Obrigatório	Descrição
`reqTraceId`	string	Obrigatório	Identificador único da solicitação
`playerId`	string	Obrigatório	Identificador único do jogador no sistema do comerciante
`currencyCode`	string	Obrigatório	Código da moeda da carteira
`gameCode`	string	Obrigatório	Código do jogo
`transactionId`	string	Obrigatório	Identificador único da transação na plataforma
`roundId`	string	Obrigatório	Identificador único da rodada do jogo
`betId`	string	Obrigatório	Identificador da aposta relacionada
`betAmount`	string	Obrigatório	Valor apostado nesta transação
`winAmount`	string	Obrigatório	Valor pago nesta transação
`isFree`	boolean	Obrigatório	Indica se o registro foi gerado por uma partida grátis
`isEnd`	boolean	Obrigatório	Indica se a rodada atual do jogo terminou
`betTime`	string	Obrigatório	Horário da aposta
`settledTime`	string	Obrigatório	Horário da liquidação
`type`	string	Obrigatório	Tipo da notificação: win ou bet_win

                          {
  "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"
}

                          {
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "merchantBetId": "merchant-bet-demo-001",
    "balance": "108.50"
  }
}

POST`/game/v5/cash/deposit`Transferir saldo para a carteira de jogo

No modelo de carteira de transferência, transfere o valor informado do sistema do comerciante para a carteira de jogo do jogador.

Modelo de carteira: carteira de transferênciaChave da transação: merchantTransactionId

Campos da solicitação

Campo	Tipo	Obrigatório	Descrição
`reqTraceId`	string	Obrigatório	Identificador único usado para rastrear a solicitação
`playerId`	string	Obrigatório	Identificador único do jogador no sistema do comerciante
`currencyCode`	string	Obrigatório	Código da moeda da carteira
`amount`	string	Obrigatório	Valor da transferência
`merchantTransactionId`	string	Obrigatório	Identificador único da transação do comerciante, usado na conciliação

                          {
  "reqTraceId": "trace-demo-003",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "amount": "100.00",
  "merchantTransactionId": "merchant-txn-demo-001"
}

                          {
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "balance": "100.00"
  }
}

Conciliação de transações

Gere um merchantTransactionId único para cada transferência e guarde a solicitação e o resultado de negócio para conciliar o status final pelo endpoint de consulta de transações.

POST`/game/v5/game/record`Consultar registros dos jogos

Consulta com paginação os registros de apostas e prêmios do jogador em um intervalo de tempo.

Campos da solicitação

Campo	Tipo	Obrigatório	Descrição
`reqTraceId`	string	Obrigatório	Identificador único da solicitação
`pageNum`	integer	Obrigatório	Número da página
`pageSize`	integer	Obrigatório	Registros por página
`reqData.startTime`	string	Obrigatório	Início do intervalo da consulta
`reqData.endTime`	string	Obrigatório	Fim do intervalo da consulta
`sort`	string	Opcional	Ordem de classificação

                          {
  "reqTraceId": "trace-demo-004",
  "pageNum": 1,
  "pageSize": 50,
  "reqData": {
    "startTime": "2026-08-08T00:00:00Z",
    "endTime": "2026-08-08T23:59:59Z"
  },
  "sort": "DESC"
}

                          {
  "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"
    }]
  }
}

Dúvidas técnicas

Dúvidas frequentes nos testes de integração sobre assinatura, carteiras, idempotência, timeouts e consultas de sessão.

Como a API da AG gera a assinatura da solicitação?

Serialize o corpo final da solicitação como body e concatene merchantCode + timestamp + nonce + signType + body, nessa ordem e sem separadores. signType é fixo como HmacSHA256. Calcule HMAC-SHA256 com a chave de assinatura e coloque o resultado em X-SIGN. O body usado na assinatura deve ser exatamente igual ao conteúdo enviado.

Ver o exemplo de autenticação e assinatura

Por que C10004 é retornado?

C10004 indica falha na validação da assinatura. Primeiro, verifique o código do comerciante, timestamp, nonce, chave de assinatura e o tipo fixo HmacSHA256. Depois, confirme que o middleware não serializou novamente a string JSON assinada, não mudou a ordem dos campos nem os espaços. Guarde reqTraceId e o horário da solicitação para diagnóstico, mas nunca registre a chave de assinatura.

Ver a lista completa de códigos de erro

Qual é a diferença entre carteira única e carteira de transferência?

No modelo de carteira única, o comerciante mantém o saldo do jogador, e a plataforma colabora com a carteira do comerciante por callbacks de saldo, aposta e liquidação. No modelo de transferência, o comerciante chama endpoints como /game/v5/cash/deposit e /game/v5/cash/withdraw para mover saldo entre seu sistema e a carteira de jogo do jogador. O modelo usado depende da configuração da integração e não deve ser misturado no mesmo fluxo de transação.

Ver o catálogo de endpoints de carteira

Como tratar callbacks de carteira repetidos?

O comerciante deve usar transactionId como base de idempotência das transações de callback. Quando a mesma transação chegar novamente, devolva o resultado e o saldo já confirmados; não debite nem credite outra vez. Guarde a solicitação, o resultado de negócio e o saldo final para conciliação. A necessidade de /wallet/bet e /wallet/cancel continua sujeita à lista final de callbacks do comerciante.

Ver o callback de liquidação da carteira

Uma transferência pode ser repetida diretamente após timeout?

Não crie uma nova transação nem repita a transferência enquanto o resultado for desconhecido. Primeiro, use o merchantTransactionId original para chamar /game/v5/cash/transaction e consultar o resultado; depois, decida se deve reenviar conforme o acordo técnico final. Isso evita lançamentos duplicados quando a primeira solicitação teve sucesso, mas a resposta se perdeu na rede.

Ver o exemplo de transferência para a carteira de jogo

Para que servem reqTraceId e merchantTransactionId?

reqTraceId é o identificador único de rastreamento de cada solicitação. Ele associa logs e ajuda a diagnosticar uma chamada; deve ser gerado e registrado por solicitação, inclusive em novas tentativas. merchantTransactionId é o identificador único da transação no sistema do comerciante, usado para conciliar transferências, consultar resultados e evitar o processamento repetido da mesma transação de negócio. Os dois têm finalidades diferentes e não se substituem.

Como criar uma sessão de jogo para o jogador?

Obtenha um gameCode disponível no catálogo, prepare o identificador do jogador, a moeda, o idioma e o endereço IP e chame /game/v5/game/url com os cabeçalhos comuns. Uma resposta bem-sucedida retorna gameUrl e pode retornar expireTime; o cliente deve abrir a URL enquanto a sessão estiver válida.

Ver como criar uma sessão de jogo

Como consultar os registros de jogos do jogador?

Chame /game/v5/game/record com pageNum, pageSize e o intervalo reqData.startTime e reqData.endTime; informe sort quando necessário. Leia em gameRecordList os registros de pedido, jogador, valor apostado, prêmio, código do jogo e rodada e continue a consulta por página.

Ver o endpoint de registros dos jogos

Códigos de erro

Registre reqTraceId, o código de erro de negócio e o horário da solicitação para ajudar a diagnosticar problemas rapidamente.

Código	Mensagem	Ação recomendada
`C10000`	Request succeeded	Solicitação concluída com sucesso
`C10001`	Base service exception	Exceção no serviço de base
`C10002`	Request parameter error	Verifique os campos e tipos de dados
`C10003`	Invalid request header	Verifique os cinco cabeçalhos comuns
`C10004`	Signature error	Verifique a ordem da assinatura, a chave e o corpo original da solicitação
`C20001`	Merchant code absent	Verifique o código do comerciante
`G10001`	Game service exception	Exceção no serviço de jogos
`G20001`	Player ID empty	Informe playerId
`G20002`	Game ID absent	Verifique o código do jogo
`G20003`	Game offline	O jogo está off-line ou indisponível
`G30001`	Game user session expired	Crie uma nova sessão de jogo
`G30002`	Merchant balance insufficient	O saldo do comerciante é insuficiente
`G30003`	Player balance insufficient	O saldo do jogador é insuficiente
`G40001`	Third-party service exception	Exceção em serviço de terceiros

Verificações da integração

Confirme estes controles no protocolo final do projeto e teste-os antes de mudar para produção. Esta página pública não afirma que o servidor já os tenha ativado.

✓
Solicitações rastreáveis e logs mínimos: gere um reqTraceId único para cada chamada. Guarde apenas horário, código de resultado e identificadores mascarados necessários ao diagnóstico; não registre chaves, assinaturas completas, tokens, dados do jogador nem a carga completa da transação.
✓
Assinaturas reproduzíveis: a entrada da assinatura corresponde exatamente à string JSON enviada, e os testes cobrem C10004.
✓
Regras antirreplay explícitas: confirme a tolerância do timestamp, a unicidade do nonce e a rejeição de solicitações repetidas; teste valores expirados, reutilizados e concorrentes.
✓
Autorização e limites de recursos explícitos: valide por comerciante o acesso a endpoints, carteiras e dados e confirme limites de frequência, concorrência, paginação e valor de transação, além dos alertas.
✓
Transações idempotentes: elimine duplicidades em notificações e transferências pelo identificador da transação, evitando lançamentos duplicados em solicitações repetidas.
✓
Resultados conciliáveis: em caso de timeout ou exceção de rede, consulte o resultado da transação antes de decidir se deve tentar novamente.
✓
Valores em ponto fixo: não use números binários de ponto flutuante para saldos, valores de aposta ou prêmios.

API da Plataforma Aberta de Jogos AG

Exemplo mínimo de solicitação

Autenticação e assinatura

Cabeçalhos comuns da solicitação

String de assinatura

Resposta comum

Catálogo e endpoints típicos

Catálogo de jogos e sessões

Callbacks da carteira única

Carteira de transferência

Registros e comerciante

POST/game/v5/game/urlCriar sessão de jogo

Campos da solicitação

Dados da resposta

POST{MERCHANT-URL}/wallet/winCallback de liquidação da carteira

Campos da solicitação

POST/game/v5/cash/depositTransferir saldo para a carteira de jogo

Campos da solicitação

POST/game/v5/game/recordConsultar registros dos jogos

Campos da solicitação

Dúvidas técnicas

Como a API da AG gera a assinatura da solicitação?

Por que C10004 é retornado?

Qual é a diferença entre carteira única e carteira de transferência?

Como tratar callbacks de carteira repetidos?

Uma transferência pode ser repetida diretamente após timeout?

Para que servem reqTraceId e merchantTransactionId?

Como criar uma sessão de jogo para o jogador?

Como consultar os registros de jogos do jogador?

Códigos de erro

Verificações da integração

Fale conosco

POST`/game/v5/game/url`Criar sessão de jogo

POST`{MERCHANT-URL}/wallet/win`Callback de liquidação da carteira

POST`/game/v5/cash/deposit`Transferir saldo para a carteira de jogo

POST`/game/v5/game/record`Consultar registros dos jogos