Veículos - Monitoramento

A API de Monitoramento de Veículos controla, por veículo, se o sistema pode consultar, atualizar e vincular infrações.

Quando um veículo é criado/importado, abre-se uma janela de decisão de 5 dias. Durante essa janela o usuário pode definir se o veículo será monitorado. Após o pagamento via Pix, o veículo fica monitorado por 30 dias. Se a janela expirar sem definição, o veículo passa a expired e é tratado como não monitorado.

Apenas veículos com status EM CIRCULACAO e dentro da janela de decisão são elegíveis.

Escopo: empresa ou grupo de empresas

Todos os endpoints abaixo existem em dois escopos, com payloads e respostas idênticos:

Empresa: /v1/companies/{id}/vehicle-monitoring/...
Grupo de empresas: /v1/company-groups/{id}/vehicle-monitoring/...

No escopo de grupo, as listas (/, /eligible) agregam os veículos de todas as empresas do grupo, e a seleção (/select) gera uma única cobrança (console-charge) associada ao grupo (company_group), cobrindo veículos de várias empresas. O monitoramento permanece desabilitado no escopo de organização.

Regras de negócio

A janela de decisão dura 5 dias a partir da criação/importação do veículo.
Somente veículos EM CIRCULACAO podem ser monitorados; os demais aparecem como ineligible.
Veículos não monitorados não têm dados atualizados nem infrações consultadas/atualizadas/vinculadas.
O monitoramento ativo dura 30 dias a partir da confirmação do pagamento.
Veículos inelegíveis nunca são enviados para cobrança.

Propriedades

Status de monitoramento

Name

monitoring_status

Type

string

Description

Estado do veículo no monitoramento. Valores possíveis:

Valor	Descrição
`pending`	Dentro da janela de 5 dias, sem definição.
`awaiting_payment`	Selecionado; aguardando pagamento da cobrança Pix.
`monitored`	Monitorado e ativo (janela de 30 dias).
`unmonitored`	Definido como não monitorado.
`expired`	Janela de decisão expirou sem definição.
`ineligible`	Veículo não está EM CIRCULACAO.

Name
decision_window_expires_at
Type
string | null
Description
Data/hora (ISO 8601) em que a janela de decisão expira.
Name
monitoring_started_at
Type
string | null
Description
Data/hora (ISO 8601) de início do monitoramento de 30 dias.
Name
monitoring_expires_at
Type
string | null
Description
Data/hora (ISO 8601) de fim do monitoramento de 30 dias.
Name
billing_status
Type
string
Description
Estado da cobrança: none, pending, paid, expired, failed.

Cobrança (console-charge)

Name
id
Type
number
Description
ID da cobrança.
Name
status
Type
string
Description
pending, paid, expired, canceled ou failed.
Name
amount_cents
Type
number
Description
Valor total em centavos.
Name
currency
Type
string
Description
Moeda (padrão BRL).
Name
pix
Type
string | null
Description
Código Pix copia e cola (EMV).
Name
pix_qr_code
Type
string | null
Description
QR Code do Pix (quando disponível).
Name
pix_expires_at
Type
string | null
Description
Expiração do Pix (ISO 8601).
Name
paid_at
Type
string | null
Description
Data/hora do pagamento confirmado.

GET/v1/companies/{id}/vehicle-monitoring

Listar veículos com status de monitoramento

Retorna todos os veículos da empresa com o respectivo status de monitoramento.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da empresa.

Request

GET

/v1/companies/{id}/vehicle-monitoring

curl -G https://api.habilitar.me/v1/companies/123/vehicle-monitoring \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": [
    {
      "id": 100,
      "vehicle": { "id": 555, "license_plate": "ABC1D23", "model": "VW Gol", "status": "EM CIRCULACAO" },
      "monitoring_status": "monitored",
      "decision_window_expires_at": "2026-06-08T00:00:00.000Z",
      "monitoring_started_at": "2026-06-03T12:00:00.000Z",
      "monitoring_expires_at": "2026-07-03T12:00:00.000Z",
      "billing_status": "paid"
    }
  ],
  "total": 1
}

GET/v1/companies/{id}/vehicle-monitoring/eligible

Listar veículos elegíveis

Retorna os veículos da empresa indicando quais são elegíveis. O campo eligible_ids permite selecionar todos os elegíveis mesmo com paginação na interface.

Request

GET

/v1/companies/{id}/vehicle-monitoring/eligible

curl -G https://api.habilitar.me/v1/companies/123/vehicle-monitoring/eligible \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": [
    {
      "id": 555,
      "license_plate": "ABC1D23",
      "model": "VW Gol",
      "status": "EM CIRCULACAO",
      "eligible": true,
      "monitoring_status": "pending",
      "violations_count": 3,
      "total_amount": 845.6,
      "lost_savings": 169.12
    }
  ],
  "total": 1,
  "eligible_ids": [555]
}

POST/v1/companies/{id}/vehicle-monitoring/price

Calcular preço da seleção

Calcula o valor da seleção antes da confirmação. Veículos inelegíveis são descartados e retornados em ineligible_ids.

Corpo da Requisição

Name
vehicle_ids
Type
array
Required
obrigatório
Description
IDs dos veículos selecionados.

Request

POST

/v1/companies/{id}/vehicle-monitoring/price

curl -X POST https://api.habilitar.me/v1/companies/123/vehicle-monitoring/price \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"vehicle_ids": [555, 556, 557]}'

Response - 200

{
  "unit_amount_cents": 990,
  "total_amount_cents": 2970,
  "currency": "BRL",
  "billable_count": 3,
  "ineligible_ids": []
}

POST/v1/companies/{id}/vehicle-monitoring/select

Selecionar veículos e gerar Pix

Marca os veículos elegíveis como awaiting_payment, cria uma cobrança (console-charge) e solicita o Pix ao provedor de pagamento.

Corpo da Requisição

Name
vehicle_ids
Type
array
Required
obrigatório
Description
IDs dos veículos a monitorar. Inelegíveis são descartados.

Regras

Pelo menos um veículo elegível é obrigatório (422 caso contrário).
Veículos que não pertencem à empresa retornam 422.

Request

POST

/v1/companies/{id}/vehicle-monitoring/select

curl -X POST https://api.habilitar.me/v1/companies/123/vehicle-monitoring/select \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"vehicle_ids": [555, 556, 557]}'

Response - 201

{
  "data": {
    "charge": {
      "id": 42,
      "status": "pending",
      "amount_cents": 2970,
      "currency": "BRL",
      "pix": "00020126...5204000053039865802BR...6304ABCD",
      "pix_qr_code": null,
      "pix_expires_at": "2026-06-03T12:15:00.000Z",
      "paid_at": null
    },
    "monitored_count": 3
  }
}

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "No eligible vehicles to monitor in the selection"
}

POST/v1/companies/{id}/vehicle-monitoring/decline

Recusar monitoramento

Marca os veículos informados como unmonitored. Aplica-se apenas a veículos com status pending ou awaiting_payment.

Request

POST

/v1/companies/{id}/vehicle-monitoring/decline

curl -X POST https://api.habilitar.me/v1/companies/123/vehicle-monitoring/decline \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"vehicle_ids": [555]}'

Response - 200

{ "data": { "declined_count": 1 } }

GET/v1/companies/{id}/vehicle-monitoring/charges/{chargeId}

Consultar status da cobrança

Consulta o status atual de uma cobrança Pix. Utilize para acompanhar o pagamento (polling) até o status paid.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da empresa.
Name
chargeId
Type
number
Required
obrigatório
Description
ID da cobrança.

Request

GET

/v1/companies/{id}/vehicle-monitoring/charges/{chargeId}

curl -G https://api.habilitar.me/v1/companies/123/vehicle-monitoring/charges/42 \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "id": 42,
    "status": "paid",
    "amount_cents": 2970,
    "currency": "BRL",
    "pix": "00020126...6304ABCD",
    "pix_qr_code": null,
    "pix_expires_at": "2026-06-03T12:15:00.000Z",
    "paid_at": "2026-06-03T12:05:00.000Z"
  }
}

Autorização

Todos os endpoints exigem o cabeçalho x-api-key com a chave da organização. O acesso é restrito à organização dona da empresa — empresas de outra organização retornam 404.