Referência da API

Operações da API — API pública do BetBackoffice v1.1.0

API pública do BetBackoffice para operadoras que constroem o próprio front-end. Uso **servidor a servidor**: o navegador do jogador nunca chama esta API — o servidor do cliente (BFF) guarda os segredos e assina cada requisição. ## Autenticação (HMAC-SHA256) Toda rota (exceto as públicas de metadados) exige três cabeçalhos: - `X-Operator-Key`: chave da credencial do operador. - `X-Timestamp`: epoch em segundos; tolerância de ±5 minutos. - `X-Signature`: hex de `HMAC_SHA256(secret, string_canonica)`. ```text string_canonica = METODO + "\n" + CAMINHO_COM_QUERY + "\n" + TIMESTAMP + "\n" + SHA256_HEX(CORPO) ``` `CAMINHO_COM_QUERY` é o caminho **exatamente como enviado**, incluindo `/api/v1` e a query string. `CORPO` são os bytes enviados (vazio em GET). ## Idempotência Operações que criam recursos ou movimentam dinheiro exigem `Idempotency-Key` (8–128 caracteres). Repetir a mesma requisição com a mesma chave devolve a resposta original (`Idempotent-Replayed: true`); a mesma chave com corpo diferente retorna `409 IDEMPOTENCY_CONFLICT`. As chaves são lembradas por 24 horas. ## Webhooks Eventos de saída (seção `webhooks` desta especificação) são enviados por `POST` à URL configurada para o seu operador. Cada entrega traz `X-Webhook-Id` (id do evento, use para deduplicar), `X-Webhook-Timestamp` e `X-Webhook-Signature` = hex de `HMAC_SHA256(webhook_secret, TIMESTAMP + "." + CORPO_BRUTO)`. Responda com qualquer `2xx`; outras respostas são retentadas com espera exponencial por até 8 tentativas. Entregas são *at-least-once*: podem repetir. Use `POST /webhooks/test` para validar a integração. ## Convenções - Valores monetários são **strings decimais** com 2 casas (`"100.00"`); a moeda é a do jogador. - Datas em ISO 8601 UTC. - Erros: `{ "error": { "code", "message", "requestId", "details" } }`. O `code` é estável; a `message` pode mudar. - Todas as respostas trazem `X-Request-Id`. - Limite de requisições por operador (padrão 600/min); ao exceder, `429` com `Retry-After`.

• get /openapi.json — Especificação OpenAPI
• get /changelog — Changelog da API
• get /me — Identidade da credencial
• get /postman.json — Coleção Postman
• get /signing-snippets.json — Snippets de assinatura
• get /test-vectors.json — Vetores de teste da assinatura
• get /docs — Página de documentação
• get /players — Buscar jogador por externalId
• post /players — Cadastrar jogador
• get /players/{playerId} — Consultar jogador
• get /players/{playerId}/wallet — Saldo do jogador
• get /players/{playerId}/transactions — Extrato do jogador
• get /players/{playerId}/kyc — Situação do KYC
• post /players/{playerId}/kyc/submissions — Registrar envio de documento
• post /players/{playerId}/deposits — Criar depósito
• get /deposits/{depositId} — Consultar depósito
• post /deposits/{depositId}/confirm — Confirmar depósito
• post /deposits/{depositId}/fail — Marcar depósito como não concretizado
• post /players/{playerId}/withdrawals — Solicitar saque
• get /withdrawals/{withdrawalId} — Consultar saque
• post /withdrawals/{withdrawalId}/cancel — Cancelar saque
• get /games — Catálogo de jogos
• post /players/{playerId}/game-sessions — Criar sessão de jogo
• post /webhooks/test — Enviar webhook de teste
• post /sandbox/players/{playerId}/kyc/decision — Decidir o KYC (somente sandbox)
• post /sandbox/withdrawals/{withdrawalId}/decision — Decidir um saque (somente sandbox)

A referência interativa requer JavaScript. Baixar a especificação OpenAPI (JSON).