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

# Fluxo Completo de Pagamento

> Entenda o fluxo completo da Uvvipague: desde a consulta de débitos até o pagamento e liquidação

## Visão Geral

O fluxo completo da Uvvipague permite que o parceiro consulte débitos veiculares e realize o pagamento de forma integrada, com proteção antifraude incluída.

<Info>
  **Antifraude Integrado**: Todos os pagamentos passam pelo sistema antifraude da Uvvipague, garantindo segurança nas transações.
</Info>

## Fluxo de Integração

O processo completo é dividido em duas etapas principais:

<Steps>
  <Step title="Etapa 1: Consulta de Débitos">
    Consulte os dados do veículo e seus débitos pendentes
  </Step>

  <Step title="Etapa 2: Pagamento e Liquidação">
    Tokenize o cartão, gere o checkout e efetue o pagamento
  </Step>
</Steps>

## Etapa 1: Consulta de Débitos

Nesta etapa, você consulta as informações do veículo e seus débitos pendentes.

### 1.1 Enriquecer Dados do Veículo (Opcional)

Primeiro, você pode enriquecer os dados do veículo usando apenas a placa:

```http theme={null}
GET /api/v1/vehicle/enrichment/{licensePlate}
```

<ParamField path="licensePlate" type="string" required>
  Placa do veículo no formato ABC1234 ou ABC1D23 (Mercosul)
</ParamField>

<ParamField query="uf" type="string">
  Sigla do estado (opcional, mas recomendado para otimizar a consulta)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234?uf=SP' \
    --header 'x-api-key: SUA_API_KEY_AQUI' \
    --header 'Content-Type: application/json'
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'GET',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    }
  };

  fetch('https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234?uf=SP', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/api/v1/vehicle/enrichment/ABC1234"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  params = {
      "uf": "SP"
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()
  print(data)
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "success": true,
  "data": {
    "placa": "ABC1234",
    "renavam": "12345678901",
    "chassi": "9BWZZZ377VT004251",
    "uf": "SP",
    "municipio": "São Paulo",
    "marca": "VOLKSWAGEN",
    "modelo": "GOL 1.0",
    "anoFabricacao": "2020",
    "anoModelo": "2021",
    "cor": "PRATA",
    "combustivel": "FLEX",
    "categoria": "PARTICULAR"
  }
}
```

<Note>
  Este passo é **opcional**. Você pode pular direto para a consulta de débitos se já tiver os dados do veículo (placa, RENAVAM e CPF/CNPJ do proprietário).
</Note>

### 1.2 Consultar Débitos do Veículo

Consulte os débitos pendentes do veículo:

```http theme={null}
POST /uvvi/v1/debts
```

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.uvvipague.com.br/uvvi/v1/debts' \
    --header 'x-api-key: SUA_API_KEY_AQUI' \
    --header 'Content-Type: application/json' \
    --data '{
      "state": "SP",
      "licensePlate": "ABC1234",
      "renavam": "12345678901",
      "cpfCnpj": "12345678900"
    }'
  ```

  ```javascript JavaScript theme={null}
  const requestBody = {
    state: "SP",
    licensePlate: "ABC1234",
    renavam: "12345678901",
    cpfCnpj: "12345678900"
  };

  const options = {
    method: 'POST',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestBody)
  };

  fetch('https://api.uvvipague.com.br/uvvi/v1/debts', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/uvvi/v1/debts"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  payload = {
      "state": "SP",
      "licensePlate": "ABC1234",
      "renavam": "12345678901",
      "cpfCnpj": "12345678900"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "success": true,
  "transactionId": 817210768,
  "debts": [
    {
      "id": "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
      "amount": 293.50,
      "title": "Multa de Trânsito",
      "description": "Infração de velocidade",
      "type": "ticket",
      "dueDate": "2024-01-15",
      "isExpired": true
    },
    {
      "id": "312D6A5F-2B5A-4694-84DA-F640FC01CC74",
      "amount": 1009.36,
      "title": "Licenciamento 2024",
      "description": "Taxa de licenciamento anual",
      "type": "licensing",
      "year": 2024,
      "isExpired": false
    }
  ],
  "totalAmount": 1302.86
}
```

## Etapa 2: Pagamento e Liquidação

Após consultar os débitos, você pode processar o pagamento.

### 2.1 Tokenizar Cartão de Crédito

Antes de processar o pagamento, tokenize os dados do cartão para maior segurança:

```http theme={null}
POST /uvvi/v1/card-token
```

<ParamField body="cardNumber" type="string" required>
  Número do cartão de crédito (apenas números)
</ParamField>

<ParamField body="cardholderName" type="string" required>
  Nome do titular do cartão (como impresso no cartão)
</ParamField>

<ParamField body="expirationDate" type="string" required>
  Data de validade no formato MM/AAAA ou MM/AA
</ParamField>

<ParamField body="cvv" type="string" required>
  Código de segurança (CVV - 3 ou 4 dígitos)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.uvvipague.com.br/uvvi/v1/card-token' \
    --header 'x-api-key: SUA_API_KEY_AQUI' \
    --header 'Content-Type: application/json' \
    --data '{
      "cardNumber": "4111111111111111",
      "cardholderName": "JOAO DA SILVA",
      "expirationDate": "12/2030",
      "cvv": "123"
    }'
  ```

  ```javascript JavaScript theme={null}
  const cardData = {
    cardNumber: "4111111111111111",
    cardholderName: "JOAO DA SILVA",
    expirationDate: "12/2030",
    cvv: "123"
  };

  const options = {
    method: 'POST',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(cardData)
  };

  fetch('https://api.uvvipague.com.br/uvvi/v1/card-token', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/uvvi/v1/card-token"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  payload = {
      "cardNumber": "4111111111111111",
      "cardholderName": "JOAO DA SILVA",
      "expirationDate": "12/2030",
      "cvv": "123"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "success": true,
  "data": {
    "token": "tok_abc123def456ghi789",
    "brand": "visa",
    "lastFourDigits": "1111",
    "expiresAt": "2024-01-16T14:30:00Z"
  }
}
```

<Warning>
  **Segurança**: Nunca armazene dados completos do cartão. Sempre use o token gerado para processar pagamentos.
</Warning>

### 2.2 Simular Parcelas (Opcional)

Antes de criar o checkout, você pode simular as opções de parcelamento disponíveis:

```http theme={null}
POST /uvvi/v1/installments
```

<ParamField body="amount" type="number" required>
  Valor total a ser parcelado em reais
</ParamField>

<ParamField body="paymentMethod" type="string" required>
  Método de pagamento: `credit_card`
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.uvvipague.com.br/uvvi/v1/installments' \
    --header 'x-api-key: SUA_API_KEY_AQUI' \
    --header 'Content-Type: application/json' \
    --data '{
      "amount": 1302.86,
      "paymentMethod": "credit_card"
    }'
  ```

  ```javascript JavaScript theme={null}
  const requestBody = {
    amount: 1302.86,
    paymentMethod: "credit_card"
  };

  const options = {
    method: 'POST',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestBody)
  };

  fetch('https://api.uvvipague.com.br/uvvi/v1/installments', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/uvvi/v1/installments"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  payload = {
      "amount": 1302.86,
      "paymentMethod": "credit_card"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "success": true,
  "amount": 1302.86,
  "installments": [
    {
      "number": 1,
      "installmentAmount": 1342.95,
      "totalAmount": 1342.95,
      "interestRate": 3.08,
      "interestAmount": 40.09
    },
    {
      "number": 2,
      "installmentAmount": 676.49,
      "totalAmount": 1352.98,
      "interestRate": 3.84,
      "interestAmount": 50.12
    },
    {
      "number": 3,
      "installmentAmount": 467.95,
      "totalAmount": 1403.85,
      "interestRate": 7.75,
      "interestAmount": 100.99
    },
    {
      "number": 4,
      "installmentAmount": 363.46,
      "totalAmount": 1453.84,
      "interestRate": 11.59,
      "interestAmount": 150.98
    },
    {
      "number": 5,
      "installmentAmount": 301.18,
      "totalAmount": 1505.90,
      "interestRate": 15.58,
      "interestAmount": 203.04
    },
    {
      "number": 6,
      "installmentAmount": 259.65,
      "totalAmount": 1557.90,
      "interestRate": 19.57,
      "interestAmount": 255.04
    }
  ]
}
```

<Note>
  **Importante**: A simulação mostra todas as opções de parcelamento disponíveis com os valores exatos de juros. Use essas informações para apresentar as opções ao usuário antes de processar o pagamento.
</Note>

<Warning>
  **Atenção**: Todos os pagamentos possuem juros aplicados, incluindo pagamento à vista (1x) e PIX. Sempre apresente o valor total ao usuário de forma transparente.
</Warning>

### 2.3 Gerar Checkout

Crie um checkout com os débitos que serão pagos:

```http theme={null}
POST /uvvi/v1/checkout
```

<ParamField body="debts" type="array" required>
  Lista de IDs dos débitos a serem pagos
</ParamField>

<ParamField body="customer" type="object" required>
  Dados do cliente pagador
</ParamField>

<ParamField body="vehicle" type="object" required>
  Dados do veículo
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.uvvipague.com.br/uvvi/v1/checkout' \
    --header 'x-api-key: SUA_API_KEY_AQUI' \
    --header 'Content-Type: application/json' \
    --data '{
      "debts": [
        "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
        "312D6A5F-2B5A-4694-84DA-F640FC01CC74"
      ],
      "customer": {
        "name": "João da Silva",
        "email": "joao@example.com",
        "cpfCnpj": "12345678900",
        "phone": "11987654321"
      },
      "vehicle": {
        "licensePlate": "ABC1234",
        "renavam": "12345678901",
        "uf": "SP"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const checkoutData = {
    debts: [
      "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
      "312D6A5F-2B5A-4694-84DA-F640FC01CC74"
    ],
    customer: {
      name: "João da Silva",
      email: "joao@example.com",
      cpfCnpj: "12345678900",
      phone: "11987654321"
    },
    vehicle: {
      licensePlate: "ABC1234",
      renavam: "12345678901",
      uf: "SP"
    }
  };

  const options = {
    method: 'POST',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(checkoutData)
  };

  fetch('https://api.uvvipague.com.br/uvvi/v1/checkout', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/uvvi/v1/checkout"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  payload = {
      "debts": [
          "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
          "312D6A5F-2B5A-4694-84DA-F640FC01CC74"
      ],
      "customer": {
          "name": "João da Silva",
          "email": "joao@example.com",
          "cpfCnpj": "12345678900",
          "phone": "11987654321"
      },
      "vehicle": {
          "licensePlate": "ABC1234",
          "renavam": "12345678901",
          "uf": "SP"
      }
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "success": true,
  "checkoutId": "chk_xyz789abc123def456",
  "amount": 1302.86,
  "debts": [
    {
      "id": "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
      "amount": 293.50
    },
    {
      "id": "312D6A5F-2B5A-4694-84DA-F640FC01CC74",
      "amount": 1009.36
    }
  ],
  "expiresAt": "2024-12-15T23:59:59Z"
}
```

### 2.4 Efetuar Pagamento

Realize o pagamento usando cartão de crédito ou PIX:

```http theme={null}
POST /uvvi/v1/payment
```

<Tabs>
  <Tab title="Cartão de Crédito">
    <ParamField body="checkoutId" type="string" required>
      ID do checkout gerado
    </ParamField>

    <ParamField body="paymentMethod" type="string" required>
      Método de pagamento: `credit_card`
    </ParamField>

    <ParamField body="cardToken" type="string" required>
      Token do cartão gerado na tokenização
    </ParamField>

    <ParamField body="installments" type="number" required>
      Número de parcelas (1 para pagamento à vista)
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url 'https://api.uvvipague.com.br/uvvi/v1/payment' \
        --header 'x-api-key: SUA_API_KEY_AQUI' \
        --header 'Content-Type: application/json' \
        --data '{
          "checkoutId": "chk_xyz789abc123def456",
          "paymentMethod": "credit_card",
          "cardToken": "tok_abc123def456ghi789",
          "installments": 1
        }'
      ```

      ```javascript JavaScript theme={null}
      const paymentData = {
        checkoutId: "chk_xyz789abc123def456",
        paymentMethod: "credit_card",
        cardToken: "tok_abc123def456ghi789",
        installments: 1
      };

      const options = {
        method: 'POST',
        headers: {
          'x-api-key': 'SUA_API_KEY_AQUI',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(paymentData)
      };

      fetch('https://api.uvvipague.com.br/uvvi/v1/payment', options)
        .then(response => response.json())
        .then(data => console.log(data))
        .catch(error => console.error('Erro:', error));
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.uvvipague.com.br/uvvi/v1/payment"
      headers = {
          "x-api-key": "SUA_API_KEY_AQUI",
          "Content-Type": "application/json"
      }
      payload = {
          "checkoutId": "chk_xyz789abc123def456",
          "paymentMethod": "credit_card",
          "cardToken": "tok_abc123def456ghi789",
          "installments": 1
      }

      response = requests.post(url, headers=headers, json=payload)
      data = response.json()
      print(data)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="PIX">
    <ParamField body="checkoutId" type="string" required>
      ID do checkout gerado
    </ParamField>

    <ParamField body="paymentMethod" type="string" required>
      Método de pagamento: `pix`
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url 'https://api.uvvipague.com.br/uvvi/v1/payment' \
        --header 'x-api-key: SUA_API_KEY_AQUI' \
        --header 'Content-Type: application/json' \
        --data '{
          "checkoutId": "chk_xyz789abc123def456",
          "paymentMethod": "pix"
        }'
      ```

      ```javascript JavaScript theme={null}
      const paymentData = {
        checkoutId: "chk_xyz789abc123def456",
        paymentMethod: "pix"
      };

      const options = {
        method: 'POST',
        headers: {
          'x-api-key': 'SUA_API_KEY_AQUI',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(paymentData)
      };

      fetch('https://api.uvvipague.com.br/uvvi/v1/payment', options)
        .then(response => response.json())
        .then(data => console.log(data))
        .catch(error => console.error('Erro:', error));
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.uvvipague.com.br/uvvi/v1/payment"
      headers = {
          "x-api-key": "SUA_API_KEY_AQUI",
          "Content-Type": "application/json"
      }
      payload = {
          "checkoutId": "chk_xyz789abc123def456",
          "paymentMethod": "pix"
      }

      response = requests.post(url, headers=headers, json=payload)
      data = response.json()
      print(data)
      ```
    </CodeGroup>

    **Resposta PIX:**

    ```json theme={null}
    {
      "success": true,
      "paymentId": "pay_pix123abc456def",
      "status": "awaiting_payment",
      "qrCode": "00020126580014br.gov.bcb.pix...",
      "qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
      "expiresAt": "2024-12-15T18:30:00Z"
    }
    ```
  </Tab>
</Tabs>

**Resposta Cartão de Crédito:**

```json theme={null}
{
  "success": true,
  "paymentId": "pay_abc123def456ghi789",
  "status": "paid",
  "transactionId": "817210768",
  "amount": 1302.86,
  "installments": 1,
  "paidAt": "2024-12-15T14:30:00Z"
}
```

## Status de Pagamento

### Status Imediatos (Cartão de Crédito)

Ao processar pagamento com cartão, os seguintes status são retornados imediatamente:

<CardGroup cols={2}>
  <Card title="paid" icon="circle-check">
    **Pago**: Transação aprovada e processada com sucesso
  </Card>

  <Card title="in_analysis" icon="magnifying-glass">
    **Em Análise**: Transação em análise pelo antifraude
  </Card>

  <Card title="refused" icon="circle-xmark">
    **Recusado**: Transação recusada pela operadora ou antifraude
  </Card>

  <Card title="processing" icon="spinner">
    **Processando**: Transação sendo processada
  </Card>

  <Card title="awaiting_payment" icon="clock">
    **Aguardando Pagamento**: Aguardando confirmação (comum em PIX)
  </Card>
</CardGroup>

### Todos os Status Possíveis

Para ver a lista completa de status de transações, incluindo status de liquidação, consulte a [documentação de status](/status-transacoes).

### 2.5 Consultar Status do Pedido

Após o pagamento, você pode consultar o status de liquidação:

```http theme={null}
POST /uvvi/v1/payment/status
```

<ParamField body="paymentId" type="string" required>
  ID do pagamento a ser consultado
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.uvvipague.com.br/uvvi/v1/payment/status' \
    --header 'x-api-key: SUA_API_KEY_AQUI' \
    --header 'Content-Type: application/json' \
    --data '{
      "paymentId": "pay_abc123def456ghi789"
    }'
  ```

  ```javascript JavaScript theme={null}
  const requestBody = {
    paymentId: "pay_abc123def456ghi789"
  };

  const options = {
    method: 'POST',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestBody)
  };

  fetch('https://api.uvvipague.com.br/uvvi/v1/payment/status', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/uvvi/v1/payment/status"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  payload = {
      "paymentId": "pay_abc123def456ghi789"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "success": true,
  "paymentId": "pay_abc123def456ghi789",
  "status": "paid",
  "liquidationStatus": "settled",
  "amount": 1302.86,
  "paidAt": "2024-12-15T14:30:00Z",
  "settledAt": "2024-12-16T10:15:00Z",
  "debts": [
    {
      "id": "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF",
      "status": "settled",
      "settledAt": "2024-12-16T10:15:00Z"
    },
    {
      "id": "312D6A5F-2B5A-4694-84DA-F640FC01CC74",
      "status": "settled",
      "settledAt": "2024-12-16T10:15:00Z"
    }
  ]
}
```

## Resumo dos Endpoints

<CardGroup cols={2}>
  <Card title="Enriquecer Veículo" icon="car">
    `GET /api/v1/vehicle/enrichment/{placa}`

    Enriquece dados do veículo pela placa (opcional)
  </Card>

  <Card title="Consultar Débitos" icon="file-invoice">
    `POST /uvvi/v1/debts`

    Consulta débitos pendentes do veículo
  </Card>

  <Card title="Tokenizar Cartão" icon="credit-card">
    `POST /uvvi/v1/card-token`

    Gera token seguro do cartão de crédito
  </Card>

  <Card title="Simular Parcelas" icon="calculator">
    `POST /uvvi/v1/installments`

    Simula opções de parcelamento disponíveis
  </Card>

  <Card title="Gerar Checkout" icon="shopping-cart">
    `POST /uvvi/v1/checkout`

    Cria checkout com débitos selecionados
  </Card>

  <Card title="Efetuar Pagamento" icon="money-bill">
    `POST /uvvi/v1/payment`

    Processa pagamento via cartão ou PIX
  </Card>

  <Card title="Consultar Pagamento" icon="magnifying-glass">
    `POST /uvvi/v1/payment/status`

    Verifica status e liquidação do pagamento
  </Card>
</CardGroup>

## Fluxo Completo - Diagrama

```mermaid theme={null}
sequenceDiagram
    participant P as Parceiro
    participant API as Uvvipague API
    participant AF as Antifraude
    participant D as Detran

    Note over P,D: Etapa 1: Consulta
    P->>API: GET /vehicle/enrichment/{placa} (opcional)
    API->>D: Consulta dados
    D-->>API: Dados do veículo
    API-->>P: Informações do veículo

    P->>API: POST /debts
    API->>D: Consulta débitos
    D-->>API: Lista de débitos
    API-->>P: Débitos pendentes

    Note over P,D: Etapa 2: Pagamento
    P->>API: POST /card-token
    API-->>P: Token do cartão

    P->>API: POST /checkout
    API-->>P: Checkout ID

    P->>API: POST /payment
    API->>AF: Análise antifraude
    AF-->>API: Aprovado/Recusado
    API-->>P: Status do pagamento

    Note over P,D: Verificação
    P->>API: POST /payment/status
    API->>D: Verifica liquidação
    D-->>API: Status de liquidação
    API-->>P: Status completo
```

## Exemplo Completo de Integração

<CodeGroup>
  ```javascript Node.js theme={null}
  const UvvipagueClient = require('./uvvipague-client');

  async function processarPagamentoCompleto() {
    const client = new UvvipagueClient(process.env.UVVIPAGUE_API_KEY);
    
    try {
      // 1. Enriquecer dados do veículo (opcional)
      console.log('1. Enriquecendo dados do veículo...');
      const veiculo = await client.enriquecerVeiculo({
        licensePlate: 'ABC1234',
        uf: 'SP'
      });
      console.log('Veículo:', veiculo.data);
      
      // 2. Consultar débitos
      console.log('2. Consultando débitos...');
      const debitos = await client.consultarDebitos({
        state: 'SP',
        licensePlate: 'ABC1234',
        renavam: veiculo.data.renavam,
        cpfCnpj: '12345678900'
      });
      console.log(`Encontrados ${debitos.debts.length} débitos`);
      console.log(`Total: R$ ${debitos.totalAmount}`);
      
      // 3. Simular parcelas
      console.log('3. Simulando parcelas...');
      const simulacao = await client.simularParcelas({
        amount: debitos.totalAmount,
        paymentMethod: 'credit_card'
      });
      console.log(`Opções de parcelamento: ${simulacao.installments.length}`);
      simulacao.installments.forEach(opt => {
        console.log(`${opt.number}x de R$ ${opt.installmentAmount.toFixed(2)} (total: R$ ${opt.totalAmount.toFixed(2)})`);
      });
      
      // 4. Tokenizar cartão
      console.log('4. Tokenizando cartão...');
      const token = await client.tokenizarCartao({
        cardNumber: '4111111111111111',
        cardholderName: 'JOAO DA SILVA',
        expirationMonth: '12',
        expirationYear: '2025',
        securityCode: '123'
      });
      console.log('Token gerado:', token.cardToken);
      
      // 5. Criar checkout
      console.log('5. Criando checkout...');
      const checkout = await client.criarCheckout({
        debts: debitos.debts.map(d => d.id),
        customer: {
          name: 'João da Silva',
          email: 'joao@example.com',
          cpfCnpj: '12345678900',
          phone: '11987654321'
        },
        vehicle: {
          licensePlate: 'ABC1234',
          renavam: veiculo.data.renavam,
          uf: 'SP'
        }
      });
      console.log('Checkout ID:', checkout.checkoutId);
      
      // 6. Efetuar pagamento
      console.log('6. Efetuando pagamento...');
      const pagamento = await client.efetuarPagamento({
        checkoutId: checkout.checkoutId,
        paymentMethod: 'credit_card',
        cardToken: token.cardToken,
        installments: 1
      });
      console.log('Pagamento ID:', pagamento.paymentId);
      console.log('Status:', pagamento.status);
      
      // 7. Aguardar e consultar status
      console.log('7. Aguardando processamento...');
      await sleep(5000);
      
      const status = await client.consultarPagamento({
        paymentId: pagamento.paymentId
      });
      console.log('Status final:', status.status);
      console.log('Status de liquidação:', status.liquidationStatus);
      
      return {
        success: true,
        paymentId: pagamento.paymentId,
        status: status
      };
      
    } catch (error) {
      console.error('Erro no processamento:', error.message);
      throw error;
    }
  }

  function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  // Executar
  processarPagamentoCompleto()
    .then(result => console.log('Sucesso!', result))
    .catch(error => console.error('Falha:', error));
  ```

  ```python Python theme={null}
  import time
  from uvvipague_client import UvvipagueClient

  def processar_pagamento_completo():
      client = UvvipagueClient(api_key=os.getenv('UVVIPAGUE_API_KEY'))
      
      try:
          # 1. Enriquecer dados do veículo (opcional)
          print('1. Enriquecendo dados do veículo...')
          veiculo = client.enriquecer_veiculo(
              license_plate='ABC1234',
              uf='SP'
          )
          print(f'Veículo: {veiculo["data"]}')
          
          # 2. Consultar débitos
          print('2. Consultando débitos...')
          debitos = client.consultar_debitos(
              state='SP',
              license_plate='ABC1234',
              renavam=veiculo['data']['renavam'],
              cpf_cnpj='12345678900'
          )
          print(f'Encontrados {len(debitos["debts"])} débitos')
          print(f'Total: R$ {debitos["totalAmount"]}')
          
      # 3. Simular parcelas
      print('3. Simulando parcelas...')
      simulacao = client.simular_parcelas(
          amount=debitos['totalAmount'],
          payment_method='credit_card'
      )
      print(f'Opções de parcelamento: {len(simulacao["installments"])}')
      for opt in simulacao['installments']:
          print(f'{opt["number"]}x de R$ {opt["installmentAmount"]:.2f} (total: R$ {opt["totalAmount"]:.2f})')
      
      # 4. Tokenizar cartão
      print('4. Tokenizando cartão...')
      token = client.tokenizar_cartao(
              card_number='4111111111111111',
              cardholder_name='JOAO DA SILVA',
              expiration_month='12',
              expiration_year='2025',
              security_code='123'
          )
          print(f'Token gerado: {token["cardToken"]}')
          
      # 5. Criar checkout
      print('5. Criando checkout...')
      checkout = client.criar_checkout(
              debts=[d['id'] for d in debitos['debts']],
              customer={
                  'name': 'João da Silva',
                  'email': 'joao@example.com',
                  'cpfCnpj': '12345678900',
                  'phone': '11987654321'
              },
              vehicle={
                  'licensePlate': 'ABC1234',
                  'renavam': veiculo['data']['renavam'],
                  'uf': 'SP'
              }
          )
          print(f'Checkout ID: {checkout["checkoutId"]}')
          
      # 6. Efetuar pagamento
      print('6. Efetuando pagamento...')
      pagamento = client.efetuar_pagamento(
              checkout_id=checkout['checkoutId'],
              payment_method='credit_card',
              card_token=token['cardToken'],
              installments=1
          )
          print(f'Pagamento ID: {pagamento["paymentId"]}')
          print(f'Status: {pagamento["status"]}')
          
      # 7. Aguardar e consultar status
      print('7. Aguardando processamento...')
      time.sleep(5)
          
          status = client.consultar_pagamento(
              payment_id=pagamento['paymentId']
          )
          print(f'Status final: {status["status"]}')
          print(f'Status de liquidação: {status["liquidationStatus"]}')
          
          return {
              'success': True,
              'paymentId': pagamento['paymentId'],
              'status': status
          }
          
      except Exception as error:
          print(f'Erro no processamento: {str(error)}')
          raise

  # Executar
  if __name__ == '__main__':
      resultado = processar_pagamento_completo()
      print('Sucesso!', resultado)
  ```
</CodeGroup>

## Processamento Síncrono vs Assíncrono

<Warning>
  **Importante sobre Timeouts**: A API pode retornar respostas de forma síncrona na maioria dos casos, porém, em situações de alta carga ou lentidão nos sistemas dos Detrans, você pode receber um timeout na resposta síncrona.
</Warning>

### Comportamento da API

A API Uvvipague opera em dois modos:

<Tabs>
  <Tab title="Resposta Síncrona (Normal)">
    **Cenário Ideal**: Quando os sistemas estão operando normalmente, você recebe a resposta imediatamente na mesma requisição.

    ```javascript theme={null}
    // Requisição
    const response = await fetch('/uvvi/v1/payment', {
      method: 'POST',
      body: JSON.stringify(paymentData)
    });

    // Resposta imediata
    const result = await response.json();
    console.log(result.status); // 'paid', 'refused', etc.
    ```

    **Status retornados sincronamente:**

    * `paid` - Pagamento aprovado
    * `refused` - Pagamento recusado
    * `in_analysis` - Em análise
    * `processing` - Processando
  </Tab>

  <Tab title="Resposta Assíncrona (Timeout)">
    **Cenário de Timeout**: Se a API não conseguir processar em tempo hábil, você receberá um timeout.

    ```javascript theme={null}
    // Requisição
    try {
      const response = await fetch('/uvvi/v1/payment', {
        method: 'POST',
        body: JSON.stringify(paymentData),
        signal: AbortSignal.timeout(30000) // 30 segundos
      });
      
      const result = await response.json();
      
    } catch (error) {
      if (error.name === 'TimeoutError') {
        console.log('Timeout - aguardar webhook');
        // Aguardar notificação via webhook
      }
    }
    ```

    **Ação recomendada:**

    * Aguarde a notificação via webhook
    * O webhook será enviado quando o processamento for concluído
    * Use o `transactionId` ou `externalId` para correlacionar
  </Tab>
</Tabs>

### Fluxo Recomendado

<Steps>
  <Step title="Envie a Requisição">
    Faça a requisição de pagamento normalmente com timeout adequado de 30-60 segundos.
  </Step>

  <Step title="Trate a Resposta">
    Se receber resposta síncrona, processe o status imediatamente.
  </Step>

  <Step title="Em Caso de Timeout">
    Se ocorrer timeout, não considere como erro. Aguarde o webhook.
  </Step>

  <Step title="Receba o Webhook">
    O webhook será enviado com o status final do pagamento quando o processamento for concluído.
  </Step>

  <Step title="Fallback Manual">
    Se não receber o webhook após as retentativas, consulte manualmente o status usando o endpoint de consulta.
  </Step>
</Steps>

### Exemplo de Implementação

<CodeGroup>
  ```javascript Node.js theme={null}
  async function processarPagamento(paymentData) {
    const timeoutMs = 30000; // 30 segundos
    
    try {
      // Tentar resposta síncrona
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
      
      const response = await fetch('/uvvi/v1/payment', {
        method: 'POST',
        headers: {
          'x-api-key': process.env.API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(paymentData),
        signal: controller.signal
      });
      
      clearTimeout(timeoutId);
      
      const result = await response.json();
      
      // Resposta síncrona recebida
      console.log('Resposta síncrona:', result.status);
      await processarStatusPagamento(result);
      
      return {
        mode: 'sync',
        status: result.status,
        paymentId: result.paymentId
      };
      
    } catch (error) {
      if (error.name === 'AbortError') {
        // Timeout - aguardar webhook
        console.log('Timeout na API - aguardando webhook');
        
        // Salvar no banco como "aguardando webhook"
        await database.payments.create({
          externalId: paymentData.externalId,
          status: 'awaiting_webhook',
          createdAt: new Date()
        });
        
        return {
          mode: 'async',
          status: 'awaiting_webhook',
          message: 'Aguardando confirmação via webhook'
        };
      }
      
      throw error;
    }
  }

  // Handler do webhook
  app.post('/webhook/uvvipague', async (req, res) => {
    // Retornar 200 imediatamente
    res.status(200).json({ received: true });
    
    const { paymentId, status, externalId } = req.body;
    
    // Atualizar status no banco
    await database.payments.update(
      { externalId },
      { 
        status,
        paymentId,
        processedAt: new Date(),
        mode: 'webhook'
      }
    );
    
    console.log(`Pagamento ${paymentId} atualizado via webhook: ${status}`);
  });
  ```

  ```python Python theme={null}
  import asyncio
  import requests
  from datetime import datetime

  async def processar_pagamento(payment_data):
      timeout_seconds = 30
      
      try:
          # Tentar resposta síncrona
          response = requests.post(
              'https://api.uvvipague.com.br/uvvi/v1/payment',
              headers={
                  'x-api-key': os.getenv('API_KEY'),
                  'Content-Type': 'application/json'
              },
              json=payment_data,
              timeout=timeout_seconds
          )
          
          result = response.json()
          
          # Resposta síncrona recebida
          print(f'Resposta síncrona: {result["status"]}')
          await processar_status_pagamento(result)
          
          return {
              'mode': 'sync',
              'status': result['status'],
              'paymentId': result['paymentId']
          }
          
      except requests.Timeout:
          # Timeout - aguardar webhook
          print('Timeout na API - aguardando webhook')
          
          # Salvar no banco como "aguardando webhook"
          database.payments.create({
              'externalId': payment_data['externalId'],
              'status': 'awaiting_webhook',
              'createdAt': datetime.now()
          })
          
          return {
              'mode': 'async',
              'status': 'awaiting_webhook',
              'message': 'Aguardando confirmação via webhook'
          }

  # Handler do webhook
  @app.route('/webhook/uvvipague', methods=['POST'])
  def webhook_uvvipague():
      # Retornar 200 imediatamente
      payload = request.json
      
      payment_id = payload['paymentId']
      status = payload['status']
      external_id = payload['externalId']
      
      # Atualizar status no banco
      database.payments.update(
          {'externalId': external_id},
          {
              'status': status,
              'paymentId': payment_id,
              'processedAt': datetime.now(),
              'mode': 'webhook'
          }
      )
      
      print(f'Pagamento {payment_id} atualizado via webhook: {status}')
      
      return jsonify({'received': True}), 200
  ```
</CodeGroup>

### Boas Práticas

<CardGroup cols={2}>
  <Card title="Configure Timeout Adequado" icon="clock">
    Use timeout de 30-60 segundos para dar tempo de processamento sem travar sua aplicação.
  </Card>

  <Card title="Sempre Configure Webhook" icon="webhook">
    Configure webhooks mesmo que receba resposta síncrona. É seu fallback em caso de timeout.
  </Card>

  <Card title="Use externalId" icon="fingerprint">
    Sempre envie `externalId` único para correlacionar requisições com webhooks.
  </Card>

  <Card title="Status Intermediário" icon="hourglass">
    Salve status intermediário "awaiting\_webhook" quando ocorrer timeout para tracking.
  </Card>
</CardGroup>

<Note>
  **Resumo**: Trate a API como **síncrona por padrão**, mas esteja preparado para **processamento assíncrono via webhook** em caso de timeout. Configure webhooks como parte essencial da integração.
</Note>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Configure webhooks para receber notificações
  </Card>

  <Card title="Autenticação" icon="key" href="/autenticacao">
    Configure sua API Key para começar
  </Card>

  <Card title="ENUMs e Tipos" icon="list" href="/enums-tipos">
    Consulte todos os status e tipos possíveis
  </Card>

  <Card title="Consulta de Débitos" icon="file-invoice" href="/consulta-debitos">
    Entenda o fluxo de consulta de débitos
  </Card>
</CardGroup>