Las listas del gateway vienen en una de dos formas:

FormaCamposParámetrosDónde
Pagecount, results, next, previouspage, page_sizeBandejas de créditos y subsidios, cuota monetaria, PQRS, salud (citas, facturas, glosas, agenda), administrativo, entregas de webhooks, cartera
OffsetPageresults, limit, offset, has_more, next_offsetlimit, offsetMovimientos de la billetera y pagos de facturas

En todos los SDK una página es iterable sobre sus results y conserva el cuerpo original en raw. Lo que cambia es cómo se piden las siguientes.

SDKPageOffsetPageRecorrido automático
PythonPage (count, results, next)OffsetPage (has_more, next_offset)Bucle propio con page= / offset=
JavaScript / TSPageOffsetPagefor await (const x of page), page.iterPages(), page.getNextPage()
PHPPage (hasNext())OffsetPage (hasMore, nextOffset)Bucle do … while
.NETPageOffsetPage…AutoPagingAsync() → IAsyncEnumerable<JsonObject>
Go*Page (HasNext())*OffsetPage (HasMore, NextOffset)NewPageIterator / NewOffsetIterator (y it.All() con Go 1.23+)

Recorrer una lista por páginas #

Ejemplo: todas las PQRS abiertas y vencidas de Caja Horizonte, de 50 en 50.

page_no = 1
while True:
    page = client.pqrs.list(status="opened", overdue=True, page=page_no, page_size=50)
    for pqrs in page:
        escalate(pqrs)
    if not page.next:
        break
    page_no += 1

Recorrer una lista con limit/offset #

Ejemplo: todos los movimientos de octubre de la billetera de un usuario de Nova.

offset = 0
while True:
    page = client.wallet.transactions.list("1032456789", start_date="2026-10-01",
                                           end_date="2026-10-31", limit=100, offset=offset)
    for movement in page:
        export(movement)
    if not page.has_more or page.next_offset is None:
        break
    offset = page.next_offset

Cuidados #

  • Límites de página. page_size va de 1 a 100 (25 por defecto en la mayoría); limit de 1 a 100 (50 por defecto en movimientos). Pedir más no da error: se recorta.
  • El recorrido automático sigue next. Los iteradores de JS, .NET y Go (y hasNext() en PHP) avanzan mientras la respuesta trae next. Algunas listas no lo incluyen —por ejemplo, el historial de entregas de webhooks devuelve count, page y page_size—, y entonces el recorrido automático se queda en la primera página. En esas listas avanza tú comparando lo recibido con count (ejemplo en reintentos de webhooks).
  • Listas que no paginan. Algunas operaciones devuelven todo en una sola página (por ejemplo, los créditos de un afiliado y las listas administrativas sin parámetro de página): ahí hasNextPage()/HasNext() es falso.
  • Datos que cambian mientras recorres. Si se crean registros durante el recorrido, una página puede repetir o saltar elementos. Para exportaciones completas, filtra por un rango de fechas cerrado y deduplica por id.