> For the complete documentation index, see [llms.txt](https://ajuda.livechat360.com.br/crm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.livechat360.com.br/crm/api-docs/paginacao-ordenacao-e-filtros.md).

# Paginacao, ordenacao e filtros

## Paginação

`?page=1&per_page=30`

`page` começa em 1; `per_page` tem padrão 30 e máximo 100 (valores acima de 100 são limitados a 100, sem erro). `page=0`, `per_page=0` ou valores não inteiros retornam 400.

Para percorrer uma coleção inteira, solicite páginas sucessivas até `page >= meta.total_pages` (ou até receber uma página com menos de `per_page` itens).

## Ordenação

`?sort=campo` ordena de forma crescente; `?sort=-campo`, decrescente. Cada recurso documenta seus campos ordenáveis e o padrão. Um campo desconhecido retorna 400 listando os valores aceitos.

## Filtros

Cada campo filtrável é um parâmetro de query, com sufixos de operador:

| Sintaxe                                       | Significado                                            | Exemplo                             |
| --------------------------------------------- | ------------------------------------------------------ | ----------------------------------- |
| `?campo=valor`                                | igualdade exata (sem diferenciar maiúsculas em textos) | `?status=ongoing`                   |
| `?campo=v1,v2`                                | lista IN, **apenas parâmetros de id inteiro e enum**   | `?status=won,lost`, `?owner_id=1,2` |
| `?campo__contains=valor`                      | correspondência parcial, sem diferenciar maiúsculas    | `?name__contains=joao`              |
| `?campo__gte=` / `__lte=` / `__gt=` / `__lt=` | comparações (datas; `rating`)                          | `?created_at__gte=2026-01-01`       |
| `?custom__<nome do campo>=valor`              | igualdade em campo personalizado (**apenas contatos**) | `?custom__erp_id=9981`              |

### Regras gerais

* Parâmetros de data aceitam qualquer valor ISO 8601 e funcionam **apenas** com os sufixos de comparação (um `?created_at=` simples é ignorado).
* Filtros booleanos aceitam `true`/`false`.
* Filtros enum (ex.: `status` da negociação) rejeitam valores desconhecidos com 400, listando os aceitos.
* Vários filtros (inclusive vários `custom__`) são combinados com **E** (AND).
* Valores vazios (`?name=`) são ignorados; repetir um parâmetro (`?name=a&name=b`) retorna 400.
* Parâmetros desconhecidos são ignorados.