Conceitos
Os conceitos que a integração usa o tempo todo — relatório, diagnóstico, motorista e organização — e como eles se relacionam entre si.
Conceitos da API
| Termo | Descrição |
|---|---|
| Organização (frota) | A entidade aprovada para usar a API. As chaves, o saldo e os webhooks são por organização. |
Relatório (report) | O diagnóstico de CNH gerado para um CPF. Identificado por reportId. |
| Consulta estadual | A camada estadual do relatório: bloqueios, exames, pontos e multas do estado que emitiu a CNH. Pode não responder — nesse caso o relatório fica PROCESSING e dispara report.partially_delivered. |
| Base federal | A camada nacional do relatório. É réplica dos registros de habilitação, então a consulta estadual prevalece sobre ela quando as duas divergem. |
| API key | Credencial Bearer da organização (cnh_live_…), revelada uma única vez na criação. |
| Webhook | Notificação assinada (HMAC-SHA256) enviada quando o relatório fica pronto. |
| Linha de crédito | Limite negativo até o qual o saldo da organização pode ficar (cobrança pós-paga). |
| Idempotência | Reenviar o mesmo CPF + externalRef em uma janela curta retorna o relatório existente, sem nova cobrança. |
Conceitos de CNH
| Termo | Descrição |
|---|---|
| RENACH | Registro Nacional de Carteira de Habilitação. |
| Categoria | Tipos de veículo que o motorista está habilitado a conduzir (A, B, C, D, E). |
| Pontuação | Pontos acumulados por infrações de trânsito (Lei 14.071: soma dos últimos 12 meses). |
Status da CNH
| Status | Descrição |
|---|---|
| Regular | CNH válida e sem impedimentos. |
| Vencida | CNH com a data de validade expirada. |
| Suspensa | CNH temporariamente inválida por penalidade. |
| Cassada | CNH cancelada. |
| Bloqueada | CNH com impedimento administrativo. |
Limites e cobrança
A API aplica limites de uso por organização e cobra por relatório entregue, no modelo pós-pago. Os números exatos (req./minuto, req./dia, preço por relatório, linha de crédito) são definidos na ativação e ficam visíveis nas configurações da frota.
Detalhes técnicos
Veja Limites e cobrança para os valores
e o comportamento de 402/429.