> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Paginación
> Paginación basada en páginas en los endpoints de listado de Lerian, con parámetros page y limit y una estructura de carga paginada consistente.
Gestionar eficientemente grandes conjuntos de datos es crucial para mantener el rendimiento y la escalabilidad de la API. Nuestras APIs emplean un mecanismo robusto de paginación para entregar datos en porciones más pequeñas y manejables. Esto mejora los tiempos de respuesta y el procesamiento del lado del cliente, particularmente para aplicaciones que cargan resultados incrementalmente.
## Paginación en nuestras APIs
***
En lugar de devolver el conjunto de datos completo en una sola respuesta, lo que puede sobrecargar los recursos, los clientes pueden solicitar subconjuntos específicos de datos. Esto mejora los tiempos de respuesta y permite un manejo de datos más fluido, particularmente para aplicaciones que cargan resultados incrementalmente.
Admitimos dos parámetros de consulta para la paginación:
* `page` (integer): Especifica el número de página a recuperar. El valor predeterminado es `1`.
* Los valores negativos son inválidos y resultarán en un error.
* `limit` (integer): Define el número máximo de elementos por página. El valor predeterminado es `10`.
Por ejemplo, para recuperar la primera página de organizaciones con un máximo de 10 elementos por página:
```http HTTP theme={null}
GET /v1/organizations?page=1&limit=10
```
### Respuesta de paginación
La respuesta de paginación incluye la siguiente estructura:
* `items`: Un arreglo de entidades recuperadas para la página actual. Cada objeto contiene información detallada sobre el recurso solicitado, como se muestra en el ejemplo a continuación.
* `page`: El número de página actual, comenzando desde `1` (predeterminado).
* `limit`: El número máximo de elementos incluidos en la respuesta, como se define en la solicitud o configuración predeterminada.
A continuación se muestra un ejemplo de respuesta para una solicitud paginada:
```jsonon JSON expandable theme={null}
{
"items": [
{
"id": "0193696f-8eff-7926-a77a-0b424cf7156b",
"parentOrganizationId": null,
"legalName": "Collins Inc",
"doingBusinessAs": "The ledger.io",
"legalDocument": "78425230000190",
"address": {
"line1": "Avenida Paulista, 1234",
"line2": "CJ 203",
"zipCode": "01310916",
"city": "New Lyla",
"state": "CH",
"country": "FO"
},
"status": {
"code": "ACTIVE",
"description": "Ledger Test"
},
"createdAt": "2024-11-26T17:05:39.071587Z",
"updatedAt": "2024-11-26T17:05:39.071587Z",
"deletedAt": null,
"metadata": {
"bitcoinn": "3QH2XV7JxMRKXDqh87JG7LWuf7AeGfy",
"boolean": true,
"chave": "metadata_chave",
"double": 10.5,
"int": 1
}
}
],
"page": 1,
"limit": 1
}
```
### Tamaño máximo de página
Por defecto, los endpoints de API que admiten paginación aceptan un máximo de **100 elementos por página** (`limit=100`). Esta restricción ayuda a garantizar un rendimiento óptimo y evita tamaños de payload excesivos.
Si tu caso de uso requiere recuperar un mayor número de elementos por solicitud, puedes anular este límite configurando la variable de entorno `MAX_PAGINATION_LIMIT` en tu configuración de despliegue (archivo `.env`).
Aumentar el límite de paginación puede resultar en tiempos de respuesta más lentos dependiendo del volumen de datos y las condiciones de la infraestructura. Asegúrate de probar exhaustivamente en entornos de staging antes de aplicar el cambio en producción.
Para actualizar esta configuración en Kubernetes:
```bash bash theme={null}
kubectl edit configmap midaz-transaction -n midaz
# Establezca el nuevo valor para MAX_PAGINATION_LIMIT
kubectl rollout restart deployments midaz-transaction -n midaz
```
Midaz y todos sus servicios de plugin heredan este comportamiento.
## Paginación basada en cursor
***
Algunos endpoints utilizan paginación basada en cursor en lugar de números de página. Este enfoque es más eficiente para grandes conjuntos de datos y garantiza resultados consistentes incluso cuando los datos cambian entre solicitudes.
Los endpoints con paginación por cursor aceptan los siguientes parámetros de consulta:
* `cursor` (string): Un token codificado de una respuesta anterior (`next_cursor` o `prev_cursor`) para navegar hacia adelante o hacia atrás. Omite este parámetro para comenzar desde el inicio.
* `limit` (entero): El número máximo de elementos por página. El valor predeterminado es `10`.
* `sort_order` (string): La dirección utilizada para ordenar los resultados. Valores aceptados: `asc` (ascendente, predeterminado) o `desc` (descendente).
Al paginar con un `cursor` de una respuesta anterior, no es posible cambiar el `sort_order` durante la paginación. Los parámetros de ordenamiento deben definirse en la solicitud inicial y permanecer consistentes a lo largo de la secuencia de paginación.
Por ejemplo, para recuperar saldos usando paginación por cursor:
```http HTTP theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?limit=10
```
### Respuesta de paginación por cursor
La respuesta incluye la siguiente estructura:
* `items`: Un arreglo de entidades para la página actual.
* `next_cursor`: Un token codificado para recuperar la siguiente página. Si está ausente o vacío, no hay más resultados.
* `prev_cursor`: Un token codificado para recuperar la página anterior. Si está ausente o vacío, está en la primera página.
* `limit`: El número máximo de elementos incluidos en la respuesta.
Para navegar a la siguiente página, pasa el valor de `next_cursor` como parámetro de consulta `cursor`:
```http HTTP theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?cursor=eyJpZCI6IjAxOTNiN...&limit=10
```
A continuación se muestra un ejemplo de respuesta para una solicitud con paginación por cursor:
```json JSON theme={null}
{
"items": [
{
"id": "019c96a0-0c0d-7915-84b9-e497bfee9916",
"organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
"ledgerId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
"alias": "customer-brl-1",
"key": "default",
"assetCode": "BRL",
"available": "1000",
"onHold": "0"
}
],
"next_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0Ijp0cnVlfQ==",
"prev_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0IjpmYWxzZX0=",
"limit": 10
}
```
### ¿Qué endpoints usan paginación por cursor?
Los siguientes endpoints utilizan paginación basada en cursor:
* **Listar Transacciones** — `GET /v1/organizations/{id}/ledgers/{id}/transactions`
* **Listar Saldos** — `GET /v1/organizations/{id}/ledgers/{id}/balances`
* **Listar Operaciones por Cuenta** — `GET /v1/organizations/{id}/ledgers/{id}/accounts/{id}/operations`
* **Listar Tipos de Cuenta** — `GET /v1/organizations/{id}/ledgers/{id}/account-types`
* **Listar Rutas de Operación** — `GET /v1/organizations/{id}/ledgers/{id}/operation-routes`
* **Listar Rutas de Transacción** — `GET /v1/organizations/{id}/ledgers/{id}/transaction-routes`
Todos los demás endpoints de listado utilizan la paginación estándar basada en página descrita anteriormente.