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

El artículo no aplica a Débito Directo México
Este artículo no aplica a nuestro producto de Débito Directo (Pagos) en México.

## Paginación

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.

### Aumentar page_size

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

```shell Increase Page Size Example
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 Navigation Properties
{
  "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 una página disponible, se establece en `null`. |
| `previous` | Si está disponible, la página anterior de resultados. Si no hay una página disponible, 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` en `1000`:

```shell Example List Request
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 Example Response With 'next' Navigation Property
{
  "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 Initial response
{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Hasta 1000 resultados
}
```

```json Second response
{
  "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 Third response
{
  "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 Final response
{
  "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 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).

| Parámetro | Uso | Ejemplo |
|  --- | --- | --- |
| `fields` | Cuando deseas incluir solo estos campos en tu respuesta | `https://sandbox.belvo.com/api/{endpoint}/?fields=field1,field2` |
| `omit` | Cuando no deseas que los campos dados se incluyan en tu respuesta | `https://sandbox.belvo.com/api/{endpoint}/?omit=field3,field4` |


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

Sin Filtrar
Al no usar `filter`, el tamaño del contenido de esta respuesta es de `341 Bytes`.

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

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

Filtrado
Usando `filter` para recuperar solo el `id` y el `balance`, el tamaño del contenido de las respuestas se reduce a `73 Bytes`

```shell Filtered Request
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/?fields=id,balance' \
     --header 'accept: application/json'
```

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

### Filtrar datos de respuesta con operadores

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 en la cadena de consulta (incluyendo campos anidados), consulta la sección **Query** del método LIST para cualquier recurso en nuestra documentación de referencia de API. Por ejemplo, aquí están los parámetros de consulta para nuestro recurso de Cuentas.

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

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

### Campos anidados de destino

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.

```json Ejemplo JSON de Campos Anidados de Destino
{
  "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 (`__`).

```shell Ejemplo de Solicitud de Campos Anidados de Destino
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?account__balance__current__range=3000,5000' \
     --header 'accept: application/json'
```

Campos Filtrables por Endpoint
Para saber por cuáles campos puedes filtrar en la cadena de consulta (incluyendo campos anidados), consulta la sección **Query** del método LIST para cualquier recurso en nuestra documentación de referencia de API. Por ejemplo, aquí están los parámetros de consulta para nuestro recurso de Cuentas.

Si encuentras que no puedes filtrar un cierto campo y te gustaría hacerlo, por favor contacta al Soporte de Belvo en support@belvo.com

### Ejemplos

### Transacción igual a un ID dado

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

```shell Transaction Equal to a Given ID Example
https://sandbox.belvo.com/api/transactions/?id=2259b916-41ec-4dcb-9a01-7865d9c0657e
```

#### Transacciones de 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`:

```shell Ejemplo de Transacción de una Cuenta con Cierto Saldo
https://sandbox.belvo.com/api/transactions/?account__balance__current__gt=1000
```

#### Detalles de cuenta para uno de muchos IDs de cuenta

Usa `id__in={id1},{id2},{id3}`:

```shell Account Details for many Account IDs Example
https://sandbox.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}`:

```shell External ID Example
https://sandbox.belvo.com/api/links/?external_id={id}
```