Módulos v2

Licenciamento

O Licenciamento é a taxa anual cobrada pelos estados para manter o veículo regularizado e emitir o documento do ano. Este módulo permite que você consulte a situação do Licenciamento de um veículo da sua conta pela placa, com o total em aberto e os débitos do veículo.

4 min de leituraVale para v2

O que dá para fazer

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

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 Licenciamento precisa estar ativo no seu plano. Se não estiver, a API retorna 403. Entre em contato conosco para habilitar.

A consulta traz os débitos de Licenciamento 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 Licenciamento por placa

GET/v2/licensing/vehicles/:carPlate

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

curl -X GET \
  'https://api.frota162.com.br/v2/licensing/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": 160.22,
  "debts": [
    {
      "id": 1,
      "year": 2026,
      "amount": 160.22,
      "discountAmount": 0,
      "dueDate": "2026-12-05",
      "status": "OPEN",
      "overdue": false,
      "officialDueDate": "2026-12-05"
    }
  ]
}

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` \| `UNAVAILABLE`	Não	Situação consolidada do Licenciamento 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 Licenciamento do veículo, ordenados pelo vencimento. Vazio quando não há débito

Campos dos débitos (`debts[]`)

Campo	Tipo	Nullable	Descrição
`id`	number	Não	Identificador do débito
`year`	number	Sim	Ano de exercício
`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 definido pelo estado

Datas no formato curto

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

Situação do veículo

`situation`	Quando
`OPEN`	O veículo tem pelo menos um débito de Licenciamento 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 Licenciamento a pagar
`UNAVAILABLE`	Não foi possível obter o Licenciamento do veículo. O motivo vem em `unavailableReason`

Sem situação de isenção

Diferente do IPVA, o Licenciamento não tem a situação EXEMPT. Veículo sem Licenciamento a pagar aparece como PAID.

Motivos de indisponibilidade

`unavailableReason`	O que significa	O que fazer
`UF_NOT_COVERED`	A UF do veículo ainda não tem consulta na plataforma	Acompanhe o Licenciamento 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 Licenciamentos

GET/v2/licensing/vehicles

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

A listagem traz só débitos. Veículos sem débito não aparecem aqui. Para saber a situação de um veículo específico, use a consulta por placa.

curl -X GET \
  'https://api.frota162.com.br/v2/licensing/vehicles?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`
`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 erro aparecem no item como OPEN, 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,
      "amount": 160.22,
      "discountAmount": 0,
      "dueDate": "2026-12-05",
      "status": "OPEN",
      "overdue": false,
      "officialDueDate": "2026-12-05"
    }
  ],
  "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
`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 e o vencimento já passou, considerando a data de Brasília
`officialDueDate`	string (`YYYY-MM-DD`)	Sim	Vencimento oficial definido pelo estado

Os itens não têm campos de cota (quota, numberOfQuotas e quoteType), porque o Licenciamento não tem cotas.

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.

Erros da listagem

Status	`type`	Causa	Ação
`400`	`validation-error`	Parâmetro inválido: `pageSize` acima de 100, `status` desconhecido, `year` fora da faixa, `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 Licenciamento não ativo no plano, ou organização sem conta configurada	Confirme o módulo habilitado; se persistir, entre em contato com o suporte
`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

Exemplos de uso

Licenciamentos pendentes com vencimento no trimestre

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

Licenciamentos de um veículo em um exercício

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

Percorrer todas as páginas

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

  while (temProxima) {
    const url = `https://api.frota162.com.br/v2/licensing/vehicles?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;
}

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`	Placa malformada	Revise a placa; 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 Licenciamento 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	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

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/licensing/vehicles/TST1A05' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Placa	Cenário	Resposta
`TST1A05`	Licenciamento em aberto	`200` — `situation: OPEN`, 1 débito de R$ 160,22 a vencer em 45 dias (`overdue: false`)
`TST1A02`	Licenciamento quitado	`200` — `situation: PAID`, débito pago
`TST1A01`	Veículo sem Licenciamento a pagar	`200` — `situation: PAID`, sem débitos
`TST1A03`	Veículo sem Licenciamento a pagar	`200` — `situation: PAID`, sem débitos
`TST1A04`	UF sem cobertura	`200` — `situation: UNAVAILABLE`, `unavailableReason: UF_NOT_COVERED`
`TST1A06`	Serviço indisponível	`503` com header `Retry-After`

As mesmas placas valem na consulta de IPVA, com o cenário de IPVA de cada uma.

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.
A listagem GET /v2/licensing/vehicles não usa o catálogo de placas: consulta os débitos reais da conta, como a listagem de IPVA.

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

IPVAConsulte o IPVA

Veja a situação do IPVA do veículo e liste os débitos de IPVA da frota.

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 Licenciamento por placa​

Resposta​

Campos dos débitos (debts[])​

Situação do veículo​

Motivos de indisponibilidade​

Listar Licenciamentos​

Filtros disponíveis​

Filtro de status​

Resposta​

Campos dos itens (data[])​

Campos de paginação (page)​

Erros da listagem​

Exemplos de uso​

Licenciamentos pendentes com vencimento no trimestre​

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

Percorrer todas as páginas​

Referência de erros​

Ambiente de testes (sandbox)​

Próximos passos​

O que dá para fazer

Consultar Licenciamento por placa

Resposta

Campos dos débitos (`debts[]`)

Situação do veículo

Motivos de indisponibilidade

Listar Licenciamentos

Filtros disponíveis

Filtro de status

Resposta

Campos dos itens (`data[]`)

Campos de paginação (`page`)

Erros da listagem

Exemplos de uso

Licenciamentos pendentes com vencimento no trimestre

Licenciamentos de um veículo em um exercício

Percorrer todas as páginas

Referência de erros

Ambiente de testes (sandbox)

Próximos passos