Como eu faço para criar uma consulta de listas, buscas e filtros usando uma query?
Métodos da API que recebem o parâmetro query permitem filtros conforme as especificações abaixo.
Exemplo:
https://app.vindi.com.br/api/v1/customers?query=name:paulo
A consulta acima retornará todos os clientes que contém a string "paulo" no atributo nome. O conteúdo do parâmetro query deverá ser codificado (URL Encoded).
Por motivos de simplificação, os exemplos desta documentação não estão codificados.
Para criar uma consulta, você pode utilizar uma ou mais condições, opcionalmente agrupadas por operadores:
query=<atributo><consulta><valor>
Exemplo:
query=nome:Carlos atributo: "nome" consulta: ":" (contém) valor: "Carlos"
As seguintes consultas são suportadas pela API:
| Consulta | Descrição | Exemplos | Observações |
: | Contém | name:verônica | Case-insensitive, sempre ignorando acentos. A busca ao lado retornará nomes que contém "VERÔNICA", "veronica", "verONICA", etc. A API não suporta este operador nos campos |
= | Igual | name="Paulo Costa"code=42 | Busca exatamente pelo valor informado, case-insensitive e ignorando acentos da mesma forma que o operador acima. Utilize aspas caso queira incluir o valor desejado possua espaços. Em campos do tipo data/hora, o operador de igualdade irá buscar por registros entre 00:00:00 e 23:59:59 da data informada. |
> | Maior | created_at>"2015-02-28 14:00:00"quantity>3 | Utilize aspas caso deseje buscar por campos do tipo data/hora informando o horário. |
>= | Maior ou igual | created_at>=2015-03-01id>=1020 | |
< | Menor | quantity<5 | |
<= | Menor ou igual | id<=200 | |
NOT/not/- | Negação | -status:active | O exemplo ao lado busca por clientes que não possuem o status "ativo", porém é possível negar qualquer atributo. |
() | Agrupamento | (status:active AND name:paulo) OR name:mariana | Agrupa condições. |
Operadores disponíveis: AND/and e OR/or. Caso mais de uma condição seja informada e o operador seja omitido, AND será assumido como padrão.
Portanto:
status=active name:luis
É equivalente a:
status=active AND name:luis
Os atributos que podem ser usados nos filtros estão definidos dentro da documentação de cada método.
Buscas por data e hora
Campos do tipo data/hora devem ser consultados levando o horário em consideração, ou seja, se desejar buscar faturas pagas dentro de uma faixa de dias, termine a consulta com 23:59:59:
paid_at=>"2019-01-01" AND paid_at<="2019-01-03 23:59:59"
Se o horário não for informado, consideraremos 00:00:00. O exemplo acima busca por todos os pagamentos feitos nos dias 1, 2 e 3, independente do horário. Caso o horário fosse omitido do término, a busca seria realizada apenas no dia 1 e 2.
Buscas em campos do tipo data/hora utilizando o operador de igualdade irão buscar por registros dentro do dia informado, das 00:00:00 até 23:59:59:
paid_at=2019-01-01
Paginação
Não se esqueça de verificar os cabeçalhos da paginação para obter o total de registros encontrados.
Ordenação
A plataforma também permite ordenar os resultados de qualquer listagem usando atributos que podem ser pesquisados (descritos na documentação de cada método). Para isso, utilize os seguintes parâmetros na query string:
| Parâmetro | Descrição | Exemplos |
sort_by | Atributo da ordenação. Default: id | name, code, id |
sort_order | Sentido da ordenação: Ascendente ou descendente. Default: asc | asc, desc |