API do Bingo de Rede

REST sobre HTTPS, autenticação por token do operador, valores sempre em centavos.

Integração em 3 passos
  1. Peça ao administrador um token no backoffice (API e tokens). Ele aparece uma única vez.
  2. Envie o token no header Authorization: Bearer em toda chamada.
  3. Crie o jogador, compre cartelas e abra o jogo com um launch token de uso único.

Exemplo

curl -X GET "https://seu-dominio/api/public/v1/rooms" \
  -H "Authorization: Bearer bgo_xxxx_yyyyyyyy"

Cada token tem limite por minuto; ao exceder, a resposta é 429 com retry_after.

Fonte da verdade do saldo

O saldo oficial do jogador é o nosso. A plataforma do operador deve espelhar o valor consultado em /players/:id/balance.

Todos os valores monetários são inteiros em centavos (R$ 5,00 = 500).

Jogadores

POST
/api/public/v1/players

Cria o jogador na nossa base e devolve o id usado nas outras chamadas.

Requisição

{
  "email": "jogador@exemplo.com",
  "name": "Maria Souza",
  "point_id": "uuid-do-ponto",
  "affiliate_code": "ABC123"
}

Resposta

{ "ok": true, "player_id": "uuid", "email": "jogador@exemplo.com" }
GET
/api/public/v1/players/:id

Consulta o cadastro do jogador.

Resposta

{ "ok": true, "player": { "id": "uuid", "name": "Maria Souza" } }
GET
/api/public/v1/players/:id/balance

Saldo atual em centavos — fonte da verdade.

Resposta

{ "ok": true, "balance_cents": 25000 }

Cartelas

POST
/api/public/v1/cards/buy

Compra cartelas na rodada, aplicando os pacotes bônus da região. Idempotente pela chave enviada.

Requisição

{
  "player_id": "uuid",
  "round_id": "uuid",
  "qty": 10,
  "payment": "operator_settled",
  "idempotency_key": "pedido-9931"
}

Resposta

{ "ok": true, "mode": "operator_settled", "result": { "cards_total": 12, "bonus_qty": 2 } }
GET
/api/public/v1/cards?round_id=&player_id=

Lista as cartelas de uma rodada ou de um jogador.

Resposta

{ "ok": true, "cards": [{ "id": "uuid", "serial": "R7-000123", "is_bonus": false }] }
GET
/api/public/v1/cards/serial/:serial

Consulta a cartela pelo serial e os prêmios ligados a ela.

Resposta

{ "ok": true, "card": { "serial": "R7-000123" }, "prizes": [] }

Rodadas

GET
/api/public/v1/rounds/schedule?date=2026-07-21&room_id=

Programação do dia, por sala.

Resposta

{ "ok": true, "date": "2026-07-21", "rounds": [{ "id": "uuid", "scheduled_at": "…", "card_price": 500 }] }
GET
/api/public/v1/rounds/:id/live

Estado ao vivo: bolas sorteadas, bola atual e status.

Resposta

{ "ok": true, "state": { "status": "drawing", "balls": [12, 44], "current_ball": 44 } }
GET
/api/public/v1/rounds/:id/results

Resultado final com ganhadores e valores.

Resposta

{ "ok": true, "winners": [{ "prize_type": "bingo", "amount": 150000 }] }
GET
/api/public/v1/rounds/:id/reconcile?state_hash=&ball_count=

Reconciliação do estado: status, fita/sequence, ganhadores e hashes para o cliente corrigir divergência.

Resposta

{ "ok": true, "hashes": { "state_hash": "sha256…", "tape_hash": "sha256…", "ball_count": 24 }, "verdict": { "in_sync": false, "divergences": ["tape_behind"] } }
GET
/api/public/v1/rounds/:id/fairness

Verificação provably fair: hash publicado antes, semente revelada depois.

Resposta

{ "ok": true, "seed_hash": "sha256…", "server_seed": "…", "balls": [12, 44], "verified": true }

Prêmios

GET
/api/public/v1/prizes/winners?round_id=

Ganhadores da rodada.

Resposta

{ "ok": true, "winners": [{ "card_serial": "R7-000123", "amount": 150000 }] }
GET
/api/public/v1/prizes/payouts?status=pending

Pagamentos de prêmio e seus status.

Resposta

{ "ok": true, "payouts": [{ "id": "uuid", "status": "pending", "mode": "pix_preapproved" }] }
POST
/api/public/v1/prizes/payouts/:id/confirm

Confirma a retirada no ponto validando o serial da cartela.

Requisição

{ "card_serial": "R7-000123" }

Resposta

{ "ok": true, "status": "paid" }
POST
/api/public/v1/prizes/payouts/:id/send

Dispara o PIX de um pagamento aprovado.

Resposta

{ "ok": true, "status": "sent" }

Relatórios

GET
/api/public/v1/reports/sales?from=&to=

Vendas por período.

Resposta

{ "ok": true, "rows": [{ "date": "2026-07-20", "cards": 480, "revenue_cents": 240000 }] }
GET
/api/public/v1/reports/balances?from=&to=

Entradas, saídas e saldos por período.

Resposta

{ "ok": true, "rows": [{ "type": "prize", "total_cents": -150000 }] }

Salas e regiões

GET
/api/public/v1/rooms

Salas disponíveis para montar o lobby do operador.

Resposta

{ "ok": true, "rooms": [{ "id": "uuid", "name": "Sala Ouro", "card_format": "grid_3x5" }] }
GET
/api/public/v1/regions

Regiões acessíveis ao token.

Resposta

{ "ok": true, "regions": [{ "id": "uuid", "name": "Zona Sul" }] }

Lançamento embarcado

POST
/api/public/v1/launch

Gera um launch token curto e de uso único que abre o jogo já autenticado.

Requisição

{ "player_id": "uuid", "room_id": "uuid", "ttl_seconds": 120 }

Resposta

{ "ok": true, "url": "https://seu-dominio/launch?t=…", "expires_at": "…" }

Webhooks

GET
/api/public/v1/webhooks

Webhooks cadastrados para este token.

Resposta

{ "ok": true, "webhooks": [{ "id": "uuid", "url": "https://…", "events": ["prize.won"] }] }
POST
/api/public/v1/webhooks

Cadastra um webhook. O segredo aparece só nesta resposta.

Requisição

{
  "url": "https://sua-plataforma/hooks/bingo",
  "events": ["round.started", "sales.locked", "prize.won", "round.finished", "payment.confirmed", "payout.sent"]
}

Resposta

{ "ok": true, "webhook": { "id": "uuid" }, "secret": "whsec_…" }

Carteira do cassino (seamless wallet)

  • Cabeçalhos obrigatórios: x-operator, x-game, x-dl-ts (horário em segundos) e x-dl-sig (assinatura).
  • Assinatura: HMAC-SHA256 da mensagem "<MÉTODO>\n<caminho>\n<horário>.<corpo exato>", em hexadecimal, com a chave de débito do cassino.
  • Janela de tempo: um minuto para mais ou para menos. Relógio fora de hora é recusado.
  • Se o portal assinar a resposta (x-dl-resp-ts e x-dl-resp-sig), o bingo confere e descarta resposta com assinatura errada.
  • Repetição sem cobrar duas vezes: a referência da compra é sempre bingo:<rodada>:<compra>, derivada da compra e nunca do horário. A mesma referência devolve o mesmo lançamento.
  • Toda chamada recusada por queda do portal entra em fila e é reenviada automaticamente; nada é perdido e nada é cobrado duas vezes.
POST
/api/public/dl/seamless/authenticate

Entrada do jogador. Recusa aqui = ninguém entra e nada é cobrado.

Requisição

{
  "launch_token": "<token do link de abertura>",
  "player_id": "<id do jogador no cassino>",
  "currency": "BRL",
  "game_slug": "live-bingo",
  "operator": "dl-casino",
  "integration_host": "live-bingo.i-gaming.co",
  "sent_at": "2026-09-17T20:00:00.000Z"
}

Resposta

{ "ok": true, "balance_cents": 8847177, "currency": "BRL" }
POST
/api/public/dl/seamless/balance

Saldo do jogador. É a única fonte de verdade mostrada na tela.

Requisição

{ "launch_token": "…", "player_id": "…", "currency": "BRL" }

Resposta

{ "ok": true, "balance_cents": 8847177 }
POST
/api/public/dl/seamless/bet

Débito da compra de cartelas. Só depois do débito a cartela é emitida.

Requisição

{
  "launch_token": "…",
  "player_id": "…",
  "amount_cents": 500,
  "round_id": "<rodada>",
  "reference": "bingo:<round_id>:<purchase_id>"
}

Resposta

{ "ok": true, "balance_cents": 8846677, "transaction_id": "…" }
POST
/api/public/dl/seamless/livewin

Prêmio do jogador, creditado na carteira do cassino ao fim da rodada.

Requisição

{
  "launch_token": "…",
  "player_id": "…",
  "amount_cents": 150000,
  "round_id": "<rodada>",
  "reference": "bingo:<round_id>:win"
}

Resposta

{ "ok": true, "balance_cents": 8996677 }
POST
/api/public/dl/seamless/endround

Fim da rodada sem prêmio para aquele jogador (fecha a aposta no cassino).

Requisição

{ "launch_token": "…", "player_id": "…", "round_id": "<rodada>" }

Resposta

{ "ok": true }
POST
/api/public/dl/seamless/rollback

Devolução quando a sala é cancelada, no valor exato do débito.

Requisição

{ "launch_token": "…", "player_id": "…", "reference": "bingo:<round_id>:<purchase_id>" }

Resposta

{ "ok": true, "balance_cents": 8847177 }
POST
/api/public/v1/casino/authenticate

O portal confirma no bingo a sessão de um jogador antes de abrir o jogo. Usa a chave de API do cassino no cabeçalho Authorization.

Requisição

{
  "player_id": "<uuid do jogador no bingo>",
  "launch_token": "<token do link de abertura>",
  "external_id": "<id do jogador no cassino>"
}

Resposta

{ "ok": true, "operator": "dl-casino", "currency": "BRL", "balance_cents": 8847177, "source_of_truth": "casino" }

Eventos e assinatura

Enviamos POST assinado com HMAC SHA-256 e reenviamos em caso de falha, com espera progressiva.

round.started
sales.locked
prize.won
round.finished
payment.confirmed
payout.sent

Headers de assinatura

x-bingo-timestamp: 1784500000
x-bingo-signature: sha256=HMAC_SHA256(secret, timestamp + "." + body)

Responda 2xx em até 10s. Sem 2xx, tentamos novamente algumas vezes antes de desistir.