# Testar em sandbox sem gastar créditos

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

Muda para Sandbox no seletor abaixo do nome da aplicação, cria uma chave de API de teste e usa-a: tudo é simulado, nada é faturado e escolhes o resultado.

Mude para **Sandbox** no seletor abaixo do nome da aplicação, crie uma chave de API de teste e utilize-a. As verificações são simuladas, sem faturação, e pode escolher o resultado.

O sandbox da Didit é o equivalente aos cartões de teste de um fornecedor de pagamentos: permite-te reproduzir qualquer resultado de verificação a pedido, sem chamar fornecedores reais, sem lidar com dados pessoais reais e sem tocar no teu saldo.

## Um ambiente de teste separado

Sandbox é a aplicação de teste partilhada da organização. Os 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 na consola 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, por isso uma chave de sandbox nunca consegue chegar a dados em produção.*

1. **Mudar para Sandbox**

   Clique em **Sandbox** abaixo do nome da aplicação. Antes de regressar a **Live**, reveja a lista do workflow publicado, chave ou ligação live, webhook, pagamento e conservação dos dados; confirme ou permaneça em Sandbox.

2. **Criar uma chave de teste**

   Abra **Programadores → 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. **Criar ou copiar um workflow**

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

4. **Cria sessões normalmente**

   O mesmo endpoint, o mesmo caminho de código. A única diferença é qual chave envias.

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

## O que o sandbox muda, e o que não muda

| | Sandbox | Produção |
|---|---|---|
| Fornecedores externos | Todos simulados - nunca é chamado nenhum terceiro | Reais |
| Faturação | Nunca faturado; a verificação de saldo é ignorada | Faturado por funcionalidade concluída |
| Limite de criação de sessões | 500 por 24 horas, por aplicação | O teu saldo |
| Payload do webhook | `"environment": "sandbox"` | `"environment": "live"` |
| Dados extraídos e estado | Simulados pelo cenário que escolheres | Derivados da captura real |
| Media capturada | **Guardada de forma real**, exatamente como uma sessão em produção | Guardada |

> **Warning:** O sandbox guarda a media que captura - documentos, selfie, vídeo de prova de
> vida, ficheiros de comprovativo de morada - exatamente como uma sessão em
> produção faria. O *resultado* é simulado, mas o upload é real, por isso usa os
> documentos de amostra e os dados de teste que o fluxo oferece em vez de um
> documento de identidade real ou informação pessoal real.

Como os resultados nunca dependem dos pixels, uma fotografia propositadamente má não vai gerar uma recusa em sandbox. É o cenário que decide.

## Escolher o resultado

Passa o slug de um cenário como `sandbox_scenario` ao criares a sessão, ou deixa o testador escolher um: as sessões sandbox no fluxo alojado mostram um **seletor de cenário** dentro do cartão antes de a captura começar, além de uma faixa de documentos de amostra por baixo do componente de upload e um aviso permanente de "apenas dados de teste".

Os cenários cobrem os resultados de que realmente precisas para construir e testar:

| Queres testar | Cenário |
|---|---|
| Tudo aprovado | `approve` |
| Documento caducado | `decline_document_expired` |
| Documento ilegível | `decline_could_not_recognize_document` |
| Falha no checksum da MRZ | `decline_mrz_validation` |
| Abaixo da idade mínima | `decline_minimum_age` |
| Correspondência facial demasiado baixa | `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` |
| Discrepância de morada no comprovativo de morada | `decline_poa_address_mismatch` |
| Falha de integridade no chip NFC | `decline_nfc_chip_not_verified` |
| Validação em base de dados sem correspondência | `decline_database_no_match` |
| Precisa de revisão manual (AML) | `review_aml_possible_match` |
| Precisa de revisão manual (correspondência facial limítrofe) | `review_face_match_borderline` |
| Precisa de revisão manual (correspondência parcial de morada) | `review_poa_partial_match` |
| Discrepância no registo KYB | `decline_kyb_registry_mismatch` |

Os cenários `review_*` existem para poderes exercitar todo o caminho de revisão manual - a fila de revisão da consola, o webhook `In Review`, um revisor a aprovar ou a pedir reenvio - sem precisares de um input com nível de recusa.

> **Tip:** O catálogo em direto de cenários e valores mágicos é servido pela própria API
> em `GET /v1/sandbox/scenarios/`. Se algum slug aqui parecer desatualizado,
> confia no endpoint. Referência completa: [testes em sandbox](https://docs.didit.me/integration/sandbox-testing).

## Distinguir os dois no teu próprio código

Todos os webhooks trazem um campo `environment` - `"sandbox"` ou `"live"`. Faz a bifurcação com base nisso em vez de tentares inferir o ambiente a partir da chave, e nunca vais confundir uma sessão de teste com um cliente real.

## O que o sandbox não faz

- Não devolve dados reais de registo para uma empresa real. O KYB em sandbox usa respostas de registo simuladas.
- Não envia um SMS ou e-mail real. A verificação de telefone e e-mail são simuladas, por isso não podes usar o sandbox para pré-visualizar a entrega real de mensagens.
- Não consome o crédito mensal do teu plano - o que também significa que uma execução em sandbox não te diz nada sobre o crédito que te resta.

## Se precisares de verificações de teste reais

Algumas coisas exigem genuinamente uma chamada em produção - confirmar que o serviço de base de dados de um país específico está provisionado para ti, ou confirmar a entrega de SMS a uma operadora específica. Isso precisa de um pequeno carregamento numa aplicação em produção em vez de sandbox. Pergunta ao suporte antes de gastares nisso, para que possam confirmar primeiro que o serviço está mesmo ativado na tua conta.