Módulos v2

Multas administrativas

Multas administrativas são autuações fora do Código de Trânsito Brasileiro (CTB), como por exemplo, excesso de peso de carga. O papel deste módulo é permitir que você consulte essas infrações vinculadas à sua conta e acompanhe seus status de tratamento.

5 min de leituraVale para v2

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

Listar multas administrativas

GET/v2/administrative-fines

Retorna as multas em páginas. Todos os filtros são opcionais — sem filtros, retorna todos os registros ativos da conta.

curl -X GET \
  'https://api.frota162.com.br/v2/administrative-fines?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
`clientId`	number	—	ID do cliente na fines-api. Precisa pertencer à sua conta — se não pertencer, retorna `403`
`ait`	string	—	Número do AIT para filtro exato
`bankSlip`	string	—	Disponibilidade de boleto — valores: `all`, `with`, `without`
`isActive`	boolean	`true`	Filtra registros ativos (`true`) ou excluídos (`false`)
`treatmentStatus`	string	—	Status de tratamento do enquadramento — valores: `not_treated`, `treated`
`framingCode`	string	—	Código do enquadramento para filtro exato
`orgCode`	string	—	Código do órgão autuador para filtro exato
`framingDateStart` / `framingDateEnd`	string	—	Período pela data do enquadramento (`YYYY-MM-DD`)
`dueDateStart` / `dueDateEnd`	string	—	Período pela data de vencimento (`YYYY-MM-DD`)
`paymentDateStart` / `paymentDateEnd`	string	—	Período pela data de pagamento (`YYYY-MM-DD`)
`createdAtStart` / `createdAtEnd`	string	—	Período pela criação do registro (`YYYY-MM-DD`)
`updatedAtStart` / `updatedAtEnd`	string	—	Período pela última atualização (`YYYY-MM-DD`)
`sort`	string	—	Campo para ordenação — valores: `createdAt`, `updatedAt`, `ait`, `framingDate`, `framingAmount`, `dueDate`, `paymentDate`
`order`	string	—	Direção da ordenação — `asc` ou `desc`

Apenas um período por requisição

Você pode filtrar por no máximo um dos cinco pares de data (framingDate*, dueDate*, paymentDate*, createdAt*, updatedAt*) em cada requisição. Enviar mais de um par retorna 400. Dentro do par usado, a data final deve ser maior ou igual à inicial.

Resposta

{
  "data": [
    {
      "id": 1,
      "accountId": 1,
      "clientId": 12345,
      "divisionId": 12,
      "subDivisionId": null,
      "carPlate": "ABC1D23",
      "type": "MULTA",
      "ait": "AIT123456",
      "framingDate": "2024-01-15",
      "framingHour": "14:30",
      "framingCode": "12345678",
      "framingDescription": "Excesso de velocidade",
      "framingAddress": "Av. Paulista, 1000",
      "framingCityCode": "3550308",
      "framingCityName": "São Paulo",
      "framingUf": "SP",
      "framingPoints": 5,
      "framingAmount": 293.47,
      "discountAmount": 58.69,
      "orgCode": "SP-DER",
      "orgName": "DER",
      "ownerName": "Empresa Exemplo LTDA",
      "ownerDoc": "12345678000199",
      "driverIndicateAt": null,
      "driverIndicateId": null,
      "driverId": null,
      "driverName": null,
      "driverCnh": null,
      "driverRg": null,
      "driverRgUf": null,
      "driverCpf": null,
      "driverAddress": null,
      "driverAddressNumber": null,
      "driverZipCode": null,
      "driverDistrict": null,
      "driverCity": null,
      "driverUf": null,
      "driverIndicated": false,
      "statusAppealJustify": null,
      "statusRecurso": null,
      "dueDate": "2024-02-15",
      "paymentDate": null,
      "paymentAmount": null,
      "treatmentStatus": "not_treated",
      "inadequateConduct": null,
      "observation": null,
      "hasBankSlip": true,
      "viewStatus": null,
      "createdAt": "2024-01-15",
      "updatedAt": "2024-01-16",
      "deletedAt": null,
      "deletedId": null,
      "paid": "unpaid",
      "linkView": "https://.../download?filename=AIT123456_20240115&ext=pdf&key=..."
    }
  ],
  "page": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8,
    "hasNext": true
  }
}

Formato da resposta

A raiz da resposta é { data, page } — não { pagination, data } como em outros módulos v1.

Campos de paginação (`page`)

Campo	Descrição
`currentPage`	Página atual
`pageSize`	Itens retornados nesta página
`totalItems`	Total de registros 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.

Campos dos itens (`data[]`)

Campo	Tipo	Nullable	Descrição
`id`	number	Não	Identificador único do enquadramento
`accountId`	number	Não	ID da conta
`clientId`	number	Não	ID do cliente na fines-api
`divisionId`	number	Sim	ID da divisão
`subDivisionId`	number	Sim	ID da subdivisão
`carPlate`	string	Não	Placa do veículo
`type`	string	Sim	Tipo da infração
`ait`	string	Sim	Número do AIT (Auto de Infração de Trânsito)
`framingDate`	string (`YYYY-MM-DD`)	Não	Data do enquadramento
`framingHour`	string	Sim	Hora do enquadramento
`framingCode`	string	Não	Código do enquadramento da infração
`framingDescription`	string	Sim	Descrição do enquadramento
`framingAddress`	string	Sim	Endereço do enquadramento
`framingCityCode`	string	Sim	Código IBGE do município
`framingCityName`	string	Sim	Nome do município
`framingUf`	string	Sim	UF do enquadramento
`framingPoints`	number	Sim	Pontos do enquadramento
`framingAmount`	number	Não	Valor da multa (R$)
`discountAmount`	number	Sim	Valor de desconto (R$)
`orgCode`	string	Não	Código do órgão autuador
`orgName`	string	Não	Nome do órgão autuador
`ownerName`	string	Sim	Nome do proprietário do veículo
`ownerDoc`	string	Sim	Documento do proprietário
`driverIndicateAt`	string (`YYYY-MM-DD`)	Sim	Data da indicação do condutor
`driverIndicateId`	number	Sim	ID da indicação do condutor
`driverId`	number	Sim	ID do condutor
`driverName`	string	Sim	Nome do condutor
`driverCnh`	string	Sim	CNH do condutor
`driverRg`	string	Sim	RG do condutor
`driverRgUf`	string	Sim	UF do RG do condutor
`driverCpf`	string	Sim	CPF do condutor
`driverAddress`	string	Sim	Endereço do condutor
`driverAddressNumber`	string	Sim	Número do endereço do condutor
`driverZipCode`	string	Sim	CEP do condutor
`driverDistrict`	string	Sim	Bairro do condutor
`driverCity`	string	Sim	Cidade do condutor
`driverUf`	string	Sim	UF do condutor
`driverIndicated`	boolean	Não	Indica se o condutor foi indicado
`statusAppealJustify`	string	Sim	Justificativa do recurso
`statusRecurso`	`NR` \| `RE` \| `AR` \| `NE`	Sim	Status do recurso
`dueDate`	string (`YYYY-MM-DD`)	Sim	Data de vencimento
`paymentDate`	string (`YYYY-MM-DD`)	Sim	Data de pagamento
`paymentAmount`	number	Sim	Valor pago (R$)
`treatmentStatus`	`not_treated` \| `treated`	Sim*	Status de tratamento do enquadramento
`inadequateConduct`	number	Sim	Conduta inadequada
`observation`	string	Sim	Observação sobre a multa
`hasBankSlip`	boolean	Não	`true` se há boleto disponível para pagamento
`viewStatus`	string	Sim	Status de visualização
`createdAt`	string (`YYYY-MM-DD`)	Não	Data de criação do registro
`updatedAt`	string (`YYYY-MM-DD`)	Não	Data da última atualização
`deletedAt`	string (`YYYY-MM-DD`)	Sim	Data de exclusão
`deletedId`	number	Sim	ID do usuário que excluiu
`paid`	`paid` \| `unpaid`	Não	Status de pagamento da multa
`linkView`	string \| null	Sim	Link do PDF da vista (documento oficial da autuação ANTT). `null` quando a vista não estiver disponível

* treatmentStatus fica ausente da resposta se o valor vindo da fonte não puder ser reconhecido.

Datas no formato curto

Todos os campos de data (framingDate, dueDate, paymentDate, createdAt, updatedAt, deletedAt, driverIndicateAt) são retornados como YYYY-MM-DD, sem hora.

Vista da multa (linkView)

O campo linkView traz o link do PDF da vista — o documento oficial da autuação emitido pela ANTT — para cada item da listagem, no mesmo formato da consulta por ID. Quando a vista ainda não estiver disponível, o valor é null.

A vista é atualizada por uma captura periódica: pode levar até 7 dias para o linkView aparecer ou ser atualizado após a autuação.
Em dossiês com vários AITs (cerca de 7% das vistas), o PDF pode conter processos de outras multas além da consultada naquele item. Confira o AIT dentro do documento antes de usá-lo como comprovante exclusivo daquele enquadramento.

Erros

Todos os erros retornam o formato RFC 7807 Problem Details:

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

Status	`type`	Causa	Ação
`400`	`validation-error`	Parâmetro inválido, mais de um par de datas informado, ou data final anterior à inicial	Revise os query params
`401`	`unauthorized`	Header `Authorization` ou `Key` ausente ou inválido	Revise as credenciais — consulte o guia de autenticação
`403`	`forbidden`	Módulo não ativo no plano, organização sem conta configurada, ou `clientId` informado não pertence à sua conta	Confirme o módulo habilitado e que o `clientId` é seu; se persistir, entre em contato com o suporte
`500`	`internal-server-error`	Erro interno ao processar a consulta	Aguarde alguns instantes e tente novamente; use retry com backoff

Exemplo — mais de um período de data (`400`)

{
  "type": "urn:frota162-api-v2:error:validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Apenas um par de datas pode ser informado por requisição. Recebido: framingDate, dueDate"
}

Exemplo — `clientId` fora da conta (`403`)

{
  "type": "urn:frota162-api-v2:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Client ID does not belong to the partner account"
}

Exemplos de uso

Listar multas de um cliente específico

curl -X GET \
  'https://api.frota162.com.br/v2/administrative-fines?clientId=12345&pageSize=50' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Buscar multas por período de enquadramento

curl -X GET \
  'https://api.frota162.com.br/v2/administrative-fines?framingDateStart=2024-01-01&framingDateEnd=2024-01-31' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Buscar multas com vencimento em um período

curl -X GET \
  'https://api.frota162.com.br/v2/administrative-fines?dueDateStart=2024-04-01&dueDateEnd=2024-04-30&pageSize=100' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Filtrar por status de tratamento e boleto

curl -X GET \
  'https://api.frota162.com.br/v2/administrative-fines?treatmentStatus=not_treated&bankSlip=with' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Percorrer todas as páginas

async function buscarTodasMultas(headers) {
  const todos = [];
  let pagina = 1;
  let totalPaginas = 1;

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

    todos.push(...dados.data);
    totalPaginas = dados.page.totalPages;
    pagina++;
  }

  return todos;
}

Consultar multa administrativa por ID

GET/v2/administrative-fines/:id

Retorna um único enquadramento administrativo pelo seu identificador.

curl -X GET \
  'https://api.frota162.com.br/v2/administrative-fines/42' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC'

Resposta

Os campos retornados são os mesmos da listagem — consulte a tabela de campos acima —, acrescidos do campo abaixo, exclusivo da consulta por ID:

Campo	Tipo	Nullable	Descrição
`linkView`	string \| null	Sim	Link do PDF da vista (documento oficial da autuação ANTT). `null` quando a vista não estiver disponível

Vista da multa (linkView)

O campo linkView traz o link do PDF da vista — o documento oficial da autuação emitido pela ANTT. Quando a vista ainda não estiver disponível, o valor é null.

A vista é atualizada por uma captura periódica: pode levar até 7 dias para o linkView aparecer ou ser atualizado após a autuação.
Em alguns processos, o PDF pode conter mais de uma autuação do mesmo dossiê. Confira o AIT dentro do documento.

{
  "id": 42,
  "accountId": 1,
  "clientId": 12345,
  "divisionId": null,
  "subDivisionId": null,
  "carPlate": "ABC1D23",
  "type": null,
  "ait": null,
  "framingDate": "2024-01-15",
  "framingHour": null,
  "framingCode": "55550",
  "framingDescription": null,
  "framingAddress": null,
  "framingCityCode": null,
  "framingCityName": null,
  "framingUf": null,
  "framingPoints": null,
  "framingAmount": 293.47,
  "discountAmount": null,
  "orgCode": "DER-PR",
  "orgName": "DER",
  "ownerName": null,
  "ownerDoc": null,
  "driverIndicateAt": null,
  "driverIndicateId": null,
  "driverId": null,
  "driverName": null,
  "driverCnh": null,
  "driverRg": null,
  "driverRgUf": null,
  "driverCpf": null,
  "driverAddress": null,
  "driverAddressNumber": null,
  "driverZipCode": null,
  "driverDistrict": null,
  "driverCity": null,
  "driverUf": null,
  "driverIndicated": false,
  "statusAppealJustify": null,
  "statusRecurso": null,
  "dueDate": null,
  "paymentDate": null,
  "paymentAmount": null,
  "treatmentStatus": "not_treated",
  "inadequateConduct": null,
  "observation": null,
  "hasBankSlip": false,
  "viewStatus": null,
  "createdAt": "2024-01-15",
  "updatedAt": "2024-01-16",
  "deletedAt": null,
  "deletedId": null,
  "paid": "unpaid",
  "linkView": "https://.../download?filename=AIT123456_20240115&ext=pdf&key=..."
}

Erros

Status	`type`	Causa	Ação
`400`	`validation-error`	`id` no path não é um número inteiro positivo	Corrija o `id` — deve ser um número inteiro maior que zero
`401`	`unauthorized`	Header `Authorization` ou `Key` ausente ou inválido	Revise as credenciais — consulte o guia de autenticação
`403`	`forbidden`	Módulo 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`	`not-found`	Enquadramento não encontrado, ou pertence a outra conta — a API não distingue os dois casos	Verifique o `id`; IDs de outras contas retornam `404` por segurança
`502`	`external-api-error`	Serviço upstream (fines-api) indisponível ou retornou resposta inesperada	Aguarde alguns instantes e tente novamente; use retry com backoff

Por que 404 em vez de 403 para IDs de outra conta?

Por razões de segurança, o endpoint retorna 404 tanto para enquadramentos inexistentes quanto para enquadramentos que existem mas pertencem a outra conta. Isso impede que a API confirme a existência de recursos aos quais você não tem acesso.

Comportamentos importantes

ait pode ser nulo

O campo ait pode ser null quando o AIT ainda não foi lavrado pela fonte — isso não é um erro de integração.

Registros excluídos retornam 200

O endpoint retorna o enquadramento independentemente de estar ativo ou excluído. Verifique o campo deletedAt: se preenchido, o registro foi excluído na data indicada. Use esse campo para detectar exclusões em vez de depender da ausência do registro na listagem.

hasBankSlip: false — o que significa?

Não há boleto disponível para aquele enquadramento no momento da consulta. Quando um boleto estiver disponível, hasBankSlip será true.

linkView: null — o que significa?

A vista (PDF da autuação) ainda não está disponível para aquele enquadramento. Ela é capturada periodicamente e pode levar até 7 dias para aparecer.

Próximos passos

Indicação de condutoresIndique condutores para multas

Vincule o condutor responsável a uma multa específica.

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.

Listar multas administrativas​

Filtros disponíveis​

Resposta​

Campos de paginação (page)​

Campos dos itens (data[])​

Erros​

Exemplo — mais de um período de data (400)​

Exemplo — clientId fora da conta (403)​

Exemplos de uso​

Listar multas de um cliente específico​

Buscar multas por período de enquadramento​

Buscar multas com vencimento em um período​

Filtrar por status de tratamento e boleto​

Percorrer todas as páginas​

Consultar multa administrativa por ID​

Resposta​

Erros​

Comportamentos importantes​

Próximos passos​

Listar multas administrativas

Filtros disponíveis

Resposta

Campos de paginação (`page`)

Campos dos itens (`data[]`)

Erros

Exemplo — mais de um período de data (`400`)

Exemplo — `clientId` fora da conta (`403`)

Exemplos de uso

Listar multas de um cliente específico

Buscar multas por período de enquadramento

Buscar multas com vencimento em um período

Filtrar por status de tratamento e boleto

Percorrer todas as páginas

Consultar multa administrativa por ID

Resposta

Erros

Comportamentos importantes

Próximos passos