Developer Center
Pesquisar K

Appearance

Como funciona o endpoint de search ​

A maior parte das coleções em Pagamentos contém um endpoint search. Esse endpoint é responsável por realizar buscas dentro da coleção de seu respectivo objeto.

Este guia explica os campos utilizados na operação de busca. Se você quer saber mais sobre a estrutura do endpoint e seus outros parâmetros, veja as referências de Pagamentos.

Casos de Uso ​

É recomendado utilizar o endpoint de search quando você quer achar um um objeto em uma coleção mas não lembra o id dele para poder fazer a requisição de get/:OBJECTID. Por exemplo, você quer pegar as informações de uma venda x, mas você apenas sabe a data que ela ocorreu. Com o endpoint de search, você pode buscar as vendas por data, e assim encontrar a venda que procura. Outro exemplo. Você quer obter o item com o nome "caderno escolar", no entanto você não sabe o id dele para poder fazer a requisição de get/:OBJECTID. Com o endpoint de search, você pode procurar os itens que tenham o nome "caderno escolar".

Caso você já tenha o id do objeto que você quer, não use o endpoint de search, e sim faça uma requisição GET. Caso você não conheça as requisições possíveis, veja a referência de pagamentos

Campo Filter ​

O campo Filter contém um subcampo:

  • filters: lista de filtros aplicados na busca.

O campo filters possui regras específicas e será detalhado na seção seguinte.

Campo Filters ​

O campo filters segue a seguinte estrutura:

  • path: o campo da coleção que será pesquisado;
  • value: o valor utilizado na busca;
  • comparison: tipo de comparação realizada. Para saber mais, veja a aba que está no fim desse guia.

Como funciona a resposta do endpoint ​

No endpoint de search, utilizamos paginação por cursor. Caso você não saiba o que é, leia este artigo.

Quando você fizer uma requisição utilizando esse endpoint, a resposta terá a seguinte estrutura:

bash
total: number
hits: [{}]
previous: string
next: string
  • total: total de objetos encontrados com os parâmetros da requisição.
  • hits: lista dos objetos retornados na página atual. O número de itens em hits pode ser menor que total, pois a consulta utiliza um limite de resultados por página.
  • previous: cursor que aponta para a página anterior.
  • next: cursor que aponta para a próxima página.

Exemplo ​

Suponha que você fez a seguinte requisição:

bash
curl https://api.layers.digital/v1/payments/sales/search \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Community-Id: demo-escola' \
  --header 'Content-Type: application/json' \
  --data-raw '{"fields":[{"path":"code","sticky":true},{"path":"createdAt","sortDirection":"desc","sortOrder":1},{"path":"customer.name"},{"path":"owned.total.amount"},{"path":"payment.method"},{"path":"payment.status"},{"path":"context.entity"},{"path":"integration.status"}],"filter":{"mode":"advanced","queryText":"","filters":[]},"next":"W3siJGRhdGUiOiIyMDI1LTA5LTAzVDEzOjI4OjQzLjI0NVoifSx7IiRvaWQiOiI2OGI4NDI4OTk2N2E5NTAwMjg0NjY5NWUifV0"}'

E recebeu a seguinte resposta:

bash
total: 100
hits: (51)[{...}]
previous: "W3siJGRhdGUiOiIyMDI1LTEyLTA4VDExOjExOjQ5LjE3MFoifSx7IiRvaWQiOiI2OTM2YjI3NTgyYzNhOTg3OTU1NjJlZDAifV0"
next: "W3siJGRhdGUiOiIyMDI1LTEyLTA4VDExOjExOjQ5LjE3MFoifSx7IiRvaWQiOiI2OTM2YjI3NTgyYzNhOTg3OTU1NjJlZDAifV0"

No campo hits você recebeu apenas 51 das 100 vendas encontradas. As outras 49 estão na próxima página, definida pelo cursor presente no campo next.

Para obter os próximos resultados, basta fazer a mesma requisição, alterando apenas o valor de next no corpo da requisição com o cursor recebido na resposta anterior.

A nova resposta retornará outra lista de hits, além de novos valores de previous e next. Repita o processo até que next venha como null, indicando que não há mais páginas disponíveis.

Valores possíveis de uma comparison ​

A comparison é utilizada em operações do tipo search. Ela é dividida em quatro tipos:

  • Date;
  • Number;
  • String; e
  • Sale, essa operação é exclusiva para a coleção de vendas.

Comparison do tipo Date ​

comparisono que ela faz
relative_past_gteRetorna as datas que foram antes de x dias do dia de hoje. Exemplo: se x for igual a 10 e a data 03/12/1965, as datas retornadas estarão entre 23/11/1965 e 03/12/1965.
relative_past_ltRetorna as datas que aconteceram antes do valor de x menos a data de hoje. Exemplo: se x for igual a 10 e a data 03/12/1965, as datas retornadas serão antes de 23/11/1965. Nesse exemplo, um resultado possível seria 20/11/1965.
relative_past_eqRetorna apenas a data com o valor de x menos a data de hoje. Exemplo: se x for igual a 10 e a data 03/12/1965, a data retornada será apenas 23/11/1965.
relative_future_gteRetorna as datas que serão após o valor de x mais o dia de hoje. Exemplo: se x for igual a 10 e a data 15/10/1974, as datas retornadas serão a partir do dia 25/10/1974.
relative_future_ltRetorna as datas que serão antes do valor de x mais o dia de hoje. Exemplo: se x for igual a 10 e a data 15/10/1974, as datas retornadas serão entre 15/10/1974 e 25/10/1974.
relative_future_eqRetorna a data com o valor de x mais a data de hoje. Exemplo: se x for igual a 10 e a data 15/10/1974, a data retornada será apenas 25/10/1974.
absolute_eqRetorna as vendas com a data especificada. Exemplo: se a data é 19/01/2011, serão retornadas as vendas que tenham a data igual a 19/01/2011.
absolute_gteRetorna as datas a partir de uma data especificada. Exemplo: se a data for 19/01/2011, as datas retornadas serão após isso.
absolute_ltRetorna as datas que sejam antes da data especificada. Exemplo: se a data for 19/01/2011, as datas retornadas serão antes disso.

Comparison do tipo Number ​

comparisono que ela faz
eqRetorna apenas valores que sejam iguais.
neqRetorna apenas valores diferentes.
gtRetorna apenas valores maiores.
gteRetorna apenas valores maiores ou iguais.
ltRetorna apenas valores menores.
lteRetorna apenas valores menores ou iguais.

Comparison do tipo String ​

comparisono que ela faz
containsRetorna valores que contêm o valor especificado.
starts_withRetorna valores que comecem com o valor especificado.
ends_withRetorna valores que terminem com o valor especificado.
eqRetorna valores que sejam iguais ao valor especificado.
neqRetorna valores diferentes ao valor especificado.
inRetorna valores que estejam dentro de uma lista.

Comparison do tipo Sale ​

Essa comparação funciona apenas com objetos da coleção de vendas.

comparisono que ela faz
inRetorna documentos que estejam dentro de uma venda. Exemplo: se você quiser ver se existe o cupom "AAA" dentro de uma venda, você deve usar esse operador e especificar o caminho onde o cupom fica na coleção de vendas.