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,
  "settled_by_operator": true,
  "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_…" }

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.