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 |
Comentários
7 comentários
Lembre-se de consultar o atributo "code" sempre com o operador de igualdade!
Olá, podem me tirar uma dúvida, por favor?
Estou usando o SDK em PHP, e fazendo uma busca simples por customers. Contudo, ao coloca na query 'name=marcio garcia' ocorre um erro, ele apenas permite busca sem espaços ex: 'name=marcio' . Tentei codificar por urlencode mas não funcionou. Estranhamente se digito _ no lugar do espaço ele funciona normalmente.
Obs: este erro também ocorre em http://vindi.github.io/api-docs/dist/#!/customers/GET_version_customers_format. Embora eu vejo que ele troca espaço por %20, a API acusa erro.
Qual o jeito correto de buscar com termos com espaços, por favor?
Obrigado!!
Olá,
Uma observação...
Me parece que o formato de data aceito no filtro (ao menos para a consulta por "bills", campo "due_at") é o "ISO 8601" (Ex: "2015-06-28T14:00:00-03:00") e não o formato de banco de dados (Ex: "2015-02-28 14:00:00") como é indicado no exemplo da página.
Obrigado.
Para utilizar esses parâmetros de busca com o SDK da vindi em PHP, à princípio, deve-se utilizar o método all() do resource passando o parâmetro query com os filtros de busca:
use Vindi\Customer;
$customer = new Customer();
$customer->all([
'query'=>"status=active AND email:mail@mail.com"
]);
Apesar do resource do SDK já ter um parâmetro "query" ele não é passado para a API pelo Guzzle, tendo que deixar esse parâmetro explicito.
Estes exemplos não está funcionando, estou tomando erro 400.
O exemplo funciona no método customers, mas não consigo utilizar os operadores AND/OR no método subscriptions.
Exemplo: https://app.vindi.com.br/api/v1/subscriptions?query=customer_id=230696%20and%20(status=active%20or%20status=future)
Query: customer_id=230696 and (status=active or status=future)
Retorna:
{"errors":[{"id":"invalid_parameter","parameter":"query","message":"inválido(a)"}]}
Gian, tive um problema parecido na consulta assim:
https://app.vindi.com.br/api/v1/subscriptions?query=status=active or updated_at>2022-07-21
E no meu caso a solução foi tirar os espaços e inverter a ordem:
https://app.vindi.com.br/api/v1/subscriptions?query=updated_at>2022-07-21ORstatus=active
Testei algumas coisas diferentes com o seu caso, mas todas deram erro.
Esta documentação precisa ser revisada quanto a filtros mais complexos, pois só existem exemplos simples e eles não funcionam quando colocamos filtros compostos
Artigo fechado para comentários.