Habilitar.me

Carteira Nacional de Habilitação

A API de CNHs permite listar e obter detalhes das Carteiras Nacionais de Habilitação conectadas à sua organização. Para que as informações da CNH estejam disponíveis, é necessário que o(a) condutor(a) tenha sido autenticado(a) através do widget de login.

Propriedades

  • Name
    id
    Type
    number
    Description

    ID único da CNH.

  • Name
    license
    Type
    string
    Description

    Número de registro da CNH.

  • Name
    name
    Type
    string
    Description

    Nome completo do(a) condutor(a).

  • Name
    tax_id
    Type
    string
    Description

    CPF do(a) condutor(a) no formato XXXXXXXXXXX.

  • Name
    points
    Type
    object
    Description

    Pontuação da CNH (campos calculados/sincronizados).

    • Name
      value
      Type
      number
      Description

      Pontos acumulados na CNH (por infrações).

    • Name
      limit
      Type
      number
      Description

      Limite de pontos da CNH antes da suspensão.

    • Name
      synced_at
      Type
      string
      Description

      Data da última sincronização dos pontos no formato ISO 8601 (UTC).

  • Name
    status
    Type
    string
    Description

    Status atual da CNH. Valores possíveis:

    ValorDescrição
    activeCNH válida e ativa
    expiredCNH com validade vencida
    blockedCNH bloqueada (suspensa/cancelada)
  • Name
    class
    Type
    string
    Description

    Categoria da CNH. Valores possíveis:

    ValorDescrição
    aVeículos motorizados de duas ou três rodas, com ou sem carro lateral.
    bVeículos de quatro rodas com PBT até 3.500 kg e até 8 passageiros (excluindo o(a) condutor(a)).
    cVeículos com PBT acima de 3.500 kg (caminhões), exceto os das categorias D e E.
    dVeículos para transporte de passageiros com mais de 8 lugares (ônibus, micro-ônibus).
    eCombinação de veículos com unidade tratora B, C ou D e unidade rebocada com PBT acima de 6.000 kg (carretas/articulados).
    abCombinação das categorias A e B.
    acCombinação das categorias A e C.
    adCombinação das categorias A e D.
    aeCombinação das categorias A e E.
  • Name
    current
    Type
    boolean
    Description

    Indica se a CNH é a vigente do(a) condutor(a).

  • Name
    renach
    Type
    string
    Description

    Número RENACH da CNH.

  • Name
    commercial_driver
    Type
    boolean
    Description

    Indica se o(a) condutor(a) exerce atividade remunerada (EAR).

  • Name
    probationary_license
    Type
    boolean
    Description

    Indica se a CNH está em período probatório.

  • Name
    current_license_state
    Type
    string
    Description

    UF atual da CNH.

  • Name
    domain_license_state
    Type
    string
    Description

    UF de domínio da CNH.

  • Name
    issuer_license_state
    Type
    string
    Description

    UF emissora da CNH.

  • Name
    issue_date
    Type
    string
    Description

    Data de emissão da CNH no formato YYYY-MM-DD.

  • Name
    expiration_date
    Type
    string
    Description

    Data de validade da CNH no formato YYYY-MM-DD.

  • Name
    first_license_date
    Type
    string
    Description

    Data da primeira habilitação no formato YYYY-MM-DD.

  • Name
    files
    Type
    object
    Description

    Arquivos da CNH: a foto do(a) condutor(a) e as imagens da CNH.

    • Name
      photo
      Type
      string | boolean
      Description

      Foto do(a) condutor(a) na CNH.

      TipoDescrição
      booleanRetornado na listagem. true quando o arquivo está disponível, false caso contrário.
      stringRetornado no detalhamento. Conteúdo do arquivo como data URI Base64 (ex.: data:image/jpeg;base64,...).
    • Name
      front
      Type
      string | boolean
      Description

      Frente da CNH digital.

      TipoDescrição
      booleanRetornado na listagem. true quando o arquivo está disponível, false caso contrário.
      stringRetornado no detalhamento. Conteúdo do arquivo como data URI Base64 (ex.: data:image/jpeg;base64,...).
    • Name
      back
      Type
      string | boolean
      Description

      Verso da CNH digital.

      TipoDescrição
      booleanRetornado na listagem. true quando o arquivo está disponível, false caso contrário.
      stringRetornado no detalhamento. Conteúdo do arquivo como data URI Base64 (ex.: data:image/jpeg;base64,...).
    • Name
      qr_code
      Type
      string | boolean
      Description

      QR Code da CNH digital.

      TipoDescrição
      booleanRetornado na listagem. true quando o arquivo está disponível, false caso contrário.
      stringRetornado no detalhamento. Conteúdo do arquivo como data URI Base64 (ex.: data:image/jpeg;base64,...).
  • Name
    user
    Type
    object
    Description

    Informações do(a) condutor(a) associado à CNH.

    • Name
      id
      Type
      number
      Description

      ID do usuário.

    • Name
      external_uid
      Type
      string
      Description

      Identificador externo do usuário.

  • Name
    created_at
    Type
    string
    Description

    Data e hora em que a CNH foi registrada em nosso sistema no formato ISO 8601 (UTC).

GET/v1/drivers-licenses/

Listar CNHs

Retorna uma lista paginada das CNHs dos condutores da organização. Por padrão retorna apenas as CNHs vigentes (current = true); use filters[current][$eq]=false para listar CNHs não vigentes.

Nesta listagem, cada campo do objeto files é retornado como booleano, indicando apenas se o arquivo está disponível.

Parâmetros de Paginação

  • Name
    pagination[page]
    Type
    integer
    Description

    Número da página (começando em 1). Use junto com pagination[size].

  • Name
    pagination[size]
    Type
    integer
    Description

    Tamanho da página (número de itens por página, máximo 100). Use junto com pagination[page].

Parâmetros de Filtro

  • Name
    filters[user][id]
    Type
    object
    Description

    Filtra por identificador (id) do(a) condutor(a).

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[user][external_uid]
    Type
    object
    Description

    Filtra por identificador externo do(a) condutor(a).

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[status]
    Type
    object
    Description

    Filtra pelo status da CNH (active, expired, blocked).

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[current]
    Type
    object
    Description

    Filtra por CNHs vigentes ou não vigentes. Sobrescreve o comportamento padrão (apenas vigentes).

    Quando filters[current][$eq]=false, todos os campos de files são retornados como false. Os arquivos front, back e qr_code pertencem à CNH vigente do(a) condutor(a) e não a uma CNH específica do histórico.

    • Name
      $eq
      Type
      string
      Description

      true para apenas vigentes, false para apenas não vigentes.

  • Name
    filters[class]
    Type
    object
    Description

    Filtra pela categoria da CNH.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[tax_id]
    Type
    object
    Description

    Filtra pelo CPF do(a) condutor(a).

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

Request

GET
/v1/drivers-licenses/
curl -G https://api.habilitar.me/v1/drivers-licenses/ \
  -H "x-api-key: {token}" \
  -d "pagination[page]=1" \
  -d "pagination[size]=10"

Response

{
  "data": [
    {
      "id": 1,
      "license": "12345678901",
      "name": "JOÃO DA SILVA",
      "tax_id": "12345678900",
      "points": {
        "value": 0,
        "limit": 40,
        "synced_at": "2026-05-29T07:12:07.324Z"
      },
      "status": "active",
      "class": "b",
      "current": true,
      "renach": "1234567890",
      "commercial_driver": true,
      "probationary_license": false,
      "current_license_state": "SC",
      "domain_license_state": "SC",
      "issuer_license_state": "SP",
      "issue_date": "2024-09-24",
      "expiration_date": "2027-09-18",
      "first_license_date": "2019-11-21",
      "files": {
        "photo": true,
        "front": true,
        "back": true,
        "qr_code": true
      },
      "user": {
        "id": 1,
        "external_uid": "EXT_USER_12345"
      },
      "created_at": "2026-05-28T15:10:51.038Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10,
    "total": 1
  },
  "total": 1
}
GET/v1/drivers-licenses/{id}

Detalhar CNH

Retorna os detalhes completos de uma CNH específica.

O objeto files retorna o conteúdo completo do arquivo (data URI Base64).

Parâmetros de Rota

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da CNH que deseja consultar.

Request

GET
/v1/drivers-licenses/{id}
curl https://api.habilitar.me/v1/drivers-licenses/1 \
  -H "x-api-key: {token}"

Response - 200

{
  "data": {
    "id": 1,
    "license": "12345678901",
    "name": "JOÃO DA SILVA",
    "tax_id": "12345678900",
    "points": {
      "value": 0,
      "limit": 40,
      "synced_at": "2026-05-29T07:12:07.324Z"
    },
    "status": "active",
    "class": "b",
    "current": true,
    "renach": "1234567890",
    "commercial_driver": true,
    "probationary_license": false,
    "current_license_state": "SC",
    "domain_license_state": "SC",
    "issuer_license_state": "SP",
    "issue_date": "2024-09-24",
    "expiration_date": "2027-09-18",
    "first_license_date": "2019-11-21",
    "files": {
      "photo": "data:image/jpeg;base64,<base64-payload>",
      "front": "data:image/jpeg;base64,<base64-payload>",
      "back": "data:image/jpeg;base64,<base64-payload>",
      "qr_code": "data:image/jpeg;base64,<base64-payload>"
    },
    "user": {
      "id": 1,
      "external_uid": "EXT_USER_12345"
    },
    "created_at": "2026-05-28T15:10:51.038Z"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "Driver license with id 123 not found"
}
GET/v1/drivers-licenses/{id}/file/{file}

Obter arquivo da CNH

Retorna um arquivo específico da CNH: a foto do(a) condutor(a) ou um dos arquivos da CNH. O campo data contém o conteúdo do arquivo como uma data URI Base64 (ex.: data:image/jpeg;base64,...) ou null quando o arquivo não existe.

Parâmetros de Rota

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da CNH.

  • Name
    file
    Type
    string
    Required
    obrigatório
    Description

    Arquivo desejado. Valores possíveis:

    ValorDescrição
    photoFoto do(a) condutor(a)
    frontArquivo da frente da CNH
    backArquivo do verso da CNH
    qr-codeArquivo do QR Code da CNH

Request

GET
/v1/drivers-licenses/{id}/file/{file}
curl https://api.habilitar.me/v1/drivers-licenses/1/file/photo \
  -H "x-api-key: {token}"

Response - 200

{
  "data": "data:image/jpeg;base64,<base64-payload>"
}

Response - 404

{
  "error": "Not Found",
  "message": "Driver license with id 123 not found"
}

Eventos de Webhook

Os eventos de CNH são enviados por webhook. Como a CNH pertence a um(a) condutor(a) individual, o payload inclui o objeto user com a referência do(a) condutor(a). O objeto files (foto do(a) condutor(a) + imagens/arquivos da CNH) é incluído no payload; campos sem arquivo disponível são retornados como null.

  • Name
    drivers-license.created
    Description

    Uma nova CNH foi registrada.

  • Name
    drivers-license.updated
    Description

    Uma CNH foi atualizada (incluindo atualizações de pontuação ou dos arquivos da CNH).

Exemplo de payload

{
  "type": "drivers-license.created",
  "data": {
    "id": 1,
    "license": "12345678901",
    "name": "JOÃO DA SILVA",
    "tax_id": "12345678900",
    "points": {
      "value": 0,
      "limit": 40,
      "synced_at": "2026-05-29T07:12:07.324Z"
    },
    "status": "active",
    "class": "b",
    "current": true,
    "renach": "1234567890",
    "commercial_driver": true,
    "probationary_license": false,
    "current_license_state": "SC",
    "domain_license_state": "SC",
    "issuer_license_state": "SP",
    "issue_date": "2024-09-24",
    "expiration_date": "2027-09-18",
    "first_license_date": "2019-11-21",
    "files": {
      "photo": "data:image/jpeg;base64,<base64-payload>",
      "front": "data:image/jpeg;base64,<base64-payload>",
      "back": "data:image/jpeg;base64,<base64-payload>",
      "qr_code": "data:image/jpeg;base64,<base64-payload>"
    },
    "user": {
      "id": 1,
      "external_uid": "EXT_USER_12345"
    },
    "created_at": "2026-05-28T15:10:51.038Z",
    "updated_at": "2026-05-29T07:12:07.324Z"
  }
}

Essa página foi útil?