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.

Recomendamos encarecidamente que utilices el parámetro de consulta link en tus solicitudes de List para que solo recibas resultados para un link.id dado.

Al utilizar 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 usando el parámetro de consulta page_size:

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

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

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.

Puedes usar los filtros fields y omit en tu consulta URL para definir qué campos deseas recibir en la respuesta JSON de la API de Belvo. Recomendamos que uses estos campos de manera exclusiva, es decir, no combines fields y omit en la misma consulta. Además, solo puedes usar los filtros fields y omit en campos a nivel raíz (y no en campos anidados).

Esto es particularmente útil si deseas minimizar el tamaño del contenido de las respuestas de la API. Por ejemplo, al consultar el endpoint de cuentas, en lugar de recibir la respuesta completa 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 Filtrado en el ejemplo de código a continuación).

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

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 de tu URL de solicitud como campos de consulta. Recuerda usar doble guion bajo, __, entre el campo y el operador y el ampersand, &, para encadenar campos de consulta juntos. El ejemplo a continuación solo devolverá cuentas donde la currency sea BRL y el balance_available esté entre 3000 y 5000:

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

Es posible que desees apuntar a campos anidados dentro de la respuesta. En el ejemplo a continuación, si quisieras apuntar al campo current, entonces la ruta de consulta sería: account__balance__current. Ten en cuenta que se utilizan dobles guiones bajos (__) 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
    }
  }
}

En el ejemplo de solicitud a continuación, estamos combinando el apuntar a un campo anidado (account__balance__current) así como con el operador range. Observa que tanto para el campo anidado como para el operador, añadimos dobles guiones bajos (__).

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

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

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

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

Usa 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

Usa external_id={id}:

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