Filtros de busca

Os filtros podem ser usados para refinar ainda mais a sua busca, como por exemplo retornar pedidos que só estejam em um status ou entre um e outro. Os delimitadores te ajudam nesses cenários.

Cada recurso possui seus atributos disponíveis para filtros. Consulte a documentação do recurso desejado para saber quais você pode utilizar.

As APIs Moip possibilitam que sejam feitas buscas detalhadas. Como padrão sempre será usado três métodos para compor sua busca, podendo ser usados separadamente ou em conjunto para refinar sua busca. São eles:

  • Paginação: determina quantos registros serão retornados.
  • Consulta genérica: busca por uma string ou informação que você tenha utilizado na criação do recurso.
  • Delimitadores: delimita alguns parâmetros em sua busca.

Paginação

Os registros são atualmente ordenados pela data de criação em ordem decrescente.

Nome

Tipo

Descrição

limit

inteiro

Quantidade de registros por busca (página). O valor default é 20

offset

inteiro

Registro a partir do qual a busca vai retornar. O valor default é 0.

👍

EXEMPLO

GET https://sandbox.moip.com.br/v2/orders?limit=100&offset=300

Note que você deve delimitar o endpoint e o filtro com ?.
Ao adicionar um novo delimitador na busca adicione &.

🚧

IMPORTANTE

Ao fazer uma consulta a Moip retornará um hyperlink para que você possa fazer a navegação e fazer uma nova consulta com os mesmos parâmetros (_links.next e _links.previous), retornando os resultados posteriores e anteriores a sua consulta. Veja abaixo um exemplo dos links que devem ser retornados na busca.

"_links": {
        "next": {
            "href": "https://test.moip.com.br/v2/orders?filters=&limit=100&offset=110"
        },
        "previous": {
            "href": "https://test.moip.com.br/v2/orders?filters=&limit=100&offset=0"
        }

Consulta Genérica

É possível buscar um valor específico em seu pedido usando o parâmetro q na url do recurso, esse método é ideal para buscar um recurso por meio de seu identificador próprio.

Nome

Descrição

q

Consulta um valor em específico

👍

EXEMPLO

GET https://sandbox.moip.com.br/v2/orders?q=ORD-7NHI33JLXQQK

Nesse caso os valores possíveis da busca são:

  • Códigos identificadores Moip (são aqueles que começam com três letras e são seguidos por hash. Exemplo: ORD-7NHI33JLXQQK);
  • Nome do cliente/comprador (customer);
  • E-mail do cliente;
  • ownId;

Delimitadores

A URI deve ser montada passando os filtros dentro do parâmetro filters. Use os delimitadores :: para representar chave e valor e | para separar um filtro de outro.

Nome

Tipo

Descrição

gt(x)

number or date

Maior que - “Greater Than

ge(x)

number or date

Maior ou igual - “Greater than or Equal

lt(x)

number or date

Menor que - “Less Than

le(x)

number or date

Menor ou igual - “Less than or Equal

bt(x,y)

string

Entre - “Between

in(x,y…z)

string

Em - “IN

👍

EXEMPLO

Fazendo uma busca com os seguintes requisitos:

  • Transações de valores entre 5000 e 10000 (em centavos);
  • Formas de pagamento: Cartão de Crédito e Boleto;
  • Cliente com o nome jose silva;
  • Retornando 3 resultados.

GET https: //sandbox.moip.com.br/v2/orders?q=jose silva
&filters=status::in(PAID,WAITING)|paymentMethod::in(CREDIT_CARD,BOLETO)
|value::bt(5000,10000)&limit=3&offset=0

Você pode também fazer uma busca por pedidos dentro de um intervalo de tempo:

GET https://sandbox.moip.com.br/v2/orders?filters=createdAt::bt(2017-10-10T13:07:00Z,2017-10-25T13:08:00Z)

Para requisições via cURL use o formato url encoded:

GET https://sandbox.moip.com.br/v2/orders?filters=createdAt::bt%282017-10-10T13:07:00Z,2017-10-25T13:08:00Z%29