Paginacao, ordenacao e filtros

Parâmetros de query comuns a todas as listagens: page, per_page, sort e os sufixos de operador dos 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.