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

# Cupons de Desconto

> Sistema completo de cupons com desconto fixo ou percentual. Configure limites de uso, validade e produtos aplicáveis

## Visão geral

O sistema de **Cupons de Desconto** permite que você crie e gerencie cupons promocionais que podem ser aplicados durante o checkout. Os cupons suportam descontos percentuais ou valores fixos, com configurações flexíveis de validade e limites de uso.

## Pré-requisitos

Antes de começar, você precisa:

* Uma conta ativa na Alpa
* Sua API Key configurada (veja [Autenticação](/pages/authentication))
* Conhecimento básico de APIs REST

## Funcionalidades

* **Tipos de desconto**: Percentual (%) ou valor fixo (R\$)
* **Validade configurável**: Data de início e fim no formato ISO 8601
* **Limites de uso**: Total de usos e por usuário (null = ilimitado)
* **Valor mínimo**: Defina valor mínimo de compra em centavos
* **Valor máximo**: Limite o desconto máximo em centavos (apenas para percentuais)
* **Produtos específicos**: Aplique a todos os produtos ou apenas produtos selecionados
* **Validação pública**: Endpoint público (sem autenticação) para validar cupons no checkout

## Criando um cupom

### Requisição Básica - Desconto Percentual

```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/coupons" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DESCONTO10",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "description": "10% de desconto em qualquer compra"
  }'
```

### Requisição - Desconto Fixo

```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/coupons" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "R$50OFF",
    "discountType": "FIXED",
    "discountValue": 5000,
    "description": "R$ 50,00 de desconto"
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "DESCONTO10",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "description": "10% de desconto em qualquer compra",
    "minPurchaseCents": null,
    "maxDiscountCents": null,
    "usageLimit": null,
    "perUserLimit": null,
    "validFrom": null,
    "validUntil": null,
    "productIds": [],
    "status": "ACTIVE",
    "usedCount": 0,
    "createdAt": "2025-12-30T00:00:00.000Z"
  }
}
```

## Campos disponíveis

### Campos obrigatórios

| Campo           | Tipo   | Descrição                                                                                                                             |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `code`          | string | Código único do cupom. Máximo 50 caracteres. Apenas letras, números e hífen.                                                          |
| `discountType`  | string | Tipo de desconto. Valores: "PERCENTAGE" ou "FIXED".                                                                                   |
| `discountValue` | number | Valor do desconto. Para PERCENTAGE: valor percentual (ex: 10 = 10%). Para FIXED: valor em centavos (ex: 5000 = R\$ 50,00). Mínimo: 1. |

### Campos opcionais

| Campo              | Tipo   | Descrição                                                                      | Padrão   |
| ------------------ | ------ | ------------------------------------------------------------------------------ | -------- |
| `description`      | string | Descrição do cupom. Máximo 500 caracteres.                                     | -        |
| `minPurchaseCents` | number | Valor mínimo de compra em centavos. Mínimo: 0.                                 | null     |
| `maxDiscountCents` | number | Valor máximo de desconto em centavos. Apenas para PERCENTAGE. Mínimo: 1.       | null     |
| `usageLimit`       | number | Limite total de usos do cupom. null = ilimitado. Mínimo: 1.                    | null     |
| `perUserLimit`     | number | Limite de usos por usuário. null = ilimitado. Mínimo: 1.                       | null     |
| `validFrom`        | string | Data de início da validade. Formato ISO 8601. Exemplo: "2024-01-01T00:00:00Z". | null     |
| `validUntil`       | string | Data de fim da validade. Formato ISO 8601. Deve ser posterior a `validFrom`.   | null     |
| `productIds`       | array  | Array de IDs de produtos aplicáveis. Vazio ou null = todos os produtos.        | \[]      |
| `status`           | string | Status do cupom. Valores: "ACTIVE" ou "INACTIVE".                              | "ACTIVE" |

## 📖 Exemplos Completos

### Cupom Simples - 10% de Desconto

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/coupons', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'PROMO10',
    discountType: 'PERCENTAGE',
    discountValue: 10,
    description: '10% de desconto em qualquer compra'
  })
});
```

### Cupom com Validade e Limites

```javascript theme={null}
const validFrom = new Date();
const validUntil = new Date();
validUntil.setDate(validUntil.getDate() + 30); // Válido por 30 dias

const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/coupons', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'BLACKFRIDAY',
    discountType: 'PERCENTAGE',
    discountValue: 25,
    description: 'Black Friday - 25% de desconto',
    minPurchaseCents: 10000, // Mínimo R$ 100,00
    maxDiscountCents: 50000, // Máximo R$ 500,00 de desconto
    usageLimit: 1000, // Máximo 1000 usos totais
    perUserLimit: 1, // 1 uso por usuário
    validFrom: validFrom.toISOString(),
    validUntil: validUntil.toISOString()
  })
});
```

### Cupom para Produtos Específicos

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/coupons', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'PRODUTOESPECIAL',
    discountType: 'FIXED',
    discountValue: 2000, // R$ 20,00 de desconto
    description: 'R$ 20,00 de desconto em produtos selecionados',
    productIds: [
      'produto-1-id',
      'produto-2-id'
    ]
  })
});
```

## Validando um cupom

### Endpoint Público (Checkout)

O endpoint de validação é **público** e não requer autenticação. Use-o no checkout para validar cupons:

```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/coupons/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DESCONTO10",
    "amountCents": 10000
  }'
```

### Resposta - Cupom Válido

```json theme={null}
{
  "success": true,
  "valid": true,
  "data": {
    "code": "DESCONTO10",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "discountAmount": 1000,
    "finalAmount": 9000,
    "description": "10% de desconto em qualquer compra"
  }
}
```

### Resposta - Cupom Inválido

```json theme={null}
{
  "success": false,
  "valid": false,
  "message": "Cupom não encontrado ou inválido"
}
```

### Exemplo em JavaScript (Checkout)

```javascript theme={null}
async function validateCoupon(code, amount) {
  const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/coupons/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      code: code,
      amount: amount // Valor em centavos
    })
  });
  
  const data = await response.json();
  
  if (data.valid) {
    console.log(`Desconto: R$ ${(data.data.discountAmount / 100).toFixed(2)}`);
    console.log(`Valor final: R$ ${(data.data.finalAmount / 100).toFixed(2)}`);
    return data.data;
  } else {
    console.error(data.message);
    return null;
  }
}
```

## 🔍 Listando Cupons

### Listar Todos os Cupons

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

### Buscar Cupom Específico

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

## Atualizando um cupom

```bash theme={null}
curl -X PATCH "https://alpa-sistema-api.onrender.com/api/v1/coupons/{id}" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "INACTIVE",
    "usageLimit": 500
  }'
```

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

## 🗑️ Deletando um Cupom

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

<Warning>
  A exclusão é permanente. Cupons já utilizados mantêm o histórico de uso.
</Warning>

## Regras de validação

O sistema valida automaticamente:

1. **Código válido**: O cupom existe e está ativo
2. **Validade**: Data atual está entre `validFrom` e `validUntil`
3. **Limites de uso**: Não excedeu `usageLimit` e `perUserLimit`
4. **Valor mínimo**: Compra atinge `minPurchaseCents`
5. **Produtos aplicáveis**: Produto está na lista `productIds` (se especificado)
6. **Desconto máximo**: Para percentuais, respeita `maxDiscountCents`

## 🎯 Casos de Uso

### Promoções Temporárias

Crie cupons com validade limitada para campanhas específicas.

### Descontos por Volume

Configure valor mínimo de compra para incentivar compras maiores.

### Cupons Exclusivos

Use limites de uso para criar cupons exclusivos ou limitados.

### Produtos Específicos

Aplique descontos apenas a produtos selecionados do catálogo.

### Primeira Compra

Configure `perUserLimit: 1` para cupons de primeira compra.

## Próximos passos

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

  <Card title="Links de Pagamento" icon="link" href="/pages/guides/features/payment-links">
    Integre cupons no checkout
  </Card>
</CardGroup>