# 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

Usa el parámetro de consulta `link` al listar
Recomendamos encarecidamente que uses el parámetro de consulta `link` en tus solicitudes de **Lista** para que solo recibas resultados para un `link.id` dado.

### 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
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:


```json
{
  "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.
}
```

| Parámetro | Descripción |
|  --- | --- |
| `count` | El número total de resultados para tu consulta. |
| `next` | Si está disponible, la siguiente página de resultados. Si no hay página disponible, esto se establece en `null`. |
| `previous` | Si está disponible, la página anterior de resultados. Si no hay página disponible, esto se establece en `null`. |
| `results` | Un array de resultados para tu consulta. |


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
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:


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

Parámetros de consulta propagados
Como puedes ver en los ejemplos, cualquier parámetro de consulta que proporciones se propaga al valor de `next`. Por ejemplo, en la solicitud inicial enviamos `?link=link_id&page_size=1000`, y en la respuesta, podemos ver que estos parámetros de consulta se mantienen en la nueva URL en el parámetro `next`: `?link=link_id&page_size=1000&page=2`.

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:


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


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


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


```json
{
  "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`


Solo puedes apuntar a campos de primer nivel, lo que devolverá cualquier campo anidado

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).


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


```shell
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:

Campos filtrables por endpoint
Para saber qué campos puedes filtrar, consulta nuestra documentación de referencia de la API.
Si encuentras que no puedes filtrar un campo determinado y te gustaría hacerlo, por favor contacta al Soporte de Belvo en support@belvo.com

| Operador | Usar cuando quieras | Ejemplo |
|  --- | --- | --- |
| `=` | Obtener resultados que coincidan exactamente con un valor. | `fieldA=OpenFinance` |
| `gt` | Obtener resultados que sean mayores que un valor dado. | `fieldA__gt=5000` |
| `lt` | Obtener resultados que sean menores que un valor dado. | `fieldA__lt=6000` |
| `gte` | Obtener resultados que sean mayores o iguales a un valor dado. | `fieldA__gte=5000` |
| `lte` | Obtener resultados que sean menores o iguales a un valor dado. | `fieldA__lte=6000` |
| `in` | Obtener resultados para cualquiera de los elementos listados. Funciona con cadenas de texto. | `fieldA__in=monday,wednesday,friday` |
| `range` | Obtener resultados que estén entre dos valores. Funciona con fechas y números. Separa los dos valores con una coma. | `fieldA__range=1,5` |
| `&` | Combinar consultas. | `query1&query2` |


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.


```json
"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}`:


```curl
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`:


```curl
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}`:


```curl
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}`:


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