Skip to main content

Visão Geral

A API de Consulta de Débitos permite buscar todos os débitos pendentes de um veículo de forma assíncrona. O sistema gera um pedido de consulta que é processado e retorna os resultados via webhook.
Processamento Assíncrono: A consulta é processada de forma assíncrona. Os resultados são enviados via webhook quando a consulta for concluída.

Como Funciona

O fluxo de consulta de débitos segue estas etapas:
1

Enviar Requisição

Faça uma requisição POST com os dados do veículo (placa, renavam, CPF/CNPJ)
2

Receber Confirmação

A API retorna imediatamente confirmando que a consulta foi iniciada
3

Aguardar Processamento

O sistema consulta os débitos nos sistemas dos Detrans
4

Receber Webhook

Quando concluída, os resultados são enviados para sua URL de webhook configurada

Endpoint

Parâmetros da Requisição

string
required
Sigla do estado (UF) onde o veículo está registrado. Exemplo: SP, RJ, MG
string
required
Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul)
string
required
Número do RENAVAM do veículo (11 dígitos)
string
required
CPF ou CNPJ do proprietário do veículo (apenas números)
string
Identificador único (UUID) para rastreamento da consulta no seu sistema. Este mesmo ID será retornado nos webhooks para correlação.
Sobre o externalId: Este campo é opcional mas altamente recomendado. Envie um UUID único gerado pelo seu sistema para rastrear a consulta. A API retornará este mesmo valor no campo externalId da resposta e dos webhooks, permitindo que você correlacione facilmente as notificações com as requisições originais.

Exemplo de Requisição

Resposta Imediata

Ao enviar a requisição, você recebe uma confirmação imediata:

Respostas via Webhook

Os resultados da consulta são enviados via webhook. Existem diferentes tipos de resposta:

1. Veículo com Débitos

Quando o veículo possui débitos pendentes:

2. Veículo sem Débitos

Quando o veículo não possui débitos:

3. Veículo Não Encontrado

Quando o veículo não é encontrado nos sistemas do Detran:

4. Erro na Consulta

Quando há erro nos sistemas do Detran:

Estrutura dos Débitos

Cada débito retornado contém as seguintes informações:
string
Identificador único do débito (UUID)
number
Valor do débito em reais
string
Título descritivo do débito
string
Descrição detalhada do débito
string
Tipo do débito: ticket (multa), ipva, licensing (licenciamento), service (taxa)
string
Data de vencimento original (formato ISO 8601)
string
Data de vencimento com juros/multa (formato ISO 8601)
boolean
Indica se o débito possui desconto disponível
boolean
Indica se o débito está vencido
number
Ano de referência do débito (para IPVA e licenciamento)
boolean
Indica se o débito é obrigatório para licenciamento
array
Lista de IDs de débitos que precisam ser pagos junto com este
array
Lista de IDs de débitos que não podem ser pagos junto com este
string
Número do Auto de Infração de Trânsito (apenas para multas)

Tipos de Débitos

Multas (ticket)

Infrações de trânsito e multas gerenciadas pelo RENAINF

IPVA (ipva)

Imposto sobre Propriedade de Veículos Automotores (cota única ou parcelada)

Licenciamento (licensing)

Taxa anual de licenciamento do veículo

Taxas (service)

Taxas de serviços diversos, como multa de pátio

Dependências entre Débitos

Alguns débitos possuem dependências que devem ser respeitadas no momento do pagamento:

dependsOn (Dependências)

Lista de débitos que devem ser pagos junto com o débito atual. Por exemplo, uma multa pode depender do pagamento do IPVA.
Neste caso, para pagar o DEBITO-A, você também deve incluir DEBITO-B e DEBITO-C no pagamento.

distinct (Exclusões)

Lista de débitos que não podem ser pagos junto com o débito atual. Por exemplo, IPVA cota única não pode ser pago junto com parcelas.

Limitações por Estado

Atenção: Alguns estados possuem limitações específicas nas consultas.

Estados com IPVA Cota Única Apenas

Os seguintes estados retornam apenas IPVA em cota única:
  • Goiás (GO)
  • Maranhão (MA)
  • Mato Grosso do Sul (MS)
  • Rio Grande do Sul (RS)

Manutenção São Paulo

São Paulo (SP): O Detran-SP realiza manutenções diárias entre 00h e 07h. Durante este período, não é possível realizar consultas para veículos de SP.

Validações

Validação de RENAVAM

A API valida automaticamente o dígito verificador do RENAVAM antes de processar a consulta:
Se o RENAVAM for válido, a consulta prossegue normalmente.
Se o dígito verificador for inválido, a API retorna erro imediatamente:
Esta validação ocorre tanto em sandbox quanto em produção.

Códigos de Erro

Bad Request
Dados inválidos na requisição (RENAVAM inválido, campos obrigatórios ausentes, etc.)
Unauthorized
API Key inválida ou ausente
Not Found
Veículo não encontrado nos sistemas do Detran
Too Many Requests
Limite de requisições excedido
Server Error
Erro interno do servidor
Service Unavailable
Serviço do Detran temporariamente indisponível

Códigos de Erro Específicos

Boas Práticas

1

Configure Webhooks

Configure corretamente sua URL de webhook para receber os resultados das consultas. Veja Configuração de Webhooks.
2

Use externalId

Sempre envie um externalId único para rastrear a consulta no seu sistema e correlacionar com o webhook recebido.
3

Valide os Dados

Valide placa, RENAVAM e CPF/CNPJ antes de enviar para evitar erros desnecessários.
4

Trate Dependências

Ao processar débitos, respeite os campos dependsOn e distinct para garantir pagamentos corretos.
5

Implemente Retry

Em caso de erro 503 (serviço indisponível), implemente retry com backoff exponencial.
6

Cache Inteligente

Considere cachear resultados por algumas horas para evitar consultas duplicadas do mesmo veículo.

Exemplo Completo de Integração

Próximos Passos

Configurar Webhooks

Configure webhooks para receber os resultados das consultas.

Fluxo Completo

Veja o fluxo completo incluindo pagamento dos débitos.

Enriquecimento de Placa

Consulte dados do veículo antes de buscar débitos.

Autenticação

Entenda como autenticar suas requisições.