API pública do BetBackoffice

Referência

A referência interativa requer JavaScript. Enquanto isso, baixe a especificação OpenAPI.

Primeiros passos (15 minutos, em sandbox)

Você precisa de uma credencial de sandbox (bk_test_… e o secret sk_…) — peça à equipe pelo contato. Chaves de sandbox usam uma marca isolada: nada do que você fizer aqui toca a produção.

1. 1 Configure o ambiente

   export API_BASE_URL="https://backoffice.betfoguete.bet"
   export OPERATOR_KEY="bk_test_…"
   export OPERATOR_SECRET="sk_…"

2. 2 Confirme a assinatura

   Chame GET /api/v1/me. Deve retornar environment: "sandbox". Se receber INVALID_SIGNATURE, confira o algoritmo na aba Downloads (snippets e vetores de teste) ou use a aba Testar.

3. 3 Cadastre um jogador

   POST /api/v1/players com externalId, nome, e-mail, CPF válido e data de nascimento. Guarde o id devolvido.

4. 4 Aprove o KYC (simulado)

   Registre um documento em POST /players/{id}/kyc/submissions e simule a decisão da equipe com POST /sandbox/players/{id}/kyc/decision ({"status":"aprovado"}). Em produção essa decisão é da equipe de compliance.

5. 5 Faça um depósito

   POST /players/{id}/deposits (fica pending) e depois POST /deposits/{id}/confirm. Confira o saldo em GET /players/{id}/wallet.

6. 6 Abra um jogo

   POST /players/{id}/game-sessions devolve a gameUrl (em sandbox, uma sessão de demonstração).

7. 7 Solicite e conclua um saque

   POST /players/{id}/withdrawals, depois simule a análise com POST /sandbox/withdrawals/{id}/decision (approve e pay).

8. 8 Receba os eventos

   Peça à equipe para configurar a URL HTTPS do seu webhook e valide com POST /webhooks/test. Confira a assinatura na aba Testar (verificador de webhook).

Toda operação que cria recurso ou move dinheiro exige o cabeçalho Idempotency-Key; em timeouts, repita com a mesma chave. Erros seguem o envelope { "error": { "code", "message", "requestId" } }.

Testador assinado

Somente sandbox. Informe a chave bk_test_… e o secret. Eles ficam apenas nos campos desta página (memória do navegador): nada é gravado e nada é enviado além da assinatura calculada localmente. Chaves de produção (bk_live_…) são recusadas.

Verificador de webhook

Cole o segredo do webhook (whsec_…), o timestamp, a assinatura e o corpo bruto recebidos para conferir se a sua implementação chegaria ao mesmo resultado.

Downloads e ferramentas

• OpenAPI 3.1Especificação completa (JSON), gerada do código. Importe em Insomnia, Bruno ou no gerador de clientes de sua preferência.
• Coleção PostmanTodas as operações, com assinatura HMAC automática. Defina operatorKey e operatorSecret (sandbox) e envie.
• Snippets de assinaturaNode.js, Python, PHP, Go, Java, C# e curl/openssl: assinar requisições e verificar webhooks.
• Vetores de testeEntradas e assinaturas esperadas para conferir a sua implementação.
• ChangelogHistórico de versões e mudanças da API.
• Guias no portal ↗Autenticação, idempotência, erros, webhooks, sandbox e homologação, em português.