Checklist de integração de API de cassino: o que construir, testar e monitorar antes do go-live

Última verificação 2026-10-09

Uma integração de API de jogos de cassino quebra em lugares previsíveis: um débito reenviado e cobrado duas vezes, um rollback de uma aposta que você nunca viu, uma moeda com três casas decimais. Este checklist percorre cada camada na ordem em que o desenvolvedor encontra, com a falha que cada item evita.

Este checklist de integração de API de cassino é para o desenvolvedor que tem as chaves de API e um prazo. Ele segue a ordem em que as coisas aparecem na prática: primeiro o contrato entre a sua wallet e o provedor, depois o lobby, depois o lançamento do jogo, depois os testes e a primeira semana no ar.

Cada item existe porque algo quebra sem ele. Vá marcando num documento compartilhado e mande os itens em aberto como perguntas para o time de integração do fornecedor.

0. Antes da primeira linha de código

• Você tem a documentação completa da API, não um PDF de vendas: todos os endpoints, todos os códigos de erro, payloads de exemplo.
• Você sabe qual é o modelo de wallet. Seamless (o provedor chama o seu servidor a cada aposta e ganho) ou transfer (você move dinheiro para um saldo do lado do provedor). Este checklist parte do seamless, que é o que a maioria dos agregadores vende.
• Credenciais de staging e URL de callback de staging separadas das de produção.
• A assinatura das requisições está clara: qual header, qual algoritmo (normalmente HMAC-SHA256), quais campos são assinados e em que ordem.
• Você sabe os IPs de saída do provedor, caso ele peça para liberá-los numa allow-list.
• Você tem um contato técnico com nome e um canal que responde em horas.

1. Callbacks de wallet

O provedor vai chamar o seu servidor para quatro coisas. Construa isso antes de qualquer outra.

• Saldo (balance). Devolve o saldo disponível do jogador, na moeda do jogador.
• Débito (aposta). Desconta a aposta se houver saldo e devolve o novo saldo. Saldo insuficiente devolve o código de erro documentado, não um 500.
• Crédito (ganho). Soma o ganho. Um crédito de zero é válido e precisa dar sucesso; muitos estúdios mandam isso para fechar uma rodada perdida.
• Rollback (estorno). Reverte um débito específico anterior.
• Toda resposta é assinada ou validada do jeito que a documentação exige.
• Você verifica a assinatura de entrada em toda chamada e rejeita as inválidas com o código documentado.
• O seu endpoint responde com folga dentro do timeout do provedor. Ache o número na documentação. Se for 3 segundos, mire abaixo de 300 ms no percentil 99.
• Valores são guardados como inteiros em unidades menores ou como decimais de ponto fixo. Nunca como float.
• Débito e crédito trazem um ID de rodada e um ID de jogo. Guarde os dois.

Cenário. Um jogador numa conexão móvel lenta gira. O seu débito dá certo, mas a resposta leva 4 segundos e o provedor desiste em 3. Agora o provedor manda um rollback, ou reenvia o débito, dependendo das regras dele. As seções 2 e 3 existem para esse momento.

2. Idempotência

• Existe uma restrição de unicidade no ID de transação do provedor na sua tabela de transações.
• Um débito ou crédito repetido com o mesmo ID de transação não movimenta dinheiro de novo. Devolve a resposta original, com os mesmos valores de saldo.
• Uma chamada repetida com o mesmo ID, mas valor diferente, é rejeitada e registrada com destaque. Isso é bug do provedor ou ataque.
• Alteração de saldo e inserção da transação acontecem numa única transação de banco. Sem janela em que uma exista sem a outra.
• Chamadas simultâneas do mesmo jogador são serializadas (lock de linha ou equivalente). Dois débitos ao mesmo tempo, vindos de duas abas de jogo abertas, não podem passar os dois num saldo que só cobre um.

3. Rollbacks

• O rollback referencia o débito que cancela. Busque pelo ID de transação do provedor.
• Rollback de um débito que você nunca recebeu: registre como tombstone e devolva sucesso (ou o código documentado). Se o débito chegar depois, o tombstone impede a cobrança.
• Rollback de um débito já revertido devolve a resposta original.
• Rollback de um débito cuja rodada já tem ganho: siga a documentação à risca. Alguns provedores proíbem, outros esperam que você reverta os dois.
• Rollbacks nunca deixam um saldo num estado sem explicação. Se puderem deixá-lo negativo, defina a regra agora e documente.

4. Rodadas e jogos inacabados

• Você consegue ver quais rodadas estão abertas (débito recebido, sem crédito de fechamento).
• Você sabe como o provedor fecha rodadas paradas: crédito automático após um timeout, ferramenta manual ou chamado de suporte.
• Ganhos de bônus e de rodadas grátis vêm marcados, para a sua lógica de bônus tratá-los de forma diferente dos ganhos em dinheiro.
• O seu back office mostra o histórico completo de rodadas por jogador: cada chamada, cada resposta, timestamps.

5. Moedas

• Cada jogador tem uma moeda fixa, definida no cadastro, enviada no lançamento e repetida em todo callback.
• Você confere se a moeda do callback bate com a do jogador e rejeita divergências.
• Casas decimais corretas por moeda. A maioria das moedas fiat usa duas, algumas usam zero, outras três. Cripto pode usar oito ou mais; combine com o fornecedor a precisão usada na comunicação.
• Todo jogo que você lista suporta de fato a moeda em que você o exibe. Um estúdio pode suportar EUR e USD, mas não BDT ou ETB.
• Os limites de aposta por moeda fazem sentido. Uma aposta mínima pequena em EUR pode ficar estranha em IDR ou enorme em BTC.
• Moeda de exibição e moeda de liquidação não se misturam nos relatórios.

6. Sincronização da lista de jogos

• A lista de jogos é puxada da API de forma agendada, pelo menos uma vez por dia, e guardada localmente.
• Jogos desativados ou removidos somem do lobby na próxima sincronização, não no próximo trimestre.
• Jogos novos entram num estado de revisão, não direto no lobby, se você faz curadoria.
• Você guarda o ID estável do jogo vindo do provedor, não o nome. Nomes mudam.
• As imagens ficam em cache do seu lado ou são servidas num tamanho adequado para mobile.
• Cada jogo traz categoria, estúdio, dispositivos e moedas suportadas, para os filtros do lobby não mentirem.
• Estúdios desligados para um mercado são filtrados pelas suas próprias regras, não deixados ao acaso.

7. Launch URLs

• O lançamento com dinheiro real passa um token de sessão de vida curta, ligado ao jogador. Nunca uma senha ou um ID reutilizável.
• A expiração do token é tratada: uma aba antiga mostra uma mensagem clara, não um frame quebrado.
• Idioma, moeda, tipo de dispositivo e a URL de retorno/lobby são definidos no lançamento.
• Uma URL de depósito ou de caixa é passada quando o jogo suporta, para que “saldo insuficiente” leve a algum lugar.
• O jogo abre corretamente tanto em iframe quanto em nova janela. Alguns estúdios bloqueiam iframe em certos domínios ou navegadores.
• Lançamentos em modo demo, se existirem, nunca encostam na wallet real. Teste isso explicitamente.
• O tempo do clique ao primeiro frame é medido num celular intermediário em 4G. Acima de 5 segundos, você perde jogador.

8. Testes

• Um jogador de teste por moeda que você vai suportar.
• Uma rodada completa por tipo de jogo: slot, mesa ao vivo, crash, jogo de mesa, virtual.
• Falhas forçadas: o seu servidor devolve timeout, 500, código de saldo insuficiente. Observe o que o provedor faz em seguida.
• Chamadas duplicadas reenviadas à mão: débito duas vezes, crédito duas vezes, rollback duas vezes.
• Chamadas fora de ordem: rollback antes do débito, crédito depois do rollback.
• Duas abas, mesmo jogador, girando ao mesmo tempo.
• Sessão expirando no meio do jogo.
• Um ganho grande e um ganho zero.
• O seu relatório de conciliação bate com o do provedor no período de teste, até o centavo.

9. Go-live

• Chaves e URL de callback de produção trocadas, staging desativado para jogadores de produção.
• Monitoramento de latência dos callbacks, taxa de erro e falhas de assinatura, com alertas indo para uma pessoa, não para um dashboard que ninguém abre.
• Job diário de conciliação: os seus totais por jogo e por moeda contra os do provedor.
• Em modelos pré-pagos, um alerta de crédito baixo bem acima de zero, e alguém que consiga recarregar num domingo.
• Um botão de desligar por jogo e por estúdio no seu back office.
• O canal de suporte do fornecedor e o contato de escalonamento escritos no seu runbook.

10. Os primeiros sete dias

• Confira a conciliação toda manhã.
• Revise todos os callbacks rejeitados e as rodadas abertas.
• Acompanhe os erros de lançamento por estúdio; um estúdio ruim pode derrubar um lobby inteiro.
• Peça ao fornecedor os logs de erro do lado dele e compare.

Um time pequeno lançando uma marca cripto consegue passar por esta lista em uma semana se a documentação do fornecedor for sólida. Se a documentação for rala, a lista também serve de teste do fornecedor: conte quantos itens você precisou perguntar. O ranking de seamless wallet e a página de agregadores para novos operadores dão nota aos fornecedores exatamente nesse tipo de trabalho de integração.