BINGOfácil — Guia de Integração

Bingo ao vivo de 90 bolas, pronto pra rodar DENTRO da sua plataforma. Sua casa continua dona do saldo e do PIX do jogador — a gente entrega o jogo, embutido na sua tela, e conversa com a sua carteira por uma API assinada.

Como funciona em uma linha: você abre uma sessão pro seu jogador, embute a URL de jogo num iframe e implementa 4 endpoints de carteira que o jogo chama pra debitar aposta e creditar prêmio. Todo o resto (sorteio, narração, cartelas, prêmios) é por nossa conta.

1. Visão geral

Dois planos de comunicação:

Plano	Direção	O que faz
Controle	Sua plataforma → BINGOfácil	Abre sessão de jogo pro seu jogador (`POST /integ/v1/session`)
Carteira	BINGOfácil → sua plataforma	Debita aposta, credita prêmio, consulta saldo, estorna (`wallet/v1/*`)

O jogador NUNCA sai da sua plataforma: o jogo roda embutido (iframe) com a cara que você já conhece. O saldo é o SEU saldo — a gente nunca guarda dinheiro do seu jogador.

2. Autenticação (HMAC)

Toda chamada — nos dois sentidos — vai assinada com o secret do seu par de credenciais. Headers:

Header	Conteúdo
`X-Api-Key`	sua chave pública (`bfk_…`)
`X-Timestamp`	epoch em milissegundos do envio
`X-Signature`	`HMAC_SHA256(secret, timestamp + "." + corpoBrutoJSON)` em hex

Regras: janela de ±60 segundos no timestamp (relógio via NTP); corpo assinado é o JSON BRUTO (byte a byte, sem re-serializar); toda operação de dinheiro leva

idempotency_key única — repetir a mesma chave devolve o MESMO resultado sem mover dinheiro de novo.

Assinatura em Node:

import crypto from 'node:crypto';

function assinar(secret, body) {
  const ts = String(Date.now());
  const sig = crypto.createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');
  return { 'X-Api-Key': API_KEY, 'X-Timestamp': ts, 'X-Signature': sig };
}

3. Plano de controle — abrir sessão de jogo

POST /integ/v1/session *(disponível na fase de integração)*

{ "player_ref": "id-do-jogador-na-sua-base", "idempotency_key": "uuid-v4" }

Resposta: { "launch_url": "https://…?lt=…" } — embuta num iframe. O token de lançamento é de uso único e expira; abra uma sessão nova a cada entrada do jogador.

4. Plano de carteira — o que você implementa

Quatro endpoints HTTPS na SUA base (a wallet_base_url que você nos informa), todos verificando a assinatura HMAC acima:

Endpoint	Quando o jogo chama	Corpo
`POST wallet/v1/balance`	Ao abrir o jogo e antes de comprar	`{ player_ref }`
`POST wallet/v1/debit`	Compra de cartela	`{ player_ref, valor_centavos, rodada_ref, idempotency_key }`
`POST wallet/v1/credit`	Prêmio ganho	`{ player_ref, valor_centavos, rodada_ref, idempotency_key }`
`POST wallet/v1/rollback`	Estorno de um débito que não completou	`{ player_ref, idempotency_key_original, idempotency_key }`

Regras de ouro:

Valores SEMPRE em centavos inteiros. 1050 = R$ 10,50. Nunca float.
idempotency_key repetida = devolva o resultado original, sem mover de novo.
Saldo insuficiente no debit: responda { "erro": "SALDO_INSUFICIENTE" } com

status 400 — o jogo trata e avisa o jogador.

Defina um teto de crédito por rodada no seu lado (defesa em profundidade).

5. Erros e boas práticas

Código	Significado	O que fazer
400 `SALDO_INSUFICIENTE`	Jogador sem saldo pro débito	Fluxo normal — o jogo avisa
401	Assinatura/timestamp inválido ou credencial desativada	Confira secret, relógio (NTP) e status da credencial
409	`idempotency_key` reusada com payload diferente	Bug no seu lado — gere chave nova por operação
5xx	Erro transitório	Re-tente com a MESMA idempotency_key

Checklist antes de ir ao ar: HTTPS válido nos seus endpoints; assinatura verificada em TODA chamada recebida; idempotência testada com replay; teto de crédito configurado; teste ponta a ponta com valores de teste aprovado.

6. Referência

A primeira plataforma integrada roda este mesmo contrato em produção — no onboarding a gente compartilha exemplos reais de requisição e resposta de cada endpoint. Dúvidas: fale com quem te entregou as credenciais.