Sandbox (ambiente de teste)
O sandbox é o ambiente de teste da Dunning. Ele existe para você integrar e validar seu fluxo sem risco de tocar um devedor real: numa régua de cobrança, o pior erro de um ambiente de teste seria disparar de verdade um e-mail, SMS ou WhatsApp — ou negativar e protestar — contra uma pessoa. No sandbox isso não acontece.
O comportamento do modo sandbox já está pronto no código, mas o ambiente sandbox como URL pública ainda depende da Kobana provisionar a infraestrutura (banco isolado, host próprio). Enquanto isso, não há URL nem credenciais de sandbox para divulgar. Esta página documenta como o sandbox se comporta; quando o ambiente estiver no ar, a URL e as chaves de teste serão anunciadas aqui. Precisa testar agora? Veja a seção Como testar enquanto o sandbox não sobe, ao final desta página, ou fale com o suporte.
A trava mestra: nada real chega ao devedor
Quando a aplicação roda com APP_ENVIRONMENT=sandbox, uma trava mestra no servidor bloqueia incondicionalmente qualquer efeito externo que atingiria o devedor. É defesa em profundidade: a trava vale mesmo que um provedor de envio seja configurado por engano — ela não depende da ausência de credenciais.
Na prática, no sandbox:
- E-mail, SMS e WhatsApp são simulados. A notificação é registrada como enviada (
status: sent), mas nenhuma mensagem sai — nenhum provedor (SendGrid, Twilio, Meta...) é acionado. O envio simulado é marcado com umexternalIdno formatosandbox:<canal>ecost: 0. - Nada é cobrado. Nenhuma chamada a gateway de produção.
- Negativação e protesto não atingem birô nem cartório. Rodam contra adapters simulados.
Ou seja: você exercita a régua de cobrança de ponta a ponta e observa o resultado, sem que uma única comunicação real chegue a alguém.
O que funciona de verdade no sandbox
O sandbox simula apenas os efeitos que atingiriam o devedor. Todo o resto funciona normalmente, para você conseguir testar a integração de verdade:
- A API v1 inteira responde de verdade — autenticação, criação e leitura de cobranças, pessoas, acordos, réguas, etc. As respostas são reais; só o disparo externo é simulado.
- Webhooks de saída continuam disparando. Este é o ponto central para o integrador: seu endpoint recebe os eventos normalmente (por exemplo
notification.sent), então você consegue testar o recebimento e o processamento dos webhooks fim a fim. Os eventos de envio simulado vêm marcados com"sandbox": trueno payload, para você distingui-los em teste. - A leitura de integrações funciona. Consultar o estado das integrações da conta responde normalmente.
Banner visível
Toda tela do dashboard e do portal do devedor, quando servida em sandbox, exibe uma faixa fixa avisando que é ambiente de teste e que nenhuma cobrança ou comunicação real é enviada. É um lembrete visual pareado com a trava mestra do servidor — impossível confundir o ambiente de teste com produção.
Resumo: simulado vs. real
| No sandbox | Comportamento |
|---|---|
| E-mail / SMS / WhatsApp ao devedor | Simulado — marcado como enviado, nada sai |
| Cobrança via gateway | Simulado — nenhuma cobrança real |
| Negativação em birô / protesto em cartório | Simulado — adapters de teste |
| API v1 (auth, cobranças, pessoas, acordos, réguas...) | Real — responde normalmente |
| Webhooks de saída | Reais — disparam de verdade (com sandbox: true) |
| Leitura de integrações | Real — funciona normalmente |
| Banner "ambiente de teste" | Sempre visível no dashboard e portal |
Como testar enquanto o sandbox não sobe
Até o ambiente sandbox público existir, dá para desenvolver com segurança em produção:
- Use uma conta sem canais de envio configurados — os envios já são simulados (os canais de envio lançam erro se não houver provedor, então nada sai).
- Prefira chaves Somente leitura onde escrita não for necessária.
- Valide mutações com
X-Idempotency-Keyantes de automatizar.
Quando o sandbox subir, você apontará sua integração para a URL de teste (a ser anunciada) e ganhará a trava mestra por padrão, sem depender de configurar a conta com cuidado.