> For the complete documentation index, see [llms.txt](https://apidoc.toplojas.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.toplojas.com.br/cupons-de-desconto/listar-cupons.md).

# Listar Cupons

Retorna a **listagem de cupons de desconto** da loja, com suporte a filtros e paginação.

```
GET /cupom-desconto/
```

## 🔎 Filtros disponíveis

Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.

| Parâmetro      | Tipo    | Descrição                                                      |
| -------------- | ------- | -------------------------------------------------------------- |
| `Status`       | texto   | Filtra pelo status: `A` (Ativado) ou `D` (Desativado)          |
| `ChaveBusca`   | texto   | Busca pelo **Código do Cupom** ou pela **Observação** do cupom |
| `Pagina`       | inteiro | Página desejada (paginação)                                    |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**)                            |

## 📥 Exemplo de requisição

Buscando cupons **ativos** que contenham um termo na chave de busca, 50 por página:

```bash
curl -X GET "https://api.toplojas.com.br/cupom-desconto/?Status=A&ChaveBusca=Teste&QtdPorPagina=50" \
  -H "Authorization: Bearer [Token]" \
  -H "Loja: [Identificador de Sua Loja]"
```

## 📤 Exemplo de resposta

A resposta segue o padrão de paginação (`Dados` + `Paginacao`):

```json
{
  "Dados": [
    {
      "Codigo": "309604",
      "Status": "A",
      "CodigoCupom": "Z3a3df80d2baad67",
      "Observacao": "",
      "DataDe": "2020-10-16",
      "DataAte": "2020-11-15",
      "QtdUtilizacoes": "100",
      "QtdPorCliente": "1",
      "DescontoTipo": "P",
      "DescontoValor": "12.37",
      "ValorMinimoCompra": "0.00"
    }
  ],
  "Paginacao": {
    "PaginaAtual": 1,
    "QtdPaginas": 1,
    "QtdRegistros": 2
  }
}
```

## 📋 Campos retornados

| Campo               | Tipo    | Descrição                                                  |
| ------------------- | ------- | ---------------------------------------------------------- |
| `Codigo`            | inteiro | Código interno do cupom                                    |
| `Status`            | texto   | `A` (Ativado) ou `D` (Desativado)                          |
| `CodigoCupom`       | texto   | Código que o cliente utiliza na cesta de compras           |
| `Observacao`        | texto   | Observação privada, visível apenas para a administração    |
| `DataDe`            | data    | Início da vigência do cupom (`Ano-Mês-Dia`)                |
| `DataAte`           | data    | Fim da vigência do cupom (`Ano-Mês-Dia`)                   |
| `QtdUtilizacoes`    | inteiro | Quantidade limite de utilizações do cupom                  |
| `QtdPorCliente`     | inteiro | Quantidade de utilizações por cliente                      |
| `DescontoTipo`      | texto   | `P` (Porcentagem) ou `V` (Valor fixo)                      |
| `DescontoValor`     | decimal | Valor ou porcentagem de desconto (conforme `DescontoTipo`) |
| `ValorMinimoCompra` | decimal | Valor mínimo da compra para o cupom poder ser utilizado    |

{% hint style="info" %}
Consulte a descrição de cada campo na referência:

{% embed url="<https://api.toplojas.com.br/doc/#/CupomDesconto>" %}
{% endhint %}

Para entender o funcionamento da paginação, veja:

{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao.md)
{% endcontent-ref %}