Ambiente de teste
Os dez motoristas fictícios do sandbox e os CPFs mágicos que provocam 402, 429 e 422 de propósito. Nenhuma cobrança, nenhum dado real.
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.
Ainda não está no ar
Os CPFs abaixo já estão definidos, mas o ambiente de teste ainda não responde — falta a etapa
que serve os relatórios fictícios. Até lá, não os use com a sua chave cnh_live_: o CPF tem
dígitos válidos, então a chamada passa pela validação, consulta o provedor e é cobrada, mesmo
terminando em erro. Esta página existe para você já poder escrever o código; avisamos quando ela
passar a valer.
É o mesmo contrato
O payload de teste passa pelo mesmo serializador da produção. Se o seu código funciona aqui, funciona lá — e o contrário também vale.
Os dez motoristas
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.
| CPF | Cenário | Status esperado | Entrega |
|---|---|---|---|
100.000.001-08 | Habilitação regular, sem nenhuma pendência | VALID | imediata |
100.000.002-80 | Vence em menos de 30 dias | WARNING | imediata |
100.000.003-61 | Habilitação já vencida | EXPIRED | imediata |
100.000.004-42 | Pontuação acima do limite legal, com o processo de suspensão que ela gerou | BLOCKED | imediata |
100.000.005-23 | Bloqueio ativo, sem problema de pontuação | BLOCKED | imediata |
100.000.006-04 | Motorista profissional (EAR), categoria D — limite de 40 pontos | VALID | imediata |
100.000.007-95 | CPF sem CNH emitida | NO_LICENSE | imediata |
100.000.008-76 | Relatório que falha — dispara o webhook de erro | FAILED | ~30 s |
100.000.009-57 | Entrega lenta, para exercitar polling ou webhook | VALID | ~3 min |
100.000.010-90 | Cópia do caso feliz, para testar reenvio com externalRef | VALID | imediata |
O que cada um ensina
VALID/WARNING/EXPIREDsão os três estados de validade.WARNINGtambém aparece por outros motivos além do vencimento, então trate-o como "atenção", não como "vence logo".- Os dois
BLOCKEDchegam 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 parastatus, 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, comstatus: DELIVERED.- O relatório que falha termina em
FAILEDe 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
POSTcom o mesmoexternalRefdevem devolver o mesmoreportId, 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ágicos
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.
| CPF | HTTP | code | Quando usar |
|---|---|---|---|
100.000.011-71 | 402 | PAYMENT_REQUIRED | Saldo/limite de crédito estourado. Não deve ser re-tentado. |
100.000.012-52 | 429 | TOO_MANY_REQUESTS | Limite de uso excedido. Respeite o header Retry-After. |
100.000.013-33 | 422 | UNPROCESSABLE_CONTENT | Requisição rejeitada, mesmo com CPF bem formado. |
O 422 mágico tem dígitos válidos de propósito
Um CPF malformado já cai em 422, mas cai antes de chegar ao sandbox. Este aqui é bem formado
e mesmo assim é rejeitado, então o erro chega pelo mesmo caminho dos outros dois.
O formato do envelope de erro e o catálogo completo de códigos estão em Erros.
O que o ambiente de teste não faz
- 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 é desconhecido para o sandbox.
- Não chama o modelo de linguagem. O
aiAnalysisé fixo por cenário, eask_doutor_multasdevolve 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.