# Testar no sandbox sem gastar créditos

Source: https://help.didit.me/pt-BR/getting-started/sandbox-and-testing
Updated: 2026-10-12

Mude para Sandbox no seletor da aplicação, crie uma chave de API de teste e use-a: as verificações são simuladas, sem cobrança, e você escolhe o resultado.

Mude para **Sandbox** no seletor abaixo do nome da aplicação, crie uma chave de API de teste e use-a. As verificações são simuladas, sem cobrança, e você escolhe o resultado.

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.

## Um ambiente de teste separado

Sandbox é a aplicação de teste compartilhada da organização. Dados, chaves, webhooks e listas ficam separados de Live. Uma faixa no topo de cada página identifica o ambiente.

![A página de chaves de API no console da Didit, onde cada chave pertence a uma aplicação](https://help.didit.me/screenshots/api-keys-light.webp)

*As chaves são por aplicação, então uma chave de sandbox nunca alcança dados de produção.*

1. **Mude para Sandbox**

   Clique em **Sandbox** abaixo do nome da aplicação. Antes de voltar a **Live**, confira a lista de workflow publicado, chave ou link live, webhook, pagamento e retenção de dados; confirme ou permaneça em Sandbox.

2. **Crie uma chave de teste**

   Abra **Desenvolvedores → Chaves de API** e escolha Sandbox ao criar a chave. A chave determina o ambiente; uma chave live não cria sessões sandbox.

3. **Crie ou copie um workflow**

   Sandbox tem seus próprios workflows. Crie o fluxo de teste ou copie de Live.

4. **Crie sessões normalmente**

   Mesmo endpoint, mesmo caminho de código. A única diferença é qual chave você envia.

> **Note:** Se **Sandbox** estiver desativado, a organização ainda não tem a aplicação de teste. Peça ao suporte para ativar; é uma configuração da conta.

## 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 |

> **Warning:** 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.

> **Tip:** 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](https://docs.didit.me/integration/sandbox-testing).

## 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 o crédito mensal do seu plano - o que também significa que uma execução em sandbox não te diz nada sobre quanto crédito 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.