Documentação da API de Jogos

Guia de Integração API

Documentação técnica para implementação da Games2API

Seamless Mode

Introdução

URL de Acesso Autenticação & Headers Métodos & Formatos Limites dos Campos Formato das Respostas

Seamless

Lançar Jogo Saldo (Callback) Transações (Callback)

Catálogo

Listar Provedores Jogos e Moedas

Bônus

Jogos com Free Spins Conceder Free Spins Beterraba / Consultar Giros Restantes Bônus PGSoft Abrir Jogo Demo

Operação

Histórico de Jogo Sub-agentes

Segurança

Segurança do Callback Códigos de Retorno

URL Base da API

Todas as requisições devem ser enviadas para a URL base utilizando obrigatoriamente o protocolo HTTPS:

https://api.games2api.xyz

O endpoint raiz aceita somente POST. Requisições GET e DELETE retornam HTTP 405 com METHOD_NOT_ALLOWED.

Autenticação & Cabeçalhos

Toda chamada é autenticada pelas credenciais do agente enviadas no corpo JSON: agent_code + agent_token.

POST / HTTP/1.1
Host: api.games2api.xyz
Content-Type: application/json
Accept: application/json
X-Request-Id: pedido-2026-000123

{
  "method": "game_list",
  "agent_code": "DEMO",
  "agent_token": "SEU_AGENT_TOKEN"
}

O cabeçalho Content-Type: application/json é obrigatório. Accept: application/json é recomendado.

Cabeçalho opcional de correlação

Envie X-Request-Id (ou o campo request_id no JSON) para correlacionar logs. Se ausente, a API gera um req_... automaticamente. O mesmo valor volta no campo request_id de todas as respostas — inclusive nas de erro.

Métodos & Formatos de Dados

Utilize o método HTTP POST para todas as requisições. O corpo da mensagem deve estar estruturado em formato JSON. O roteamento é feito pelo campo method no corpo.

O cabeçalho Content-Type: application/json é indispensável.

Valores monetários são números decimais (ex.: 10.50), nunca formatados com símbolo ou separador de milhar.

Limites de Tamanho por Campo

Tabela consolidada dos limites aplicados pela API. Campos fora do limite retornam HTTP 400 com INVALID_REQUEST. Os limites são medidos em caracteres (bytes da string UTF-8), não em palavras.

Campo	Tipo	Obrigatório	Limite / regra	Descrição
method	string	Sim	até 32 (recomendado)	Nome do método, sempre em minúsculas.
agent_code	string	Sim	até 191 — não pode ser numérico no game_launch	Código do agente autenticado.
agent_token	string	Sim	até 255	Token do agente. Nunca exponha no navegador.
agent_secret	string	Callback	até 255	Secret do agente, enviado pela Games2API nos callbacks.
user_code	string	Depende	1 a 191 — sempre string	Identificador do jogador no seu sistema.
request_id	string	Não	geral: 8 a 64; freespin/bônus: 8 a 128	Chave de correlação/idempotência. Padrão `[A-Za-z0-9][A-Za-z0-9._:-]*`.
provider_code	string	Depende	até 128 (catálogo: 45)	Use exatamente o valor retornado pelo catálogo.
game_code	string	Depende	até 191	Código público do jogo retornado pelo catálogo.
lang	string	Depende	até 16	`pt`, `es` ou `en`. Subtags viram a principal (pt-BR → pt).
currency	string	Não	3 (ISO 4217)	Padrão: moeda cadastrada no agente.
email	string	Depende	até 254, formato válido	Localiza o jogador no CRM de bônus.
amount (financeiro)	decimal	Depende	> 0 (bônus) / ≥ 0 (depósito); sem máximo explícito	Valor em moeda corrente, 2 casas decimais.
amount (free spins)	inteiro	Sim	1 a 1000	Quantidade de giros grátis.
spins	inteiro	Sim (Beterraba)	1 a 10000	Quantidade de giros no contrato Beterraba.
level	inteiro	Não (Beterraba)	≥ 1 e presente em `available_levels`	Nível do bônus Beterraba. Padrão 1.
bonus_id	string	Sim (Beterraba)	8 a 64 — `[A-Za-z0-9._:-]`	Chave de idempotência da concessão.
bet_amount	decimal	Depende	> 0; padrão 1.00	Valor de cada giro (Originals, Aviatrix, SP).
bet_level	inteiro	Depende	0 a 6 (Ryan)	Nível de aposta do Ryan; repassado ao 1GAMEHUB.
max_promo_win	decimal	Não (Aviatrix)	> 0; padrão 1000.00	Prêmio promocional máximo.
expires_in_days	inteiro	Não	> 0; padrão 7	Validade do bônus em dias.
rtp	número/string	Não	—	Repassado ao 1GAMEHUB.
bonus_name	string	Não	até 100	Nome da campanha PGSoft.
description	string	Não	até 255	Descrição do bônus PGSoft.
page_number	inteiro	Não	≥ 1; padrão 1	Paginação de `bonus_games`.
row_count	inteiro	Não	1 a 5000; padrão 500	Itens por página em `bonus_games`.
perPage	inteiro	Sim (get_game_log)	≥ 1	Quantidade máxima de registros no histórico.
subagent_code	string	Sim (subagentes)	até 191	Código do sub-agente.

Formato das Respostas

Sucesso

{
  "status": 1,
  "msg": "SUCCESS",
  "request_id": "pedido-2026-000123"
}

Falha padronizada

{
  "status": 0,
  "msg": "GAME_NOT_FOUND",
  "request_id": "pedido-2026-000123",
  "error": {
    "code": "GAME_NOT_FOUND",
    "category": "configuration",
    "retryable": false,
    "provider": "PGSOFT",
    "game_code": "fortune-tiger",
    "message": "Jogo não encontrado ou inativo."
  }
}

Considere sucesso somente quando o HTTP estiver entre 200 e 299 e "status": 1. O código HTTP acompanha a categoria: 4xx para erro definitivo do pedido, 5xx para dependência indisponível e 2xx para sucesso.

Quando error.retryable for true, aguarde error.retry_after_ms antes de repetir. 4xx nunca deve ser repetido sem corrigir a requisição.

Referência de Endpoints

Lançar Jogo (Game Launch)

POST

Gera a URL de acesso para o jogador entrar no jogo. No modo Seamless o cadastro do jogador é criado automaticamente na primeira chamada; o saldo vem da sua carteira pelos callbacks.

{
    "method": "game_launch",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "user_code": "user123",
    "provider_code": "PGSOFT",
    "game_code": "fortune-tiger",
    "lang": "pt",
    "currency": "BRL",
    "request_id": "launch-2026-000123"
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
user_code	string	Sim	1 a 191; não pode ser numérico	Identificador do jogador. Obrigatoriamente string (envie "123", não 123).
provider_code	string	Sim	até 128	Provedor retornado por `provider_list`.
game_code	string	Sim	até 191	Jogo retornado por `game_list`.
lang	string	Sim	até 16	`pt`, `es` ou `en`.
currency	string	Não	3 (ISO 4217)	Sobrescreve a moeda do agente. Usado principalmente pelo provedor SP.
request_id	string	Não	8 a 64	Correlação. Devolvido em `request_id`.

Exemplo de Resposta (HTTP 200):

{
    "status": 1,
    "msg": "SUCCESS",
    "launch_url": "https://...",
    "request_id": "launch-2026-000123"
}

Erros: GAME_NOT_FOUND (404), CURRENCY_NOT_SUPPORTED (422), PROVIDER_UNAVAILABLE/UPSTREAM_TIMEOUT (502/504, repetível).

Consultar Saldo (Callback)

Webhook POST

A Games2API envia esta requisição para o seu servidor (siteEndPoint) para obter o saldo do jogador. Responda em até 30 segundos.

Recebido pela Games2API

{
    "method": "user_balance",
    "agent_code": "DEMO",
    "agent_secret": "SUA_SECRET_KEY",
    "user_code": "user123",
    "request_id": "req_...",
    "provider_code": "PGSOFT",
    "game_code": "fortune-tiger",
    "session_id": "req_...",
    "currency": "BRL"
}

Resposta esperada do seu servidor

{
    "status": 1,
    "user_balance": 1500.00
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
method	string	—	fixo	`user_balance`.
agent_code	string	Recebido	até 191	Confira se é o seu agente.
agent_secret	string	Recebido	até 255	Valide com `hash_equals`. Nunca processe sem validar.
user_code	string	Recebido	até 191	Jogador consultado.
provider_code / game_code	string	Recebido	—	Contexto da sessão, apenas para correlação.
user_balance	decimal	Resposta	≥ 0	Saldo atual. A API também aceita o nome `balance`.

Se a resposta não trouxer status: 1 com saldo numérico, a tentativa é tratada como falha e enfileirada para nova tentativa automática.

Notificar Transação (Callback)

Webhook POST

Enviada para o seu servidor a cada aposta, ganho ou estorno. Use txn_id para deduplicar: reenvios do mesmo txn_id não podem debitar/creditar duas vezes.

Recebido pela Games2API

{
    "method": "transaction",
    "agent_code": "DEMO",
    "agent_secret": "SUA_SECRET_KEY",
    "agent_balance": 5000.00,
    "user_code": "user123",
    "user_balance": 1500.00,
    "game_type": "slot",
    "request_id": "req_...",
    "slot": {
        "provider_code": "PGSOFT",
        "game_code": "fortune-tiger",
        "bet_money": 1.00,
        "win_money": 2.50,
        "txn_id": "TXN_UNICO",
        "txn_type": "credit",
        "currency": "BRL"
    }
}

Resposta esperada do seu servidor

{
    "status": 1,
    "user_balance": 1501.50
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
agent_balance	decimal	Recebido	≥ 0	Saldo do agente na Games2API, somente leitura.
user_balance	decimal	Recebido	≥ 0	Saldo do jogador antes da transação.
slot.provider_code	string	Recebido	até 128	Provedor do jogo.
slot.game_code	string	Recebido	até 191	Jogo.
slot.bet_money	decimal	Recebido	≥ 0	Valor apostado nesta transação.
slot.win_money	decimal	Recebido	≥ 0	Valor ganho nesta transação.
slot.txn_id	string	Recebido	até 191	Chave de idempotência única da transação.
slot.txn_type	string	Recebido	debit / credit / bonus / refund	Natureza da transação.
slot.currency	string	Recebido	3	Moeda da transação.
user_balance (resposta)	decimal	Resposta	≥ 0	Saldo final após aplicar bet/win.

Sem uma resposta válida, a transação é considerada não confirmada e pode ser reenviada. Implemente deduplicação por txn_id antes de alterar saldo.

Listar Provedores

POST

Lista os provedores ativos. Use o campo code como provider_code. Cache de 5 minutos.

{
    "method": "provider_list",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN"
}

Resposta resumida:

{
    "status": 1,
    "msg": "Lista de provedores",
    "providers": [{
        "code": "PGSOFT",
        "name": "PGSOFT",
        "Status": 1,
        "type": "slot",
        "types": ["slot"],
        "types_normalized": ["SLOT"],
        "currencies": ["BRL", "USD"],
        "currencies_known": true,
        "currencies_source": "observed",
        "currencies_count": 2,
        "currencies_rejected_count": 0,
        "currencies_tested_at": "2026-10-04 18:00:00+00"
    }]
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
types	array	Resposta	—	Tipos brutos publicados pelo provedor.
types_normalized	array	Resposta	SLOT / CASINO / CRASH / ...	Tipos normalizados para exibição.
currencies	array/null	Resposta	—	`null` quando ainda não há matriz de moedas.
currencies_known	boolean	Resposta	—	Indica se existe matriz de moedas para o provedor.
currencies_source	string/null	Resposta	observed / probed	Origem da evidência de moedas.

Lista de Jogos, Free Spins e Moedas

POST

O método game_list exige provider_code e informa a elegibilidade de cada jogo e a matriz de moedas do provedor. Cache de 1 hora.

{
    "method": "game_list",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "provider_code": "ORIGINALS"
}

{
    "status": 1,
    "msg": "SUCCESS",
    "games": [{
        "id": 123,
        "game_code": "jogodotigrinho",
        "game_name": "Jogo do Tigrinho",
        "banner": "https://.../jogodotigrinho-v2.png",
        "status": 1,
        "provider": "ORIGINALS",
        "type": "SLOT",
        "freespins_supported": true,
        "currencies": ["BRL", "USD"],
        "currencies_known": true,
        "currencies_tested_at": "2026-10-04 18:00:00+00"
    }]
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
provider_code	string	Sim	até 128	Provedor retornado por `provider_list`.
freespins_supported	boolean	Resposta	—	Suporte individual do jogo a rodadas grátis.
currencies	array/null	Resposta	—	Moedas aceitas; `null` quando ainda não há informação.
currencies_known	boolean	Resposta	—	Indica se o provedor possui matriz de moedas.
currencies_tested_at	string/null	Resposta	—	Data da evidência mais recente.

Listar Jogos Elegíveis

POST

Use freespin_games como fonte dinâmica. provider_code é opcional; sem ele, a API lista todos os jogos ativos elegíveis. Não mantenha lista fixa no painel.

{
    "method": "freespin_games",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "provider_code": "ORIGINALS"
}

{
    "status": 1,
    "msg": "SUCCESS",
    "providers": {
        "ORIGINALS": { "method": "freespin", "list_in_freespin_games": true, "note": null },
        "BETERRABA": { "method": "freespin_grant", "list_in_freespin_games": true, "note": "..." }
    },
    "count": 1,
    "count_by_api": { "ORIGINALS": 1 },
    "games": [{ "game_code": "jogodotigrinho", "game_name": "Jogo do Tigrinho", "provider": "ORIGINALS", "type": "SLOT", "API": "ORIGINALS" }]
}

Use exatamente o campo provider retornado como provider_code. Jogos Beterraba podem usar o sufixo -BT e trazer available_levels.

Conceder Free Spins

POST

Suporte atual pelo método freespin: Originals, Ryan, Aviatrix, SP e 1GAMEHUB. Beterraba/MGator usa freespin_grant. BGaming ainda não aceita concessão.

{
    "method": "freespin",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "user_code": "usuario123",
    "provider_code": "ORIGINALS",
    "game_code": "jogodotigrinho",
    "amount": 20,
    "bet_amount": 1.00,
    "expires_in_days": 7,
    "request_id": "bonus-2026-000001"
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
user_code	string	Sim	1 a 191	Deve pertencer ao agente autenticado.
provider_code / game_code	string	Sim	128 / 191	Use os valores retornados por `freespin_games`.
amount	inteiro	Sim	1 a 1000	Quantidade de giros grátis.
expires_in_days	inteiro	Não	> 0; padrão 7	Validade em dias.
request_id	string	Não	8 a 128 — `[A-Za-z0-9._:-]`	Idempotência da concessão.
bet_amount	decimal	Depende	> 0; padrão 1.00	Originals, Aviatrix e SP.
bet_level	inteiro	Depende	0 a 6	Ryan; também enviado ao 1GAMEHUB.
max_promo_win	decimal	Não	> 0; padrão 1000.00	Aviatrix.
email	string	1GAMEHUB	até 254; formato válido	Sobrescreve o e-mail cadastrado.
rtp	número/string	Não	—	Encaminhado ao 1GAMEHUB.

Exemplos por integração

Ryan

{ "method":"freespin", "provider_code":"PROVEDOR-RYAN", "game_code":"CODIGO_DO_JOGO", "user_code":"usuario123", "amount":10, "bet_level":2, "expires_in_days":7 }

Aviatrix

{ "method":"freespin", "provider_code":"AVIATRIX", "game_code":"nft-aviatrix", "user_code":"usuario123", "amount":5, "bet_amount":1.00, "max_promo_win":1000.00, "request_id":"avia-2026-000001" }

{ "method":"freespin", "provider_code":"SP", "game_code":"CODIGO_DO_JOGO", "user_code":"usuario123", "amount":10, "bet_amount":1.00, "request_id":"sp-2026-000001" }

1GAMEHUB

{ "method":"freespin", "provider_code":"PROVEDOR_1GAMEHUB", "game_code":"CODIGO_PUBLICO", "user_code":"usuario123", "amount":20, "email":"[email protected]", "request_id":"hub-2026-000001" }

Inclua também agent_code e agent_token em todos os exemplos.

No Aviatrix, amount é a quantidade de apostas promocionais; bet_amount é o valor de cada uma. No 1GAMEHUB a concessão vira saldo e exige e-mail válido.

Beterraba e Consultas de Free Spins

A integração Beterraba/MGator possui contrato próprio e usa bonus_id como chave de idempotência.

1. Consultar níveis

{
  "method": "freespin_available",
  "agent_code": "DEMO",
  "agent_token": "SEU_AGENT_TOKEN",
  "game_code": "3250379"
}

2. Conceder no Beterraba

{
  "method": "freespin_grant",
  "agent_code": "DEMO",
  "agent_token": "SEU_AGENT_TOKEN",
  "user_code": "usuario123",
  "game_code": "3250379",
  "spins": 10,
  "level": 1,
  "currency": "BRL",
  "bonus_id": "campanha-2026-000001"
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
game_code	string	freespin_available / grant	até 191	Jogo do Beterraba retornado pelo catálogo.
spins	inteiro	Sim	1 a 10000	Quantidade de giros.
level	inteiro	Não	≥ 1; presente em `available_levels`	Nível do bônus. Padrão 1.
currency	string	Não	3	Padrão BRL.
bonus_id	string	Sim	8 a 64 — `[A-Za-z0-9._:-]`	Chave de idempotência criada pelo painel.

Mesma chave e parâmetros retorna duplicate: true; parâmetros diferentes retornam HTTP 409.
Jogadores do modo Seamless são criados sob demanda no grant.

Status Beterraba

{ "method":"freespin_status", "bonus_id":"campanha-2026-000001" }

Cancelar Beterraba

{ "method":"freespin_cancel", "bonus_id":"campanha-2026-000001" }

Restantes Aviatrix

{ "method":"freespin_remaining", "user_code":"usuario123", "bonus_id":"ID_OPCIONAL" }

Inclua agent_code e agent_token em todas as chamadas. Erros: INVALID_BONUS_ID, spins deve ser um inteiro entre 1 e 10000, level deve ser um inteiro maior que zero, INVALID_USER (400); REQUEST_ALREADY_PROCESSED (409); FREESPIN_GAME_NOT_ELIGIBLE, INVALID_FREESPIN_LEVEL (422).

Considere sucesso somente com HTTP 2xx e "status": 1. Gere e persista request_id ou bonus_id antes do envio e reutilize a mesma chave ao repetir uma tentativa após timeout.

Consultar Giros Restantes (Aviatrix)

POST

Retorna quantos giros promocionais restam para o jogador. Sem bonus_id, consulta a concessão mais recente; se não houver, retorna sucesso com contadores zerados.

{
    "method": "freespin_remaining",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "user_code": "usuario123",
    "bonus_id": "ID_OPCIONAL"
}

{
    "status": 1,
    "msg": "SUCCESS",
    "provider": "AVIATRIX",
    "remaining": 5,
    "bet_count_limit": 5,
    "bet_count_placed": 0
}

Erro: INVALID_USER (400).

Bônus PGSoft

DisponívelPOST

Métodos de bônus em carteira da PGSoft. Todos exigem agent_code, agent_token e provider_code: "PGSOFT". Outro provedor retorna BONUS_NOT_SUPPORTED_FOR_PROVIDER (422).

{
    "method": "bonus_create",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "provider_code": "PGSOFT",
    "request_id": "bonus-2026-000001",
    "user_code": "usuario123",
    "game_code": "fortune-tiger",
    "amount": 10.00,
    "currency": "BRL",
    "rollover_multiplier": 5,
    "expires_in_days": 7,
    "bonus_type": 0,
    "non_discardable": true
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
request_id	string	Sim	8 a 128 — máx. 128 no provedor	Vira `transaction_id`/`transfer_reference`; garante idempotência.
user_code	string	Sim (create/assign/status)	1 a 191	Jogador do bônus.
game_code	string/array	Sim (create)	até 191 cada	Aceita lista; os jogos devem ter a mesma aposta-base.
amount	decimal	Sim (create)	> 0	Valor do bônus.
rollover_multiplier	decimal	Não	≥ 0; padrão 1	Multiplicador de rollover.
expires_in_days	inteiro	Não	≥ 1; padrão 7	Validade em dias.
bonus_name	string	Não	até 100	Nome da campanha.
bonus_type	inteiro	Não	padrão 0	Tipo de bônus da PGSoft.
non_discardable	boolean	Não	true / false	Impede descarte do bônus.
minimum_conversion_amount	decimal	Não	≥ 0	Conversão mínima.
maximum_conversion_amount	decimal	Não	≥ 0	Conversão máxima.
bonus_id	inteiro	Sim (assign/cancel)	—	ID de campanha retornado pela PGSoft.
balance_id	inteiro	Não (cancel)	—	Cancela apenas o bônus do jogador.
flexible	boolean	Não (assign)	true / false	Ativa o modo flexível por jogador.
status	inteiro/array	Não (status)	—	Filtra por status.

Listar campanhas — bonus_games

{ "method":"bonus_games", "provider_code":"PGSOFT", "page_number":1, "row_count":500, "from_time":1700000000000, "to_time":1800000000000 }

Atribuir — bonus_assign

{ "method":"bonus_assign", "provider_code":"PGSOFT", "request_id":"bonus-2026-000002", "user_code":"usuario123", "bonus_id":10915 }

Consultar — bonus_status

{ "method":"bonus_status", "provider_code":"PGSOFT", "user_code":"usuario123" }

Cancelar — bonus_cancel

{ "method":"bonus_cancel", "provider_code":"PGSOFT", "bonus_id":10915, "user_code":"usuario123", "balance_id":134243099 }

Erros: BONUS_NOT_SUPPORTED_FOR_PROVIDER, INVALID_BONUS_RULES, INVALID_OR_INACTIVE_GAME, INVALID_AMOUNT (422); INVALID_USER (400). O bônus fica na carteira PGSoft até a conversão BonusToCash.

Abrir Jogo em Modo Demo

DisponívelPOST

Abre uma sessão demonstrativa sem movimentar o saldo real do jogador ou do agente. O agente precisa ter a permissão demo habilitada.

{
    "method": "game_launch_demo",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "user_code": "user123",
    "provider_code": "BGAMING",
    "game_code": "acceptance:test",
    "lang": "pt",
    "currency": "BRL"
}

{
    "status": 1,
    "msg": "SUCCESS",
    "launch_url": "https://provedor.exemplo/jogo-demo",
    "request_id": "req_..."
}

Erros: DEMO_NOT_ENABLED_FOR_AGENT (422), GAME_NOT_FOUND (404), GAME_LAUNCH_FAILED/PROVIDER_UNAVAILABLE (502).

Histórico de Jogo

POST

Consulta o histórico de transações do jogador em um intervalo de datas.

{
    "method": "get_game_log",
    "agent_code": "DEMO",
    "agent_token": "SEU_AGENT_TOKEN",
    "user_code": "usuario123",
    "start": "2026-10-01 00:00:00",
    "end": "2026-10-31 23:59:59",
    "perPage": 100
}

Campo	Tipo	Obrigatório	Limite / regra	Descrição
user_code	string	Sim	1 a 191	Jogador consultado.
start	string	Sim	—	Data inicial (`Y-m-d H:i:s`).
end	string	Sim	—	Data final (`Y-m-d H:i:s`).
perPage	inteiro	Sim	≥ 1	Máximo de registros retornados.

Resposta: {"status":1,"slot":[...]}. Retorna 404 quando o jogador não existe ou não há registros no período.

Sub-agentes

POST

Movimenta o saldo entre o agente autenticado e um sub-agente. Os três métodos usam subagent_code (até 191 caracteres).

Depositar

{ "method":"subagent_deposit", "subagent_code":"SUB01", "amount":500.00 }

Retirar

{ "method":"subagent_withdraw", "subagent_code":"SUB01", "amount":200.00 }

Resetar

{ "method":"subagent_reset", "subagent_code":"SUB01" }

Resposta: agent_balance e subagent_balance. Erros: INVALID_SUBAGENT, INSUFFICIENT_FUNDS (400). Inclua agent_code e agent_token em todas as chamadas.

Segurança das Notificações (Callbacks)

Para garantir a integridade das notificações enviadas pela Games2API (Seamless), valide o campo agent_secret em cada requisição recebida, usando comparação em tempo constante (hash_equals).

Responda somente com JSON e HTTP 200 quando a operação for aplicada.
Use txn_id como chave de idempotência; o mesmo txn_id pode chegar mais de uma vez.
Não devolva o saldo antes de persistir a transação.
O endpoint precisa ser HTTPS público; URLs privadas, com IP privado ou credenciais na URL são recusadas.
Timeouts: conexão de 10s e resposta de 30s. Falhas transitórias (502/503/504, DNS e TCP) são repetidas automaticamente apenas em leitura de saldo.

Importante: Nunca processe transações sem a validação da Secret Key em seu back-end.

Tabela de Códigos de Retorno

Código	Significado	Ação Recomendada
1	Sucesso absoluto	Prosseguir com a operação
0	Erro (ver `msg` e `error`)	Tratar conforme o HTTP e `error.code`
-1	Autenticação falhou (legado)	Validar token e código do agente

Códigos HTTP e erros canônicos

HTTP	Código	Categoria	Repetir?	Significado
400	INVALID_REQUEST	client	Não	Campos obrigatórios, tipo ou limite inválido.
400	INVALID_USER	client	Não	Jogador não pertence ao agente.
400	INVALID_AGENT_TYPE	client	Não	Método não disponível para o tipo de agente.
404	GAME_NOT_FOUND	configuration	Não	Jogo/provedor inativo ou inexistente.
405	METHOD_NOT_ALLOWED	client	Não	Use POST na raiz da API.
409	INSUFFICIENT_USER_FUNDS	business	Não	Saldo insuficiente — recusa normal de negócio.
409	IDEMPOTENCY_CONFLICT	integrity	Não	Chave reutilizada com parâmetros diferentes.
409	REQUEST_ALREADY_PROCESSED	integrity	Não	`bonus_id` reutilizado com outros parâmetros.
422	CURRENCY_NOT_SUPPORTED	configuration	Não	Moeda não suportada pelo jogo.
422	FREESPIN_NOT_SUPPORTED_FOR_PROVIDER	configuration	Não	Integração sem suporte a concessão.
422	FREESPIN_GAME_NOT_ELIGIBLE	configuration	Não	Jogo não consome free spins.
422	INVALID_FREESPIN_LEVEL	configuration	Não	Nível fora de `available_levels`.
422	BONUS_NOT_SUPPORTED_FOR_PROVIDER	configuration	Não	Bônus PGSoft com provedor diferente de PGSOFT.
429	FREESPIN_RATE_LIMITED	temporary	Sim	Limite do provedor atingido.
500	TRANSACTION_FAILED	integrity	Não	Falha ao registrar a transação.
502	PROVIDER_UNAVAILABLE / UPSTREAM_ERROR	temporary	Sim	Provedor indisponível ou resposta inválida.
503	WALLET_UNAVAILABLE / ACCOUNT_UNAVAILABLE	temporary	Sim	Carteira/conta temporariamente indisponível.
504	UPSTREAM_TIMEOUT	temporary	Sim	Tempo limite ao consultar o provedor.

Em falhas repetíveis, aguarde error.retry_after_ms (3s a 15s). Para concessões, reenvie com o mesmo request_id/bonus_id; para transações, o mesmo txn_id.

Guia de Integração API

Introdução

Seamless

Catálogo

Bônus

Operação

Segurança

URL Base da API

Autenticação & Cabeçalhos

Métodos & Formatos de Dados

Limites de Tamanho por Campo

Formato das Respostas

Referência de Endpoints

Lançar Jogo (Game Launch)

Consultar Saldo (Callback)

Notificar Transação (Callback)

Listar Provedores

Lista de Jogos, Free Spins e Moedas

Listar Jogos Elegíveis

Conceder Free Spins

Beterraba e Consultas de Free Spins

Consultar Giros Restantes (Aviatrix)

Bônus PGSoft

Abrir Jogo em Modo Demo

Histórico de Jogo

Sub-agentes

Segurança das Notificações (Callbacks)

Tabela de Códigos de Retorno

Central de Suporte