Veículos - Pedágio Eletrônico

A API de Pedágios Eletrônicos lista e detalha as passagens importadas do SENATRAN para as empresas e os usuários da sua organização.

A listagem devolve o resumo da passagem. O detalhe inclui jornada, cobrança, tag, operador e a linha do tempo de eventos. Enquanto o detalhe ainda não foi sincronizado, sync_level permanece summary e os grupos extras podem vir vazios.

Propriedades

Name
id
Type
number
Description
ID único da passagem.
Name
external_uid
Type
string
Description
UUID original da passagem no SENATRAN.
Name
license_plate
Type
string
Description
Placa do veículo.
Name
passage_at
Type
string | null
Description
Data e hora da passagem em ISO 8601.
Name
location
Type
string | null
Description
Local da passagem.
Name
gantry
Type
string | null
Description
Pórtico.
Name
amount
Type
number | null
Description
Valor cobrado em reais.
Name
payment_due_at
Type
string | null
Description
Prazo de pagamento em ISO 8601.

Name

status

Type

string

Description

Status normalizado da passagem. Valores possíveis:

Valor	Descrição
`processing`	Passagem ainda em processamento.
`pending`	Aguardando pagamento.
`overdue`	Prazo de pagamento vencido.
`exempt`	Passagem isenta.
`paid`	Pagamento confirmado.
`paid_late`	Pagamento confirmado após o vencimento.
`canceled`	Passagem cancelada.
`unknown`	Status não classificado.

Name
reference_status
Type
string | null
Description
Status original retornado pelo SENATRAN.
Name
payment_url
Type
string | null
Description
URL de pagamento da concessionária.
Name
dispute_url
Type
string | null
Description
URL de contestação da concessionária.
Name
concessionaire_name
Type
string | null
Description
Nome da concessionária.
Name
concessionaire_tax_id
Type
string | null
Description
CNPJ da concessionária.
Name
sync_level
Type
string | null
Description
Nível de sincronização: summary enquanto só o resumo existe, full depois do detalhe.
Name
company
Type
object
Description
Empresa associada quando a passagem 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 | null
  Description
  Identificador externo da empresa.
Name
user
Type
object
Description
Usuário associado quando a passagem pertence a um usuário da organização.
- Name
  id
  Type
  number
  Description
  ID do usuário na organização.
- Name
  external_uid
  Type
  string | null
  Description
  Identificador externo do usuário.
Name
vehicle
Type
object
Description
Veículo associado quando a placa existe no mesmo tenant.
- Name
  id
  Type
  number
  Description
  ID do veículo.
- Name
  license_plate
  Type
  string | null
  Description
  Placa do veículo.
Name
passage
Type
object
Description
Presente apenas no detalhe. Jornada da passagem, incluindo entrada, saída e mapas quando existirem.
Name
payment
Type
object
Description
Presente apenas no detalhe. Cobrança, tag, operador e valores pagos.
Name
events
Type
array
Description
Presente apenas no detalhe. Linha do tempo com stage, description, occurred_at e status.

GET/v1/vehicles/tolls

Listar Pedágios

Retorna o resumo paginado das passagens da organização, da mais recente para a mais antiga.

A listagem inclui empresas da organização e usuários com vínculo ativo. Passagens de usuários inativos não aparecem.

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. 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[passage_at]
Type
object
Description
Filtra pela data da passagem.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor.
- Name
  $lt
  Type
  string
  Description
  Menor que o valor.
- Name
  $lte
  Type
  string
  Description
  Menor ou igual ao valor.
- Name
  $gt
  Type
  string
  Description
  Maior que o valor.
- Name
  $gte
  Type
  string
  Description
  Maior ou igual ao valor.
Name
filters[payment_due_at]
Type
object
Description
Filtra pelo vencimento, com os mesmos operadores de data.
Name
filters[status]
Type
object
Description
Filtra pelo status normalizado.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor. Ex: paid.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor.
Name
filters[license_plate]
Type
object
Description
Filtra pela placa.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor.
Name
filters[concessionaire_tax_id]
Type
object
Description
Filtra pelo CNPJ da concessionária ($eq, $ne).
Name
filters[concessionaire_name]
Type
object
Description
Filtra pelo nome da concessionária ($eq, $ne).
Name
filters[company][id]
Type
object
Description
Filtra pelo ID da empresa ($eq, $ne).
Name
filters[company][external_uid]
Type
object
Description
Filtra pelo identificador externo da empresa ($eq, $ne).
Name
filters[company][tax_id]
Type
object
Description
Filtra pelo CNPJ da empresa ($eq, $ne).
Name
filters[user][id]
Type
object
Description
Filtra pelo ID do usuário ($eq, $ne).
Name
filters[user][external_uid]
Type
object
Description
Filtra pelo identificador externo do usuário ($eq, $ne).

Request

GET

/v1/vehicles/tolls

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

Response

{
  "data": [
    {
      "id": 7,
      "external_uid": "9eb8455b-9eaa-57c3-a74e-3bb66b089152",
      "license_plate": "SEG2A82",
      "passage_at": "2026-08-18T14:30:52.000Z",
      "location": "BR 369 KM 179 Leste",
      "gantry": "EPR PARANA S/A",
      "amount": 59.85,
      "payment_due_at": "2026-09-17T23:59:59.000Z",
      "status": "paid",
      "reference_status": "PAGO",
      "payment_url": "https://pay.example",
      "dispute_url": "https://dispute.example",
      "concessionaire_name": "EPR PARANA S/A",
      "concessionaire_tax_id": "60978495000150",
      "sync_level": "full",
      "company": {
        "id": 1,
        "name": "Empresa 1",
        "external_uid": "EMP123"
      },
      "vehicle": {
        "id": 9,
        "license_plate": "SEG2A82"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10,
    "total": 1
  },
  "total": 1
}

GET/v1/vehicles/tolls/{id}

Detalhar Pedágio

Retorna os dados completos de uma passagem, incluindo jornada, cobrança e eventos.

Passagens fora do escopo da organização retornam 404 Not Found. Se o usuário vinculado estiver inativo na organização, a API responde 403 Forbidden.

Parâmetros de Rota

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

Request

GET

/v1/vehicles/tolls/{id}

curl https://api.habilitar.me/v1/vehicles/tolls/7 \
  -H "x-api-key: {token}"

Response

{
  "data": {
    "id": 7,
    "external_uid": "9eb8455b-9eaa-57c3-a74e-3bb66b089152",
    "license_plate": "SEG2A82",
    "passage_at": "2026-08-18T14:30:52.000Z",
    "location": "BR 369 KM 179 Leste",
    "gantry": "EPR PARANA S/A",
    "amount": 59.85,
    "payment_due_at": "2026-09-17T23:59:59.000Z",
    "status": "paid",
    "reference_status": "PAGO",
    "payment_url": "https://pay.example",
    "dispute_url": "https://dispute.example",
    "concessionaire_name": "EPR PARANA S/A",
    "concessionaire_tax_id": "60978495000150",
    "sync_level": "full",
    "company": {
      "id": 1,
      "name": "Empresa 1",
      "external_uid": "EMP123"
    },
    "vehicle": {
      "id": 9,
      "license_plate": "SEG2A82"
    },
    "passage": {
      "at": "2026-08-18T14:30:52.000Z",
      "location": "BR 369 KM 179 Leste",
      "gantry": "EPR PARANA S/A",
      "billing_model": "free_flow",
      "entry_at": "2026-08-18T14:00:00.000Z",
      "entry_gantry_location": "KM 170",
      "entry_gantry_map_url": "https://maps.example/in",
      "exit_at": "2026-08-18T14:30:52.000Z",
      "exit_gantry_location": "KM 179",
      "exit_gantry_map_url": "https://maps.example/out",
      "updated_at": "2026-08-18T15:00:00.000Z"
    },
    "payment": {
      "amount": 59.85,
      "due_at": "2026-09-17T23:59:59.000Z",
      "billing_type": "tag",
      "processing_confirmed_at": "2026-08-18T15:05:00.000Z",
      "tag_status": "active",
      "tag_number": "123",
      "tag_operator_name": "Sem Parar",
      "vehicle_category": "C3",
      "paid_amount": 59.85,
      "paid_at": "2026-08-19T10:00:00.000Z",
      "operator_name": "Sem Parar",
      "operator_tax_id": "123",
      "updated_at": "2026-08-19T10:00:00.000Z",
      "url": "https://pay.example",
      "dispute_url": "https://dispute.example"
    },
    "events": [
      {
        "stage": "PAGO",
        "description": "Pagamento confirmado",
        "occurred_at": "2026-08-19T10:00:00.000Z",
        "status": "paid"
      }
    ]
  }
}