Filtros na requisição

CONTEÚDO

1. Visão Geral
2. Operadores lógicos para utilização nos filtros
   1. Operadores de igualdade
   2. Operadores de intervalo
3. Campos de chave estrangeira
   
4. Utilizar in com uma lista de valores
5. Realizar filtro por um período de data
6. Verificar se um campo está nulo
7. Paginação de resultados

01. VISÃO GERAL

Para utilizar um filtro na requisição da API de Integração, basta adicionar a chave Integration-Filter no header com o valor que deseja filtrar, além das outras chaves da request, conforme a imagem:

Note que, neste exemplo, é realizada uma request no serviço de oportunidades, uma busca pelo código 61. Dessa forma, a estrutura do filtro é a seguinte:

{campo->operador->valor}

É necessário que seja adicionada a operação dentro das chaves. Caso deseje adicionar mais de um filtro, basta acrescentar  um novo conjunto de chaves sem separação por vírgula, conforme exemplo:

{code->eq->61}{status→eq→PROGRESS}

Nesse caso, o filtro trará apenas a oportunidade de código igual a 61 e status igual a PROGRESS.

02. OPERADORES LÓGICOS PARA UTILIZAÇÃO NOS FILTROS

São permitidos alguns operadores para que o filtro seja construído. São eles:

a. Operadores lógicos

b. Operadores de filtragem

03. CAMPOS DE CHAVE ESTRANGEIRA

Para realizar um filtro por uma chave estrangeira, é necessário passar a entidade e o campo a ser filtrado. No caso de oportunidades, há o identificador de usuário que é retornado no campo userId.

Entretanto, para filtrar por um id específico de um usuário, é necessário referenciar a tabela user e o campo id da seguinte forma:

{user.id->eq->b69b712f-7bd6-357d-9cda-59959c89a2b1}

04. UTILIZAR IN COM UMA LISTA DE VALORES

Para utilizar um filtro in com uma lista de valores, é necessário adicionar os valores dentro da estrutura [valores], da seguinte forma:

{code->in->[61,62,63]}

OBSERVAÇÃO: não pode haver espaços entre as vírgulas e os valores.

05. REALIZAR FILTRO POR UM PERÍODO DE DATA

Para filtrar por um período de data, é necessário adicionar um filtro "maior que" e outro de "menor que". Conforme operadores listados anteriormente, o formato de data é o seguinte:

2020-06-30T13:26:32.163Z

Segue abaixo um filtro de oportunidade criada entre os dias 29 e 30 de janeiro de 2020:

{createdAt->ge->2020-01-29T00:00:00.000Z}{createdAt->lt->2020-01-31T00:00:00.000Z}

06. VERIFICAR SE UM CAMPO ESTÁ NULO

Para verificar se um campo está nulo, basta adicionar o operador isNull no lugar do operador e valor, conforme exemplo:

{externalId->isNull}

Note que serão trazidas todas as oportunidades em que o campo externalId não foi preenchido. Desta forma, é possível trabalhar com os campos para realizar os filtros necessários em sua requisição.

07. PAGINAÇÃO DE RESULTADOS

Dentro de uma requisição de GET nas APIs é possível utilizar dentro do cabeçalho integration-filter a quantidade de registros a serem listados, da seguinte forma:

{pageSize->100}

No exemplo acima, são listados 100 resultados como retorno da requisição. Se não for informado este filtro pageSize as APIs retornam 500 resultados como valor padrão.

Para navegar entre as páginas de resultados, é possível definir a numeração também no cabeçalho da requisição:

{page→0}

No exemplo acima, são listados os registros da primeira página, de acordo com a quantidade máxima definida no filtro pageSize. A numeração inicia com o valor 0.

É possível combinar os dois filtros da seguinte forma:

{pageSize→100}{page→1}

No filtro do exemplo acima são listados os registros da segunda página, caso existam.

Disponibilizamos um atributo no corpo da resposta que pode ser usado para controlar o fim da navegação de páginas de resultados chamado de hasNext, que funciona baseado no valor definido pelo atributo pageSize.

A lógica do funcionamento do hasNext é a seguinte:

Se houver registros na próxima página, hasNext apresentará o valor true, indicando que tem mais páginas de resultados para leitura

Se não houver registros na próxima página, hasNext apresentará o valor false, indicando que a página atual é a última com resultados

O hasNext facilita identificar a ultima página, caso não seja usado é possível identificar a ultima página usando a quantidade de valores lidos com relação ao tamanho máximo da paginação.

Artigos relacionados:

Formato, métodos e retorno das requisições

Como utilizar na prática