Testar no sandbox sem gastar créditos
Sandbox é um modo por aplicação em que todo provedor é simulado, nada é cobrado, e você pode forçar qualquer resultado de verificação que precisar - approved, declined ou in review.
Sandbox é um modo em uma aplicação, não um botão dentro da sua aplicação live. Crie uma segunda aplicação em modo sandbox, use a chave de API dela, e toda verificação é simulada, nada é cobrado, e você pode forçar o resultado que quiser. Se você só vê uma aplicação de produção, precisa criar a de sandbox - o modo é escolhido por aplicação.
O sandbox da Didit é o equivalente aos cartões de teste de um provedor de pagamentos: ele permite reproduzir qualquer resultado de verificação sob demanda, sem chamar provedores reais, sem lidar com dados pessoais reais e sem tocar no seu saldo.
#Sandbox é um modo em uma aplicação
Essa é a parte que mais confunde as pessoas. Live e sandbox são aplicações separadas dentro da mesma organização, então o tráfego de teste e os dados de produção nunca se misturam. Cada aplicação tem um modo, live ou sandbox.
- Uma chave pertence a uma aplicação - a chave da aplicação sandbox não consegue tocar sessões live.
- Crie uma chave separada para testes em vez de reutilizar a de produção.
- Crie uma segunda aplicação
No console, abra o seletor de aplicações no topo e crie uma nova aplicação. Escolha sandbox como o modo dela.
- Use a chave de API dessa aplicação
Pegue a chave de API em API & Webhooks enquanto a aplicação sandbox estiver selecionada. Não existe uma "chave de teste" separada em uma aplicação live - a chave é o ambiente.
- Monte um workflow nela
Aplicações sandbox têm seus próprios workflows. Recrie (ou copie) o fluxo que você quer testar.
- Crie sessões normalmente
Mesmo endpoint, mesmo caminho de código. A única diferença é qual chave você envia.
Se o seu console só mostra uma aplicação de produção e nenhuma forma de adicionar uma sandbox, peça ao suporte para habilitar a criação de aplicações sandbox para a sua organização - isso é uma configuração no nível da conta, não algo que você configurou errado.
#O que o sandbox muda, e o que não muda
| Sandbox | Live | |
|---|---|---|
| Provedores externos | Todos simulados - nenhum terceiro é chamado | Reais |
| Cobrança | Nunca cobrado; a verificação de saldo é ignorada | Cobrado por funcionalidade concluída |
| Limite de criação de sessão | 500 a cada 24 horas, por aplicação | Seu saldo |
| Payload do webhook | "environment": "sandbox" | "environment": "live" |
| Dados extraídos e status | Simulados pelo cenário que você escolher | Derivados da captura real |
| Mídia capturada | Armazenada de verdade, exatamente como em uma sessão live | Armazenada |
O sandbox armazena a mídia que captura - documentos, selfie, vídeo de prova de vida, arquivos de comprovante de endereço - exatamente como uma sessão live faria. O resultado é simulado, mas o upload é real, então use os documentos de amostra e os dados de teste que o fluxo oferece em vez de um documento de identidade real ou informações pessoais reais.
Como os resultados nunca dependem dos pixels, uma foto propositalmente ruim não vai gerar um decline no sandbox. O cenário é quem decide.
#Escolhendo o resultado
Passe um slug de cenário como sandbox_scenario ao criar a sessão, ou deixe o testador escolher: sessões de sandbox no fluxo hospedado mostram um seletor de cenário dentro do card antes da captura começar, além de uma faixa de documentos de amostra sob o componente de upload e um banner permanente de "somente dados de teste".
Os cenários cobrem os resultados que você realmente precisa para construir e testar:
| Quer testar | Cenário |
|---|---|
| Tudo aprovado | approve |
| Documento vencido | decline_document_expired |
| Documento ilegível | decline_could_not_recognize_document |
| Falha de checksum do MRZ | decline_mrz_validation |
| Abaixo da idade mínima | decline_minimum_age |
| Reconhecimento facial baixo demais | decline_face_match_low_similarity |
| Ataque de apresentação na prova de vida | decline_liveness_attack |
| Ocorrência de sanções/PEP em AML | decline_aml_hit |
| Endereço IP bloqueado | decline_ip_blocklist |
| Divergência de endereço no comprovante de endereço | decline_poa_address_mismatch |
| Chip NFC falhou na integridade | decline_nfc_chip_not_verified |
| Validação em base de dados não encontrou nada | decline_database_no_match |
| Precisa de revisão manual (AML) | review_aml_possible_match |
| Precisa de revisão manual (reconhecimento facial limítrofe) | review_face_match_borderline |
| Precisa de revisão manual (endereço parcial) | review_poa_partial_match |
| Divergência no registro do KYB | decline_kyb_registry_mismatch |
Os cenários review_* existem para você exercitar todo o caminho de revisão manual - a fila de revisão do console, o webhook In Review, um revisor aprovando ou solicitando reenvio - sem precisar de uma entrada com nível de decline.
O catálogo ao vivo de cenários e valores mágicos é servido pela própria API em
GET /v1/sandbox/scenarios/. Se algum slug aqui parecer desatualizado, confie no endpoint.
Referência completa: testes em sandbox.
#Diferenciando os dois no seu próprio código
Todo webhook carrega um campo environment - "sandbox" ou "live". Baseie sua lógica nisso em vez de tentar inferir o ambiente a partir da chave, e você nunca vai confundir uma sessão de teste com um cliente real.
#O que o sandbox não faz
- Não retorna dados de registro reais para uma empresa real. O KYB de sandbox usa respostas de registro simuladas.
- Não envia um SMS ou e-mail real. A verificação de telefone e e-mail é simulada, então você não pode usar o sandbox para pré-visualizar a entregabilidade real de mensagens.
- Não consome suas cotas mensais gratuitas - o que também significa que uma execução em sandbox não te diz nada sobre quantas verificações grátis você ainda tem.
#Se você precisa de verificações de teste reais
Algumas coisas exigem uma chamada live de fato - checar se o serviço de base de dados de um país específico está provisionado para você, ou confirmar a entrega de SMS para uma operadora específica. Isso exige uma pequena recarga em uma aplicação live em vez do sandbox. Fale com o suporte antes de gastar com isso, para que possam confirmar primeiro que o serviço realmente está habilitado na sua conta.