Os filtros possibilitam selecionar um subconjunto específico de resultados de uma requisição.
Caso uma rota de requisição aceite filtros, você poderá acrescentar uma string de consulta (como na paginação) à URL de requisição, para especificar os parâmetros de filtragem.
Existem 3 possibilidades diferentes de efetuar filtros em uma requisição, que chamamos de Pesquisa simples, Pesquisa dinâmica e Pesquisa dinâmica composta.
Segue abaixo a explicação e exemplos de cada uma das possibilidades:
Pesquisa simples
Neste tipo de filtro, você pode selecionar um subconjunto a partir um 1 único campo.
Por exemplo, para retornar as filas de atendimento que possuem na descrição a palavra "venda", você deve usar a seguinte string de consulta searchFields=description&search=venda e sua URL de requisição ficará como a do trecho abaixo:
https://{{subdominio}}.cxm.pipe.run/api/v2/queues?searchFields=description&search=venda
Como pode ser visto no exemplo acima, foi necessário enviar 2 campos na URL da requisição, searchFields e search. O campo searchFields representa o nome do campo que você está filtrando, e o campo search representa o valor que está sendo filtrado.
Pesquisa dinâmica
Assim como na pesquisa simples, neste tipo de filtro, você também pode selecionar um subconjunto a partir um 1 único campo. A diferença está na forma de enviar a string de filtragem, que nesta situação você precisa enviar 1 único campo.
Por exemplo, utilizando o mesmo filtro anterior, onde queremos retornar as filas de atendimento que possuem na descrição a palavra "venda", você deve usar a seguinte string de consulta search=description:venda e sua URL de requisição ficará como a do trecho abaixo:
https://{{subdominio}}.cxm.pipe.run/api/v2/queues?search=description:venda
Como pode ser visto no exemplo acima, foi necessário enviar apenas 1 campo na URL da requisição, chamado search. No campo search deve ser enviado o nome do campo que você está filtrando e o valor que está sendo filtrado, separados pelo caractere ":" (dois-pontos).
Pesquisa dinâmica composta
Este tipo de filtro utiliza a mesma sintaxe do tipo de pesquisa dinâmica, mas você pode selecionar um subconjunto a partir de 2 ou mais campos.
Por exemplo, para retornar as filas de atendimento que possuem na descrição a palavra "venda" e também que pertençam à carteira com ID igual a 2, você deve usar a seguinte string de consulta search=card_id:2;description:venda&searchJoin=and e sua URL de requisição ficará como a do trecho abaixo:
https://{{subdominio}}.cxm.pipe.run/api/v2/queues?search=card_id:2;description:venda&searchJoin=and
Como pode ser visto no exemplo acima, foi necessário enviar 2 campos na URL da requisição, search e searchJoin. O campo search representa os campos e valores ques estão sendo filtrados; utilize o caractere ";" (ponto-e-vírgula) para separar os filtros. O campo searchJoin representa o tipo de condição aplicado entre os múltiplos filtros. O valores permitidos são "and" e "or", se o campo não for informado, o valor padrão será "or".
Filtro por intervalo de datas
Para efetuar filtros em campos do tipo data ou data/hora, ainda é possível filtrar por um intervalo de datas (between).
Por exemplo, para efetuar um filtro onde você deseja retornar apenas registros com data de criação entre 01/01/2025 a 31/01/2025, você deve usar a seguinte string de consulta search=created_at:2023-07-01,2023-07-10.
Note que foi utilizado a sintaxe do tipo de pesquisa dinâmica e a data inicial e final estão separadas pelo caractere "," (vírgula).
Importante também saber que as datas devem ser informadas no padrão AAAA-MM-DD.