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:Endpoint
Parâmetros da Requisição
Sigla do estado (UF) onde o veículo está registrado. Exemplo:
SP, RJ, MGPlaca do veículo no formato ABC1234 ou ABC1D23 (Mercosul)
Número do RENAVAM do veículo (11 dígitos)
CPF ou CNPJ do proprietário do veículo (apenas números)
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:Identificador único do débito (UUID)
Valor do débito em reais
Título descritivo do débito
Descrição detalhada do débito
Tipo do débito:
ticket (multa), ipva, licensing (licenciamento), service (taxa)Data de vencimento original (formato ISO 8601)
Data de vencimento com juros/multa (formato ISO 8601)
Indica se o débito possui desconto disponível
Indica se o débito está vencido
Ano de referência do débito (para IPVA e licenciamento)
Indica se o débito é obrigatório para licenciamento
Lista de IDs de débitos que precisam ser pagos junto com este
Lista de IDs de débitos que não podem ser pagos junto com este
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.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
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:RENAVAM Válido
RENAVAM Válido
RENAVAM Inválido
RENAVAM Inválido
Códigos de Erro
Dados inválidos na requisição (RENAVAM inválido, campos obrigatórios ausentes, etc.)
API Key inválida ou ausente
Veículo não encontrado nos sistemas do Detran
Limite de requisições excedido
Erro interno do servidor
Serviço do Detran temporariamente indisponível
Códigos de Erro Específicos
| Código | Descrição |
|---|---|
| 900 | Serviço indisponível |
| 901 | Timeout na consulta ao Detran |
| 902 | Dados inconsistentes retornados pelo Detran |
| 903 | Manutenção programada do Detran |
Boas Práticas
Configure Webhooks
Configure corretamente sua URL de webhook para receber os resultados das consultas. Veja Configuração de Webhooks.
Use externalId
Sempre envie um
externalId único para rastrear a consulta no seu sistema e correlacionar com o webhook recebido.Trate Dependências
Ao processar débitos, respeite os campos
dependsOn e distinct para garantir pagamentos corretos.Implemente Retry
Em caso de erro 503 (serviço indisponível), implemente retry com backoff exponencial.