Veículos - Principal Condutor

A API de Principal Condutor lista o histórico de indicações de um veículo, cria uma nova indicação e cancela ou remove a indicação atual. A solicitação nasce em pending e o SENATRAN valida nome e categoria do condutor.

Para indicar o condutor de uma infração já registrada (indicação de real infrator), utilize as Indicações de Infração.

Propriedades

Name
id
Type
number
Description
ID único da indicação.
Name
uid
Type
string
Description
Código de autorização. Fica nulo enquanto a solicitação ainda não recebeu o código.

Name

status

Type

enum

Description

Status normalizado da indicação.

Valor	Descrição
`pending`	Pendente de processamento.
`filed`	Aguardando confirmação do condutor indicado.
`canceling`	Cancelamento ou exclusão em andamento.
`active`	Indicação autorizada e vigente.
`canceled`	Solicitação cancelada antes de vigorar.
`rejected`	Indicação recusada pelo condutor indicado.
`removed`	Indicação ativa removida.
`failed`	Falha na solicitação ou no cancelamento.
`unknown`	Status não classificado.

Name
status_reason
Type
string
Description
Motivo da exclusão quando a indicação deixa de vigorar. null quando não se aplica.
Name
status_reason_description
Type
string
Description
Descrição do motivo de exclusão. null quando não se aplica.
Name
driver
Type
object
Description
Snapshot do condutor.
- Name
  tax_id
  Type
  string
  Description
  CPF do condutor.
- Name
  name
  Type
  string
  Description
  Nome do condutor.
- Name
  license
  Type
  string
  Description
  Número de registro da CNH.
- Name
  class
  Type
  string
  Description
  Categoria da CNH.
Name
vehicle
Type
object
Description
Snapshot do veículo.
- Name
  id
  Type
  number
  Description
  ID do veículo.
- Name
  license_plate
  Type
  string
  Description
  Placa do veículo.
- Name
  renavam
  Type
  string
  Description
  Código RENAVAM.
Name
requested_at
Type
string
Description
Data e hora da solicitação em ISO 8601.
Name
expires_at
Type
string
Description
Prazo para autorização em ISO 8601.
Name
authorized_at
Type
string
Description
Data e hora da autorização em ISO 8601.
Name
activated_at
Type
string
Description
Data e hora da ativação em ISO 8601.
Name
canceled_at
Type
string
Description
Data e hora do cancelamento em ISO 8601.
Name
removed_at
Type
string
Description
Data e hora da exclusão em ISO 8601.
Name
last_synced_at
Type
string
Description
Última sincronização em ISO 8601.
Name
company
Type
object
Description
Empresa associada quando o veículo pertence a uma empresa da organização.
- Name
  id
  Type
  number
  Description
  ID da empresa.
- Name
  name
  Type
  string
  Description
  Nome da empresa.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo da empresa.
Name
user
Type
object
Description
Usuário associado quando o veículo pertence a um usuário da organização.
- Name
  id
  Type
  number
  Description
  ID do usuário.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo do usuário.

GET/v1/vehicles/{id}/drivers

Listar Principal Condutor

Lista o histórico paginado de indicações do veículo. A consulta prévia e a confirmação no SENATRAN acontecem no worker, não nesta listagem.

Indicações fora do escopo da organização retornam 404 Not Found.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID do veículo.

Paginação

Use pagination[page] com pagination[size], ou pagination[start] com pagination[limit]. Não misture os dois pares.

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. Use junto com pagination[page].
Name
pagination[start]
Type
integer
Description
Offset inicial. Use junto com pagination[limit].
Name
pagination[limit]
Type
integer
Description
Quantidade de itens a retornar, máximo 100. Use junto com pagination[start].

Filtros

Name
filters[status]
Type
object
Description
Filtra pelo status normalizado.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
Name
filters[requested_at]
Type
object
Description
Filtra pela data da solicitação. Formato ISO 8601.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
- Name
  $lt
  Type
  string
  Description
  Menor que o valor especificado.
- Name
  $lte
  Type
  string
  Description
  Menor ou igual ao valor especificado.
- Name
  $gt
  Type
  string
  Description
  Maior que o valor especificado.
- Name
  $gte
  Type
  string
  Description
  Maior ou igual ao valor especificado.
Name
filters[activated_at]
Type
object
Description
Filtra pela data de ativação. Formato ISO 8601.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
- Name
  $lt
  Type
  string
  Description
  Menor que o valor especificado.
- Name
  $lte
  Type
  string
  Description
  Menor ou igual ao valor especificado.
- Name
  $gt
  Type
  string
  Description
  Maior que o valor especificado.
- Name
  $gte
  Type
  string
  Description
  Maior ou igual ao valor especificado.

Request

GET

/v1/vehicles/{id}/drivers

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

Response - 200

{
  "data": [
    {
      "id": 11,
      "uid": "0CAVKF",
      "status": "pending",
      "driver": {
        "tax_id": "12345678901",
        "name": "João da Silva",
        "license": "12345678901",
        "class": "ab"
      },
      "vehicle": {
        "id": 9,
        "license_plate": "ABC1234",
        "renavam": "00123456789"
      },
      "requested_at": "2026-08-24T16:42:05.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10,
    "total": 1
  },
  "total": 1
}

GET/v1/vehicles/{id}/drivers/{driverId}

Detalhar Principal Condutor

Retorna o detalhe de uma indicação do histórico do veículo.

Indicações fora do escopo da organização retornam 404 Not Found.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID do veículo.
Name
driverId
Type
number
Required
obrigatório
Description
ID da indicação.

Request

GET

/v1/vehicles/{id}/drivers/{driverId}

curl https://api.habilitar.me/v1/vehicles/9/drivers/11 \
  -H "x-api-key: {token}"

Response - 200

{
  "data": {
    "id": 11,
    "uid": "0CAVKF",
    "status": "pending",
    "status_reason": null,
    "status_reason_description": null,
    "driver": {
      "tax_id": "12345678901",
      "name": "João da Silva",
      "license": "12345678901",
      "class": "ab"
    },
    "vehicle": {
      "id": 9,
      "license_plate": "ABC1234",
      "renavam": "00123456789"
    },
    "requested_at": "2026-08-24T16:42:05.000Z",
    "expires_at": null,
    "authorized_at": null,
    "activated_at": null,
    "canceled_at": null,
    "removed_at": null,
    "last_synced_at": null,
    "company": {
      "id": 3,
      "name": "Empresa 1",
      "external_uid": "EMP123"
    },
    "user": {
      "id": 1,
      "external_uid": "USR123"
    }
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "Vehicle driver with id 11 not found"
}

POST/v1/vehicles/{id}/drivers

Indicar Principal Condutor

Cria a indicação em pending e dispara o worker. A resposta é 201 Created assim que a linha local existe. A consulta prévia e o POST no SENATRAN ocorrem em seguida. No sandbox, isso só é simulado quando a chave e o veículo estão em sandbox.

Envie tax_id e license, ou o driver_id de um condutor já cadastrado em /v1/drivers. Com driver_id, a API preenche o CPF e o número da CNH a partir do condutor. O documento precisa estar com status valid e o condutor precisa pertencer à empresa do veículo. Campos enviados junto com driver_id prevalecem; o condutor só completa o que faltar.

Já existir uma indicação em pending, filed, canceling ou active retorna 409 Conflict. Veículo sem posse, placa ou RENAVAM retorna 422 Unprocessable Entity. Condutor inexistente retorna 404 Not Found. Documento fora de valid, condutor de outra empresa ou veículo sem empresa retornam 422 Unprocessable Entity.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID do veículo.

Corpo da Requisição

Envie driver_id ou os dois campos tax_id e license.

Name
driver_id
Type
number
Description
ID do condutor em /v1/drivers. Usado somente quando o documento está valid e o condutor pertence à empresa do veículo.
Name
tax_id
Type
string
Description
CPF do condutor. Obrigatório quando driver_id não é enviado.
Name
license
Type
string
Description
Número de registro da CNH. Obrigatório quando driver_id não é enviado.

Request

POST

/v1/vehicles/{id}/drivers

curl -X POST https://api.habilitar.me/v1/vehicles/9/drivers \
  -H "x-api-key: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_id": "12345678901",
    "license": "12345678901"
  }'

Response - 201

{
  "data": {
    "id": 12,
    "status": "pending",
    "driver": {
      "tax_id": "12345678901",
      "license": "12345678901"
    }
  }
}

Response - 404

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

Response - 409

{
  "error": "Conflict",
  "message": "Conflict: vehicle already has a current principal driver indication"
}

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "Unprocessable: driver document status must be valid"
}

Sandbox

A simulação vale quando a chave de API é de sandbox e o veículo também está marcado como sandbox. Nesse caso a indicação não vai ao SENATRAN. A criação responde 201 com status pending e, um minuto depois, grava o status conforme o último dígito do CPF. Se o status deixar de ser pending durante essa espera, a simulação não sobrescreve o registro.

Name
0
Type
active
Description
Indicação autorizada e vigente.
Name
1
Type
pending
Description
Pendente de processamento.
Name
2
Type
failed
Description
Falha na solicitação ou no cancelamento.
Name
3
Type
canceled
Description
Solicitação cancelada antes de vigorar.
Name
4
Type
removed
Description
Indicação ativa removida.
Name
5
Type
filed
Description
Aguardando confirmação do condutor indicado.
Name
6–9
Type
canceled
Description
Mesmo resultado do dígito 3. CPF sem dígito também termina em canceled.

O cancelamento também é simulado. A resposta é 202 com status canceling. Um minuto depois, se a indicação ainda estiver canceling, pending ou filed vira canceled e active vira removed.

DELETE/v1/vehicles/{id}/drivers/{driverId}

Cancelar ou Remover Indicação

Cancela uma indicação pending ou filed, ou remove uma indicação active. O histórico é preservado. A resposta é 202 Accepted e o status passa a canceling até o SENATRAN confirmar canceled ou removed. No sandbox, a confirmação também é simulada.

Indicações em outro status retornam 409 Conflict. O registro não é apagado.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID do veículo.
Name
driverId
Type
number
Required
obrigatório
Description
ID da indicação.

Request

DELETE

/v1/vehicles/{id}/drivers/{driverId}

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

Response - 202

{
  "data": {
    "id": 11,
    "uid": "0CAVKF",
    "status": "canceling"
  }
}

Response - 409

{
  "error": "Conflict",
  "message": "Conflict: indication cannot be canceled in the current status"
}

Name
id
Type
number
Description
ID único da indicação.
Name
status
Type
enum
Description
Status normalizado da indicação. Valores possíveis em Propriedades.
Name
driver
Type
object
Description
Snapshot do condutor.
- Name
  tax_id
  Type
  string
  Description
  CPF do condutor.
- Name
  license
  Type
  string
  Description
  Número de registro da CNH.
Name
vehicle
Type
object
Description
Snapshot do veículo.
- Name
  id
  Type
  number
  Description
  ID do veículo.
- Name
  license_plate
  Type
  string
  Description
  Placa do veículo.
- Name
  renavam
  Type
  string
  Description
  Código RENAVAM.
Name
company
Type
object
Description
Empresa associada quando o veículo pertence a uma empresa da organização. Omitido quando não houver empresa.
- Name
  id
  Type
  number
  Description
  ID da empresa.
- Name
  name
  Type
  string
  Description
  Nome da empresa.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo da empresa.
Name
user
Type
object
Description
Usuário associado quando o veículo pertence a um usuário da organização. Omitido quando não houver usuário.
- Name
  id
  Type
  number
  Description
  ID do usuário.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo do usuário.

vehicle.driver.created

{
  "type": "vehicle.driver.created",
  "data": {
    "id": 11,
    "status": "pending",
    "driver": {
      "tax_id": "12345678901",
      "license": "12345678901"
    },
    "vehicle": {
      "id": 9,
      "license_plate": "ABC1234",
      "renavam": "00123456789"
    },
    "company": {
      "id": 3,
      "name": "Empresa 1",
      "external_uid": "EMP123"
    }
  }
}

EVENT

vehicle.driver.updated

Disparado quando uma indicação de principal condutor é atualizada, inclusive mudança de status.

Propriedades

Name
id
Type
number
Description
ID único da indicação.
Name
uid
Type
string | null
Description
Código de autorização. Fica nulo enquanto a solicitação ainda não recebeu o código.
Name
status
Type
enum
Description
Status normalizado da indicação. Valores possíveis em Propriedades.
Name
status_reason
Type
string | null
Description
Motivo da exclusão quando a indicação deixa de vigorar. null quando não se aplica.
Name
status_reason_description
Type
string | null
Description
Descrição do motivo de exclusão. null quando não se aplica.
Name
driver
Type
object
Description
Snapshot do condutor.
- Name
  tax_id
  Type
  string
  Description
  CPF do condutor.
- Name
  name
  Type
  string | null
  Description
  Nome do condutor.
- Name
  license
  Type
  string
  Description
  Número de registro da CNH.
- Name
  class
  Type
  string | null
  Description
  Categoria da CNH.
Name
vehicle
Type
object
Description
Snapshot do veículo.
- Name
  id
  Type
  number
  Description
  ID do veículo.
- Name
  license_plate
  Type
  string
  Description
  Placa do veículo.
- Name
  renavam
  Type
  string
  Description
  Código RENAVAM.
Name
requested_at
Type
string
Description
Data e hora da solicitação em ISO 8601.
Name
expires_at
Type
string | null
Description
Prazo para autorização em ISO 8601.
Name
authorized_at
Type
string | null
Description
Data e hora da autorização em ISO 8601.
Name
activated_at
Type
string | null
Description
Data e hora da ativação em ISO 8601.
Name
canceled_at
Type
string | null
Description
Data e hora do cancelamento em ISO 8601.
Name
removed_at
Type
string | null
Description
Data e hora da exclusão em ISO 8601.
Name
last_synced_at
Type
string | null
Description
Última sincronização em ISO 8601.
Name
company
Type
object
Description
Empresa associada quando o veículo pertence a uma empresa da organização. Omitido quando não houver empresa.
- Name
  id
  Type
  number
  Description
  ID da empresa.
- Name
  name
  Type
  string
  Description
  Nome da empresa.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo da empresa.
Name
user
Type
object
Description
Usuário associado quando o veículo pertence a um usuário da organização. Omitido quando não houver usuário.
- Name
  id
  Type
  number
  Description
  ID do usuário.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo do usuário.

vehicle.driver.updated

{
  "type": "vehicle.driver.updated",
  "data": {
    "id": 11,
    "uid": "0CAVKF",
    "status": "pending",
    "status_reason": null,
    "status_reason_description": null,
    "driver": {
      "tax_id": "12345678901",
      "name": "João da Silva",
      "license": "12345678901",
      "class": "ab"
    },
    "vehicle": {
      "id": 9,
      "license_plate": "ABC1234",
      "renavam": "00123456789"
    },
    "requested_at": "2026-08-24T16:42:05.000Z",
    "expires_at": null,
    "authorized_at": null,
    "activated_at": null,
    "canceled_at": null,
    "removed_at": null,
    "last_synced_at": null,
    "company": {
      "id": 3,
      "name": "Empresa 1",
      "external_uid": "EMP123"
    },
    "user": {
      "id": 1,
      "external_uid": "USR123"
    }
  }
}