Listas, buscas e filtros

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ê poderá utilizar uma ou mais condições, opcionalmente agrupadas por operadores:

query=<atributo><consulta><valor>

Exemplo:

query=email:gmail.com
  atributo: "email"
  consulta: ":" (contém)
  valor:    "gmail.com"

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.

Evite usar este operador quando estiver buscando pelo atributo code. Neste caso, prefira 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 queira incluir o valor desejado possua espaços.
> 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 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 quem podem user usados nos filtros estão definidos dentro da documentação de cada método.

Paginação

Não 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 qualquer atributo pesquisável (listados 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

 

Tem mais dúvidas? Envie uma solicitação

Comentários

  • Avatar
    Wagner Narde

    Lembre-se de consultar o atributo "code" sempre com o operador de igualdade!

  • Avatar
    Vitor Siqueira

    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!!

Powered by Zendesk