Ambiente de teste

O ambiente de teste existe para você errar sem custo. Uma chave cnh_test_ responde com motoristas fictícios, nunca toca no seu saldo e percorre o mesmo contrato assíncrono da produção: 202 → transições de status → payload serializado → webhook assinado.

Onde está a sua chave de testeCopiar o link da seção

Toda organização já tem uma chave cnh_test_, sem pedido nem espera. Ela fica em Configurações → API, na secção Ambiente de teste: clique em Mostrar chave para vê-la inteira ou copie-a direto. Ao contrário da chave de produção, ela continua visível ali sempre que você voltar, e não expira.

Se a chave vazar, use Gerar nova chave: a anterior para de funcionar na hora. Qualquer membro da organização vê a chave; gerar uma nova, configurar o webhook e reenviar entregas cabe aos proprietários e administradores.

Os dez motoristasCopiar o link da seção

Cada CPF abaixo corresponde a um caminho que o seu código precisa tratar. Todos são fictícios, com dígitos verificadores válidos, e não pertencem a ninguém.

O que cada um ensinaCopiar o link da seção

• VALID / WARNING / EXPIRED são os três estados de validade. WARNING também aparece por outros motivos além do vencimento, então trate-o como "atenção", não como "vence logo".
• Os dois BLOCKED chegam por caminhos diferentes. Um vem da pontuação: duas infrações gravíssimas em 12 meses derrubam o limite de 40 para 20 pontos, e o excesso abriu um processo de suspensão. O outro vem de um bloqueio ativo, com a validade da habilitação em dia. Se o seu código só olha para status, os dois são iguais; se ele explica o motivo ao usuário, não são.
• O motorista com EAR usa outra aritmética. Quem exerce atividade remunerada tem sempre 40 pontos de limite, independentemente de gravíssimas. Este motorista acumula os mesmos 23 pontos do caso bloqueado e continua regular — é o teste de que o seu cálculo não é uma constante.
• NO_LICENSE é uma resposta definitiva, não um erro. O CPF existe e não tem CNH. O relatório é entregue normalmente, com status: DELIVERED.
• O relatório que falha termina em FAILED e dispara o webhook de erro. É a única forma de exercitar esse caminho sem esperar por uma falha real.
• A entrega lenta leva cerca de três minutos. Se o sandbox respondesse sempre na hora, você escreveria um código que quebra em produção. PROCESSING é estado normal, nunca erro.
• A cópia do caso feliz existe para reenvios: dois POST com o mesmo externalRef devem devolver o mesmo reportId, sem criar um segundo relatório.

Todos os motoristas entregues trazem o campo aiAnalysis preenchido, com um texto fixo por cenário — o formato é idêntico ao da produção.

CPFs mágicosCopiar o link da seção

Estes CPFs nunca geram relatório. Cada um devolve sempre o mesmo erro, para você exercitar o tratamento de falhas de propósito — é o mesmo truque dos cartões de teste.

O formato do envelope de erro e o catálogo completo de códigos estão em Erros.

Como reconhecer um relatório de testeCopiar o link da seção

• No corpo: todo relatório traz livemode. É false para os criados com cnh_test_ e true em produção — no GET /api/v1/reports/{reportId} e no webhook.
• No webhook: as entregas de teste vão para a mesma URL, com o header X-MinhaCNH-Livemode: false, e são assinadas com um secret de teste derivado do seu secret de produção. Um verificador que só conhece o de produção as rejeita. O header fica fora da assinatura: decida o ambiente pelo livemode do corpo, depois de verificar. Veja Verificar Assinatura.
• Isolamento: uma chave de teste não enxerga relatórios de produção e vice-versa (404), e o externalRef de um ambiente nunca devolve o relatório do outro.

Erros próprios do sandboxCopiar o link da seção

Os três chegam como 422 UNPROCESSABLE_CONTENT; diferencie-os por data.reason. O ambiente de teste também tem limite de uso: os mesmos limites por minuto e por dia da sua chave de produção, contados só sobre as requisições de teste, com o 429 no mesmo formato. Enquanto a produção não estiver ativada, o limite diário do ambiente de teste é de no máximo 200 relatórios.

O que o ambiente de teste não fazCopiar o link da seção

• Não cobra. Nenhuma requisição de teste entra no seu extrato ou no seu saldo.
• Não aceita outros CPFs. Qualquer CPF fora das duas tabelas acima é recusado com sandbox_cpf_not_in_corpus.
• Não cria condutores na sua conta. O relatório de teste traz o condutor fictício no payload, mas ele não aparece na sua lista de condutores nem conta como assento.
• Não chama o modelo de linguagem. O aiAnalysis é fixo por cenário, e ask_doutor_multas devolve uma resposta canônica com o mesmo formato da produção.

Para trocar de ambiente, basta trocar a chave: cnh_live_ fala com a produção, cnh_test_ fala com o sandbox. O restante do seu código não muda.