> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipague.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar Débitos

> Consulta débitos pendentes de um veículo (multas, IPVA, licenciamento, taxas). Processamento assíncrono com retorno via webhook.

## Descrição

Consulta débitos pendentes de um veículo incluindo multas, IPVA, licenciamento e taxas diversas.

<Warning>
  Este endpoint processa a consulta de forma **assíncrona**. Os resultados serão enviados via webhook quando a consulta for concluída.
</Warning>

## 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

<Info>
  O campo `externalId` é **altamente recomendado**. Use um UUID único para rastrear a consulta e correlacionar com os webhooks recebidos.
</Info>

## Códigos de Resposta HTTP

### 200 - Sucesso

Consulta iniciada com sucesso. Aguarde o webhook com os resultados.

```json theme={null}
{
  "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)

<Note>
  Consulte a [documentação de ENUMs](/enums-tipos#search-response-type) para detalhes sobre cada tipo.
</Note>

## 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`


## OpenAPI

````yaml POST /uvvi/v1/debts
openapi: 3.1.0
info:
  title: Uvvipague API
  description: >-
    API completa para consulta e pagamento de débitos veiculares em todo o
    Brasil
  version: 1.0.0
  contact:
    name: Suporte Uvvipague
    email: suporte@uvvipague.com.br
    url: https://uvvipague.com.br
servers:
  - url: https://api.uvvipague.com.br
    description: Servidor de Produção
  - url: https://api-sandbox.uvvipague.com.br
    description: Servidor de Homologação/Sandbox
security:
  - apiKey: []
tags:
  - name: Veículos
    description: Endpoints para consulta e enriquecimento de informações de veículos
  - name: Débitos
    description: Endpoints para consulta de débitos veiculares
  - name: Pagamentos
    description: Endpoints para processamento de pagamentos
  - name: Webhooks
    description: Endpoints para configuração e gerenciamento de webhooks
paths:
  /uvvi/v1/debts:
    post:
      tags:
        - Débitos
      summary: Consultar Débitos Veiculares
      description: >-
        Consulta débitos pendentes de um veículo (multas, IPVA, licenciamento,
        taxas). Processamento assíncrono com retorno via webhook.
      operationId: getVehicleDebts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DebtsRequest'
      responses:
        '200':
          description: >-
            Consulta iniciada com sucesso. Resultados serão enviados via
            webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebtsInitialResponse'
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DebtsRequest:
      type: object
      required:
        - state
        - licensePlate
        - renavam
        - cpfCnpj
      properties:
        state:
          type: string
          description: Sigla do estado (UF)
          example: DF
        licensePlate:
          type: string
          description: Placa do veículo
          example: JFI8753
        renavam:
          type: string
          description: Número do RENAVAM (11 dígitos)
          example: '56387604559'
        cpfCnpj:
          type: string
          description: CPF ou CNPJ do proprietário (apenas números)
          example: '11111111111'
        externalId:
          type: string
          description: Identificador único (UUID) para rastreamento
          example: 550e8400-e29b-41d4-a716-446655440000
    DebtsInitialResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Consulta de débitos iniciada com sucesso
        requestId:
          type: string
          example: req_abc123xyz
        externalId:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          example: PROCESSING
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - UNAUTHORIZED
                - NOT_FOUND
                - VALIDATION_ERROR
                - RATE_LIMIT_EXCEEDED
                - SERVICE_UNAVAILABLE
              example: INVALID_REQUEST
              description: Código do erro
            message:
              type: string
              example: Parâmetros inválidos na requisição
            details:
              type: object
              description: Detalhes adicionais sobre o erro
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key fornecida no painel administrativo da Uvvipague

````