> ## Documentation Index
> Fetch the complete documentation index at: https://fortal-pay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cupons

> Crie, liste, consulte, atualize e remova cupons de desconto.

Cupons representam descontos configurados pelo merchant. Eles podem conceder um percentual ou um valor fixo, possuir período de validade e limitar a quantidade de utilizações.

<CardGroup cols={3}>
  <Card title="Criar cupom" icon="ticket-plus">
    Requer uma API key `FULL_ACCESS`.
  </Card>

  <Card title="Consultar cupons" icon="list">
    Aceita API keys `READ_ONLY` e `FULL_ACCESS`.
  </Card>

  <Card title="Alterar cupons" icon="ticket-check">
    Atualização e remoção exigem uma API key `FULL_ACCESS`.
  </Card>
</CardGroup>

## Tipos de desconto

<Tabs>
  <Tab title="PERCENTAGE">
    `value` representa um percentual inteiro entre `1` e `100`. Para conceder 15% de desconto, envie `15`.
  </Tab>

  <Tab title="FIXED_AMOUNT">
    `value` representa o desconto em centavos. Para conceder R\$ 20,00 de desconto, envie `2000`.
  </Tab>
</Tabs>

## Criar um cupom

### Desconto percentual

```bash theme={null}
curl --request POST 'https://api-sandbox.fortalpay.tech/v1/coupons' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "BEMVINDO10",
    "type": "PERCENTAGE",
    "value": 10,
    "max_uses": 100,
    "starts_at": "2026-08-10",
    "expires_at": "2026-08-31"
  }'
```

### Desconto fixo ilimitado

```bash theme={null}
curl --request POST 'https://api-sandbox.fortalpay.tech/v1/coupons' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "MENOS2000",
    "type": "FIXED_AMOUNT",
    "value": 2000,
    "max_uses": -1
  }'
```

### Campos da criação

| Campo        | Obrigatório | Regra                                                                                                      |
| ------------ | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `code`       | Sim         | Código com até 50 caracteres. É normalizado em letras maiúsculas e deve ser único no merchant.             |
| `type`       | Sim         | `PERCENTAGE` ou `FIXED_AMOUNT`.                                                                            |
| `value`      | Sim         | Percentual inteiro de 1 a 100 ou valor fixo em centavos, conforme o tipo.                                  |
| `max_uses`   | Não         | Limite positivo. Use `null`, omita o campo ou envie `-1` para uso ilimitado.                               |
| `starts_at`  | Não         | Início da validade em `yyyy-MM-dd` (início do dia) ou `yyyy-MM-dd'T'HH:mm:ss`.                             |
| `expires_at` | Não         | Fim da validade em `yyyy-MM-dd` (fim do dia) ou `yyyy-MM-dd'T'HH:mm:ss`; deve ser posterior a `starts_at`. |

A criação retorna HTTP `201`, inicia `used_count` em `0` e define o status como `ACTIVE`.

## Listar cupons

```bash theme={null}
curl --request GET 'https://api-sandbox.fortalpay.tech/v1/coupons?page=0&size=20' \
  --header 'Authorization: ApiKey <api_key>'
```

A listagem retorna somente cupons do merchant autenticado que não foram removidos logicamente, ordenados pela data de criação em ordem decrescente.

## Consultar pelo identificador

```bash theme={null}
curl --request GET 'https://api-sandbox.fortalpay.tech/v1/coupons/<coupon_id>' \
  --header 'Authorization: ApiKey <api_key>'
```

Um identificador inexistente, removido ou pertencente a outro merchant retorna `404`.

## Atualizar um cupom

`PUT /coupons/{id}` realiza uma atualização parcial. Envie somente os campos que precisam mudar.

```bash theme={null}
curl --request PUT 'https://api-sandbox.fortalpay.tech/v1/coupons/<coupon_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 15,
    "max_uses": 200,
    "expires_at": "2026-09-30",
    "status": "ACTIVE"
  }'
```

Todos os campos da criação podem ser atualizados, além de `status`, que aceita `ACTIVE` ou `INACTIVE`. As regras do tipo, valor, período e limite de usos são revalidadas após a alteração.

<Warning>
  O corpo deve conter ao menos um valor não nulo. Atualmente, enviar `null` em `max_uses`, `starts_at` ou `expires_at` não limpa o valor existente; o campo é ignorado. Para tornar o uso ilimitado, envie `max_uses: -1`.
</Warning>

## Quando o cupom pode ser usado

Um cupom somente está disponível quando todas estas condições são atendidas:

* O status é `ACTIVE`.
* A data atual não é anterior a `starts_at`, quando informada.
* A data atual não é posterior a `expires_at`, quando informada.
* `used_count` ainda é menor que `max_uses`, salvo quando o uso é ilimitado.

## Remover um cupom

```bash theme={null}
curl --request DELETE 'https://api-sandbox.fortalpay.tech/v1/coupons/<coupon_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>'
```

A remoção é lógica e retorna HTTP `204` sem corpo. O cupom deixa de aparecer na listagem, não pode mais ser consultado e não fica disponível para novos usos. Registros históricos permanecem preservados.

## Campos retornados

| Campo        | Tipo              | Descrição                                                          |
| ------------ | ----------------- | ------------------------------------------------------------------ |
| `id`         | UUID              | Identificador público do cupom.                                    |
| `code`       | string            | Código normalizado em letras maiúsculas.                           |
| `type`       | enum              | `PERCENTAGE` ou `FIXED_AMOUNT`.                                    |
| `value`      | number            | Percentual inteiro ou valor fixo em reais com duas casas decimais. |
| `max_uses`   | integer \| null   | Limite configurado; `null` ou `-1` representa uso ilimitado.       |
| `used_count` | integer           | Quantidade de usos registrada.                                     |
| `starts_at`  | date-time \| null | Início opcional da validade.                                       |
| `expires_at` | date-time \| null | Fim opcional da validade.                                          |
| `status`     | enum              | `ACTIVE` ou `INACTIVE`.                                            |
| `created_at` | date-time         | Data de criação.                                                   |
| `updated_at` | date-time         | Data da última atualização.                                        |