Introducción

En esta página puedes encontrar toda la información que necesitas sobre cómo funcionan la paginación y el filtrado con la API de Belvo.

Paginación

Aumentar page_size

Al usar el método List, por defecto recibirás 100 resultados por página. Sin embargo, puedes aumentar esto a un máximo de 1000 resultados utilizando el parámetro de consulta page_size:

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

Propiedades de navegación

En la respuesta para cualquier solicitud de Lista, recibirás propiedades de navegación en la raíz de la respuesta para ayudarte en tus solicitudes subsecuentes:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Hasta 1000 resultados, dependiendo del parámetro page_size.
}

En el caso de que haya más resultados que el límite superior establecido por page_size, necesitarás usar el valor del parámetro next para recibir la siguiente página de resultados (que utiliza el parámetro de consulta page).

Por ejemplo, en el caso de que realices la siguiente llamada de Lista, estableciendo page_size a 1000:

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

Recibirás la siguiente respuesta JSON:

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

Luego puedes usar la URL en el parámetro next para realizar tus siguientes llamadas a la API hasta que next sea igual a null. En el bloque de código a continuación te proporcionamos un ejemplo de todas las respuestas dadas esta situación:

{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Hasta 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": [] // Hasta 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": [] // Hasta 1000 resultados
}

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

Filtrando Respuestas

Usar filtros en tu solicitud puede reducir significativamente el tamaño de la respuesta del servidor, así como asegurarte de eliminar cualquier dato que no necesites para realizar el trabajo.

Obtener solo ciertos campos

Puedes usar el filtro fields en tu consulta URL para definir qué campos:

• Quieres que se devuelvan en tu respuesta.
  fields=field1,field2
• Quieres que se excluyan en tu respuesta.
  omit=field1,field2

Por ejemplo, al consultar el endpoint de cuentas, en lugar de recibir toda la respuesta del servidor, puedes agregar ?fields=id,balance al final de tu consulta para obtener solo el ID de la cuenta y el balance (ver la pestaña Filtered en el ejemplo de código a continuación).

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 # Unfiltered size

{
  "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 # Filtered query

HTTP/1.1 200 OK
Content-Type: application/json
Content-Size: 73 Bytes # Returned filtered response

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

Filtrar datos de respuesta

Puedes usar filtros adicionales en tu consulta URL para limitar las respuestas que recibes. Belvo admite los siguientes operadores para tus consultas:

Para usar los operadores, simplemente agrégales al final del campo de consulta (recuerda usar doble guion bajo, __, entre el campo y el operador). El ejemplo a continuación solo devolverá cuentas donde la currency es COP y el balance_available está entre 3000 y 5000:

Dirigir campos anidados

Es posible que desees dirigir campos anidados dentro de la respuesta. En el ejemplo a continuación, si quisieras dirigir el campo current, entonces la ruta de consulta sería: account__balance__current. Ten en cuenta que los dobles guiones bajos (__) se utilizan para indicar que un campo está anidado dentro de otro campo.

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

A continuación, verás algunos ejemplos de cómo aplicar filtros a tus llamadas 🤓.

Transacción igual a un ID dado

Usa id={el-id-que-quieres}:

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

Transacciones desde una cuenta con cierto saldo

Usa account__balance__current__gt={value}. Necesitarás usar dobles guiones bajos para obtener el saldo actual ya que el campo current está anidado con balance y account:

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

Detalles de la cuenta para uno de muchos IDs de cuenta

Usa 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

Enlaces con un cierto external_id

Usa external_id={id}:

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