O sandbox é o ambiente para você construir e validar a integração sem risco. Ele usa o mesmo endereço da produção; quem define o ambiente é a chave.
| Sandbox | Produção | |
|---|---|---|
| Chave | bk_test_… |
bk_live_… |
| Dados | marca isolada br-sandbox (nunca se mistura com a produção) |
marca real da operadora |
| Dinheiro | fictício | real |
| KYC e saques | você decide com as rotas de sandbox | decide a equipe de compliance |
| Sessão de jogo | demonstração (saldo fictício) | sessão real |
GET /api/v1/me sempre informa environment e brand.isSandbox da chave em uso — use-o para garantir que o seu servidor está apontando para o ambiente certo.
Isolamento
- Uma chave de sandbox só enxerga jogadores da marca sandbox; uma chave de produção só enxerga os da sua marca real. É garantido no banco de dados, não só na aplicação.
- Não há como misturar: dados criados em sandbox nunca aparecem na produção e vice-versa.
- Os IDs de jogador do sandbox (
PLU-…) não existem na produção.
Rotas exclusivas de sandbox
Em produção estas rotas respondem 403 SANDBOX_ONLY.
| Rota | O que simula |
|---|---|
POST /sandbox/players/{playerId}/kyc/decision |
a decisão de compliance: {"status":"aprovado"} ou {"status":"reprovado"} |
POST /sandbox/withdrawals/{withdrawalId}/decision |
a análise do saque: approve, reject ou pay |
As duas disparam os mesmos webhooks da produção (kyc.status_changed, withdrawal.status_changed), então você exercita o seu receptor de eventos de ponta a ponta.
pay só vale para saques approved e debita a carteira uma única vez; tentar pagar de novo retorna 409 INVALID_WITHDRAWAL_STATE.
O que é igual à produção
Autenticação HMAC, idempotência, validações, limites de uso, formato de erros, paginação e webhooks se comportam exatamente como na produção. Regras de negócio também: saque exige KYC aprovado, autoexclusão e limite diário bloqueiam depósitos, e assim por diante.
Boas práticas
- Configure o seu ambiente de homologação com
bk_test_…e o de produção combk_live_…em cofres de segredo separados. - Não reutilize
externalIdde teste como se fossem dados reais. - Antes de pedir as chaves de produção, percorra o checklist de homologação em sandbox.