Veículos (vehicles)

O recurso vehicles expõe os veículos próprios cadastrados na sua conta: placa, chassi, RENAVAM, marca e modelo, tipo, situação do IPVA, datas de renovação do licenciamento e informações de seguro.

Acesso


Módulo	`veiculos`
Escopos	`vehicles:read` (ou `:read`, ou `:write`)
Operações	somente leitura

Sem o módulo no contrato, a resposta é 403 module_not_enabled. Sem o escopo na chave, é 403 insufficient_scope.

Endpoints

Método	Endpoint	Descrição
`GET`	`/v1/vehicles`	Lista veículos, com paginação por cursor
`GET`	`/v1/vehicles/{id}`	Retorna um veículo pelo `id`

A listagem usa o envelope padrão com data, pagination e meta, e aceita limit (1 a 100, padrão 20), cursor, sort e fields. Veja Paginação, filtros e ordenação.

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do veículo
`placa`	`string \| null`	Placa do veículo, por exemplo `ABC1D23`
`chassi`	`string \| null`	Número do chassi
`renavam`	`string \| null`	Código RENAVAM
`marca`	`string \| null`	Fabricante, por exemplo `Fiat`
`modelo`	`string \| null`	Modelo do veículo, por exemplo `Strada Endurance`
`tipo_veiculo`	`string \| null`	Tipo do veículo, por exemplo `carro`, `moto`, `caminhao`
`status_ipva`	`string \| null`	Situação do IPVA, por exemplo `pago`, `pendente`
`mes_renovacao`	`integer \| null`	Mês de renovação do licenciamento, de 1 a 12
`dia_renovacao`	`integer \| null`	Dia de renovação do licenciamento, de 1 a 31
`seguro`	`string \| null`	Seguradora e apólice, em texto livre
`foto_url`	`string \| null`	URL da foto do veículo
`ativo`	`boolean`	`false` quando o veículo foi desativado
`created_at`	`timestamp (ISO 8601)`	Criação do registro
`updated_at`	`timestamp (ISO 8601)`	Última atualização

Filtros e ordenação

Campo	Operadores	Exemplo
`placa`	`eq`, `ilike`	`filter[placa][ilike]=ABC%25`
`marca`	`eq`, `ilike`	`filter[marca][ilike]=Fiat%25`
`ativo`	`eq`	`filter[ativo][eq]=true`

Filtros combinam com AND. Em ilike, o curinga % precisa ser codificado como %25 na URL. A ordenação padrão é -created_at; sort também aceita created_at, updated_at e placa, com - na frente para ordem decrescente.

Exemplos

Listar

curl "$LIGGA_BASE/v1/vehicles?limit=2&sort=-created_at&filter[ativo][eq]=true" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": [
    {
      "id": "3f8a1c2d-5e6b-4a7f-9c0d-1e2f3a4b5c6d",
      "placa": "ABC1D23",
      "chassi": "9BWZZZ377VT004251",
      "renavam": "00123456789",
      "marca": "Fiat",
      "modelo": "Strada Endurance",
      "tipo_veiculo": "carro",
      "status_ipva": "pago",
      "mes_renovacao": 3,
      "dia_renovacao": 15,
      "seguro": "Porto Seguro — apólice 55.123.456",
      "foto_url": "https://cdn.ligga.app/veiculos/strada.jpg",
      "ativo": true,
      "created_at": "2026-02-18T13:40:21.000Z",
      "updated_at": "2026-06-30T08:12:05.000Z"
    },
    {
      "id": "8b2d4e6f-1a3c-4d5e-8f90-a1b2c3d4e5f6",
      "placa": "XYZ9E87",
      "chassi": null,
      "renavam": null,
      "marca": "Honda",
      "modelo": "CG 160 Titan",
      "tipo_veiculo": "moto",
      "status_ipva": "pendente",
      "mes_renovacao": 8,
      "dia_renovacao": null,
      "seguro": null,
      "foto_url": null,
      "ativo": true,
      "created_at": "2026-01-09T10:05:44.000Z",
      "updated_at": "2026-05-22T16:31:10.000Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjhiMmQ0ZTZmLTFhM2MtNGQ1ZS04ZjkwLWExYjJjM2Q0ZTVmNiIsInYiOiIyMDI2LTAxLTA5VDEwOjA1OjQ0LjAwMFoifQ",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JXQ8V2K5M7N9P0R1S2T3U4VZ" }
}

Para a próxima página, repita a chamada com cursor=<pagination.next_cursor> enquanto has_more for true.

Buscar por id

curl "$LIGGA_BASE/v1/vehicles/3f8a1c2d-5e6b-4a7f-9c0d-1e2f3a4b5c6d?fields=id,placa,marca,modelo,status_ipva" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "3f8a1c2d-5e6b-4a7f-9c0d-1e2f3a4b5c6d",
    "placa": "ABC1D23",
    "marca": "Fiat",
    "modelo": "Strada Endurance",
    "status_ipva": "pago"
  },
  "meta": { "request_id": "req_01JXQ8V2K5M7N9P0R1S2T3U4VZ" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`insufficient_scope`	Chave sem `vehicles:read`
403	`module_not_enabled`	Módulo `veiculos` fora do contrato
404	`not_found`	`id` inexistente ou de outra conta
422	`validation`	Campo de filtro, operador, `sort` ou `cursor` não aceito
429	`rate-limit-exceeded`	Limite de requisições do plano excedido

Um filtro por campo em inglês, como filter[plate][eq]=ABC1D23, cai em 422 validation com detail apontando o campo recusado.

Veja também

Paginação, filtros e ordenação — limit, cursor, sort e fields
Módulos e escopos — o que o módulo veiculos libera
Erros — o corpo de erro completo
Sua conta (me) — confira os escopos da sua chave