Métodos de listagem que aceitam o parâmetro query podem receber filtros para especificar quais registros deverão ser retornados.
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>
Através desta funcionalidade também é possível executar as seguintes pesquisas:
| Query | Retorno |
|---|---|
name:paulo | Busca por registros contendo a string "paulo" (case insensitive) no campo "nome". |
code=42 | Busca o único cliente com o campo do código externo exatamente igual a "42" . |
created_at>=2015-01-15 | Clientes criados a partir do dia 15/01/2015. |
status:active AND email:gmail.com | Clientes ativos com o email contendo a string "gmail.com". |
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 code, registry_code e email. Neste caso, utilize o operador de igualdade. | |||
| = | 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 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-01 id>=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
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 |