Criar Relatório
Como solicitar um relatório de CNH pela API: parâmetros aceitos, resposta imediata, processamento assíncrono e o custo de cada chamada.
Endpoint
/api/v1/reportsEnfileira um diagnóstico de CNH e devolve o reportId para acompanhar.
POST /api/v1/reports
Authorization: Bearer cnh_live_<prefix>_<secret>
Content-Type: application/jsonCorpo da requisição
Prop
Type
{
"cpf": "123.456.789-09",
"externalRef": "driver-42"
}Respostas
202 Accepted — enfileirado com sucesso
{
"reportId": "clxyz...",
"status": "PROCESSING",
"driver": {
"id": "cldrv...",
"cpf": "123.456.789-09",
"name": "João Silva",
"licenseNumber": "12345678901",
"licenseCategory": "AB",
"expiryDate": "2028-05-10T00:00:00.000Z",
"issueState": "SP"
},
"statusUrl": "/api/v1/reports/clxyz...",
"webhookConfigured": true,
"estimatedDeliveryAt": "2026-06-01T12:05:00Z"
}O `driver` do ACK já vem identificado
O 202 traz os sete campos do bloco driver, não só id e cpf — é a confirmação de que o CPF
enviado resolveu para o condutor certo, antes de você esperar pelo relatório. Os campos vêm null
quando o CPF não tem CNH emitida ou quando o enriquecimento não completou.
Formato das respostas de erro
Todas as respostas de erro seguem o envelope padrão da API: code, status, message e,
quando aplicável, um objeto data com detalhes. Ver o catálogo completo de erros.
402 Payment Required — credit line excedida
O objeto data traz o saldo, o limite e o preço por relatório (na mesma unidade do creditBalance
da organização, ver Limites e Cobrança).
{
"defined": false,
"code": "PAYMENT_REQUIRED",
"status": 402,
"message": "Credit line exceeded",
"data": {
"balance": -49000,
"limit": -50000,
"pricePerReport": 1500
}
}422 Unprocessable Content — CPF inválido
{
"defined": false,
"code": "UNPROCESSABLE_CONTENT",
"status": 422,
"message": "Invalid CPF"
}429 Too Many Requests — rate limit excedido
O header Retry-After indica quantos segundos aguardar. O data.reason indica qual limite foi atingido
(perMinute ou perDay).
{
"defined": false,
"code": "TOO_MANY_REQUESTS",
"status": 429,
"message": "Too Many Requests",
"data": {
"retryAfter": 60,
"reason": "perMinute"
}
}Idempotência automática
Se enviar o mesmo cpf + externalRef dentro de 1 hora, o endpoint retorna o relatório existente
sem criar um novo nem cobrar novamente. Ver Idempotência.