Referência da API

Consultas

Disparo da consulta de débitos e leitura dos itens pagáveis.

A consulta é assíncrona do ponto de vista do integrador: crie, depois leia até ready ou failed. O limite é de 20 criações por hora.

POST/api/v1/vehicles/{vehicle_id}/consultations

Abre uma consulta para o veículo da conta. Não há corpo.

Path

Campo	Tipo	Presença	Descrição
`vehicle_id`	`uuid`	obrigatório	Veículo ativo da conta.

curl -X POST \
https://api.zera.mobi/api/v1/vehicles/8c1d9e2a-7b34-4f10-9a11-22b33c44d55e/consultations \
-H "X-Api-Key: zera_live_..." \
-H "X-Account-Id: 4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f"

{
"id": "11aa22bb-33cc-44dd-55ee-66ff77889900",
"vehicle_id": "8c1d9e2a-7b34-4f10-9a11-22b33c44d55e",
"plate": "ABC1D23",
"status": "pending",
"stage": "queued",
"found_new_debts": false,
"error_message": "",
"error_code": "",
"error_title": "",
"error_action": "",
"total_amount": "0.00",
"items": []
}

GET/api/v1/consultations/{consultation_id}

Estado atual. Com status: ready, cobre os débitos em items.

Item de débito

Campo	Tipo	Presença	Descrição
`id`	`uuid`	obrigatório	Entra em debt_item_ids na criação do pedido.
`kind`	`string`	obrigatório	ipva, ipva_unique, ipva_installment, licensing, ticket, renainf_ticket, insurance, service ou other.
`group`	`string`	obrigatório	Família: ipva, licensing, ticket, insurance, service ou other.
`amount`	`string`	obrigatório	Valor decimal.
`due_date`	`date`	opcional	Vencimento, quando o órgão informa.
`depends_on`	`uuid`	opcional	Outro item que precisa ser pago junto.
`is_payable`	`boolean`	obrigatório	false impede o item de entrar no pedido.

{
"id": "11aa22bb-33cc-44dd-55ee-66ff77889900",
"status": "ready",
"stage": "ready",
"total_amount": "129.90",
"items": [
  {
    "id": "99aa88bb-77cc-66dd-55ee-4433221100ff",
    "kind": "ipva",
    "group": "ipva",
    "description": "IPVA 2026",
    "amount": "129.90",
    "due_date": "2026-03-15",
    "year": 2026,
    "depends_on": null,
    "depends_on_description": "",
    "is_payable": true
  }
]
}

GET /api/v1/vehicles/{vehicle_id}/consultations lista o histórico paginado. GET /api/v1/vehicles/{vehicle_id}/consultations/latest devolve só a mais recente, ou 404 com {"detail":"Nenhuma consulta encontrada."} se nunca houve consulta.