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

# Links de pagamento

> Crie links de pagamento personalizados com PIX, cartão e boleto. Configure parcelamento, estoque e URLs de redirecionamento

## Visão geral

Os **Links de pagamento** são URLs personalizadas que você pode criar e compartilhar com seus clientes para receber pagamentos. Cada link pode ser configurado com valores, métodos de pagamento, produtos e muito mais.

## Funcionalidades

* **Slug único**: Cada link tem um identificador único e personalizável
* **Múltiplos métodos de pagamento**: PIX, Cartão de Crédito/Débito, Boleto
* **Produtos**: Associe produtos do seu catálogo ao link
* **Controle de estoque**: Configure quantidade limitada de vendas
* **Parcelamento**: Configure parcelamento até 12x
* **Validade**: Defina data de expiração para o link
* **Meta Pixel**: Integre com Meta Pixel para rastreamento
* **URL de redirecionamento**: Configure para onde redirecionar após pagamento

## Criando seu primeiro link

### Requisição Básica

```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/payment-links" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Produto Premium",
    "description": "Acesso completo à plataforma",
    "amount": 9900,
    "currency": "BRL",
    "settings": {
      "pixEnabled": true,
      "creditCardEnabled": true,
      "boletoEnabled": false,
      "maxInstallments": 12
    }
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "produto-premium-abc123",
    "title": "Produto Premium",
    "description": "Acesso completo à plataforma",
    "amount": 9900,
    "currency": "BRL",
    "status": "ACTIVE",
    "createdAt": "2025-12-30T00:00:00.000Z",
    "updatedAt": "2025-12-30T00:00:00.000Z"
  }
}
```

<Note>
  A URL pública do checkout é montada a partir do `slug`: `https://checkout.usealpa.com/pay/{slug}`.
</Note>

## Campos disponíveis

### Campos obrigatórios

| Campo   | Tipo   | Descrição                                           |
| ------- | ------ | --------------------------------------------------- |
| `title` | string | Título do link de pagamento. Máximo 255 caracteres. |

### Campos opcionais

| Campo                | Tipo    | Descrição                                                                  | Padrão   |
| -------------------- | ------- | -------------------------------------------------------------------------- | -------- |
| `description`        | string  | Descrição detalhada do link. Máximo 1000 caracteres.                       | -        |
| `amount`             | number  | Valor em centavos. Exemplo: 9900 = R$ 99,00. Mínimo: 100 (R$ 1,00).        | -        |
| `currency`           | string  | Código da moeda. Atualmente apenas "BRL" é suportado.                      | "BRL"    |
| `expiresAt`          | string  | Data de expiração no formato ISO 8601. Exemplo: "2024-12-31T23:59:59Z".    | null     |
| `redirectUrl`        | string  | URL completa para redirecionar após pagamento. Deve começar com https\://. | -        |
| `productDescription` | string  | Descrição adicional do produto. Máximo 500 caracteres.                     | -        |
| `stockQuantity`      | number  | Quantidade disponível em estoque. 0 = ilimitado. Mínimo: 0.                | 0        |
| `stockEnabled`       | boolean | Ativa controle de estoque. Se true, `stockQuantity` é obrigatório.         | false    |
| `metaPixelCode`      | string  | ID do Meta Pixel para rastreamento. Formato: números apenas.               | -        |
| `status`             | string  | Status do link. Valores: "ACTIVE" ou "INACTIVE".                           | "ACTIVE" |

### Configurações de pagamento (`settings`)

O objeto `settings` permite configurar métodos de pagamento e comportamentos do checkout.

| Campo                      | Tipo    | Descrição                                         | Padrão |
| -------------------------- | ------- | ------------------------------------------------- | ------ |
| `pixEnabled`               | boolean | Habilita pagamento via PIX.                       | true   |
| `boletoEnabled`            | boolean | Habilita pagamento via Boleto.                    | false  |
| `creditCardEnabled`        | boolean | Habilita pagamento via Cartão de Crédito.         | true   |
| `maxInstallments`          | number  | Número máximo de parcelas. Mínimo: 1, Máximo: 12. | 1      |
| `interestFreeInstallments` | number  | Parcelas sem juros. Deve ser ≤ `maxInstallments`. | 1      |
| `interestRate`             | number  | Taxa de juros mensal (%).                         | 0      |
| `requirePhone`             | boolean | Exige telefone no checkout.                       | true   |
| `requireAddress`           | boolean | Exige endereço completo no checkout.              | false  |

**Exemplo:**

```json theme={null}
{
  "settings": {
    "pixEnabled": true,
    "boletoEnabled": false,
    "creditCardEnabled": true,
    "maxInstallments": 12,
    "interestFreeInstallments": 3,
    "interestRate": 2.5,
    "requirePhone": true,
    "requireAddress": true
  }
}
```

### Personalização do Checkout (`checkoutConfig`)

O campo `checkoutConfig` permite personalizar a aparência e o comportamento visual do checkout (White-label).

#### Tema (`theme`)

| Campo          | Tipo   | Descrição                                                 |
| -------------- | ------ | --------------------------------------------------------- |
| `primaryColor` | string | Cor principal em Hexadecimal (ex: `#FF3D02`).             |
| `logoUrl`      | string | URL da logomarca da sua empresa.                          |
| `buttonText`   | string | Texto personalizado para o botão de pagamento.            |
| `bannerUrl`    | string | URL da imagem do banner de topo.                          |
| `bannerLayout` | string | Layout do banner: `full`, `contained`, `compact`, `none`. |
| `fontFamily`   | string | Fonte: `default` (sans), `serif`, `mono`.                 |
| `borderRadius` | string | Cantos: `square`, `default`, `rounded`.                   |
| `colorScheme`  | string | Esquema: `light`, `dark`, `system`.                       |

#### Componentes e Blocos

| Campo             | Tipo    | Descrição                                     |
| ----------------- | ------- | --------------------------------------------- |
| `showHeader`      | boolean | Exibe/oculta o cabeçalho com logo.            |
| `showPoweredBy`   | boolean | Se `false`, remove a marca "Powered by Alpa". |
| `showSocialProof` | boolean | Exibe depoimentos/prova social configurados.  |
| `showTermsFooter` | boolean | Exibe links de Termos e Privacidade.          |

**Exemplo Completo:**

```json theme={null}
{
  "checkoutConfig": {
    "theme": {
      "primaryColor": "#000000",
      "fontFamily": "serif",
      "bannerLayout": "compact",
      "borderRadius": "square"
    },
    "showHeader": true,
    "showPoweredBy": false,
    "showTermsFooter": true,
    "termsUrl": "https://meusite.com/termos"
  }
}
```

### Associando Produtos

```json theme={null}
{
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ]
}
```

<Note>
  Quando produtos são associados, o valor total é calculado automaticamente baseado nos preços dos produtos e quantidades.
</Note>

## 📖 Exemplos Completos

### Link Simples com PIX e Cartão

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Curso Online',
    description: 'Acesso completo ao curso por 1 ano',
    amount: 19900, // R$ 199,00
    currency: 'BRL',
    settings: {
      pixEnabled: true,
      creditCardEnabled: true,
      maxInstallments: 6,
      interestFreeInstallments: 3
    }
  })
});
```

### Link com Produtos e Estoque

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Pacote Premium',
    description: 'Inclui 3 produtos do catálogo',
    products: [
      { productId: 'produto-1-id', quantity: 1 },
      { productId: 'produto-2-id', quantity: 2 }
    ],
    stockQuantity: 50,
    stockEnabled: true,
    settings: {
      pixEnabled: true,
      creditCardEnabled: true,
      boletoEnabled: true
    }
  })
});
```

### Link com Expiração e Redirecionamento

```javascript theme={null}
const expiresAt = new Date();
expiresAt.setDate(expiresAt.getDate() + 30); // Expira em 30 dias

const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Oferta Especial',
    description: 'Válido apenas este mês',
    amount: 9900,
    expiresAt: expiresAt.toISOString(),
    redirectUrl: 'https://meusite.com.br/obrigado',
    settings: {
      pixEnabled: true,
      creditCardEnabled: true
    }
  })
});
```

## Listando links

### Listar Todos os Links

```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/payment-links?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"
```

### Buscar Link Específico

```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/payment-links/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"
```

## Atualizando um link

```bash theme={null}
curl -X PATCH "https://alpa-sistema-api.onrender.com/api/v1/payment-links/{id}" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Novo Título",
    "status": "INACTIVE"
  }'
```

<Note>
  Você pode atualizar apenas os campos que desejar. Campos não enviados permanecerão inalterados.
</Note>

## 🗑️ Deletando um Link

```bash theme={null}
curl -X DELETE "https://alpa-sistema-api.onrender.com/api/v1/payment-links/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"
```

<Warning>
  A exclusão é permanente e não pode ser desfeita. Certifique-se de que realmente deseja deletar o link.
</Warning>

## URL do checkout

Após criar um link, você receberá uma URL no formato:

```
https://checkout.usealpa.com/pay/{slug}
```

Esta URL pode ser compartilhada diretamente com seus clientes.

## 📊 Status do Link

* `ACTIVE`: Link ativo e disponível para pagamentos
* `INACTIVE`: Link desativado (não aceita novos pagamentos)

## Casos de uso

### E-commerce

Crie links para produtos específicos com controle de estoque e múltiplos métodos de pagamento.

### Assinaturas

Configure links recorrentes com valores e parcelamento adequados.

### Doações

Crie links simples para receber doações via PIX ou cartão.

### Cursos Online

Associe produtos (cursos) aos links e controle o acesso.

## 📚 Próximos Passos

<CardGroup cols={2}>
  <Card title="Referência da API" icon="code" href="/pages/payment-links/reference">
    Veja todos os endpoints disponíveis
  </Card>

  <Card title="Produtos" icon="box" href="/pages/guides/features/products">
    Aprenda a gerenciar produtos
  </Card>

  <Card title="Webhooks" icon="bell" href="/pages/guides/features/webhooks">
    Configure notificações em tempo real
  </Card>
</CardGroup>