---
title: 'Parâmetros de listagem'
description: 'Filtre, ordene e pagine qualquer endpoint de listagem usando a sintaxe q[]/o[]/e/p.'
---

# Parâmetros de listagem

Todo endpoint de listagem da API Guper entende uma gramática de querystring compartilhada para filtragem, ordenação e paginação. Aprendeu em um recurso, vale para todos.

> **`q[]` ou QON?** Esta é a gramática `q[]`, para **ler e listar**: buscar um cliente, filtrar pedidos, paginar um relatório. O [QON](/docs/{lang}/api-reference/register/audience-query/qon-query) é outra coisa — expressões aninhadas em JSON que servem **só para montar audiência** no construtor de segmentação. Para achar um cliente por CPF ou e-mail, é `q[]`, aqui — não QON.

## Filtragem — `q[coluna][operador]=valor`

```
q[coluna][operador]=valor
```

- **`coluna`** — pode ser composta, separada por `;` ou `|`.
- **`operador`** — um dos:

| Operador | Significado | Equivalente SQL |
|---|---|---|
| `E` | igual | `=` |
| `!E` | diferente | `!=` |
| `B` | anterior | `<` |
| `BE` | anterior ou igual | `<=` |
| `A` | posterior | `>` |
| `AE` | posterior ou igual | `>=` |
| `IS` | é | `IS NULL` |
| `!IS` | não é | `IS NOT NULL` |
| `IN` | contido | `IN (1, 2, …)` |
| `!IN` | não contido | `NOT IN (1, 2, …)` |
| `L` | like | `LIKE "valor"` |
| `!L` | not like | `NOT LIKE "valor"` |
| `LL` | left-like | `LIKE "%valor"` |
| `!LL` | not left-like | `NOT LIKE "%valor"` |
| `RL` | right-like | `LIKE "valor%"` |
| `!RL` | not right-like | `NOT LIKE "valor%"` |
| `LRL` | left+right like | `LIKE "%valor%"` |
| `!LRL` | not left+right like | `NOT LIKE "%valor%"` |
| `S` | busca | busca por termo em uma ou mais colunas |

### Múltiplos valores

Operadores que aceitam múltiplos valores devem ser configurados em sequência:

```
q[coluna][IN]=1&q[coluna][]=2&q[coluna][]=3
```

Gera `coluna IN (1, 2, 3)`.

### Filtro NULL

```
q[coluna][IS]=null
```

## Ordenação — `o[coluna]=direção`

```
o[coluna]=direção
```

- **`coluna`** — coluna pela qual ordenar.
- **`direção`** — `ASC` / `asc` / `1` para ascendente, `DESC` / `desc` / `0` para descendente.

## Paginação — `e=entries&p=page`

| Parâmetro | Default | Observações |
|---|---|---|
| `e` (entries) | `20` | Itens por página. Máximo `1000`. `0` significa sem limite. |
| `p` (page) | `1` | Mínimo `1`. |

## Exemplos

### Faixa de datas

A mesma coluna aceita **dois operadores na mesma consulta** — é assim que se monta um intervalo:

```
GET /api/register/customer?q[createdAt][AE]=2026-08-01 00:00:00&q[createdAt][BE]=2026-08-31 23:59:59
```

Gera `createdAt >= '2026-08-01 00:00:00' AND createdAt <= '2026-08-31 23:59:59'`.

> **Cuidado com a data sem hora no `BE`.** `q[createdAt][BE]=2026-08-31` significa `2026-08-31 00:00:00` — tudo que aconteceu **durante** o dia 31 fica de fora. Ou vá até `23:59:59`, ou use `B` (menor que) no dia seguinte:
>
> ```
> q[createdAt][AE]=2026-08-01&q[createdAt][B]=2026-09-01
> ```

Um lado só também vale, quando o intervalo é aberto:

```
q[order_date][AE]=2026-08-01     → de 1º de agosto em diante
q[order_date][B]=2026-08-01      → antes de 1º de agosto
```

Lembre de aplicar URL-encode nos valores: o espaço vira `%20` (ou `+`), e `2026-08-01 00:00:00` vira `2026-08-01%2000%3A00%3A00`.

### Cliente por e-mail exato

```
GET /api/register/customer?q[email][E]=maria@exemplo.com
```

Buscar cliente **é isto** — a listagem filtrada. Não use `create` nem `get-or-create` para consultar: eles escrevem, e criam o cliente que você só queria procurar.

### Um trecho do texto

```
GET /api/register/customer?q[name][LRL]=silva
```

`LRL` é "contém" (`LIKE '%silva%'`). Como casa qualquer pedaço, `q[email][LRL]=x@gmail.com` também traz `maria.mx@gmail.com` — para duplicidade real, use `E`.

### Buscar em várias colunas de uma vez

```
GET /api/register/customer?q[name;email][S]=maria silva
```

O termo é quebrado por espaço: **cada palavra** precisa aparecer em **pelo menos uma** das colunas. Palavras combinam com `E`, colunas com `OU`.

### Vários valores na mesma coluna

```
GET /api/order/data?q[status][IN]=completed&q[status][]=shipped
```

### Preenchido ou vazio

```
q[canceledAt][IS]=null      → só os não cancelados
q[canceledAt][!IS]=null     → só os cancelados
```

### Tudo junto

```
GET /api/order/data?q[status][E]=completed&q[order_date][AE]=2026-08-01&q[order_date][B]=2026-09-01&o[order_date]=desc&e=50&p=2
```

Segunda página de 50 pedidos concluídos em agosto/2026, dos mais novos para os mais antigos.

## Antes de sair filtrando

- **Coluna não filtrável é ignorada em silêncio.** Alguns recursos limitam quais colunas aceitam filtro; se você mandar outra, ela é descartada sem erro — e a resposta volta **sem aquele filtro**, com mais linhas do que você esperava. Confirme o resultado em vez de assumir.
- **Sem operador é igualdade**: `q[status]=completed` faz o mesmo que `q[status][E]=completed`.
- **O nome da coluna muda por serviço.** É `createdAt` no register e `order_date` / `createAt` no order — use o mesmo nome que aparece na resposta do endpoint.
- **`e=0` (ou `e=all`) desliga o limite.** Em base grande isso é uma resposta enorme e uma consulta cara; prefira paginar.
