Módulos v2

IPVA

O IPVA (Imposto sobre a Propriedade de Veículos Automotores) é cobrado anualmente pelos estados, em cota única ou parcelado. Este módulo permite que você consulte a situação do IPVA de um veículo pela placa e liste os débitos de IPVA dos veículos da sua conta, acompanhando o que está em aberto ou já foi pago.

6 min de leituraVale para v2

O que dá para fazer

Operação	Endpoint
Consultar o IPVA de um veículo	`GET /v2/ipva/vehicles/:carPlate`
Listar débitos de IPVA com filtros	`GET /v2/ipva`

Autenticação

Este módulo usa a mesma autenticação HMAC-SHA256 da API v1. Requer os headers Authorization e Key. Consulte o guia de autenticação se ainda não configurou.

Módulo obrigatório

O módulo IPVA precisa estar ativo no seu plano. Se não estiver, a API retorna 403. Entre em contato conosco para habilitar.

As duas operações trazem os débitos de IPVA que já estão na plataforma para os veículos da sua conta. A API não faz uma consulta nova ao órgão de trânsito a cada chamada.

Consultar IPVA por placa

GET/v2/ipva/vehicles/:carPlate

Retorna a situação consolidada do IPVA de um veículo da sua conta, o total em aberto e todos os débitos de IPVA do veículo. Use quando você precisa responder "este veículo tem IPVA a pagar?" sem percorrer a listagem.

curl -X GET \
  'https://api.frota162.com.br/v2/ipva/vehicles/ABC1D23' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Parâmetro	Onde	Descrição
`carPlate`	path	Placa do veículo (padrão antigo ou Mercosul). Aceita com ou sem hífen e em minúsculas (`abc-1d23` vira `ABC1D23`)

A placa precisa ser de um veículo cadastrado na sua conta. Placa fora da conta retorna 404. Para testar cada cenário sem dados reais, use as placas do ambiente de testes.

Resposta

{
  "vehicle": { "carPlate": "ABC1D23", "uf": "SP" },
  "situation": "OPEN",
  "unavailableReason": null,
  "totalOpenAmount": 950.5,
  "debts": [
    {
      "id": 1,
      "year": 2026,
      "quota": 1,
      "numberOfQuotas": 3,
      "quoteType": "installments",
      "amount": 1000.5,
      "discountAmount": 50,
      "dueDate": "2026-03-31",
      "status": "OPEN",
      "overdue": true,
      "officialDueDate": "2026-09-15"
    }
  ]
}

Campo	Tipo	Nullable	Descrição
`vehicle.carPlate`	string	Não	Placa do veículo
`vehicle.uf`	string	Sim	UF do veículo
`situation`	`OPEN` \| `PAID` \| `EXEMPT` \| `UNAVAILABLE`	Não	Situação consolidada do IPVA do veículo. Veja situação do veículo
`unavailableReason`	string	Sim	Motivo, preenchido só quando `situation` é `UNAVAILABLE`. Veja motivos
`totalOpenAmount`	number	Não	Soma dos débitos em aberto (valor menos desconto), em R$, com 2 casas decimais
`debts[]`	array	Não	Débitos de IPVA do veículo, ordenados pelo vencimento. Vazio quando não há débito

Cada item de debts[] tem os mesmos campos dos itens da listagem, exceto vehicle, que já vem no topo da resposta.

Situação do veículo

`situation`	Quando
`OPEN`	O veículo tem pelo menos um débito de IPVA em aberto
`PAID`	O veículo não tem débito em aberto: todos foram quitados, ou o veículo foi consultado e não tem IPVA a pagar
`EXEMPT`	O veículo está marcado como isento de IPVA
`UNAVAILABLE`	Não foi possível obter o IPVA do veículo. O motivo vem em `unavailableReason`

Motivos de indisponibilidade

`unavailableReason`	O que significa	O que fazer
`UF_NOT_COVERED`	A UF do veículo ainda não tem consulta de IPVA na plataforma	Acompanhe o IPVA desse veículo por outro canal
`RECENTLY_REGISTERED`	O veículo foi cadastrado há pouco tempo e ainda não foi consultado	Consulte novamente nos próximos dias
`MISSING_RENAVAM`	O cadastro do veículo está sem RENAVAM	Complete o RENAVAM no cadastro do veículo
`INVALID_OR_MISSING_UF`	O cadastro do veículo está sem UF ou com UF inválida	Corrija a UF no cadastro do veículo

Motivo null com UNAVAILABLE

Se situation for UNAVAILABLE e unavailableReason vier null, a situação do veículo não pôde ser determinada. Trate como indisponível e consulte novamente mais tarde.

Listar IPVAs

GET/v2/ipva

Retorna os débitos de IPVA em páginas. Todos os filtros são opcionais. Sem filtros, retorna todos os débitos de IPVA da conta, ordenados pelo vencimento mais próximo.

curl -X GET \
  'https://api.frota162.com.br/v2/ipva?status=PENDING&pageSize=20&currentPage=1' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Filtros disponíveis

Parâmetro	Tipo	Padrão	Descrição
`currentPage`	number	`1`	Número da página (começa em 1)
`pageSize`	number	`10`	Itens por página, máximo 100
`carPlate`	string	—	Placa do veículo, busca exata. Aceita com ou sem hífen e em minúsculas (`abc-1d23` vira `ABC1D23`)
`status`	string	—	Status de pagamento do débito: `PENDING` ou `PAID`. Veja filtro de status
`year`	number	—	Ano de exercício, de 2000 até o ano seguinte ao atual
`dueDateFrom` / `dueDateTo`	string	—	Período pela data de vencimento (`YYYY-MM-DD`). `dueDateTo` deve ser maior ou igual a `dueDateFrom`
`quoteType`	string	—	Modalidade: `unique` (cota única) ou `installments` (parcelado)
`sort`	string	`dueDate`	Campo de ordenação: `dueDate`, `year`, `amount` ou `carPlate`
`order`	string	`asc`	Direção da ordenação: `asc` ou `desc`

Parâmetros desconhecidos são ignorados. Um valor inválido em um parâmetro conhecido retorna 400 indicando o campo.

Filtro de status

O filtro status usa o status de pagamento do débito:

Valor	O que retorna
`PENDING`	Débitos aguardando pagamento
`PAID`	Débitos pagos pela plataforma

O filtro não é o mesmo que o campo status do item

O campo status de cada item (OPEN/PAID) é uma situação consolidada. Débitos em processamento, bloqueados ou com baixa manual aparecem no item como OPEN ou PAID, mas não entram em nenhum dos dois valores do filtro. Para ter a visão completa da frota, liste sem o filtro status e use o campo status do item.

Resposta

{
  "data": [
    {
      "id": 1,
      "vehicle": { "carPlate": "ABC1D23", "uf": "SP" },
      "year": 2026,
      "quota": 1,
      "numberOfQuotas": 3,
      "quoteType": "installments",
      "amount": 1000.5,
      "discountAmount": 50,
      "dueDate": "2026-03-31",
      "status": "OPEN",
      "overdue": true,
      "officialDueDate": "2026-09-15"
    }
  ],
  "page": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 42,
    "totalPages": 3,
    "hasNext": true
  }
}

Campos dos itens (`data[]`)

Campo	Tipo	Nullable	Descrição
`id`	number	Não	Identificador do débito
`vehicle.carPlate`	string	Não	Placa do veículo
`vehicle.uf`	string	Sim	UF do veículo
`year`	number	Sim	Ano de exercício
`quota`	number	Sim	Número da cota
`numberOfQuotas`	number	Sim	Quantidade total de cotas do exercício
`quoteType`	`unique` \| `installments`	Sim	Modalidade: `unique` (cota única) ou `installments` (parcelado)
`amount`	number	Sim	Valor do débito (R$)
`discountAmount`	number	Sim	Valor de desconto (R$)
`dueDate`	string (`YYYY-MM-DD`)	Sim	Data de vencimento
`status`	`OPEN` \| `PAID`	Não	Situação do débito: `OPEN` (em aberto) ou `PAID` (quitado)
`overdue`	boolean	Não	`true` quando o débito está em aberto (`status: OPEN`) e o vencimento já passou, considerando a data de Brasília
`officialDueDate`	string (`YYYY-MM-DD`)	Sim	Vencimento oficial do imposto definido pelo estado

Datas no formato curto

Os campos de data (dueDate, officialDueDate) são retornados como YYYY-MM-DD, sem hora.

Campos de paginação (`page`)

Campo	Descrição
`currentPage`	Página atual
`pageSize`	Itens por página solicitados
`totalItems`	Total de débitos que atendem aos filtros
`totalPages`	Total de páginas disponíveis
`hasNext`	`true` se houver próxima página

Este é o formato padrão de paginação da API v2 ({ data, page }). Veja o guia de Paginação para detalhes e como iterar sobre todas as páginas.

Página além do total ou filtro sem resultado

Pedir uma página além da última, ou usar um filtro que não encontra nada, retorna 200 com data: []. Na página além do total, totalItems continua mostrando o total real.

Referência de erros

Todos os erros retornam o formato RFC 7807 Problem Details:

{
  "type": "urn:frota162-api-v2:error:{tipo}",
  "title": "Título do erro",
  "status": 400,
  "detail": "Descrição específica do problema"
}

Status	`type`	Causa	Ação
`400`	`validation-error`	Parâmetro inválido (ex.: placa malformada, `pageSize` acima de 100, `status` desconhecido, `dueDateTo` anterior a `dueDateFrom`)	Revise os parâmetros; a resposta indica o campo
`401`	`unauthorized`	Header `Authorization` ou `Key` ausente ou inválido	Revise as credenciais — consulte o guia de autenticação
`403`	`forbidden`	Módulo IPVA não ativo no plano, ou organização sem conta configurada	Confirme o módulo habilitado; se persistir, entre em contato com o suporte
`404`	`vehicle-not-found`	Placa não encontrada entre os veículos da sua conta (só na consulta por placa)	Confira a placa e se o veículo está cadastrado na conta
`503`	`service-unavailable`	Serviço temporariamente indisponível	Tente novamente após o tempo indicado no header `Retry-After` (em segundos)
`500`	`internal-server-error`	Erro interno ao processar a consulta	Aguarde alguns instantes e tente novamente; use retry com backoff

Exemplo — `pageSize` acima do limite (`400`)

curl -X GET \
  'https://api.frota162.com.br/v2/ipva?pageSize=101' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

A resposta é 400 com validation-error, apontando o campo pageSize.

Exemplo — período invertido (`400`)

?dueDateFrom=2026-06-01&dueDateTo=2026-05-31 retorna 400 com a mensagem dueDateTo deve ser maior ou igual a dueDateFrom, apontando o campo dueDateTo.

Exemplos de uso

Verificar se um veículo tem IPVA a pagar

async function ipvaEmAberto(placa, headers) {
  const resposta = await fetch(
    `https://api.frota162.com.br/v2/ipva/vehicles/${placa}`,
    { headers },
  );

  if (resposta.status === 404) {
    return null; // veículo não está na conta
  }

  const ipva = await resposta.json();
  return ipva.situation === 'OPEN' ? ipva.totalOpenAmount : 0;
}

IPVAs pendentes com vencimento no trimestre

curl -X GET \
  'https://api.frota162.com.br/v2/ipva?status=PENDING&dueDateFrom=2026-01-01&dueDateTo=2026-03-31&pageSize=100' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

IPVAs de um veículo em um exercício

curl -X GET \
  'https://api.frota162.com.br/v2/ipva?carPlate=ABC1D23&year=2026' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Maiores valores primeiro

curl -X GET \
  'https://api.frota162.com.br/v2/ipva?sort=amount&order=desc' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Percorrer todas as páginas

async function buscarTodosIpvas(headers) {
  const todos = [];
  let pagina = 1;
  let temProxima = true;

  while (temProxima) {
    const url = `https://api.frota162.com.br/v2/ipva?currentPage=${pagina}&pageSize=100`;
    const resposta = await fetch(url, { headers });
    const dados = await resposta.json();

    todos.push(...dados.data);
    temProxima = dados.page.hasNext;
    pagina++;
  }

  return todos;
}

Ambiente de testes (sandbox)

No ambiente sandbox, a consulta por placa não acessa os veículos reais da conta: um catálogo determinístico de placas devolve respostas fixas para você exercitar cada situation e os erros da sua integração. Mesma placa → mesma resposta, sempre. As datas de vencimento são relativas à data da consulta, então o catálogo não envelhece.

curl -X GET \
  'https://api.sandbox.v2.frota162.com.br/v2/ipva/vehicles/TST1A01' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Placa	Cenário	Resposta
`TST1A01`	IPVA em aberto	`200` — `situation: OPEN`, 3 cotas de R$ 500,00, 1 já vencida (`overdue: true`, `totalOpenAmount: 1500`)
`TST1A02`	IPVA quitado	`200` — `situation: PAID`, cota única paga
`TST1A03`	Veículo isento	`200` — `situation: EXEMPT`, sem débitos
`TST1A04`	UF sem cobertura	`200` — `situation: UNAVAILABLE`, `unavailableReason: UF_NOT_COVERED`
`TST1A05`	Veículo sem IPVA a pagar	`200` — `situation: PAID`, sem débitos
`TST1A06`	Serviço indisponível	`503` com header `Retry-After`

Regras do catálogo:

Qualquer placa válida fora da tabela retorna 404 (vehicle-not-found), como uma placa que não está na sua conta.
Placa malformada é recusada na validação (400), sem consultar o catálogo.
O catálogo vale só para a consulta por placa. A listagem GET /v2/ipva não usa essas placas.

Somente sandbox

Estas placas são fictícias e válidas apenas no ambiente sandbox. Em produção, a consulta usa os veículos e débitos da sua conta.

Próximos passos

PaginaçãoNavegue pelos resultados

Entenda como iterar sobre grandes volumes de dados.

Tratamento de errosLide com erros

Veja como tratar cada código de status, incluindo o 503 com Retry-After.

O que dá para fazer​

Consultar IPVA por placa​

Resposta​

Situação do veículo​

Motivos de indisponibilidade​

Listar IPVAs​

Filtros disponíveis​

Filtro de status​

Resposta​

Campos dos itens (data[])​

Campos de paginação (page)​

Referência de erros​

Exemplo — pageSize acima do limite (400)​

Exemplo — período invertido (400)​

Exemplos de uso​

Verificar se um veículo tem IPVA a pagar​

IPVAs pendentes com vencimento no trimestre​

IPVAs de um veículo em um exercício​

Maiores valores primeiro​

Percorrer todas as páginas​

Ambiente de testes (sandbox)​

Próximos passos​

O que dá para fazer

Consultar IPVA por placa

Resposta

Situação do veículo

Motivos de indisponibilidade

Listar IPVAs

Filtros disponíveis

Filtro de status

Resposta

Campos dos itens (`data[]`)

Campos de paginação (`page`)

Referência de erros

Exemplo — `pageSize` acima do limite (`400`)

Exemplo — período invertido (`400`)

Exemplos de uso

Verificar se um veículo tem IPVA a pagar

IPVAs pendentes com vencimento no trimestre

IPVAs de um veículo em um exercício

Maiores valores primeiro

Percorrer todas as páginas

Ambiente de testes (sandbox)

Próximos passos