Introdução

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

Paginação

Aumentar page_size

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'

Propriedades de navegação

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 nesta 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
}

Filtrando Respostas

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.

Obter apenas certos campos

Você pode usar o filtro fields na sua consulta de URL para definir quais campos:

• Você deseja que sejam retornados na sua resposta.
  fields=field1,field2
• Você deseja que sejam excluídos na sua resposta.
  omit=field1,field2

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 Filtered no exemplo de código abaixo).

GET https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/

HTTP/1.1 200 OK
Content-Type: application/json
Content-Size: 341 Bytes # Tamanho não filtrado

{
  "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"
}

GET https://sandbox.belvo.com/api/accounts/
5a772f98-befc-4217-8ae7-a087e73a7c28/?fields=id,balance # Consulta filtrada

HTTP/1.1 200 OK
Content-Type: application/json
Content-Size: 73 Bytes # Resposta filtrada retornada

{
  "id":"5a772f98-befc-4217-8ae7-a087e73a7c28",
  "balance": {
      "current": 63054.93,
      "available": 62985.22
  }
}

Filtrar dados de resposta

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 do campo de consulta (lembre-se de usar duplo sublinhado, __, entre o campo e o operador). O exemplo abaixo retornará apenas contas onde a currency é COP e o balance_available está entre 3000 e 5000:

Campos aninhados de destino

Você pode querer direcionar campos aninhados dentro da resposta. No exemplo abaixo, se você quisesse direcionar o campo current, então o caminho da consulta seria: account__balance__current. Por favor, note que 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
   }
}

Abaixo você verá alguns exemplos de como aplicar filtros às suas chamadas 🤓.

Transação igual a um determinado ID

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

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

Transações de uma conta com determinado saldo

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://api.belvo.com/api/transactions/?account__balance__current__gt=1000

Detalhes da conta para um dos muitos IDs de conta

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

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

Links com um determinado external_id

Use external_id={id}:

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