Habilitar.me

Condutores

A API de Condutores gerencia o cadastro de condutores vinculados às empresas da organização. Use estes registros para indicar o infrator em uma infração de trânsito.

Propriedades

  • Name
    id
    Type
    number
    Description

    ID único do condutor.

  • Name
    tax_id
    Type
    string | null
    Description

    CPF do condutor (somente dígitos).

  • Name
    name
    Type
    string | null
    Description

    Nome completo.

  • Name
    license
    Type
    string | null
    Description

    Número de registro da CNH.

  • Name
    id_number
    Type
    string | null
    Description

    Número do documento de identidade (RG).

  • Name
    id_issuer
    Type
    string | null
    Description

    Órgão emissor e UF do RG (ex.: SSP/SP).

  • Name
    phone
    Type
    string | null
    Description

    Telefone no formato internacional E.164, com + e código do país (ex.: +5511987654321).

  • Name
    class
    Type
    string | null
    Description

    Categoria da CNH: a, b, c, d, e, ab, ac, ad ou ae.

  • Name
    issue_date
    Type
    string | null
    Description

    Data de emissão da CNH (YYYY-MM-DD).

  • Name
    expiry_date
    Type
    string | null
    Description

    Data de validade da CNH (YYYY-MM-DD).

  • Name
    first_license_date
    Type
    string | null
    Description

    Data da primeira habilitação (YYYY-MM-DD).

  • Name
    birth_date
    Type
    string | null
    Description

    Data de nascimento (YYYY-MM-DD).

  • Name
    toxicological_exam_expiry_date
    Type
    string | null
    Description

    Data de expiração do exame toxicológico (YYYY-MM-DD).

  • Name
    toxicological_exam_status
    Type
    enum | null
    Description

    Status do exame toxicológico.

    ValorDescrição
    validO exame está dentro da validade.
    expiredO exame está vencido.
    unknownStatus desconhecido
  • Name
    toxicological_collection
    Type
    string | null
    Description

    Data da coleta do exame toxicológico (YYYY-MM-DD).

  • Name
    toxicological_observations
    Type
    string | null
    Description

    Observações do exame toxicológico.

  • Name
    document
    Type
    object | null
    Description

    CNH cadastrada. null quando o condutor ainda não tem arquivo.

    • Name
      id
      Type
      number
      Description

      ID do arquivo.

    • Name
      name
      Type
      string
      Description

      Nome do arquivo.

    • Name
      mime
      Type
      string
      Description

      MIME type (application/pdf, image/jpeg ou image/png).

    • Name
      status
      Type
      enum
      Description

      Status da CNH.

      ValorDescrição
      pendingAguardando o envio do arquivo. Status inicial na criação e na atualização do arquivo.
      reviewCNH em revisão.
      validCNH validada.
      invalidCNH inválida. Envie outra CNH em Atualizar Condutor.
      expiredCNH vencida. Envie outra CNH em Atualizar Condutor.
    • Name
      status_reason
      Type
      enum | null
      Description

      Justifica o status quando a CNH é invalid. É null em pending, review, valid e expired.

      ValorDescrição
      illegibleA CNH está ilegível ou o documento não pôde ser confirmado.
      incompleteFaltam campos obrigatórios extraídos da CNH.
      wrong_document_typeO arquivo não é uma CNH.
      unsupported_formatFormato ou arquivo inválido (vazio, MIME não suportado).
      data_mismatchO CPF extraído não confere com o cadastro do condutor.
      duplicate_tax_idJá existe condutor com o mesmo CPF nesta empresa.
  • Name
    companies
    Type
    object[]
    Description

    Empresas da organização vinculadas ao condutor.

    • Name
      id
      Type
      number
      Description

      ID da empresa.

    • Name
      name
      Type
      string | null
      Description

      Nome da empresa.

    • Name
      tax_id
      Type
      string | null
      Description

      CNPJ da empresa.

  • Name
    created_at
    Type
    string | null
    Description

    Data de criação em ISO 8601.

  • Name
    updated_at
    Type
    string | null
    Description

    Data da última atualização em ISO 8601.

GET/v1/drivers

Listar Condutores

Retorna uma lista paginada dos condutores da organização.

Paginação

Use apenas um dos dois métodos:

  • 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

    Itens por página (máximo 100).

  • Name
    pagination[start]
    Type
    integer
    Description

    Índice do primeiro item (começando em 0). Use junto com pagination[limit].

  • Name
    pagination[limit]
    Type
    integer
    Description

    Número máximo de itens (máximo 100).

Filtros

  • Name
    filters[tax_id][$eq]
    Type
    string
    Description

    CPF exato.

  • Name
    filters[name][$contains]
    Type
    string
    Description

    Nome contém o valor.

  • Name
    filters[company][id][$eq]
    Type
    integer
    Description

    Condutores vinculados a esta empresa.

  • Name
    filters[document_status][$eq]
    Type
    enum
    Description

    pending, review, valid, invalid ou expired.

Request

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

Response

{
  "data": [
    {
      "id": 1,
      "tax_id": "39053344705",
      "name": "João da Silva",
      "license": "01234567890",
      "id_number": "2810416",
      "id_issuer": "SSP/SP",
      "phone": "+5511987654321",
      "class": "ab",
      "issue_date": "2022-05-10",
      "expiry_date": "2032-05-10",
      "first_license_date": "2012-05-10",
      "birth_date": "1990-01-15",
      "toxicological_exam_expiry_date": "2027-09-07",
      "toxicological_exam_status": "valid",
      "toxicological_collection": "2024-09-07",
      "toxicological_observations": null,
      "document": {
        "id": 44,
        "name": "cnh.pdf",
        "mime": "application/pdf",
        "status": "valid",
        "status_reason": null
      },
      "companies": [
        {
          "id": 3,
          "name": "Empresa Exemplo LTDA",
          "tax_id": "12345678000190"
        }
      ],
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-20T14:45:00.000Z"
    }
  ],
  "pagination": { "page": 1, "size": 10, "total": 1 },
  "total": 1
}
GET/v1/drivers/{id}

Detalhar Condutor

Retorna um condutor da organização. Condutores de outras organizações respondem 404.

Request

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

Response

{
  "data": {
    "id": 1,
    "tax_id": "39053344705",
    "name": "João da Silva",
    "license": "01234567890",
    "id_number": "2810416",
    "id_issuer": "SSP/SP",
    "phone": "+5511987654321",
    "class": "ab",
    "issue_date": "2022-05-10",
    "expiry_date": "2032-05-10",
    "first_license_date": "2012-05-10",
    "birth_date": "1990-01-15",
    "toxicological_exam_expiry_date": "2027-09-07",
    "toxicological_exam_status": "valid",
    "toxicological_collection": "2024-09-07",
    "toxicological_observations": null,
    "document": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf",
      "status": "valid",
      "status_reason": null
    },
    "companies": [
      {
        "id": 3,
        "name": "Empresa Exemplo LTDA",
        "tax_id": "12345678000190"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}
POST/v1/drivers

Criar Condutor

Cria o condutor a partir da CNH.

Corpo da Requisição

  • Name
    document
    Type
    object
    Required
    obrigatório
    Description

    Metadados do arquivo da CNH para emitir a URL pré-assinada.

    • Name
      file_name
      Type
      string
      Required
      obrigatório
      Description

      Nome do arquivo (PDF, JPG ou PNG).

    • Name
      content_type
      Type
      string
      Required
      obrigatório
      Description

      application/pdf, image/jpeg ou image/png.

    • Name
      size
      Type
      integer
      Required
      obrigatório
      Description

      Tamanho em bytes (máximo 50 MB).

  • Name
    companies
    Type
    number[]
    Required
    obrigatório
    Description

    IDs das empresas para vincular.

  • Name
    phone
    Type
    string
    Description

    Telefone no formato internacional E.164, com + e código do país (ex.: +5511987654321).

Resposta

  • Name
    data.id
    Type
    number
    Description

    ID do condutor recém-criado.

  • Name
    data.phone
    Type
    string | null
    Description

    Telefone enviado na requisição, em E.164. null quando omitido.

  • Name
    data.companies
    Type
    object[]
    Description

    Empresas da organização vinculadas ao condutor.

    • Name
      id
      Type
      number
      Description

      ID da empresa.

    • Name
      name
      Type
      string | null
      Description

      Nome da empresa.

    • Name
      tax_id
      Type
      string | null
      Description

      CNPJ da empresa.

  • Name
    data.document
    Type
    object
    Description

    CNH recém-cadastrada. Status inicial pending.

    • Name
      id
      Type
      number
      Description

      ID do arquivo.

    • Name
      name
      Type
      string
      Description

      Nome do arquivo.

    • Name
      mime
      Type
      string
      Description

      MIME type (application/pdf, image/jpeg ou image/png).

    • Name
      status
      Type
      enum
      Description

      Status da CNH. No create é pending.

    • Name
      status_reason
      Type
      enum | null
      Description

      null enquanto o status não for invalid.

    • Name
      upload
      Type
      object
      Description

      URL pré-assinada para o envio da CNH.

      • Name
        url
        Type
        string
        Description

        URL pré-assinada para o PUT do arquivo. Válida pelo tempo em expires_in.

      • Name
        method
        Type
        string
        Description

        Sempre PUT.

      • Name
        headers
        Type
        object
        Description

        Cabeçalhos obrigatórios no PUT, incluindo Content-Type.

      • Name
        expires_in
        Type
        number
        Description

        Validade da URL, em segundos (15 minutos).

Request

POST
/v1/drivers
curl -X POST https://api.habilitar.me/v1/drivers \
  -H "Content-Type: application/json" \
  -H "x-api-key: {token}" \
  -d '{
    "phone": "+5511987654321",
    "companies": [3],
    "document": {
      "file_name": "cnh.pdf",
      "content_type": "application/pdf",
      "size": 245760
    }
  }'

Response 201

{
  "data": {
    "id": 1,
    "phone": "+5511987654321",
    "companies": [
      { "id": 3, "name": "Empresa Exemplo LTDA", "tax_id": "12345678000190" }
    ],
    "document": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf",
      "status": "pending",
      "status_reason": null,
      "upload": {
        "url": "https://media.example/put?X-Amz-Signature=...",
        "method": "PUT",
        "headers": { "Content-Type": "application/pdf" },
        "expires_in": 900
      }
    }
  }
}

Implementação recomendada

O arquivo da CNH não precisa transitar pelos seus servidores. O frontend envia só os metadados; o binário vai direto à URL pré-assinada.

O frontend envia os metadados da CNH ao backend, que cria o condutor na API habilitar.me, recebe a URL pré-assinada e a devolve para o frontend fazer o PUT do arquivo.FrontendBackendAPI habilitar.meStorage1. Metadados do arquivofile_name, content_type, size2. POST /v1/driverscria o condutor3. 201 · id e URLdocument.upload.url4. Devolve a URLbackend → frontend5. PUT do arquivoURL pré-assinada
Só os metadados passam pelo backend. O arquivo vai do frontend direto ao storage.
  1. O usuário seleciona o arquivo da CNH. O frontend lê file_name, content_type e size e envia esses dados ao backend.
  2. O backend repassa as informações para a API habilitar.me em Criar Condutor.
  3. A API habilitar.me retorna o id do condutor e o objeto data.document, incluindo a URL pré-assinada em data.document.upload (url, method, headers, expires_in).
  4. O backend devolve essa URL ao frontend.
  5. O frontend envia o arquivo com PUT na URL pré-assinada, usando o Content-Type de data.document.upload.headers.

A partir daí o documento é validado internamente. Um evento de webhook (driver.document.updated) informa o resultado. A validação pode levar alguns minutos.

Envie o arquivo da CNH via PUT na URL pré-assinada retornada em data.document.upload.url:

curl -X PUT "{data.document.upload.url}" \
  -H "Content-Type: application/pdf" \
  --data-binary @cnh.pdf

Sandbox

No ambiente sandbox, o título do arquivo (document.file_name sem a extensão) pode forçar o resultado da validação. O título deve ser exatamente valid, invalid ou expired — por exemplo valid.pdf, invalid.png ou expired.jpg.

  • Name
    valid
    Type
    string
    Description

    Define document.status como valid.

  • Name
    invalid
    Type
    string
    Description

    Define document.status como invalid. O status_reason é illegible.

  • Name
    expired
    Type
    string
    Description

    Define document.status como expired.

Exemplos: valid.pdf, invalid.png, expired.jpg.

PATCH/v1/drivers/{id}

Atualizar Condutor

Atualiza o documento e as informações de contato do condutor. Informe ao menos um campo.

Envie document para cadastrar ou substituir a CNH pelo mesmo fluxo do create: metadados no PATCH, binário na URL pré-assinada. Vale enviar só document. Sem document, a resposta permanece { data } do condutor, sem document.upload. Com arquivo novo, o status volta para pending.

Se a nova CNH não puder ser validada, o CPF extraído não coincidir com o cadastro, ou já existir outro condutor com o mesmo CPF nesta empresa, a extração resulta em document.status = invalid e document.status_reason descreve o motivo. A CNH anterior não é restaurada. CNH com expiry_date vencida resulta em expired.

Corpo da Requisição

  • Name
    phone
    Type
    string
    Description

    Telefone no formato internacional E.164, com + e código do país (ex.: +5511987654321).

  • Name
    document
    Type
    object
    Description

    Metadados do arquivo da CNH para emitir a URL pré-assinada. Cadastra a CNH ou substitui a existente.

    • Name
      file_name
      Type
      string
      Required
      obrigatório
      Description

      Nome do arquivo (PDF, JPG ou PNG).

    • Name
      content_type
      Type
      string
      Required
      obrigatório
      Description

      application/pdf, image/jpeg ou image/png.

    • Name
      size
      Type
      integer
      Required
      obrigatório
      Description

      Tamanho em bytes (máximo 50 MB).

Resposta

  • Name
    data.document.upload
    Type
    object
    Description

    Presente somente quando document é enviado no corpo. URL pré-assinada para o envio da CNH.

    • Name
      url
      Type
      string
      Description

      URL pré-assinada para o PUT do arquivo. Válida pelo tempo em expires_in.

    • Name
      method
      Type
      string
      Description

      Sempre PUT.

    • Name
      headers
      Type
      object
      Description

      Cabeçalhos obrigatórios no PUT, incluindo Content-Type.

    • Name
      expires_in
      Type
      number
      Description

      Validade da URL, em segundos (15 minutos).

Request

PATCH
/v1/drivers/{id}
curl -X PATCH https://api.habilitar.me/v1/drivers/1 \
  -H "Content-Type: application/json" \
  -H "x-api-key: {token}" \
  -d '{
    "phone": "+5511987654321",
    "document": {
      "file_name": "cnh.pdf",
      "content_type": "application/pdf",
      "size": 245760
    }
  }'

Response 200

{
  "data": {
    "id": 1,
    "tax_id": "39053344705",
    "name": "João da Silva",
    "license": "01234567890",
    "id_number": "2810416",
    "id_issuer": "SSP/SP",
    "phone": "+5511987654321",
    "class": "ab",
    "issue_date": "2022-05-10",
    "expiry_date": "2032-05-10",
    "first_license_date": "2012-05-10",
    "birth_date": "1990-01-15",
    "toxicological_exam_expiry_date": "2027-09-07",
    "toxicological_exam_status": "valid",
    "toxicological_collection": "2024-09-07",
    "toxicological_observations": null,
    "document": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf",
      "status": "pending",
      "status_reason": null,
      "upload": {
        "url": "https://media.example/put?X-Amz-Signature=...",
        "method": "PUT",
        "headers": { "Content-Type": "application/pdf" },
        "expires_in": 900
      }
    },
    "companies": [
      {
        "id": 3,
        "name": "Empresa Exemplo LTDA",
        "tax_id": "12345678000190"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}
GET/v1/drivers/{id}/file

Baixar Arquivo da CNH

Retorna uma URL GET pré-assinada (15 minutos) para o arquivo da CNH.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID do condutor.

Request

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

Response - 200

{
  "data": {
    "url": "https://media.example/get?X-Amz-Signature=..."
  }
}
POST/v1/drivers/{id}/companies

Vincular Empresa

Vincula o condutor a uma empresa da organização. O id na URL é o do condutor.

Retorna 409 se o vínculo já existir e 400 se a empresa não pertencer à organização.

Corpo da Requisição

  • Name
    company_id
    Type
    integer
    Required
    obrigatório
    Description

    ID da empresa da organização.

Resposta

  • Name
    data
    Type
    object
    Description

    Condutor atualizado, com a empresa incluída em companies.

Request

POST
/v1/drivers/{id}/companies
curl -X POST https://api.habilitar.me/v1/drivers/1/companies \
  -H "Content-Type: application/json" \
  -H "x-api-key: {token}" \
  -d '{ "company_id": 3 }'

Response 200

{
  "data": {
    "id": 1,
    "tax_id": "39053344705",
    "name": "João da Silva",
    "companies": [
      {
        "id": 3,
        "name": "Empresa Exemplo LTDA",
        "tax_id": "12345678000190"
      }
    ]
  }
}

Response 409

{
  "error": "Conflict",
  "message": "This driver is already linked to this company"
}
DELETE/v1/drivers/{id}/companies

Desvincular Empresa

Remove o vínculo do condutor com uma empresa. O cadastro permanece, inclusive quando este é o último vínculo. O id na URL é o do condutor.

Retorna 404 se o condutor não estiver vinculado a essa empresa, 400 se a empresa não pertencer à organização e 409 se houver indicação de infração nessa empresa.

Corpo da Requisição

  • Name
    company_id
    Type
    integer
    Required
    obrigatório
    Description

    ID da empresa da organização.

Resposta

  • Name
    data
    Type
    object
    Description

    Condutor atualizado, sem a empresa removida em companies.

Request

DELETE
/v1/drivers/{id}/companies
curl -X DELETE https://api.habilitar.me/v1/drivers/1/companies \
  -H "Content-Type: application/json" \
  -H "x-api-key: {token}" \
  -d '{ "company_id": 3 }'

Response 409

{
  "error": "Conflict",
  "message": "This driver cannot be removed because it is linked to a traffic violation indication"
}
DELETE/v1/drivers/{id}

Remover Condutor

Exclui o cadastro do condutor e o arquivo da CNH, removendo todos os vínculos com empresas.

Retorna 409 se o condutor estiver vinculado a uma indicação de infração.

Request

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

Response 200

{
  "data": null,
  "deleted": true
}

Response 409

{
  "error": "Conflict",
  "message": "This driver cannot be removed because it is linked to a traffic violation indication"
}

Eventos de Webhook

Os eventos de condutor são enviados por webhook.

EVENT

driver.created

Disparado quando um condutor é cadastrado.

O data segue o recurso de condutor. Com o upload da CNH no cadastro, document.status começa em pending.

Payload

{
  "type": "driver.created",
  "data": {
    "id": 1,
    "tax_id": null,
    "name": null,
    "license": null,
    "id_number": null,
    "id_issuer": null,
    "phone": "+5511987654321",
    "class": null,
    "issue_date": null,
    "expiry_date": null,
    "first_license_date": null,
    "birth_date": null,
    "toxicological_exam_expiry_date": null,
    "toxicological_exam_status": null,
    "toxicological_collection": null,
    "toxicological_observations": null,
    "document": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf",
      "status": "pending",
      "status_reason": null
    },
    "companies": [
      {
        "id": 3,
        "tax_id": "12345678000190",
        "external_uid": "EMP",
        "name": "Empresa Exemplo LTDA"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}
EVENT

driver.updated

Disparado quando os dados do condutor são alterados.

Payload

{
  "type": "driver.updated",
  "data": {
    "id": 1,
    "tax_id": "39053344705",
    "name": "João da Silva",
    "license": "01234567890",
    "id_number": "2810416",
    "id_issuer": "SSP/SP",
    "phone": "+5511987654321",
    "class": "ab",
    "issue_date": "2022-05-10",
    "expiry_date": "2032-05-10",
    "first_license_date": "2012-05-10",
    "birth_date": "1990-01-15",
    "toxicological_exam_expiry_date": "2027-09-07",
    "toxicological_exam_status": "valid",
    "toxicological_collection": "2024-09-07",
    "toxicological_observations": null,
    "document": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf",
      "status": "valid",
      "status_reason": null
    },
    "companies": [
      {
        "id": 3,
        "tax_id": "12345678000190",
        "external_uid": "EMP",
        "name": "Empresa Exemplo LTDA"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}
EVENT

driver.deleted

Disparado quando o condutor é removido. O payload é o estado do condutor imediatamente antes da exclusão.

Payload

{
  "type": "driver.deleted",
  "data": {
    "id": 1,
    "tax_id": "39053344705",
    "name": "João da Silva",
    "license": "01234567890",
    "id_number": "2810416",
    "id_issuer": "SSP/SP",
    "phone": "+5511987654321",
    "class": "ab",
    "issue_date": "2022-05-10",
    "expiry_date": "2032-05-10",
    "first_license_date": "2012-05-10",
    "birth_date": "1990-01-15",
    "toxicological_exam_expiry_date": "2027-09-07",
    "toxicological_exam_status": "valid",
    "toxicological_collection": "2024-09-07",
    "toxicological_observations": null,
    "document": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf",
      "status": "valid",
      "status_reason": null
    },
    "companies": [
      {
        "id": 3,
        "tax_id": "12345678000190",
        "external_uid": "EMP",
        "name": "Empresa Exemplo LTDA"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}
EVENT

driver.document.updated

Disparado quando o status da validação da CNH muda (pending → review → valid, invalid ou expired).

Payload

{
  "type": "driver.document.updated",
  "data": {
    "id": 1,
    "tax_id": "39053344705",
    "name": "João da Silva",
    "license": "01234567890",
    "id_number": "2810416",
    "id_issuer": "SSP/SP",
    "phone": "+5511987654321",
    "class": "ab",
    "issue_date": "2022-05-10",
    "expiry_date": "2032-05-10",
    "first_license_date": "2012-05-10",
    "birth_date": "1990-01-15",
    "toxicological_exam_expiry_date": "2027-09-07",
    "toxicological_exam_status": "valid",
    "toxicological_collection": "2024-09-07",
    "toxicological_observations": null,
    "document": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf",
      "status": "valid",
      "status_reason": null
    },
    "companies": [
      {
        "id": 3,
        "tax_id": "12345678000190",
        "external_uid": "EMP",
        "name": "Empresa Exemplo LTDA"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

Essa página foi útil?