Filtros básicos

Muitas listagens da API aceitam filtros e ordenação simples, enviados como parâmetros na URL. Esta página mostra como filtrar com filter[campo], como ordenar com sort e como tratar os erros de filtro ou ordenação não permitidos. Para combinar filtros com operadores como “maior que” ou “contém”, ou com and e or, use a Busca avançada, que recebe os filtros no corpo de uma requisição POST.

Filtrar pela URL

Para filtrar, envie o parâmetro filter com o nome do campo entre colchetes. Esta requisição completa, com autenticação, lista as metas ativas:

curl -g -H "Authorization: Bearer {{token_de_acesso}}" \
  "https://api.olie.ai/api/management/goals?filter[status]=active"

A opção -g impede que o curl interprete os colchetes da URL. Para aplicar vários filtros, repita o parâmetro com outros campos. A API devolve só os itens que atendem a todos os filtros:

GET /api/management/goals?filter[status]=active&filter[title]=Vendas

Os filtros aceitos e a forma de comparação variam por endpoint. Nas metas, por exemplo, filter[title] busca parte do título e filter[status] exige o valor exato. A referência de cada endpoint lista os filtros que ele aceita.

Ordenar os resultados

Para ordenar, envie o parâmetro sort com o nome do campo. A ordem padrão é crescente:

GET /api/management/goals?sort=title

Para ordem decrescente, coloque um hífen (-) antes do nome do campo:

GET /api/management/goals?sort=-created_at

Alguns endpoints aceitam várias ordenações, separadas por vírgula. A API aplica a primeira e usa as seguintes para desempatar:

GET /api/management/goals?sort=title,-created_at

Os campos aceitos em sort também variam por endpoint e estão na referência de cada um.

Incluir itens excluídos

Alguns endpoints aceitam o filtro trashed, que controla se os itens excluídos entram na listagem:

GET /api/management/goals?filter[trashed]=with

Valor	Resultado
`with`	Traz os itens ativos e os excluídos.
`only`	Traz só os itens excluídos.
Sem o filtro	Traz só os itens ativos.

Na listagem de funis, trashed se refere aos funis arquivados.

Buscar por um termo

Alguns endpoints aceitam o parâmetro search, fora de filter, que procura um termo em mais de um campo ao mesmo tempo. Na listagem de projetos, por exemplo, search procura o termo no nome e no código do projeto:

GET /api/management/projects?search=CRM

Os campos em que search procura estão na referência de cada endpoint.

Limitações

Os filtros básicos atendem consultas simples e têm três limites:

Comparação definida pelo endpoint. Cada filtro compara de um jeito só, exato ou parcial, e você não escolhe o operador.
Só a combinação “e”. Todos os filtros precisam ser atendidos ao mesmo tempo. Não há como pedir um filtro “ou” outro.
Sem filtros em relacionamentos complexos. Filtros sobre dados ligados ao item, como respostas de formulário, ficam na busca avançada.

Para esses casos, use a Busca avançada.

Erros de filtro e ordenação

Filtros e ordenações fora da lista do endpoint são recusados com HTTP 400. A própria resposta de erro lista os valores aceitos.

Filtro não permitido

A API responde com message: "invalid_filter_query" quando a URL traz um filter[campo] que o endpoint não aceita. O campo allowed_filters lista os filtros aceitos, e unknown_filters mostra os que foram recusados:

{
  "response": false,
  "message": "invalid_filter_query",
  "error": "Requested filter(s) `owner` are not allowed. Allowed filter(s) are `title, status, type, comparison_mode, periodicity, user_id, funnel_step_id, start_date_gte, end_date_lte, trashed`.",
  "allowed_filters": ["title", "status", "type", "comparison_mode", "periodicity", "user_id", "funnel_step_id", "start_date_gte", "end_date_lte", "trashed"],
  "unknown_filters": ["owner"]
}

Para resolver, troque o filtro recusado por um dos valores de allowed_filters ou remova-o da URL.

Ordenação não permitida

A API responde com message: "invalid_sort_query" quando o sort usa um campo que o endpoint não aceita. O campo allowed_sorts lista as ordenações aceitas, e unknown_sorts mostra as que foram recusadas:

{
  "response": false,
  "message": "invalid_sort_query",
  "error": "Requested sort(s) `cost` is not allowed. Allowed sort(s) are `credits_debited, tokens_used, latency, created_at`.",
  "allowed_sorts": ["credits_debited", "tokens_used", "latency", "created_at"],
  "unknown_sorts": ["cost"]
}

Para resolver, use em sort um dos valores de allowed_sorts, com ou sem o hífen da ordem decrescente.

Páginas relacionadas

Estas páginas complementam os filtros básicos:

Paginação: os parâmetros page e perPage, que você pode combinar com os filtros.
Busca avançada: filtros com operadores, and e or e ordenação no corpo de requisições POST.
Estrutura de respostas: o formato comum das respostas de erro.

Introdução

Geral

Referência da API

Filtrar pela URL

Ordenar os resultados

Incluir itens excluídos

Buscar por um termo

Limitações

Erros de filtro e ordenação

Filtro não permitido

Ordenação não permitida

Páginas relacionadas

​Filtrar pela URL

​Ordenar os resultados

​Incluir itens excluídos

​Buscar por um termo

​Limitações

​Erros de filtro e ordenação

​Filtro não permitido

​Ordenação não permitida

​Páginas relacionadas

Filtrar pela URL

Ordenar os resultados

Incluir itens excluídos

Buscar por um termo

Limitações

Erros de filtro e ordenação

Filtro não permitido

Ordenação não permitida

Páginas relacionadas