Skip to main content
POST
/
uvvi
/
v1
/
debts
Consultar Débitos Veiculares
curl --request POST \
  --url https://api.uvvipague.com.br/uvvi/v1/debts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "state": "DF",
  "licensePlate": "JFI8753",
  "renavam": "56387604559",
  "cpfCnpj": "11111111111",
  "externalId": "550e8400-e29b-41d4-a716-446655440000"
}
'
{
  "success": true,
  "message": "Consulta de débitos iniciada com sucesso",
  "requestId": "req_abc123xyz",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}

​
Descrição

Consulta débitos pendentes de um veículo incluindo multas, IPVA, licenciamento e taxas diversas.
Este endpoint processa a consulta de forma assíncrona. Os resultados serão enviados via webhook quando a consulta for concluída.

​
Fluxo de Processamento

  1. Envie a requisição com os dados do veículo
  2. Receba confirmação imediata de que a consulta foi iniciada
  3. Aguarde o processamento (geralmente 10-30 segundos)
  4. Receba os resultados via webhook configurado

​
Campo externalId

O campo externalId é altamente recomendado. Use um UUID único para rastrear a consulta e correlacionar com os webhooks recebidos.

​
Códigos de Resposta HTTP

​
200 - Sucesso

Consulta iniciada com sucesso. Aguarde o webhook com os resultados. 
{
  "message": "Consulta iniciada com sucesso",
  "transactionId": 817210768,
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}

​
400 - Bad Request

Dados inválidos na requisição:
  • Placa inválida
  • RENAVAM inválido
  • CPF/CNPJ inválido
  • Estado (UF) inválido

​
422 - Unprocessable Entity

Dados válidos mas não podem ser processados:
  • Veículo não encontrado
  • Estado temporariamente indisponível

​
Tipos de Resposta via Webhook

Após o processamento, você receberá um webhook com um dos seguintes tipos:
  • debts: Veículo possui débitos pendentes
  • VehicleWithoutDebts: Veículo sem débitos
  • VehicleNotFound: Veículo não encontrado
  • search-error-event: Erro na consulta (indisponibilidade do Detran)
Consulte a documentação de ENUMs para detalhes sobre cada tipo.

​
Próximos Passos

Após receber os débitos via webhook, você pode:
  • Simular parcelas com /uvvi/v1/installments
  • Criar um checkout com /uvvi/v1/checkout
  • Processar o pagamento com /uvvi/v1/payment

Authorizations

​
x-api-key
string
header
required

API Key fornecida no painel administrativo da Uvvipague

Body

application/json
​
state
string
required

Sigla do estado (UF)

Example:

"DF"

​
licensePlate
string
required

Placa do veículo

Example:

"JFI8753"

​
renavam
string
required

Número do RENAVAM (11 dígitos)

Example:

"56387604559"

​
cpfCnpj
string
required

CPF ou CNPJ do proprietário (apenas números)

Example:

"11111111111"

​
externalId
string

Identificador único (UUID) para rastreamento

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

Consulta iniciada com sucesso. Resultados serão enviados via webhook.

​
success
boolean
Example:

true

​
message
string
Example:

"Consulta de débitos iniciada com sucesso"

​
requestId
string
Example:

"req_abc123xyz"

​
externalId
string
Example:

"550e8400-e29b-41d4-a716-446655440000"

​
status
string
Example:

"PROCESSING"