Skip to main content
Essa documentação é sobre filtros simples aplicados no URL, se você estiver procurando por filtros complexos, consulte a documentação de Busca Avançada.
Alguns endpoints da API fornecem filtragem e ordenação simples através de parâmetros de query string. Este sistema é ideal para casos de uso básicos onde você precisa filtrar por campos específicos ou ordenar resultados.

​
Como Funciona

O sistema de filtro simples utiliza parâmetros de query string na URL da requisição. Você pode combinar múltiplos filtros e ordenação em uma única requisição.

​
Filtros

Para aplicar filtros, use o parâmetro filter seguido do nome do campo entre colchetes: 
GET /api/endpoint?filter[campo]=valor

​
Filtros Múltiplos

Você pode aplicar vários filtros simultaneamente: 
GET /api/endpoint?filter[name]=Mike&filter[email][email protected]

​
Tipos de Filtros

Os filtros disponíveis variam por endpoint. Alguns exemplos comuns incluem:
  • Filtro exato: filter[id]=123
  • Filtro por status: filter[status]=1
  • Filtros customizados: Alguns endpoints oferecem filtros especiais através de callbacks
Os campos disponíveis para filtragem são definidos por cada endpoint. Consulte a documentação específica do endpoint para ver quais filtros estão disponíveis.

​
Ordenação

Para ordenar os resultados, use o parâmetro sort: 
GET /api/endpoint?sort=campo

​
Ordenação Descendente

Para ordenar em ordem decrescente, adicione um hífen (-) antes do nome do campo: 
GET /api/endpoint?sort=-created_at

​
Múltiplas Ordenações

Alguns endpoints suportam múltiplas ordenações separadas por vírgula: 
GET /api/endpoint?sort=name,-created_at
Os valores possíveis para o campo de ordenação variam por endpoint. Consulte a documentação específica do endpoint para ver quais campos estão disponíveis.

​
Filtros Especiais

​
Filtro de Itens Deletados

Alguns endpoints suportam o filtro trashed para incluir itens deletados: 
GET /api/endpoint?filter[trashed]=with
Valores possíveis:
  • with: Inclui apenas itens deletados
  • only: Retorna apenas itens deletados
  • without: Exclui itens deletados (padrão)

​
Filtros com Callbacks

Alguns endpoints oferecem filtros avançados através de callbacks. Estes filtros podem realizar consultas mais complexas:
O filtro search em alguns casos busca o termo em múltiplos campos (nome, email, ID) simultaneamente, para facilitar buscas.

​
Limitações

O sistema de filtro simples tem algumas limitações:
  • Operadores limitados: Geralmente suporta apenas igualdade (=) e alguns operadores específicos por campo
  • Sem operadores lógicos: Não é possível combinar filtros com AND ou OR de forma explícita
  • Sem filtros aninhados: Não suporta filtros em relacionamentos complexos
Para necessidades mais complexas de filtragem, use o sistema de Busca Avançada que oferece operadores relacionais, lógicos e filtros em relacionamentos.

​
Campos Disponíveis

Os campos disponíveis para filtragem e ordenação variam por endpoint. Para descobrir quais campos estão disponíveis:
  1. Consulte a documentação específica do endpoint
  2. Verifique a resposta de erro quando usar um campo inválido
  3. Alguns endpoints expõem metadados sobre campos disponíveis

​
Tratamento de Erros

Se você usar um campo inválido ou um valor incorreto, a API retornará um erro de validação:
Error
{
  "response": false,
  "message": "validation_error",
  "error": "The filter field 'campo_invalido' is not allowed."
}

​
Resumo

  • Use filter[campo]=valor para aplicar filtros
  • Use sort=campo ou sort=-campo para ordenação
  • Combine múltiplos filtros na mesma requisição
  • Consulte a documentação do endpoint para campos disponíveis
  • Para filtros complexos, considere usar o sistema de Busca Avançada