Paginación

Los endpoints de lista de Midaz entregan los datos en porciones más pequeñas y manejables. Esto mejora los tiempos de respuesta y el procesamiento del lado del cliente, en particular para aplicaciones que cargan resultados de forma incremental. Las demás APIs de Lerian definen sus propios parámetros, valores predeterminados y límites de paginación. Consulta la referencia de cada API.

Paginación basada en páginas

En lugar de devolver todo el conjunto de datos en una sola respuesta, lo que puede sobrecargar los recursos, los clientes pueden solicitar subconjuntos específicos de datos. Los endpoints basados en páginas admiten dos parámetros de consulta:

page (entero): especifica el número de página que se recuperará. El valor predeterminado es 1.
- Los valores menores que 1 devuelven un error.
limit (entero): define la cantidad máxima 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:

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, a partir de 1 (predeterminado).
limit: la cantidad máxima de elementos incluidos en la respuesta, según lo definido en la solicitud o en la configuración predeterminada.

A continuación se muestra un ejemplo de respuesta para una solicitud paginada:

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

De forma predeterminada, Midaz acepta un máximo de 100 elementos por página (limit=100). Esta restricción evita tamaños de payload excesivos. Si tu caso de uso requiere recuperar una cantidad mayor 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). Las listas de paquetes de cobro mantienen el máximo de 100.

Aumentar el límite de paginación puede generar tiempos de respuesta más lentos según el volumen de datos y las condiciones de la infraestructura. Prueba exhaustivamente en entornos de staging antes de aplicar el cambio en producción.

Después de cambiarlo, reinicia el Ledger. Para definirlo en un despliegue de Midaz, consulta el README del chart de Midaz.

Paginación basada en cursor

Algunos endpoints usan paginación basada en cursor en lugar de números de página. Este enfoque es más eficiente para conjuntos de datos grandes o que cambian con frecuencia. Los endpoints basados en cursor admiten los siguientes parámetros de consulta:

cursor (cadena): 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 empezar desde el principio.
limit (entero): la cantidad máxima de elementos por página.
sort_order (cadena): la dirección usada para ordenar los resultados. Valores aceptados: asc (ascendente) o desc (descendente).

Configura sort_order en la solicitud inicial y mantenlo igual mientras sigues los cursores.

Por ejemplo, para recuperar saldos usando paginación por cursor:

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ás en la primera página.
limit: la cantidad máxima de elementos incluidos en la respuesta.

Para navegar a la página siguiente, pasa el valor de next_cursor como el parámetro de consulta cursor:

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 paginada por cursor:

{
    "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?

La referencia de cada endpoint en la API muestra si admite page o cursor.

Resumen

Fundamentos de integración

Estabilidad y calidad

Diccionario de campos

Streaming de eventos

Paginación basada en páginas

Respuesta de paginación

Tamaño máximo de página

Paginación basada en cursor

Respuesta de paginación por cursor

¿Qué endpoints usan paginación por cursor?

​Paginación basada en páginas

​Respuesta de paginación

​Tamaño máximo de página

​Paginación basada en cursor

​Respuesta de paginación por cursor

​¿Qué endpoints usan paginación por cursor?

Paginación basada en páginas

Respuesta de paginación

Tamaño máximo de página

Paginación basada en cursor

Respuesta de paginación por cursor

¿Qué endpoints usan paginación por cursor?