Criar Relatório

POST /api/v1/reports — enfileira um diagnóstico de CNH. Retorna 202 Accepted com reportId e statusUrl.

Endpoint

POST /api/v1/reports
Authorization: Bearer cnh_live_<prefix>_<secret>
Content-Type: application/json

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`cpf`	`string`	Sim	CPF do motorista no formato `000.000.000-00` ou `00000000000`
`externalRef`	`string`	Não	Referência interna do cliente (máx. 255 chars); usada para idempotência

{
  "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"
  },
  "statusUrl": "/api/v1/reports/clxyz...",
  "webhookConfigured": true,
  "estimatedDeliveryAt": "2026-06-01T12:05:00Z"
}

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.