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

# Criar Checkout

> Cria um checkout para pagamento de débitos veiculares

## Descrição

Cria um checkout para pagamento de débitos veiculares. O checkout agrupa os débitos selecionados e gera um identificador único que será usado no processamento do pagamento.

<Info>
  **Validade**: O checkout é válido por 24 horas após a criação. Após este período, será necessário criar um novo checkout.
</Info>

## Fluxo de Uso

<Steps>
  <Step title="Consultar Débitos">
    Primeiro, consulte os débitos do veículo via POST `/uvvi/v1/debts`.
  </Step>

  <Step title="Selecionar Débitos">
    Permita que o cliente escolha quais débitos deseja pagar.
  </Step>

  <Step title="Criar Checkout">
    Crie o checkout com os débitos selecionados usando este endpoint.
  </Step>

  <Step title="Processar Pagamento">
    Use o `checkoutId` retornado para processar o pagamento.
  </Step>
</Steps>

## Seleção de Débitos

### Débitos Obrigatórios

Alguns débitos são **obrigatórios** e devem ser pagos em conjunto:

* **IPVA**: Deve ser pago junto com o licenciamento
* **Licenciamento**: Pode ter débitos dependentes
* **Multas**: Algumas multas são pré-requisitos para o licenciamento

<Warning>
  **Atenção aos Dependentes**: Consulte a [documentação de débitos dependentes](/debitos-dependentes) para entender as regras de dependência entre débitos.
</Warning>

### Validação de Débitos

A API valida automaticamente:

* Se todos os débitos obrigatórios estão incluídos
* Se os débitos pertencem ao mesmo veículo
* Se os débitos ainda estão válidos e não foram pagos
* Se os valores correspondem aos débitos consultados

## Campo externalId

<Tip>
  **Rastreabilidade**: Use o campo `externalId` (UUID) para rastrear o checkout no seu sistema e correlacionar com webhooks futuros.
</Tip>

```javascript theme={null}
const externalId = crypto.randomUUID(); // Gera UUID v4

const checkout = await criarCheckout({
  debts: debitosSelecionados,
  customer: dadosCliente,
  externalId: externalId // Use o mesmo ID para rastreamento
});
```

## Dados do Cliente

Os dados do cliente são necessários para:

* Emissão de nota fiscal
* Envio de comprovantes por e-mail
* Validação antifraude
* Comunicação sobre o status do pagamento

### Campos Obrigatórios

* **name**: Nome completo do cliente
* **email**: E-mail válido para envio de comprovantes
* **cpfCnpj**: CPF ou CNPJ (apenas números)

<Note>
  O CPF/CNPJ informado deve corresponder ao proprietário do veículo ou pessoa autorizada a pagar os débitos.
</Note>

## Estrutura do Checkout

### Débitos

Cada débito deve conter:

```json theme={null}
{
  "id": "debt_123abc",
  "amount": 206.86
}
```

* **id**: Identificador do débito retornado na consulta
* **amount**: Valor do débito (para validação)

### Cliente

```json theme={null}
{
  "name": "João da Silva",
  "email": "joao@example.com",
  "cpfCnpj": "12345678900"
}
```

## Exemplo de Uso Completo

```javascript theme={null}
// 1. Após consultar débitos e receber via webhook
const debitos = webhookData.debts;

// 2. Cliente seleciona quais débitos pagar
const debitosSelecionados = debitos.filter(d => 
  clienteEscolheu.includes(d.id)
);

// 3. Criar checkout
const response = await fetch('https://api.uvvipague.com.br/uvvi/v1/checkout', {
  method: 'POST',
  headers: {
    'x-api-key': 'sua-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    debts: debitosSelecionados.map(d => ({
      id: d.id,
      amount: d.amount
    })),
    customer: {
      name: 'João da Silva',
      email: 'joao@example.com',
      cpfCnpj: '12345678900'
    },
    externalId: crypto.randomUUID()
  })
});

const { data } = await response.json();

// 4. Usar checkoutId no pagamento
console.log(`Checkout criado: ${data.checkoutId}`);
console.log(`Total: R$ ${data.totalAmount}`);
console.log(`Expira em: ${data.expiresAt}`);
```

## Resposta do Checkout

A resposta contém:

* **checkoutId**: ID único do checkout para usar no pagamento
* **totalAmount**: Valor total de todos os débitos selecionados
* **expiresAt**: Data/hora de expiração do checkout (24 horas)

```json theme={null}
{
  "success": true,
  "data": {
    "checkoutId": "chk_abc123xyz",
    "totalAmount": 1302.86,
    "expiresAt": "2024-01-16T14:30:00Z"
  }
}
```

## Expiração do Checkout

<Warning>
  **Checkout Expirado**: Se tentar processar um pagamento com um checkout expirado, você receberá um erro 422. Neste caso, crie um novo checkout.
</Warning>

### Renovar Checkout

Se o checkout expirar antes do pagamento:

```javascript theme={null}
// Verificar se checkout expirou
const agora = new Date();
const expiracao = new Date(checkout.expiresAt);

if (agora > expiracao) {
  console.log('Checkout expirado, criando novo...');
  const novoCheckout = await criarCheckout(mesmosDebitos);
}
```

## Códigos de Resposta HTTP

### 200 - Sucesso

Checkout criado com sucesso. Use o `checkoutId` para processar o pagamento.

### 400 - Bad Request

Dados inválidos na requisição. Possíveis motivos:

* Débitos inválidos ou não encontrados
* Valores não correspondem aos débitos
* Dados do cliente inválidos (CPF/CNPJ, e-mail)
* Débitos obrigatórios faltando

### 422 - Unprocessable Entity

Dados válidos mas não podem ser processados:

* Débitos já foram pagos
* Débitos de veículos diferentes
* Dependências de débitos não satisfeitas
* Checkout duplicado (mesmo externalId)

## Validação de Dependências

Antes de criar o checkout, valide as dependências:

```javascript theme={null}
function validarDependencias(debitos, debitosSelecionados) {
  for (const debito of debitosSelecionados) {
    if (debito.dependencies && debito.dependencies.length > 0) {
      const dependenciasFaltando = debito.dependencies.filter(depId => 
        !debitosSelecionados.find(d => d.id === depId)
      );
      
      if (dependenciasFaltando.length > 0) {
        throw new Error(
          `Débito ${debito.description} requer: ${dependenciasFaltando.join(', ')}`
        );
      }
    }
  }
  return true;
}
```

## Interface de Usuário

### Boas Práticas

<AccordionGroup>
  <Accordion title="Mostre o Total Claramente" icon="calculator">
    Exiba o valor total antes de criar o checkout:

    ```jsx theme={null}
    <div className="checkout-summary">
      <h3>Resumo do Pagamento</h3>
      <ul>
        {debitosSelecionados.map(d => (
          <li key={d.id}>
            {d.description}: R$ {d.amount.toFixed(2)}
          </li>
        ))}
      </ul>
      <strong>Total: R$ {total.toFixed(2)}</strong>
    </div>
    ```
  </Accordion>

  <Accordion title="Indique Débitos Obrigatórios" icon="exclamation-triangle">
    Marque visualmente débitos que devem ser pagos juntos:

    ```jsx theme={null}
    {debito.required && (
      <Badge color="red">Obrigatório</Badge>
    )}
    ```
  </Accordion>

  <Accordion title="Valide Antes de Enviar" icon="check-circle">
    Valide no frontend antes de criar o checkout:

    ```javascript theme={null}
    if (!validarEmail(customer.email)) {
      alert('E-mail inválido');
      return;
    }

    if (!validarCPF(customer.cpfCnpj)) {
      alert('CPF/CNPJ inválido');
      return;
    }
    ```
  </Accordion>

  <Accordion title="Mostre Tempo de Expiração" icon="clock">
    Informe ao cliente sobre a validade do checkout:

    ```jsx theme={null}
    <Alert>
      Este checkout expira em 24 horas.
      Conclua o pagamento antes de {formatarData(expiresAt)}.
    </Alert>
    ```
  </Accordion>
</AccordionGroup>

## Próximos Passos

Após criar o checkout:

<CardGroup cols={2}>
  <Card title="Tokenizar Cartão" icon="credit-card" href="/api-reference/endpoint/card-token">
    Tokenize o cartão do cliente de forma segura
  </Card>

  <Card title="Simular Parcelas" icon="calculator" href="/api-reference/endpoint/installments">
    Simule opções de parcelamento para o valor total
  </Card>

  <Card title="Processar Pagamento" icon="money-bill-wave" href="/api-reference/endpoint/payment">
    Efetue o pagamento usando o checkoutId
  </Card>

  <Card title="Débitos Dependentes" icon="link" href="/debitos-dependentes">
    Entenda as regras de dependência entre débitos
  </Card>
</CardGroup>

## Suporte

<Card title="Dúvidas sobre Checkout?" icon="headset" href="mailto:suporte@uvvipague.com.br">
  Entre em contato para esclarecer dúvidas sobre criação de checkout e validação de débitos.
</Card>


## OpenAPI

````yaml POST /uvvi/v1/checkout
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/checkout:
    post:
      tags:
        - Pagamentos
      summary: Criar Checkout
      description: Cria um checkout para pagamento de débitos veiculares
      operationId: createCheckout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: Checkout criado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CheckoutRequest:
      type: object
      required:
        - debts
        - customer
      properties:
        debts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: debt_123abc
              amount:
                type: number
                example: 206.86
        customer:
          type: object
          properties:
            name:
              type: string
              example: João da Silva
            email:
              type: string
              example: joao@example.com
            cpfCnpj:
              type: string
              example: '12345678900'
        externalId:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
    CheckoutResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            checkoutId:
              type: string
              example: chk_abc123xyz
            totalAmount:
              type: number
              example: 1302.86
            expiresAt:
              type: string
              format: date-time
              example: '2024-01-15T23:59:59Z'
    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

````