Introdução

Nesta página, você encontrará todas as informações necessárias sobre como a paginação e filtragem funcionam com a API da Belvo.

Recomendamos fortemente que você use o parâmetro de consulta link em suas requisições de List para que você receba apenas os resultados para um determinado link.id.

Ao usar o método List, por padrão, você receberá 100 resultados por página. No entanto, você pode aumentar isso para um máximo de 1000 resultados usando o parâmetro de consulta page_size:

curl --request GET \
--url 'https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000'

Na resposta para qualquer solicitação de Lista, você receberá propriedades de navegação na raiz da resposta para auxiliá-lo em suas solicitações subsequentes:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Até 1000 resultados, dependendo do parâmetro page_size.
}

No caso de haver mais resultados do que o limite superior definido por page_size, você precisará usar o valor do parâmetro next para receber a próxima página de resultados (que usa o parâmetro de consulta page).

Por exemplo, no caso de você fazer a seguinte chamada de Lista, definindo page_size para 1000:

curl --request GET \
     --url 'https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000' \
     --header 'accept: application/json'

Você receberá a seguinte resposta JSON:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Até 1000 resultados
}

Você pode então usar a URL no parâmetro next para fazer suas chamadas de API seguintes até que next seja igual a null. No bloco de código abaixo, fornecemos um exemplo de todas as respostas dadas essa situação:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Até 1000 resultados
}

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=3",
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=1",
  "results": [] // Até 1000 resultados
}

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=4",
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "results": [] // Até 1000 resultados
}

{
  "count": 3542,
  "next": null,
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=3",
  "results": [] // Até 1000 resultados
}

Usar filtros na sua solicitação pode reduzir significativamente o tamanho da resposta do servidor, além de garantir que você elimine qualquer dado que não precise para realizar o trabalho.

Você pode usar os filtros fields e omit na sua consulta de URL para definir quais campos você deseja receber na resposta JSON da API da Belvo. Recomendamos que você use esses campos exclusivamente, ou seja, não combine fields e omit na mesma consulta. Além disso, você só pode usar os filtros fields e omit em campos de nível raiz (e não em campos aninhados).

Isso é particularmente útil se você deseja minimizar o tamanho do conteúdo das respostas da API. Por exemplo, ao consultar o endpoint de contas, em vez de receber a resposta completa do servidor, você pode adicionar ?fields=id,balance ao final da sua consulta para obter apenas o ID da conta e o saldo (veja a aba Filtrado no exemplo de código abaixo).

curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/' \
     --header 'accept: application/json'

{
  "id":"5a772f98-befc-4217-8ae7-a087e73a7c28",
  "type":"Créditos",
  "name":"CRED PREST BANAMEX",
  "number":null,
  "category":"LN",
  "collected_at":"2019-08-13T08:00:44.251929Z",
  "bank_product_id":"18",
  "currency":"MXN",
  "balance": {
      "current": 63054.93,
      "available": 62985.22
  },
  "link":"2259b916-41ec-4dcb-9a01-7865d9c0657e",
  "internal_identification":"1"
}

Você pode usar filtros adicionais na sua consulta de URL para restringir as respostas que recebe. A Belvo suporta os seguintes operadores para suas consultas:

Para usar os operadores, basta adicioná-los ao final da URL da sua solicitação como campos de consulta. Lembre-se de usar duplo sublinhado, __, entre o campo e o operador e o e comercial, &, para encadear campos de consulta juntos. O exemplo abaixo retornará apenas contas onde a currency é BRL e o balance_available está entre 3000 e 5000:

curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?currency=BRL&balance_available__range=3000,5000' \
     --header 'accept: application/json'

Você pode querer direcionar campos aninhados dentro da resposta. No exemplo abaixo, se você quiser direcionar o campo current, o caminho da consulta seria: account__balance__current. Observe que os duplos sublinhados (__) são usados para indicar que um campo está aninhado dentro de outro campo.

{
  "accounts": {
    "link": "57f212dc-1ba4-407f-b7f0-15a5e5ff17ae",
    "category": "CHECKING_ACCOUNT",
    "type": "Cuentas de efectivo",
    "number": "002180700688677950",
    "balance": {
      "available": 4523.48,
      "current": 4523.48
    }
  }
}

No exemplo de requisição abaixo, estamos combinando o direcionamento de um campo aninhado (account__balance__current) com o operador range. Note que tanto para o campo aninhado quanto para o operador, adicionamos duplos sublinhados (__).

curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?account__balance__current__range=3000,5000' \
     --header 'accept: application/json'

Use id={o-id-que-você-deseja}:

https://sandbox.belvo.com/api/transactions/?id=2259b916-41ec-4dcb-9a01-7865d9c0657e

Use account__balance__current__gt={value}. Você precisará usar duplo sublinhado para obter o saldo atual, pois o campo current está aninhado com balance e account:

https://sandbox.belvo.com/api/transactions/?account__balance__current__gt=1000

Use id__in={id1},{id2},{id3}:

https://sandbox.belvo.com/api/accounts/?id__in=
2259b916-41ec-4dcb-9a01-7865d9c0657e,
5a772f98-befc-4217-8ae7-a087e73a7c28,
574d4a4f-1101-4bb0-bb7c-e27a440af507

Use external_id={id}:

https://sandbox.belvo.com/api/links/?external_id={id}