# Paginación Basada en Cursor

## Mejoras en la paginación

Para mejorar el rendimiento y la fiabilidad de nuestra API, estamos migrando progresivamente nuestros métodos de Lista a paginación basada en cursor. Esta actualización está diseñada para proporcionar una experiencia más estable y eficiente, especialmente al manejar grandes volúmenes de datos.

Estructura Obsoleta
La paginación basada en cursor **reemplazará** los objetos `_links` y `metadata` anteriores:


```json Estructura de Paginación Obsoleta
{
  "_links": {
    "first": "/{resource}?limit=20",
    "last": "/{resource}?page=4&limit=20",
    "next": "/{resource}?page=3&limit=20",
    "previous": "/{resource}?page=2&limit=20"
  },
  "metadata": {
    "totalItems": 100,
    "itemCount": 10,
    "itemsPerPage": 10,
    "totalPages": 10,
    "currentPage": 1
  }
}
```

## Cómo Funciona

### Estructura

Con la introducción de la paginación basada en cursor, la estructura de nuestras respuestas de API para los métodos de Lista se actualizará. Aquí tienes un vistazo al nuevo formato (ver la clave de paginación):


```json Cursor Token Example
{
  "items": [
    // Objetos de recurso
  ],
  "pagination": { // [!code highlight]
    "nextCursorToken": "eyJpZCI6IjBkMWEzNzdiLWI0YzUtNGE5NC05ZTJlLTgzZTU5ZDFmNmE5YyIsImNyZWF0ZWREYXRlIjoiMjAyNS0wNy0wMlQxMjozNDo1NloifQ==", // [!code highlight]
    "previousCursorToken": null, // [!code highlight]
  }
}
```

### Navegando Resultados

Para navegar a través de resultados paginados, utilizarás el `nextCursorToken` (o `previousCursorToken`) de una respuesta como un parámetro en tu siguiente solicitud. Por ejemplo:

1. **Solicitud Inicial**: Tu primera solicitud a un endpoint de Lista no incluirá un `nextCursorToken`.

```shell Llamada API Inicial
curl GET baseUrl/account_movements?limit=100
```
2. **Solicitudes Subsecuentes**: Para recuperar el siguiente conjunto de resultados, toma el valor de `nextCursorToken` del objeto de paginación en la respuesta y úsalo como el parámetro de consulta `nextCursorToken` en tu siguiente llamada. En el caso de que desees el conjunto anterior de resultados, toma el valor de `previousCursorToken` y pásalo como el parámetro de consulta `previousCursorToken`.

```shell Llamadas API Subsecuentes
# Avanzando
GET baseUrl/account_movements?limit=100&nextCursorToken={pagination.nextCursorToken}

# Retrocediendo
GET baseUrl/account_movements?limit=100&previousCursorToken={pagination.previousCursorToken}
```


Puedes continuar haciendo solicitudes con el nuevo `nextCursorToken` o `previousCursorToken` de cada respuesta hasta que el valor del campo sea `null` (indicando que no hay más resultados).

## Endpoints Actualmente Soportados

Estamos implementando esta mejora en nuestra API. Los siguientes métodos de Lista actualmente soportan paginación basada en cursor:

- `GET baseUrl/account_movements` (En Producción el 5 de agosto de 2025)
- `GET baseUrl/payment_requests` (En Producción el 5 de agosto de 2025)
- `GET baseUrl/payment_methods` (En Producción el 8 de agosto de 2025)
- `GET baseUrl/customers` (En Producción el 22 de agosto de 2025)
- `GET baseUrl/consents` (En Producción el 22 de agosto de 2025)


## Cómo Adoptar la Nueva Paginación

Hemos diseñado la transición para que sea lo más fluida posible.

- **Para Nuevos Clientes:** La paginación basada en cursor está habilitada por defecto para todos los nuevos clientes.
- **Para Clientes Existentes:** Una vez que hayas actualizado tu integración para manejar el nuevo formato de respuesta y solicitud de paginación, por favor contacta a nuestro equipo de soporte. Luego activaremos esta función para tu cuenta.


## Lista de Verificación de Migración

- [ ] Actualizar el análisis de respuestas para usar el objeto `pagination`
- [ ] Reemplazar la lógica basada en páginas con el manejo de token de cursor
- [ ] Probar con tus filtros y ordenamientos existentes
- [ ] Contactar al soporte para habilitar la paginación por cursor