API de Integração - DreamTechGames
Funções obrigatórias para liberar uma nova integração
Condição para liberar uma nova integração em produção. A consulta assinada por ID é uma função obrigatória da integração, assim como o comprovante durável e a proteção contra duplicação. A integração só pode ser liberada depois que as três funções forem implementadas e validadas com a DreamTechGames.
- Consulta por ID: responder ao método
transaction_status, contratodtg-reconciliation-v1, em tratamento somente leitura, com autenticação da consulta e assinatura do comprovante de resposta. - Comprovante durável: confirmar a operação financeira somente depois do commit definitivo, preservando a identidade e os valores originais. Nas novas homologações, incluir
txn_idereceipt_idna confirmação positiva; a consulta por ID deve devolver esse recibo quando a operação estiverapplied. - Proteção contra duplicação: persistir uma identidade única por agente + jogador + provedor + transação. Repetições idênticas, inclusive simultâneas, devolvem o resultado já registrado sem nova movimentação. Mesma identidade com valores divergentes deve ser rejeitada como conflito.
Compatibilidade com integrações existentes: contratos já integrados antes desta revisão continuam válidos, com seus endpoints, credenciais, envelopes e respostas homologados. A publicação desta documentação não ativa consultas nem altera callbacks em uso. Esses operadores também podem acrescentar as funções novas após homologação com a equipe DreamTechGames, preservando o fluxo financeiro existente. Não substitua automaticamente um receptor já integrado pelos exemplos de nova integração.
No cadastro de novos agentes, o callback HTTPS é obrigatório e também é o endereço de consulta por ID. Depois de criar o agente, configure as credenciais no seu servidor e implemente transaction_status nessa mesma URL. A plataforma verifica automaticamente o método e a assinatura da resposta. Enquanto a validação estiver pendente, as aberturas de jogos retornam HTTP 409 com AGENT_RECONCILIATION_PENDING; as credenciais e o status ficam disponíveis nos detalhes do agente. Após a resposta válida, a consulta é habilitada automaticamente e as aberturas são liberadas. Essa verificação de capacidade não substitui os demais testes de homologação financeira descritos abaixo. Os testes financeiros de homologação devem usar exclusivamente carteira, dados e destinatário de sandbox, sem jogadores ou dinheiro reais. Não reenviar operações históricas como teste.
Veja Consulta por ID e reconciliação — contrato v1.
Proteções de integração — atualização de 01/10/2026
- Callback do operador: use HTTPS na porta 443, certificado válido e DNS público. Endereços locais, privados, reservados, redirecionamentos, credenciais embutidas e fragmentos na URL são rejeitados. Todos os endereços retornados pelo DNS precisam ser públicos; o destino validado é fixado durante a conexão para impedir DNS rebinding.
- Resposta do callback: devolva uma confirmação pequena, abaixo de 1 MB, imediatamente após concluir a transação. Há limites de tempo de conexão e resposta; uma falha pode exigir conciliação ou reentrega conforme o adaptador. Aplique idempotência persistente pelo identificador da transação e rejeite reutilização do identificador com dados divergentes.
- Credenciais: token e secret devem pertencer ao mesmo agente. Faça as chamadas no backend do operador. Nunca registre esses valores no console, analytics ou logs; URLs de sessão também são confidenciais. Os contratos legados que recebem credenciais na query continuam exclusivamente servidor a servidor.
- Limites: trate HTTP 429 com espera e retentativa limitada. Não tente contornar bloqueios alternando IPs. Separe falhas de autenticação de erros temporários.
- Administração: administradores do portal precisam cadastrar e confirmar um autenticador TOTP. A senha sozinha não libera o painel. Guarde os códigos de recuperação fora do navegador; cada código só pode ser usado uma vez.
- Pagamentos: o webhook do provedor é separado do callback do operador e da sessão do painel. Valida assinatura, janela de tempo e identidade do evento antes de processar o crédito; a mesma entrega não deve creditar novamente.
Fluxo de segurança: backend do operador → credenciais do mesmo agente → limite de chamadas → lançamento autorizado → callback HTTPS validado → transação idempotente → confirmação → reconciliação. Webhooks precisam ser alcançáveis pelo remetente autorizado; sua proteção depende da autenticação e validação, não de esconder a URL.
Documentação técnica para operadores integrarem jogos, catálogo, configuração de agente, rodadas grátis e callbacks financeiros da agregadora DreamTechGames.
Comece por aqui
- Cadastre o agente e sua URL HTTPS de callback no painel. Configure o token e o secret gerados no servidor do operador. O novo agente permanece pendente até o callback responder à validação automática de consulta por ID.
- Implemente o callback financeiro com autenticação, transação de banco, recibo durável e idempotência persistente, inclusive para chamadas simultâneas.
- Implemente a consulta por ID
transaction_status, somente leitura, com as assinaturas e o formato exato de resposta descritos no contrato v1 abaixo. - Consulte provedores e catálogo; use os códigos retornados, sem montar URLs de jogos manualmente.
- Consulte as carteiras e selecione
wallet_typeda entrada do catálogo. Distribuição é a origem técnica; não determina sozinha a carteira comercial. - Faça o launch pelo seu backend e abra exatamente o
launch_urlrecebido. Nunca exponhasecretKeyno navegador. - Antes da entrada da nova integração em produção, homologue em sandbox carregamento, HUD, três giros consecutivos de teste, reload, repetição sequencial e simultânea do mesmo callback sem nova movimentação, conflito de valores e recuperação por consulta após perda da resposta.
Fluxo de integração
Painel → agente + callback HTTPS → credenciais no backend do operador
↓
GET providers → GET games → game_code + provider + wallet_type
↓
GET balances → carteira disponível → POST game_launch
↓
launch_url → bootstrap → GameInfo → HUD → giro de QA → resultado → próximo giro
↓
Callback → autenticar → validar identidade/valores → bloquear carteira no banco
↓
Transação já existe? ─ sim → conferir payload e devolver resposta persistida
│ não
└→ aplicar aposta e prêmio juntos → gravar recibo → commit → confirmar JSON
Fluxo da recarga do proprietário
Painel Carteira → cotação → intenção + lote de créditos → cobrança PIX
↓
webhook VexusPay com assinatura válida
↓
validar moeda + valor + referência → bloquear pagamento e carteira
↓
crédito único + lote creditado + COMPLETED → saldo disponível
Gerar o QR Code não credita saldo. COMPLETED é terminal: eventos tardios não desfazem um crédito. Timeout ao gerar cobrança exige conciliação da mesma intenção; não significa pagamento recusado. O saldo comercial do proprietário e o saldo do jogador são registros distintos.
Consulta, repetição e erros
| Operação | Regra de repetição |
|---|---|
| Catálogo / saldos | Repetir com espera progressiva em falha de rede; nunca registrar credenciais em logs |
| Launch | Consultar o erro antes de repetir; manter o mesmo user_code, sem criar aliases |
| Callback | Reenviar a mesma identidade e valores; duplicata retorna a resposta persistida |
| Payload diferente com a mesma transação | Rejeitar com conflito e reconciliar |
| 403 / 409 / 422 / 423 | Corrigir credencial, saldo, payload ou disponibilidade; não repetir indefinidamente |
| 5xx / timeout | Estado pode ser incerto; consultar/reconciliar antes de iniciar outra operação financeira |
O catálogo informa disponibilidade administrativa. Isso não substitui homologação visual e financeira do título. Nem todo jogo suporta bônus ou todos os envelopes de callback; consulte as diferenças abaixo.
Modelo de crédito
O agente identifica o white label, autentica as chamadas e informa a callback_url; ele não possui saldo próprio. Todo crédito comercial pertence às carteiras do proprietário do agente. Uma recarga é aplicada diretamente na carteira selecionada e passa a atender todos os agentes daquele mesmo proprietário.
- Jogos Standard, inclusive os de
distribution: "dreamtechgames", consomembalance(Carteira Principal). - A carteira é indicada pelo campo
wallet_typeda entrada de catálogo. Preserve o valor retornado pela API;originalnão determina a carteira. - Jogos Ao Vivo possuem uma carteira separada. Não presuma suporte de lançamento de um jogo ausente do catálogo publicado.
Não existe endpoint público para transferir crédito a um agente. A recarga financeira é administrada pela DreamTechGames e deve estar concluída antes do lançamento do jogo.
Use sempre game_code, provider.name e distribution da mesma entrada atual de GET /api/v2/games. Um título DreamTechGames mantém sua identidade de catálogo, independentemente da interface utilizada: por exemplo, o Fortune Tiger ativo usa fortune-tiger-dreamtechgames, provider DREAMTECHGAMES e distribution dreamtechgames. Ele não consome a carteira DreamTechPremium nem chama o lançamento de outro catálogo.
GET /api/v2/balances expõe somente as carteiras comerciais do proprietário. Ele não provisiona nem expõe ledgers operacionais internos de um runtime DreamTechGames. Se um jogo já aberto devolver uma recusa terminal de saldo/cobertura, não trate como falha de rede e não repita indefinidamente; interrompa o giro e solicite reconciliação financeira à operação DreamTechGames.
Ambiente
Base URL de produção:
https://dreamtechgames.fun
Cabeçalhos padrão:
Content-Type: application/json
Accept: application/json
Padrões financeiros:
| Item | Padrão |
|---|---|
| Moeda | BRL |
| Precisão | Decimal em reais, com 2 casas. Ex.: 10.50 |
| Centavos inteiros | Não usar. Envie 0.25, não 25 |
| Timezone | America/Sao_Paulo |
Produção e homologação usam credenciais distintas. Não há sandbox separado nesta versão; para homologar, use credenciais, usuários e jogos de teste combinados com a operação DreamTechGames.
Autenticação
O operador recebe três credenciais:
O login e a senha do painel identificam o usuário do portal; eles não autenticam a API v2. No menu Agentes, cadastre um agente vinculado à sua conta e use o agentToken e o secretKey desse agente nas chamadas servidor a servidor. Uma conta recém-criada ainda não possui essas credenciais até concluir esse cadastro.
| Campo | Descrição |
|---|---|
| agent_code | Identificador público do operador |
| agent_token | Token de autenticação |
| agent_secret | Secret de autenticação |
Nas chamadas do operador para a DreamTechGames, envie as credenciais no corpo ou query string usando os nomes abaixo:
| Credencial | Campo enviado |
|---|---|
| agent_token | agentToken |
| agent_secret | secretKey |
Nos callbacks enviados da DreamTechGames para o operador, as credenciais seguem no corpo em snake_case:
| Campo | Descrição |
|---|---|
| agent_code | Identificador público do operador |
| agent_secret | Secret do operador |
Segurança operacional:
- HTTPS é obrigatório.
- Allowlist de IP é recomendada.
- HMAC e Bearer token não são enviados nesta versão.
slot.txn_iddeve ser tratado como chave idempotente.
Rotas
| Verbo | Rota | Finalidade |
|---|---|---|
| POST | /api/v2/game_launch |
Abrir jogo |
| GET | /api/v2/providers |
Listar provedores |
| GET | /api/v2/games |
Listar jogos |
| GET | /api/v2/balances |
Consultar saldos comerciais da carteira do operador autenticado |
| GET | /api/v2/agent |
Consultar configuração do agente |
| PUT | /api/v2/agent |
Atualizar configuração do agente |
| POST | /api/v2/free_bonus |
Agendar rodadas grátis |
| GET | /api/v2/free_bonus |
Listar rodadas grátis |
| DELETE | /api/v2/free_bonus |
Remover rodadas grátis |
POST /api/v2/game_launch
Abre uma sessão de jogo para um jogador do operador.
Antes do launch, consulte GET /api/v2/balances e selecione a carteira pelo
wallet_type da entrada de catálogo. Saldo em outra carteira não cobre o jogo.
Jogos de origem DreamTechPremium podem estar no catálogo Standard ou Premium; preserve
o mapeamento retornado pela API.
Payload
{
"secretKey": "SEU_AGENT_SECRET",
"agentToken": "SEU_AGENT_TOKEN",
"user_code": "123",
"user_balance": 100.50,
"game_code": "fortune-tiger-dreamtechgames",
"provider": "DREAMTECHGAMES",
"lang": "pt",
"game_original": false,
"user_rtp": 96
}
Campos
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| secretKey | Sim | string | Secret do agente |
| agentToken | Sim | string | Token do agente |
| user_code | Sim | string | ID único do jogador no cassino |
| user_balance | Sim | number | Saldo atual do jogador em BRL |
| game_code | Sim | string | Código retornado no catálogo |
| provider | Sim | string | Nome do provedor retornado no catálogo |
| lang | Não na DreamTechGames | string | Idioma. Padrão local: pt. Nos jogos do catálogo externo, o campo é enviado ao upstream DreamTechPremium, onde é obrigatório. |
| game_original | Não na DreamTechGames | boolean | Quando ausente, é resolvido pelo catálogo. Nos jogos do catálogo externo, o campo é enviado ao upstream DreamTechPremium, onde é obrigatório. |
| user_rtp | Não | integer | RTP por usuário aplicado no lançamento |
Resposta de sucesso
HTTP 200:
{
"status": 1,
"msg": "SUCCESS",
"launch_url": "https://api.dreamtechgames.fun/URL_DE_SESSAO_RETORNADA_PELO_SERVIDOR"
}
Abra o launch_url em iframe, popup ou nova aba.
Fortune Rabbit no catálogo DreamTechGames
fortune-rabbit-dreamtechgames é um título normal do catálogo: qualquer agente ativo pode abri-lo pelo mesmo POST /api/v2/game_launch. Não há parâmetro, rota ou credencial exclusiva para um white label específico. O runtime recebe somente a identidade do agente já autenticado e a callback_url HTTPS cadastrada no Admin; nunca aceita uma URL de callback enviada pelo navegador.
Resposta de erro
{
"status": 0,
"msg": "Credenciais inválidas."
}
Códigos HTTP
| HTTP | Significado |
|---|---|
| 200 | Sucesso |
| 400 | Falha no provedor |
| 403 | Credenciais inválidas, saldo/carteira insuficiente ou jogo indisponível |
| 409 | Carteira não configurada ou estado financeiro que exige reconciliação |
| 422 | Payload inválido |
| 408 | Timeout |
| 504 | Timeout de gateway |
| 5xx | Indisponibilidade interna ou externa |
Mensagens reconhecidas pelo integrador
Mantenha o tratamento literal das mensagens abaixo:
| Mensagem | Tratamento recomendado |
|---|---|
Credenciais inválidas. |
Bloquear chamada e revisar credenciais |
user_not_found |
Reconciliar a identidade com a operação; preservar o mesmo user_code |
user not found |
Reconciliar a identidade com a operação; preservar o mesmo user_code |
invalid user |
Reconciliar a identidade com a operação; preservar o mesmo user_code |
unknown user |
Reconciliar a identidade com a operação; preservar o mesmo user_code |
influencer |
Reconciliar a identidade com a operação; preservar o mesmo user_code |
Saldo insuficiente. |
Atualizar saldo antes de tentar novamente |
Carteira sem saldo suficiente para iniciar o jogo. |
Consultar /api/v2/balances e recompor a carteira indicada por wallet_type |
Not enough cash. |
Recusa terminal do runtime; não repetir como erro de rede e solicitar reconciliação operacional |
Este jogo está temporariamente indisponível. |
Ocultar ou bloquear jogo no operador |
Exemplo cURL
curl -X POST "https://dreamtechgames.fun/api/v2/game_launch" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"secretKey": "SEU_AGENT_SECRET",
"agentToken": "SEU_AGENT_TOKEN",
"user_code": "123",
"user_balance": 100.50,
"game_code": "fortune-tiger-dreamtechgames",
"provider": "DREAMTECHGAMES",
"lang": "pt",
"game_original": false,
"user_rtp": 96
}'
GET /api/v2/providers
Lista os provedores disponíveis.
Resposta
{
"status": 1,
"data": [
{
"id": "1",
"name": "DREAMTECHGAMES",
"status": true
}
]
}
Campos
| Campo | Tipo | Descrição |
|---|---|---|
| status | integer | 1 em caso de sucesso |
| data | array | Lista de provedores |
| data[].id | string | ID sequencial do provedor |
| data[].name | string | Nome usado no payload de abertura |
| data[].status | boolean | Disponibilidade do provedor |
| data[].type | string | Opcional: live nas provedoras do catálogo Ao Vivo |
| data[].wallet_catalog | string | Identificador comercial retornado pela API; preserve o valor recebido |
| data[].wallet_type | string | Opcional: balance_playfiverPremium nas provedoras Ao Vivo |
Exemplo cURL
curl -X GET "https://dreamtechgames.fun/api/v2/providers" \
-H "Accept: application/json"
GET /api/v2/games
Lista os jogos disponíveis. O filtro por provedor é opcional. Para catálogos grandes, use page (a partir de 1) e per_page (de 1 a 500). Ao informar qualquer um deles, a resposta inclui meta.page, meta.per_page, meta.total e meta.last_page. Sem paginação, o retorno mantém compatibilidade com a lista completa e não inclui meta.
Query string opcional
provider=DREAMTECHGAMES&page=1&per_page=50
Resposta
{
"status": 1,
"data": [
{
"name": "Fortune Tiger",
"wallet_type": "balance",
"wallet_catalog": "standard",
"distribution": "dreamtechgames",
"game_code": "fortune-tiger-dreamtechgames",
"image_url": "https://dreamtechgames.fun/storage/games/banners/exemplo.png",
"status": true,
"original": false,
"provider": {
"name": "DREAMTECHGAMES"
}
}
]
}
Campos
| Campo | Tipo | Descrição |
|---|---|---|
| status | integer | 1 em caso de sucesso |
| data | array | Lista de jogos |
| data[].wallet_type | string | Carteira comercial efetivamente usada no lançamento |
| data[].wallet_catalog | string | Identificador comercial retornado pela API; preserve o valor recebido |
| data[].game_type | string | Campo de classificação do catálogo: live nas entradas Ao Vivo; pode estar ausente nas demais entradas v2 |
| data[].distribution | string | Origem técnica; não usar isoladamente para escolher carteira |
| data[].name | string | Nome público do jogo |
| data[].game_code | string | Código usado na abertura |
| data[].image_url | string | URL da imagem/banner |
| data[].status | boolean | Disponibilidade do jogo |
| data[].original | boolean | Indica jogo original da casa |
| data[].provider.name | string | Nome do provedor usado na abertura |
| data[].rounds_free | boolean | Indica se o jogo aparece com suporte a rodadas grátis no catálogo; a concessão ainda depende da liberação operacional |
| meta | object | Presente somente quando page ou per_page é informado; contém página atual, tamanho, total e última página |
Exemplo de meta para page=1&per_page=50:
{"page":1,"per_page":50,"total":13,"last_page":1}
O total do exemplo é ilustrativo; leia total e last_page da resposta atual para percorrer todas as páginas.
Mapeamento obrigatório
| Formato final | Observação |
|---|---|
data |
Lista sempre nesta chave |
name |
Nome do jogo |
image_url |
URL da imagem |
status: true |
Booleano |
original: false |
Booleano |
provider: { "name": "DREAMTECHGAMES" } |
Objeto com chave name |
Classificação Ao Vivo e sincronização
Nas entradas publicadas da carteira Ao Vivo, game_type é live nas listas v1 e v2. Na lista de provedoras v1, type é live; na v2, os campos opcionais de Ao Vivo identificam as provedoras desse catálogo. Guarde os campos de classificação ao importar e percorra todas as páginas. Atualize os registros existentes pela mesma identidade de catálogo, sem duplicá-los. Não use o nome comercial da provedora, original ou distribution para deduzir carteira ou substituir códigos de abertura.
Essa classificação é da vitrine. Não a copie para o callback financeiro: o envelope vigente de cada adaptador permanece como homologado, inclusive game_type: "slot" e os valores em slot quando esse é o contrato recebido. Não renomeie provider.name, provider_code, game_code ou distribution para colocar um título na categoria Ao Vivo.
Exemplo cURL
curl -X GET "https://dreamtechgames.fun/api/v2/games?provider=DREAMTECHGAMES" \
-H "Accept: application/json"
Disponibilidade administrada
Somente jogos com status: true são retornados no catálogo. Isso inclui os títulos DreamTechGames e os títulos DreamTechPremium já ativos no nosso catálogo, pelo mesmo GET /api/v2/games. No painel DreamTechGames, o administrador pode ativar ou desativar um título; a alteração vale imediatamente para todos os white labels e também bloqueia novos lançamentos do título desativado. Registros e histórico não são removidos.
GET /api/v2/balances
Consulta os saldos comerciais da carteira proprietária do agente autenticado. Envie agentToken e secretKey na query string. O retorno não expõe nem usa saldo no registro do agente.
curl -X GET "https://dreamtechgames.fun/api/v2/balances?agentToken=SEU_AGENT_TOKEN&secretKey=SEU_AGENT_SECRET" \
-H "Accept: application/json"
{
"status": 1,
"data": {
"Carteira Principal": 0,
"Carteira DreamTechPremium": 0,
"Jogos Ao Vivo": 0
}
}
Use wallet_type da entrada do catálogo para escolher a carteira e a chave correspondente de GET /api/v2/balances. Preserve os valores do contrato retornados pela API. Não deduza a carteira por original ou pelo nome do provedor. Jogos Ao Vivo exigem uma entrada publicada para esse produto.
GET /api/v2/agent
Consulta a configuração operacional do agente.
Query string
agentToken=SEU_AGENT_TOKEN&secretKey=SEU_AGENT_SECRET
Resposta
{
"status": 1,
"data": {
"rtp": 96,
"bonus_enable": true,
"dreamtech_bonus_enable": false,
"limit_enable": false,
"limit_amount": 0,
"limit_hours": 0
}
}
Campos
| Campo | Tipo | Descrição |
|---|---|---|
| status | integer | 1 em caso de sucesso |
| data.rtp | integer | RTP global do agente |
| data.bonus_enable | boolean | Indica se bônus está habilitado |
| data.dreamtech_bonus_enable | boolean | Indica se bônus nativo DreamTechGames está habilitado |
| data.limit_enable | boolean | Indica se limite operacional está habilitado |
| data.limit_amount | number | Valor do limite |
| data.limit_hours | integer | Janela do limite em horas |
Exemplo cURL
curl -X GET "https://dreamtechgames.fun/api/v2/agent?agentToken=SEU_AGENT_TOKEN&secretKey=SEU_AGENT_SECRET" \
-H "Accept: application/json"
PUT /api/v2/agent
Atualiza a configuração operacional do agente.
Payload
{
"agentToken": "SEU_AGENT_TOKEN",
"secretKey": "SEU_AGENT_SECRET",
"rtp": 96,
"bonus_enable": true,
"dreamtech_bonus_enable": false,
"limit_enable": false,
"limit_amount": 0,
"limit_hours": 0
}
Campos
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| agentToken | Sim | string | Token do agente |
| secretKey | Sim | string | Secret do agente |
| rtp | Não | integer | RTP global de 0 a 100 |
| bonus_enable | Não | boolean | Habilita ou desabilita bônus |
| dreamtech_bonus_enable | Não | boolean | Habilita ou desabilita bônus nativo DreamTechGames |
| limit_enable | Não | boolean | Habilita ou desabilita limite |
| limit_amount | Não | number | Valor do limite |
| limit_hours | Não | integer | Janela do limite em horas |
Resposta
{
"status": 1,
"data": {
"rtp": 96,
"bonus_enable": true,
"dreamtech_bonus_enable": false,
"limit_enable": false,
"limit_amount": 0,
"limit_hours": 0
}
}
Exemplo cURL
curl -X PUT "https://dreamtechgames.fun/api/v2/agent" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"agentToken": "SEU_AGENT_TOKEN",
"secretKey": "SEU_AGENT_SECRET",
"rtp": 96,
"bonus_enable": true,
"dreamtech_bonus_enable": false,
"limit_enable": false,
"limit_amount": 0,
"limit_hours": 0
}'
Rodadas grátis
As rotas abaixo permitem agendar, listar e remover rodadas grátis. O agendamento fica registrado na DreamTechGames e a execução depende do suporte do jogo/provedor. A funcionalidade permanece bloqueada até que um administrador a habilite após a aprovação operacional e regulatória; enquanto bloqueada, o POST retorna 423. Mesmo habilitada, a API aceita somente jogos selecionados explicitamente em Configurações → Rodadas grátis.
POST /api/v2/free_bonus
Agenda rodadas grátis para um jogador ou registra uma campanha geral para os jogadores do próprio agente. Cada concessão tem idempotência e os jogos sem suporte confirmado são recusados.
Payload
{
"agentToken": "SEU_AGENT_TOKEN",
"secretKey": "SEU_AGENT_SECRET",
"user_code": "123",
"game_code": "fortune-tiger-dreamtechgames",
"rounds": 10,
"idempotency_key": "campanha-de-lancamento-001"
}
Campos
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| agentToken | Sim | string | Token do agente |
| secretKey | Sim | string | Secret do agente |
| target_scope | Não | individual ou general |
Padrão individual. Em general, o envio alcança somente os jogadores vinculados ao agente autenticado. |
| user_code | Sim no individual | string | ID único do jogador no cassino. Não envie no modo general. |
| game_code | Sim | string | Código do jogo |
| rounds | Sim | integer | Quantidade de rodadas por jogador, de 1 a 1.000 |
| idempotency_key | Recomendado | string | Chave única do cliente; repetir a mesma chave e o mesmo payload não duplica a concessão/campanha. |
Resposta
{
"status": true,
"msg": "Rodadas grátis agendadas.",
"data": {"id": 123, "game_code": "fortune-tiger-dreamtechgames", "user_code": "123", "rounds": 10, "status": "pending"},
"replayed": false
}
data contém a concessão criada; replayed informa se a mesma chave idempotente devolveu uma concessão anterior. A mensagem e o estado exatos podem variar por provedor.
Campanha geral
Para enviar a todos os jogadores elegíveis do mesmo agente, troque o escopo e omita user_code. A resposta é 202 Accepted, pois cada destinatário é processado em fila e pode ser acompanhado no painel Rodadas grátis.
{
"agentToken": "SEU_AGENT_TOKEN",
"secretKey": "SEU_AGENT_SECRET",
"target_scope": "general",
"game_code": "fortune-tiger-dreamtechgames",
"rounds": 100,
"idempotency_key": "lote-agosto-2026"
}
Consulte o andamento da campanha pelo mesmo endpoint: GET /api/v2/free_bonus?agentToken=...&secretKey=...&campaign_id=ID_DA_CAMPANHA. A resposta inclui totais de destinatários, processados, concluídos, ignorados e falhos.
Exemplo cURL
curl -X POST "https://dreamtechgames.fun/api/v2/free_bonus" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"agentToken": "SEU_AGENT_TOKEN",
"secretKey": "SEU_AGENT_SECRET",
"user_code": "123",
"game_code": "fortune-tiger-dreamtechgames",
"rounds": 10,
"idempotency_key": "rodadas-jogador-123-001"
}'
GET /api/v2/free_bonus
Lista as últimas 100 rodadas grátis do agente.
Query string
agentToken=SEU_AGENT_TOKEN&secretKey=SEU_AGENT_SECRET
Resposta
{
"status": true,
"msg": "",
"data": [
{
"id": 123,
"game_id": "fortune-tiger-dreamtechgames",
"game_name": "Fortune Tiger",
"player_id": "123",
"rounds": 10,
"total_rounds": 10,
"status": "pending",
"created_at": "2026-07-07 14:30:00"
}
]
}
Exemplo cURL
curl -X GET "https://dreamtechgames.fun/api/v2/free_bonus?agentToken=SEU_AGENT_TOKEN&secretKey=SEU_AGENT_SECRET" \
-H "Accept: application/json"
DELETE /api/v2/free_bonus
Remove um agendamento de rodadas grátis.
Payload
{
"agentToken": "SEU_AGENT_TOKEN",
"secretKey": "SEU_AGENT_SECRET",
"id": 123
}
Campos
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| agentToken | Sim | string | Token do agente |
| secretKey | Sim | string | Secret do agente |
| id | Sim | integer | ID retornado na listagem |
Resposta
{
"status": true,
"msg": "Rodada grátis cancelada.",
"data": {"id": 123, "status": "cancelled"}
}
O campo data contém o estado devolvido pelo adaptador do jogo e pode ser null quando não houver registro retornado.
Exemplo cURL
curl -X DELETE "https://dreamtechgames.fun/api/v2/free_bonus" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"agentToken": "SEU_AGENT_TOKEN",
"secretKey": "SEU_AGENT_SECRET",
"id": 123
}'
Webhook / Callback
Quem envia e quem confirma
Há duas integrações independentes: DreamTechPremium/iGameWin → DreamTechGames e DreamTechGames → operador/white label. O fornecedor envia a operação e recebe a resposta da DreamTechGames. Essa resposta não comprova o recebimento pelo operador. A entrega ao operador é confirmada pela resposta positiva do callback cadastrado no agente. O nome da fila interna não identifica quem respondeu.
A DreamTechGames persiste a operação, evita duplicação e registra envio, resposta ou incerteza. O operador aplica sua movimentação de carteira de forma idempotente e responde após o commit. Uma confirmação positiva é a declaração do receptor; não é acesso direto da DreamTechGames ao banco dele. Sem resposta conclusiva, a entrega permanece não comprovada.
Formatos atuais e compatibilidade
As filas centrais de DreamTechPremium/iGameWin e dos adaptadores nativos usam method: "transaction", game_type: "slot" e os valores em slot. O campo superior type: "WinBet" pertence ao envelope de compatibilidade de determinados adaptadores e não está presente em todas as filas. Não o exija como campo universal nem substitua method por ele. Identifique o adaptador homologado pelos campos recebidos; mantenha os formatos já integrados.
Na consulta de saldo de compatibilidade, são enviados method: "user_balance" e type: "BALANCE" com as credenciais do agente. Os exemplos abaixo de WinBet/REFUND descrevem envelopes legados específicos; não são um contrato único de todos os jogos. O Fortune Rabbit mantém o envelope próprio descrito nesta seção.
Na saída iGameWin, slot.txn_id identifica o evento enviado ao operador e slot.source_txn_id preserva o ID do fornecedor. A idempotência do receptor usa o ID de saída recebido; não troque um pelo outro.
Exemplo do envelope de transação das filas centrais (credenciais ilustrativas):
{
"method": "transaction",
"agent_code": "SEU_AGENT_CODE",
"agent_secret": "****",
"user_code": "123",
"game_type": "slot",
"user_balance": 95.50,
"slot": {
"provider_code": "DREAMTECHGAMES",
"game_code": "fortune-tiger-dreamtechgames",
"txn_id": "TXN_UNICO",
"txn_type": "debit_credit",
"bet_money": 5.00,
"win_money": 0.00,
"user_before_balance": 100.50,
"user_after_balance": 95.50
}
}
Compatibilidade dos contratos anteriores: HTTP 200 e {"status":1,"user_balance":95.50}. O validador legado aceita essa confirmação sem ID; se informado em txn_id, transaction_id ou seus aliases suportados, precisa corresponder ao evento recebido. HTTP 200 sem confirmação positiva não basta. Para novas integrações, a homologação exige também txn_id e receipt_id durável, preservando os demais campos exigidos pelo título.
Encerramento administrativo de um passivo é uma decisão interna auditada: preserva os registros, mantém a entrega como não comprovada, impede reenvio e não cria uma nova movimentação financeira. Não equivale a recibo do operador nem comprova crédito ao jogador.
O white label informa sua própria URL HTTPS no cadastro do agente. A DreamTechGames envia callbacks somente para a callback_url vinculada ao agente autenticado; ela não é uma rota hospedada em dreamtechgames.fun.
https://cassino-do-cliente.exemplo/api/dreamtechgames/callback
O comportamento de entrega depende do provedor. Para Fortune Rabbit, a transação é registrada antes da entrega em uma outbox durável, usa a chave de idempotência rabbit:{transaction_id} e preserva a identidade da operação durante tentativas e recuperação. A política depende do processo do título; resposta incerta ou não confirmada pode exigir conciliação, sem novo envio financeiro automático. O operador deve responder 2xx somente depois de aplicar ou reconciliar a transação; falhas definitivas ficam disponíveis para reconciliação.
Envelope específico do Fortune Rabbit
Fortune Rabbit liquida uma rodada inteira em uma única notificação assíncrona. Para esse título, use transaction_id (ou txn_id) como chave de idempotência e aplique bet e win de modo atômico. O título mantém seu envelope de compatibilidade e não envia o campo genérico type no topo.
{
"transaction_id": "TXN_UNICO",
"txn_id": "TXN_UNICO",
"round_id": "ROUND_UNICO",
"idempotency_key": "rabbit:TXN_UNICO",
"agent_code": "SEU_AGENT_CODE",
"agent_secret": "****",
"user_code": "123",
"game_code": "fortune-rabbit",
"provider_code": "DREAMTECHGAMES",
"bet": 5.00,
"win": 0.00,
"user_balance": 95.00,
"slot": {
"txn_id": "TXN_UNICO",
"round_id": "ROUND_UNICO",
"bet": 5.00,
"win": 0.00,
"user_before_balance": 100.00,
"user_after_balance": 95.00
}
}
Nos envelopes legados que usam type no topo, o campo define o tipo do evento. Essa regra não se aplica universalmente aos envelopes method: transaction ou ao contrato específico do Rabbit:
| Valor | Finalidade |
|---|---|
| BALANCE | Consulta de saldo |
| WinBet | Aposta + resultado atômico |
| REFUND | Estorno/rollback |
Callback BALANCE
Consulta o saldo atual do jogador no operador.
Payload enviado pela DreamTechGames
{
"type": "BALANCE",
"user_code": "123"
}
Resposta esperada do operador
HTTP 200:
{
"status": 1,
"msg": "SUCCESS",
"balance": 95.50,
"user_balance": 95.50
}
Callback WinBet
Envia aposta e resultado em uma única transação financeira.
Payload enviado pela DreamTechGames
{
"type": "WinBet",
"game_type": "slot",
"user_code": "123",
"agent_code": "SEU_AGENT_CODE",
"agent_secret": "****",
"user_balance": 95.50,
"slot": {
"provider_code": "DREAMTECHGAMES",
"game_code": "fortune-tiger-dreamtechgames",
"type": "BASE",
"bet_money": 5.00,
"win_money": 0.00,
"txn_id": "TXN_UNICO",
"round_id": "ROUND_UNICO",
"txn_type": "debit_credit",
"user_before_balance": 100.50,
"user_after_balance": 95.50,
"timestamp": "2026-07-07T14:30:00-03:00"
}
}
Campos
| Campo | Tipo | Descrição |
|---|---|---|
| type | string | WinBet |
| game_type | string | Tipo do jogo. Ex.: slot |
| user_code | string | ID do jogador no operador |
| agent_code | string | Código público do agente |
| agent_secret | string | Secret do agente |
| user_balance | number | Saldo final esperado |
| slot.provider_code | string | Provedor do jogo |
| slot.game_code | string | Código do jogo |
| slot.type | string | Condicional por título. Ex.: BASE; não é universal |
| slot.bet_money | number | Valor apostado |
| slot.win_money | number | Valor ganho |
| slot.txn_id | string | ID único da transação |
| slot.round_id | string | ID da rodada quando disponibilizado pelo contrato |
| slot.txn_type | string | debit_credit |
| slot.user_before_balance | number | Saldo antes da transação |
| slot.user_after_balance | number | Saldo depois da transação |
| slot.timestamp | string | Data/hora ISO-8601 quando disponibilizada pelo contrato |
Regras do operador
- Validar
user_code. - Validar credenciais recebidas no corpo.
- Aplicar idempotência por agente + jogador +
slot.txn_id; guardar também hash do payload e resposta. Mesma identidade com valores diferentes é conflito. - Duplicata deve retornar HTTP 200 com saldo reconciliado, sem debitar novamente.
- Debitar
slot.bet_money. - Creditar
slot.win_money.
Resposta de sucesso
{
"status": 1,
"msg": "SUCCESS",
"balance": 95.50,
"user_balance": 95.50
}
Callback REFUND
Estorna uma transação. O campo type no topo é REFUND; slot.win_money traz o valor a restituir.
Payload enviado pela DreamTechGames
{
"type": "REFUND",
"game_type": "slot",
"user_code": "123",
"agent_code": "SEU_AGENT_CODE",
"agent_secret": "****",
"user_balance": 100.50,
"slot": {
"provider_code": "DREAMTECHGAMES",
"game_code": "fortune-tiger-dreamtechgames",
"type": "BASE",
"bet_money": 0.00,
"win_money": 5.00,
"txn_id": "TXN_REFUND_UNICO",
"round_id": "ROUND_UNICO",
"txn_type": "refund",
"user_before_balance": 95.50,
"user_after_balance": 100.50,
"timestamp": "2026-07-07T14:35:00-03:00"
}
}
Resposta de sucesso
{
"status": 1,
"msg": "SUCCESS",
"balance": 100.50,
"user_balance": 100.50
}
Erros esperados no callback
| HTTP | Resposta | Situação |
|---|---|---|
| 404 | { "status": 0, "msg": "USER_NOT_FOUND" } |
Jogador inexistente |
| 403 | { "status": 0, "msg": "INVALID_CREDENTIALS" } |
Credenciais inválidas |
| 409 | { "status": 0, "msg": "INSUFFICIENT_FUNDS" } |
Saldo insuficiente |
| 422 | { "status": 0, "msg": "MISSING_FIELDS" } |
Campos obrigatórios ausentes |
| 500 | { "status": 0, "msg": "INTERNAL_ERROR" } |
Erro interno do operador |
No callback de transação oficial DreamTechPremium, saldo insuficiente é
HTTP 400 / INSUFFICIENT_USER_FUNDS. A DreamTechGames mantém
HTTP 409 / INSUFFICIENT_FUNDS no contrato legado do operador e faz a tradução
explicitamente; o integrador não deve transformar qualquer 409 ou 5xx em
sucesso genérico.
Confirmação de entrega do callback
- A entrega só é concluída com HTTP
2xxe confirmação positiva explícita no JSON (status: 1,ok: true,success: trueou equivalente documentado). - HTTP resolvido com
status: 0,ok: false, credencial inválida ou resposta sem confirmação positiva permanece pendente conforme o adaptador; pode exigir conciliação sem nova tentativa. Consulte a política por processo ao final. - O receiver deve devolver o mesmo saldo reconciliado e, quando suportado, o
slot.txn_id; um identificador divergente reprova a confirmação. - Nunca confirme primeiro e processe depois: a resposta positiva declara que a transação idempotente já foi persistida.
Idempotência
slot.txn_idé único por evento financeiro.slot.round_idagrupa eventos da mesma rodada.- Duplicatas devem retornar HTTP 200 com saldo já reconciliado.
- Duplicatas nunca devem debitar ou creditar novamente.
Checklist de integração
- Criar agente no painel, definir a
callback_urlHTTPS exclusiva do white label e obteragentTokenesecretKey. - Manter ativos no admin apenas os jogos que o white label poderá consumir; jogos inativos somem do catálogo e recusam novos launches.
- Validar
GET /api/v2/providers. - Validar
GET /api/v2/games. - Consultar
GET /api/v2/balancese confirmar a carteira exigida pelowallet_typedo título. - Abrir jogo com
POST /api/v2/game_launch. - Implementar callback
BALANCE. - Implementar callback
WinBet. - Implementar callback
REFUND. - Validar idempotência por
slot.txn_ide confirmação positiva explícita. - Liberar jogos em produção após teste financeiro ponta a ponta.
Arquivos disponíveis
https://dreamtechgames.fun/developer
https://dreamtechgames.fun/api-documentation
https://dreamtechgames.fun/developer/openapi.json
https://dreamtechgames.fun/developer/postman.json
Segurança e limites de chamadas
As credenciais do operador devem permanecer no seu servidor. Nunca coloque agent_token, agent_secret ou secretKey no JavaScript público, console, analytics ou repositório. O navegador recebe somente o endereço de sessão retornado pelo lançamento; trate esse endereço como sensível e não o compartilhe.
Fluxo recomendado
Navegador do jogador → backend do operador → API DreamTech (credenciais)
← URL de sessão
Navegador → jogo → liquidação → callback autenticado no backend do operador
Na API da agregadora (dreamtechgames.fun), o catálogo permite até 120 chamadas/minuto por IP; demais chamadas de integração, até 1.200/minuto por IP. Callbacks possuem orçamento separado de 6.000/minuto por IP. O painel aplica limites menores em login, recuperação de senha, cadastro e alterações financeiras. A API legada possui limites próprios; use o contrato público documentado nesta página.
Ao receber HTTP 429, aguarde o intervalo indicado no cabeçalho Retry-After. Use espera progressiva com variação aleatória. Não faça repetição imediata em loop. Ao repetir uma transação, mantenha o mesmo identificador de idempotência e o mesmo conteúdo. Nunca gere um novo ID apenas para contornar timeout ou limite.
Cadastre callbacks HTTPS em domínio público, na porta 443, sem usuário/senha embutidos na URL. Endereços locais ou reservados são rejeitados no cadastro. No receptor, valide credenciais/assinatura antes de processar valores; confira jogador, moeda, valor e ID, e garanta idempotência em transação de banco. Não aceite saldo ou resultado enviado pelo navegador como prova de pagamento.
Chamadas necessárias ao funcionamento do jogo continuam visíveis no painel de rede do navegador. A segurança depende da autenticação, autorização e validação no servidor, mesmo que alguém conheça o endpoint.
Consulta por ID e reconciliação — contrato v1
A implementação deste contrato é obrigatória para novas integrações, junto do comprovante durável e da proteção contra duplicação. Os contratos já integrados permanecem compatíveis e podem incorporar a consulta após homologação específica. Para agentes novos, a validação usa automaticamente o callback cadastrado e, após aprovação, habilita a rotina para as filas suportadas. Integrações anteriores conservam a configuração já existente. Não muda apostas, prêmios, identificação de transações ou respostas dos callbacks financeiros existentes. Não tente descobrir métodos enviando operações exploratórias ao webhook financeiro.
Responsabilidades do operador
Novos agentes devem tratar o método transaction_status na própria URL HTTPS do callback cadastrado. Integrações anteriores com URL dedicada já homologada mantêm seus endereços e contratos. Na mesma URL, selecione esse método antes das validações de campos financeiros e mantenha os callbacks de aposta existentes inalterados. Ele deve consultar seu registro durável sem debitar, creditar, apostar, liquidar ou reenviar operações. Para novos agentes, não é necessário cadastrar outro endereço: a plataforma utiliza automaticamente o callback informado no cadastro. A consulta é executada pela DreamTechGames, não é um endpoint público hospedado por ela.
A confirmação applied só pode ser emitida depois do commit do lançamento no ledger do operador. A identidade de idempotência deve ser persistida com unicidade no escopo agente + jogador + fornecedor + transação, e a movimentação financeira deve ocorrer na mesma transação de banco. Uma repetição idêntica retorna o resultado original sem movimentar novamente; valores diferentes para a mesma identidade são conflito. Preserve IDs como strings, inclusive zeros à esquerda e capitalização.
not_found deve ser consultado na fonte autoritativa, incluindo o registro de idempotência e retenção histórica, não em cache ou réplica atrasada. Se o registro foi arquivado, expirou ou não há certeza sobre a ausência, responda erro/indisponibilidade, nunca ausência autoritativa. Operações rejeitadas devem permanecer registradas como rejected.
Validação automática dos novos agentes
A plataforma consulta um jogador e uma transação fictícios, aleatórios e inexistentes, com valores zero. O callback deve autenticar a assinatura da DreamTechGames e responder HTTP 200 com state: not_found, authoritative: true, os mesmos identificadores e a assinatura de resposta definida abaixo. Não crie jogador, saldo, aposta ou lançamento para essa consulta. HTTP 200 sem assinatura válida não aprova o agente.
A rotina tenta validar automaticamente em lotes limitados, normalmente a cada minuto. O painel mostra o estado pendente ou ativo. Indisponibilidade, assinatura inválida, resposta divergente ou alteração da configuração mantêm o novo agente pendente. Ao alterar callback, token ou secret de um desses novos agentes, é necessária uma nova validação para abrir novas sessões. Sessões e liquidações em andamento continuam usando seus fluxos existentes.
Esta validação comprova a capacidade de consulta autenticada, mas não comprova, sozinha, idempotência financeira, aplicação de pagamentos ou todos os cenários de recuperação. Esses testes continuam necessários em homologação com dados fictícios. A conciliação posterior confirma apenas o que estiver comprovado pelo operador; ausência ou divergência permanece pendente, sem reenvio automático de pagamentos.
Consulta assinada
POST para a URL de consulta homologada do operador; Content-Type: application/json. Exemplo fictício:
{
"version": "dtg-reconciliation-v1",
"method": "transaction_status",
"request_id": "74100c590fac4618a16a556b38fb9f72",
"transaction": {
"agent_code": "AGENTE_EXEMPLO",
"user_code": "jogador-exemplo",
"txn_id": "transacao-original",
"provider_code": "DREAMTECHGAMES",
"game_code": "fortune-snake",
"currency": "BRL",
"bet_cents": 50,
"win_cents": 250
}
}
A consulta possui quatro campos no topo: version, method, request_id e transaction. Dentro de transaction, são obrigatórios agent_code, user_code, txn_id, provider_code, game_code, currency, bet_cents e win_cents. IDs são strings; valores são inteiros não negativos em centavos. Zero é válido e não representa campo ausente. Não use uma validação de vazio que rejeite zero. Não exija slot, user_balance ou segredo no corpo dessa consulta: sua autenticação é Ed25519, descrita abaixo. Validadores globais do callback financeiro também precisam respeitar essa separação.
Os valores inteiros em centavos descrevem a operação que está sendo consultada; não são ordem de execução. O receptor deve comparar os dados com seus próprios registros antes de responder. Moeda suportada nesta versão: BRL.
A DreamTechGames assina o corpo exato com Ed25519. Cabeçalhos: X-DTG-Signature (v1: + assinatura Base64), X-DTG-Key-Id, X-DTG-Timestamp (segundos Unix), X-DTG-Nonce (32 caracteres hexadecimais) e X-DTG-Audience (SHA-256 hexadecimal da URL exata cadastrada). Chaves públicas: https://app.dreamtechgames.fun/.well-known/dtg-callback-keys.json.
Mensagem assinada em UTF-8, separada por LF, sem LF final:
DTG-CALLBACK-V1
POST
<X-DTG-Key-Id>
<X-DTG-Timestamp>
<X-DTG-Nonce>
<X-DTG-Audience>
<sha256 hexadecimal dos bytes originais do corpo>
Valide a chave pública confiável, assinatura, URL, timestamp (janela recomendada de 300 segundos) e unicidade do nonce. Não serialize novamente o JSON antes de validar. O segredo do agente não é enviado nessa consulta.
Resposta autenticada do operador
HTTP 200, com version, request_id e transaction exatamente correspondentes à consulta, preservando tipos. Acrescente state e, para applied, receipt_id estável e não vazio:
{
"version": "dtg-reconciliation-v1",
"request_id": "74100c590fac4618a16a556b38fb9f72",
"transaction": {
"agent_code": "AGENTE_EXEMPLO",
"user_code": "jogador-exemplo",
"txn_id": "transacao-original",
"provider_code": "DREAMTECHGAMES",
"game_code": "fortune-snake",
"currency": "BRL",
"bet_cents": 50,
"win_cents": 250
},
"state": "applied",
"receipt_id": "lancamento-duravel-123"
}
Inclua X-DTG-Reconciliation-Signature com v1: seguido de HMAC-SHA256 hexadecimal minúsculo, usando o agent_secret vigente como chave. A mensagem HMAC é:
DTG-RECONCILIATION-RESPONSE-V1
<request_id da consulta>
<sha256 hexadecimal dos bytes exatos da resposta>
Sem LF final. O segredo fica exclusivamente nos servidores; não o publique em JavaScript do navegador. A resposta fica vinculada à consulta aleatória atual, impedindo reaproveitar uma prova de outra consulta. Corpo máximo aceito: 64 KiB. Redirecionamentos são recusados.
| Estado | Significado | Tratamento automático |
|---|---|---|
applied |
Operação original gravada definitivamente | Confirma a entrega na fila, sem novo débito ou crédito |
processing |
Operação ainda sem conclusão | Mantém pendência e consulta novamente |
not_found |
Ausência comprovada na fonte autoritativa; exige authoritative: true |
Mantém pendência por padrão; só agenda envio original se allow_replay foi homologado e habilitado |
rejected |
Recusa definitiva registrada | Mantém conciliação; não credita, cancela ou libera seguidores automaticamente |
Erro HTTP, assinatura inválida, identidade/valor divergente ou resposta ambígua nunca confirma entrega. Recomenda-se identificar recusas com códigos específicos, como INSUFFICIENT_PLAYER_FUNDS, INSUFFICIENT_OPERATOR_FUNDS e IDEMPOTENCY_CONFLICT. A consulta não contorna uma insuficiência financeira.
Ativação, cobertura e limites
As configurações existentes são preservadas. Para novos agentes, a habilitação é persistida automaticamente após a validação do callback, sem reenvio financeiro. A configuração administrativa legada fica em config/callback_reconciliation.php. Cada agente informa enabled, URL de consulta homologada, allow_replay (padrão seguro: false) e profiles, um mapa de fila para ID mínimo exclusivo. O corte deve ser medido na ativação. Incluir o passivo antigo exige revisão explícita do escopo; não copie IDs de exemplos.
Exemplo de estrutura, não de cadastro real:
return [
123 => [
'enabled' => true,
'url' => 'https://operador.example/reconciliation',
'allow_replay' => false,
'profiles' => ['snake' => 10000, 'dragon' => 5000],
],
];
Adaptadores disponíveis: pg, native, tiger, mr_treasure, playfiver (inclui notificações IGameWin nessa fila), snake e dragon. Somente registros em reconciliation_required são selecionados nas filas centrais/Snake; no Dragon, somente failed. Entregues, cancelados, filas em execução e pendências ainda geridas pelo worker normal não são reprocessados por esta extensão. Rabbit com entrega própria, Piñata e rotas diretas específicas sem adaptador continuam nos seus processos existentes; não declarar cobertura automática desses caminhos.
Execução: php artisan callbacks:reconcile-operator --limit=10, acionada por timer a cada minuto, sem sobreposição via bloqueio no MySQL. Cada registro consultado aguarda pelo menos 300 segundos antes de nova consulta. Provas, hashes e decisões ficam em callback_reconciliation_checks. A rotina só atualiza estado de entrega; nunca altera jogadores, carteiras, histórico financeiro ou valores do evento.
Antes de permitir reenvio automático, homologue repetição concorrente do mesmo ID, valores divergentes, perda de ACK após commit, resposta antiga, assinatura inválida, separação de agentes e consulta autoritativa após arquivamento. Clientes atuais não precisam mudar para continuar recebendo os callbacks existentes. Precisam implementar e homologar o endpoint acima para aderir a esta extensão. A assinatura do callback não comprova, sozinha, que o destinatário a verificou.
Entrega, conciliação e contagem — compatibilidade dos contratos
Esta revisão não altera URLs, credenciais, IDs, valores nem respostas exigidas dos clientes atuais. Para novas integrações, consulta por ID, comprovante durável e proteção contra duplicação são requisitos de homologação. A URL, as assinaturas e a recuperação de resposta perdida devem ser validadas antes da liberação. Operadores já integrados podem incorporar o mesmo contrato sem substituir os callbacks atuais; o uso da consulta depende de homologação e configuração específica.
Campos por envelope
A tabela genérica de campos descreve possibilidades; não é uma lista de campos obrigatórios para todos os jogos. Não rejeite um envelope homologado pela ausência de um campo específico de outro título.
| Fluxo | Identificação e valores | Campos condicionais |
|---|---|---|
| DreamTechPremium via DreamTechGames | method: transaction, user_code, game_type, slot.provider_code, slot.game_code, slot.txn_id, slot.txn_type, slot.bet_money, slot.win_money |
round_id, type e timestamp não são garantidos neste envelope; não os exija universalmente. |
| iGameWin via fila central | Envelope transaction/slot; valores em bet_money e win_money; ID enviado ao operador opaco, atualmente igw:<recibo> |
source_txn_id e source_game_code identificam a origem, quando enviados. Não use o ID de origem no lugar do evento enviado ao operador. Débito e crédito separados possuem eventos próprios. |
Jogos próprios com slot |
Identidade em slot.txn_id, valores em bet_money/win_money ou bet/win, conforme o contrato homologado |
round_id, type, saldos, promoções e datas dependem do título. Se ambos os aliases monetários existirem, devem concordar. Rótulos históricos PGSOFT/PRAGMATIC não autorizam reescrever IDs ou supor mudança de contrato. |
| Fortune Rabbit com entrega própria | Preserve o envelope específico e os aliases descritos na seção do título; rodada inteira aplicada atomicamente | Não exigir type no topo. Não confundir entrega ao operador com relatório posterior à central. |
| Rotas diretas / legadas | Preserve o envelope e o destinatário homologados para a rota | Receber uma confirmação na central não comprova entrega posterior ao operador. |
As credenciais agent_code, agent_secret e, quando configurado, agent_token são hidratadas no envio conforme o contrato do agente. A forma persistida internamente pode não conter todos os campos de autenticação. Chaves privadas e segredos nunca pertencem ao navegador ou a extratos compartilháveis.
Identidade, confirmação e erros
- Trate IDs como strings opacas, preservando capitalização e zeros. A chave econômica inclui agente, jogador, provedor e ID do evento enviado. Uma rodada pode ter vários eventos.
- Na mesma transação de banco do receptor, grave a identidade, aplique os valores uma única vez e guarde a resposta original. Uma repetição idêntica devolve o resultado daquele evento sem novos lançamentos, mesmo que o saldo atual tenha mudado.
- Compare a identidade e os valores econômicos. Timestamp, nonce, assinatura e rotação de credenciais não transformam a mesma operação econômica em outra aposta.
- Confirme com HTTP
2xxe JSON positivo somente após o commit. Clientes atuais mantêm a resposta homologada. Para novas homologações, é obrigatório devolver tambémtxn_ide umreceipt_iddurável; a assinatura autentica a mensagem, não comprova sozinha o lançamento na carteira. - Em
MISSING_FIELDS, mantenha o código compatível e acrescente, quando suportado,missing_fields: ["slot.txn_id"]. Em conflitos, informeIDEMPOTENCY_CONFLICT. Distinga insuficiência do jogador (INSUFFICIENT_PLAYER_FUNDS) da carteira do operador (INSUFFICIENT_OPERATOR_FUNDS) nas novas homologações; códigos legados continuam aceitos conforme o contrato existente. - Nunca interprete
409,422,5xx, timeout ou ausência de JSON como confirmação. Não converta recusas em sucesso para esvaziar a fila.
Política de entrega por processo
| Processo | Resposta perdida, recusa ou confirmação ausente | Recuperação |
|---|---|---|
| Fila central DreamTechPremium/iGameWin protegida | Mantém conciliação; não faz nova tentativa financeira às cegas | Resposta positiva já capturada, ou consulta por ID homologada; passivo anterior permanece preservado. |
| Filas centrais de jogos próprios | Estados e retentativas dependem do adaptador; o diário durável impede repetir uma solicitação incerta quando aplicável | Confirmar entrega somente com identidade, valores e resposta válidos. A recuperação nova por diário é limitada aos recibos posteriores à ativação, nos adaptadores PG, Tiger, Mr Treasure e nos jogos de posse central da fila native (Ice & Fire, Mouse e Lucky Tiger). Os demais mantêm o processo responsável pelo fechamento e os adaptadores já existentes. |
| Filas próprias, relatório Rabbit e fechamento Aviator | Permanecem com seus processos e regras de fechamento | Supervisão comum; recuperação operacional permanece com o processo responsável. Um fechamento não deve ser marcado completo apenas por um ACK financeiro de outra etapa. |
retry, dead_letter, failed, reconciliation_required, QUARANTINED e equivalentes são estados específicos de adaptadores, não uma sequência universal. A supervisão identifica filas atrasadas, motivo da espera, falha de leitura e estados desconhecidos. Verifique cada etapa; não some contagens entre filas como se fossem rodadas únicas.
A ausência autoritativa por ID exige consulta homologada do receptor. not_found em cache, réplica atrasada ou arquivo incompleto não autoriza reenvio. Sem essa capacidade, não é possível resolver toda resposta perdida exclusivamente no remetente. Reenvio de passivo histórico requer decisão separada; esta revisão não o habilita.
Histórico, GGR, créditos e horários
- Registro no histórico e contabilização local são diferentes de confirmação externa. Uma operação já contabilizada não deve ser lançada novamente porque seu callback está pendente.
- GGR operacional = soma das apostas pagas − soma dos prêmios correspondentes, incluindo eventos somente de prêmio derivados dessas apostas. Depósitos não entram nessa fórmula.
- A cobrança comercial segue a regra vigente na liquidação; pode diferir do GGR quando o percentual comercial sobre prêmios é diferente de 100%. Preserve evidências da regra aplicada; não recalcule o passado pela regra atual.
- No painel atual, o total de rodadas conta registros de aposta com valor positivo. Histórico inclui também créditos e registros sem movimentação. Quantidade de callbacks, quantidade de registros e quantidade de rodadas não são equivalentes.
- Datas novas devem indicar offset ou UTC explicitamente. Exibição brasileira usa
America/Sao_Paulo. Campos históricos sem offset têm convenções por origem; esta revisão não altera datas antigas nem impõe campo novo aos callbacks atuais.
Homologação e operação
Antes da ativação, testar: dois agentes com o mesmo código de jogador; repetição concorrente do mesmo ID; ID repetido com valores diferentes; perda da resposta depois do commit; reinício; prêmio separado do débito; continuação de bônus; credencial inválida; resposta positiva com ID divergente; assinatura inválida; consulta após arquivamento. Os testes usam saldo fictício e destinatário controlado.
A supervisão comum funciona fora dos giros, em lotes pequenos, com limites de CPU, memória e duração. Não envia callbacks, não altera saldos, não reabre passivos e não bloqueia rodadas aceitas. Manter os processos atuais não significa declarar todas as filas com recuperação automática idêntica.
Recuperação por comprovante e consulta por ID ao operador
Os adaptadores de consulta remota listados na seção anterior são distintos desta recuperação local: a disponibilidade de comprovantes internos não acrescenta automaticamente suporte à consulta remota em todos os títulos.
O processamento distingue registro da rodada, liquidação financeira e confirmação de entrega. Um registro recebido por uma fila interna não comprova, sozinho, o lançamento na carteira externa do operador.
As filas possuem recuperação local por comprovante compatível com sua etapa: resposta positiva capturada e íntegra para entrega externa; recibo e histórico persistidos e conferidos para o encaminhamento interno. Identidade do agente/jogador, ID da operação, destino e valores devem coincidir. A recuperação não reenvia callbacks nem cria uma segunda aposta, prêmio ou cobrança. Evidência ausente, contraditória ou uma tentativa ainda em andamento mantém a operação em análise. O fechamento do Aviator mantém a gravação atômica e o processamento idempotente próprios.
Essa recuperação é interna e não acrescenta campos obrigatórios aos callbacks atuais. Operações anteriores ao corte de ativação não são reenviadas por esse processo. Os formatos e as assinaturas existentes permanecem válidos.
Para comprovar automaticamente operações sem resposta capturada, a consulta por ID, requisito das novas integrações, deve ser implementada no servidor do operador, conforme o protocolo de reconciliação desta documentação. Para novos agentes, ela usa o método transaction_status na URL do callback cadastrado e passa pela validação automática descrita acima. Endereços dedicados de integrações anteriores são preservados. A consulta deve ser somente leitura e vincular agente, jogador, ID, valores e resultado persistido; uma consulta de saldo atual não substitui o comprovante da transação.
A publicação dessa capacidade não obriga clientes existentes a alterar a integração. Enquanto um operador já integrado não homologar a atualização do receptor, a plataforma continua operando com seu contrato atual e conserva como não comprovadas as entregas que não tenham evidência suficiente. Um endpoint de consulta hospedado pela DreamTech demonstra nossos registros e respostas recebidas, não o estado independente da carteira do operador.
Exemplos e roteiro de homologação para novas integrações
Confirmação financeira após commit — exemplo fictício
Este exemplo ilustra os campos adicionais da confirmação de uma nova integração; não substitui o envelope de resposta já homologado de um cliente existente. Responda sucesso somente após gravar a operação e sua movimentação definitivamente:
{
"status": 1,
"txn_id": "transacao-original",
"receipt_id": "lancamento-duravel-123"
}
Se o contrato financeiro do jogo exige outros campos de resposta, como saldo, preserve-os também. Repetir a mesma operação idêntica deve devolver seu resultado persistido e o mesmo recibo, sem reaplicar valores nem substituir o resultado histórico pelo saldo atual. Para os catálogos que enviam prefixos, preserve o ID completo: por exemplo, igw:4268, não o ID do fornecedor indicado apenas em source_txn_id.
Separação da consulta na URL atual
ler os bytes originais e o JSON
se method == transaction_status:
autenticar a assinatura Ed25519 da consulta
validar version, request_id e transaction, aceitando zero centavos
consultar o registro durável e conferir identidade, moeda e valores
devolver a resposta do contrato v1 com assinatura HMAC
encerrar sem chamar a rotina financeira
caso contrário:
seguir o tratamento financeiro e a autenticação do respectivo contrato
Esse tratamento deve ocorrer antes de um validador financeiro que exija slot, saldo ou credenciais no corpo. A consulta não cria aposta, não atualiza saldo, não cobra créditos e não recalcula GGR. Erros devem indicar os campos ausentes quando possível, sem expor segredos.
Critérios obrigatórios de homologação
| Teste em sandbox | Resultado exigido |
|---|---|
| Operação gravada e consulta pelo ID original | Mesmo agente, jogador, provedor, jogo, moeda, centavos e recibo durável |
| Repetição sequencial e simultânea do callback idêntico | Um lançamento financeiro; mesma resposta e mesmo recibo |
| Mesmo ID e identidade com valores diferentes | Conflito, sem novo lançamento |
| Mesmo ID em agentes ou jogadores distintos | Isolamento das identidades, sem mistura de carteiras |
| Commit seguido de perda da resposta | Consulta assinada confirma o registro sem reenviar a movimentação |
| Consulta de operação com aposta ou prêmio zero | Zero aceito como valor; leitura sem movimentação |
| Assinatura inválida, resposta alterada ou identidade divergente | Recusa da prova; nenhuma confirmação inventada |
| Operação em processamento ou rejeitada | Estado verdadeiro preservado; nenhuma liquidação automática |
| ID não encontrado | Ausência autoritativa somente após busca completa; na dúvida, erro/indisponibilidade |
| Consulta de qualquer estado | Nenhum débito, crédito, aposta ou alteração de histórico |
A coleção Postman inclui um modelo de consulta e uma resposta applied. Os cabeçalhos de assinatura devem ser gerados pelo backend autorizado para os bytes e a URL exatos; o modelo não contém chave privada, não assina automaticamente e permanece protegido contra envio acidental. Não habilite reenvio de operações antigas nem use contas reais para esses testes.