Módulo Consulta de CNH — API v2 (Beta)

Beta

Este módulo está em beta. Disponível somente entrando em contato. A API pode sofrer alterações antes da versão final.

Visão geral

Valide a habilitação de um condutor em tempo real. Envie o CPF ou o número da CNH e receba, na mesma requisição, os dados da carteira e do condutor — sem filas nem webhooks.

Use este módulo para:

Onboarding de motoristas — confirme a CNH antes de liberar o cadastro.
Checagens de conformidade — verifique bloqueios, exames e validade.
Validação de habilitação — garanta que o condutor está apto antes de uma operação.

O módulo oferece dois modos de consulta:

Modo	Endpoint	Quando usar
Individual	`GET /v2/cnh/consult`	Uma consulta por vez, no fluxo do usuário.
Em lote	`POST /v2/cnh/consult/batch`	Vários documentos numa requisição — onboarding em massa, reconciliação de base.

Pré-requisitos

Antes de usar este módulo, certifique-se de ter:

Acesso ao módulo — a consulta de CNH precisa estar habilitada para a sua organização. Sem o acesso, a API retorna 403. Solicite no onboarding.
Credenciais HMAC — Access Token e Secret Key fornecidos no onboarding.

Autenticação

Este módulo usa a mesma autenticação HMAC-SHA256 da API v1 — sem novas credenciais. Toda requisição (individual ou em lote) exige dois headers:

Header	Valor	Descrição
`Authorization`	`Basic {ACCESS_TOKEN}`	Access Token fornecido no onboarding.
`Key`	`{HMAC_SIGNATURE}`	Assinatura HMAC-SHA256 da requisição.

Veja o cálculo da assinatura no Guia de Autenticação HMAC.

Correlation ID (opcional)

Envie o header x-correlation-id: {UUID} para rastrear a requisição nos logs. Se ausente, a API gera um automaticamente.

Início rápido

Confirme que a Consulta de CNH está habilitada para a sua organização.
Tenha em mãos suas credenciais HMAC.
Escolha o modo:
- Individual — GET /v2/cnh/consult?documentNumber=<CPF ou CNH>.
- Em lote — POST /v2/cnh/consult/batch com a lista em documentNumbers.
Trate a resposta 200 e os erros da Referência de erros, ao final da página.

Consultar uma CNH

GET /v2/cnh/consult

Uma única chamada autenticada por HMAC retorna todos os dados disponíveis para o documento informado.

Parâmetros de query

Parâmetro	Obrigatório	Tipo	Descrição
`documentNumber`	Sim	string	Documento do condutor: CPF (11 dígitos) ou o número de registro da CNH. Aceita com ou sem máscara — a API remove a pontuação e completa zeros à esquerda. A distinção entre CPF e CNH é automática.

Exemplo de requisição

curl -X GET \
  'https://api.sandbox.v2.frota162.com.br/v2/cnh/consult?documentNumber=12312312312' \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}'

Resposta (`200 OK`)

A resposta traz dois blocos: license (dados da habilitação) e driver (dados do condutor). O núcleo de cada bloco vem sempre; os campos estendidos aparecem conforme a UF e o tipo de dado disponível.

{
  "license": {
    "number": "1231231231",
    "category": "AB",
    "renach": "SC123123123",
    "registryNumber": "12345678912",
    "issuedAt": "2023-03-07T00:00:00-03:00",
    "expiresAt": "2033-03-19T03:00:00.000Z",
    "firstLicenseAt": "2008-09-13T03:00:00.000Z",
    "observation": "Apto para Transporte Remunerado",
    "photoUrl": "https://cdn.exemplo.com/cnh/foto.png",
    "toxicologicalExam": {
      "collectedAt": "2023-06-23T03:00:00.000Z",
      "detectionWindowDate": "2023-06-23T03:00:00.000Z",
      "status": "APTO",
      "expiresAt": "2023-09-21T03:00:00.000Z"
    },
    "blocks": [
      {
        "state": "PR",
        "date": "2023-11-22T03:00:00.000Z",
        "description": "54 PONTOS",
        "penaltyDays": 180,
        "penaltyStartsAt": "2023-11-22T03:00:00.000Z",
        "penaltyEndsAt": "2024-05-20T03:00:00.000Z"
      }
    ],
    "exams": [
      {
        "name": "APTIDÃO FÍSICA E MENTAL",
        "date": "2019-04-03T03:00:00.000Z",
        "result": "APTO",
        "validUntil": "03/04/2024",
        "desiredCategory": "E",
        "allowedCategory": "E",
        "city": "CURITIBA/PR",
        "state": "PR"
      }
    ],
    "courses": [
      {
        "name": "ATUALIZAÇÃO - TRANSPORTE PRODUTOS PERIGOSOS",
        "startedAt": "30/08/2022",
        "endedAt": "31/08/2022",
        "workloadHours": 20,
        "category": "B",
        "modality": "ENSINO A DISTÂNCIA",
        "expiresAt": "31/08/2027",
        "city": "RECIFE/PE",
        "state": "PE"
      }
    ]
  },
  "driver": {
    "name": "TESTE DA SILVA",
    "documentNumber": "12312312312",
    "birthDate": "1979-04-24T03:00:00.000Z",
    "motherName": "MARIA DA SILVA",
    "fatherName": "JOSE DA SILVA",
    "email": "teste@exemplo.com",
    "phone": "47999999991",
    "address": "RUA EXEMPLO 000, CENTRO - BLUMENAU/SC",
    "rg": {
      "number": "89462320",
      "state": "PR",
      "issuer": "SESP"
    }
  }
}

Bloco `license` (habilitação)

Campo	Sempre presente	Descrição
`number`	Sim	Número da CNH
`category`	Sim	Categoria (ex: `AB`)
`renach`	Sim	Número RENACH
`registryNumber`	Sim	Número de registro
`issuedAt`	Sim	Data de emissão
`expiresAt`	Sim	Data de validade
`firstLicenseAt`	Sim	Data da primeira habilitação
`observation`	Não	Observações da habilitação
`photoUrl`	Não	URL da foto (quando disponível)

Bloco `driver` (condutor)

Campo	Sempre presente	Descrição
`name`	Sim	Nome do condutor
`documentNumber`	Sim	CPF do condutor
`birthDate`	Sim	Data de nascimento
`motherName`	Sim	Nome da mãe
`fatherName`	Sim	Nome do pai
`email`	Não	E-mail
`phone`	Não	Telefone
`address`	Não	Endereço
`rg`	Não	Objeto com `number`, `state`, `issuer`

Campos estendidos de `license`

Dependendo da UF e do tipo de dado disponível, o bloco license pode incluir os campos abaixo. Quando ausentes, não são retornados.

toxicologicalExam — exame toxicológico

Campo	Descrição
`collectedAt`	Data da coleta
`detectionWindowDate`	Data-limite da janela de detecção
`status`	Situação do exame (ex: `APTO`)
`expiresAt`	Validade do exame

blocks[] — bloqueios/impedimentos (ex: suspensão do direito de dirigir)

Campo	Sempre presente	Descrição
`state`	Sim	UF
`date`	Sim	Data do bloqueio
`description`	Não	Descrição
`penaltyDays`	Não	Dias de penalidade
`penaltyStartsAt`	Não	Início da penalidade
`penaltyEndsAt`	Não	Fim da penalidade

exams[] — exames de habilitação

Campo	Sempre presente	Descrição
`name`	Sim	Nome do exame
`date`	Sim	Data
`result`	Não	Resultado
`validUntil`	Não	Validade
`desiredCategory`	Não	Categoria pretendida
`allowedCategory`	Não	Categoria permitida
`city`	Não	Cidade
`state`	Não	UF

courses[] — cursos vinculados à habilitação

Campo	Sempre presente	Descrição
`name`	Sim	Nome do curso
`startedAt`	Sim	Início
`endedAt`	Sim	Término
`workloadHours`	Não	Carga horária
`category`	Não	Categoria
`modality`	Não	Modalidade
`expiresAt`	Não	Validade
`city`	Não	Cidade
`state`	Não	UF

Pontuação não incluída

O histórico de pontuação/infrações do condutor não é retornado por este endpoint no momento.

Consultar em lote

POST /v2/cnh/consult/batch

Consulte vários documentos numa única requisição — em vez de N chamadas ao endpoint individual, envie uma lista e receba um resultado por item.

O lote usa falha parcial: se um documento não for localizado ou a consulta dele falhar, os demais continuam. A resposta é sempre 200 quando o lote é processável — sucesso ou falha é reportado item a item em results[].

Corpo da requisição

Campo	Obrigatório	Tipo	Descrição
`documentNumbers`	Sim	string[]	Lista de documentos: cada item é um CPF (11 dígitos) ou um número de registro da CNH. Aceita com ou sem máscara. Mínimo 1, máximo 50 por requisição.

{
  "documentNumbers": [
    "529.982.247-25",
    "13987734337",
    "70708347487"
  ]
}

Limite por lote

O máximo é 50 documentos por requisição (configurável pelo ambiente). Para bases maiores, divida em lotes e envie sequencialmente. Acima do limite, a API recusa o lote inteiro com 400.

Resposta (`200 OK`)

A resposta traz results[] (um por documento, na mesma ordem enviada) e summary (contagem consolidada).

{
  "results": [
    {
      "documentNumber": "52998224725",
      "status": "found",
      "data": {
        "license": { "number": "1231231231", "category": "AB" },
        "driver": { "name": "TESTE DA SILVA", "documentNumber": "52998224725" }
      },
      "error": null
    },
    {
      "documentNumber": "13987734337",
      "status": "not_found",
      "data": null,
      "error": null
    },
    {
      "documentNumber": "70708347487",
      "status": "error",
      "data": null,
      "error": {
        "code": "CNH_CONSULT_FAILED",
        "message": "Falha ao consultar o fornecedor"
      }
    }
  ],
  "summary": {
    "total": 3,
    "found": 1,
    "notFound": 1,
    "error": 1
  }
}

O objeto data de um item found tem a mesma estrutura (license + driver, com campos estendidos) do endpoint individual documentado acima. Foi resumido no exemplo por brevidade.

Campos de `results[]`

Campo	Descrição
`documentNumber`	Documento consultado, já normalizado (só dígitos).
`status`	`found` = localizado · `not_found` = não localizado (resultado válido, não é erro) · `error` = falha técnica na consulta.
`data`	Dados da CNH (`license` + `driver`) quando `status: found`; caso contrário `null`.
`error`	Objeto `{ code, message }` quando `status: error`; caso contrário `null`.

Campos de `summary`

Campo	Descrição
`total`	Total de itens no lote.
`found`	Itens localizados.
`notFound`	Itens não localizados.
`error`	Itens com falha de consulta.

Falha do lote vs. falha do item

O lote tem dois níveis de falha — não confunda:

Nível	Quando	Resultado
Lote inteiro	Formato inválido: lista vazia, acima do limite, ou qualquer item com CPF/CNH inválido.	`400` — nada é consultado.
Item	Documento válido mas não localizado, ou falha ao consultar o fornecedor.	`200` — reportado em `results[].status` (`not_found` / `error`).

Ou seja: a validação de formato é tudo-ou-nada (rejeita o lote); a consulta é resiliente por item.

Reprocessamento

not_found é um resultado definitivo — não reenvie. Já error indica falha técnica e potencialmente transitória: reprocesse apenas esses itens, com backoff.

Ambiente de testes (sandbox)

No ambiente sandbox, a consulta não acessa dados reais: um catálogo determinístico de CPFs devolve respostas fixas para você exercitar cada cenário da sua integração (inclusive erros e timeout). Mesmo CPF → mesma resposta, sempre. As datas retornadas são relativas à data da consulta (nunca vencem no catálogo).

Envie um destes CPFs em documentNumber (ou monte uma lista com eles no lote):

CPF	Cenário	Resposta
`13460936282`	CNH válida	`200` — categoria AB, sem bloqueios, toxicológico negativo, 1 exame apto, 1 curso
`34048421891`	CNH com suspensão	`200` — igual à válida + 1 bloqueio (suspensão de 180 dias vigente)
`58750246666`	CNH vencida	`200` — `expiresAt` no passado
`50662186702`	Toxicológico positivo	`200` — `toxicologicalExam.status` positivo
`13987734337`	Não localizada	`404`
`70708347487`	Erro temporário do serviço	`500`
`92028337532`	Resposta lenta	`200` após ~20s — para testar o timeout do seu cliente

Regras do catálogo:

O catálogo resolve apenas por CPF. Uma CNH (número de registro) válida cai no cenário "não localizada" (404).
Qualquer CPF válido fora da tabela também retorna 404 — mesmo comportamento de "não localizada".
CPF inválido é recusado na validação (400), sem consultar o catálogo.

Testando o lote

Monte um documentNumbers com estes CPFs para exercitar found, not_found e error num único request — ex.: 13460936282 (found), 13987734337 (not_found) e 70708347487 (error).

Somente sandbox

Estes CPFs são fictícios e válidos apenas no ambiente sandbox. Em produção, a consulta usa dados reais.

Referência de erros

Formato RFC 7807

A API v2 retorna erros no padrão RFC 7807 Problem Details. Veja o Guia de Tratamento de Erros para a referência completa.

Todos os erros retornam o seguinte formato:

{
  "type": "urn:frota162-api-v2:error:{tipo}",
  "title": "Título do erro",
  "status": 404,
  "detail": "Descrição específica do problema",
  "instance": "/v2/cnh/consult",
  "traceId": "abc123def456"
}

Erros por status

400 — Requisição inválida

Individual: documentNumber não enviado ou fora do formato de CPF/CNH.

Em lote: documentNumbers vazio, com mais de 50 itens, ou contendo um documento fora do formato. A mensagem identifica o documento com problema; o path do erro aponta o índice do item na lista.

{
  "type": "urn:frota162-api-v2:error:validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "documento inválido \"111\": informe um CPF ou CNH válido",
  "instance": "/v2/cnh/consult/batch",
  "traceId": "abc123"
}

401 — Autenticação ausente ou inválida

Header Authorization: Basic {ACCESS_TOKEN} ou Key: {HMAC_SIGNATURE} ausente, ou assinatura HMAC inválida.

{
  "type": "urn:frota162-api-v2:error:unauthorized",
  "title": "Unauthorized Access",
  "status": 401,
  "detail": "Missing required header: Authorization",
  "instance": "/v2/cnh/consult",
  "traceId": "abc123"
}

403 — Sem acesso ao módulo

A consulta de CNH não está habilitada para a sua organização. Entre em contato para solicitar acesso.

{
  "type": "urn:frota162-api-v2:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to access this resource",
  "instance": "/v2/cnh/consult",
  "traceId": "abc123"
}

404 — CNH não localizada

Nenhuma CNH localizada para o documento informado. Aplica-se apenas ao endpoint individual — no lote, este cenário vira status: not_found no item.

{
  "type": "urn:frota162-api-v2:error:driver-not-found",
  "title": "Driver Not Found",
  "status": 404,
  "detail": "The specified driver was not found in the system",
  "instance": "/v2/cnh/consult",
  "traceId": "abc123"
}

422 — Documento inválido ou não encontrado

O documento foi recusado na consulta — verifique o CPF/CNH informado. Aplica-se apenas ao endpoint individual.

{
  "type": "urn:frota162-api-v2:error:unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "O documento informado é inválido ou não foi encontrado.",
  "instance": "/v2/cnh/consult",
  "traceId": "abc123"
}

500 — Erro interno

Falha temporária ao processar a consulta. Retente com backoff; se persistir, contate o suporte informando o traceId. No lote, uma falha de consulta de um item vira status: error — o lote em si continua 200.

{
  "type": "urn:frota162-api-v2:error:internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request",
  "instance": "/v2/cnh/consult",
  "traceId": "abc123"
}

Referência rápida

Status	`type`	Aplica-se a	Causa	Ação
`400`	`validation-error`	Ambos	Documento ausente/inválido; lista vazia ou acima de 50	Revisar o parâmetro / a lista
`401`	`unauthorized` / `authentication-failed`	Ambos	Header ausente ou HMAC inválido	Revisar headers e recalcular HMAC
`403`	`forbidden`	Ambos	Organização sem acesso ao módulo	Solicitar acesso
`404`	`driver-not-found`	Individual	CNH não localizada	Verificar o documento
`422`	`unprocessable-entity`	Individual	Documento inválido/não encontrado	Verificar CPF/CNH
`429`	`rate-limit-exceeded`	Ambos	Limite de requisições atingido	Aguardar e retentar
`500`	`internal-server-error`	Ambos	Falha temporária ao processar	Retentar com backoff
`status: not_found`	—	Item do lote	Documento não localizado	Resultado definitivo — não reenviar
`status: error`	—	Item do lote	Falha ao consultar o fornecedor	Reprocessar só esse item, com backoff

Visão geral​

Pré-requisitos​

Autenticação​

Início rápido​

Consultar uma CNH​

Parâmetros de query​

Exemplo de requisição​

Resposta (200 OK)​

Bloco license (habilitação)​

Bloco driver (condutor)​

Campos estendidos de license​

Consultar em lote​

Corpo da requisição​

Resposta (200 OK)​

Campos de results[]​

Campos de summary​

Falha do lote vs. falha do item​

Ambiente de testes (sandbox)​

Referência de erros​

Erros por status​

Referência rápida​

Visão geral

Pré-requisitos

Autenticação

Início rápido

Consultar uma CNH

Parâmetros de query

Exemplo de requisição

Resposta (`200 OK`)

Bloco `license` (habilitação)

Bloco `driver` (condutor)

Campos estendidos de `license`

Consultar em lote

Corpo da requisição

Resposta (`200 OK`)

Campos de `results[]`

Campos de `summary`

Falha do lote vs. falha do item

Ambiente de testes (sandbox)

Referência de erros

Erros por status

Referência rápida