Paginación

Los endpoints de listado usan paginación por cursor: cada página trae un next_cursor opaco que devuelves para obtener la página siguiente.

Con la API REST

Esto es lo que devuelve la API de verdad. limit va de 1 a 100 (default 20).

curl "https://api.simplo.cl/api/v1/billing/dte?limit=2" \
  -H "X-Api-Key: $SIMPLO_API_KEY"

{
  "items": [
    {
      "id": "4f9c9c2e-8a49-4f2e-9d5f-0d8f3a1b2c3d",
      "tipo_dte": 33,
      "folio": 1042,
      "estado": "aceptado",
      "rut_receptor": "76543210-3",
      "razon_social_receptor": "Cliente Ejemplo SpA",
      "fecha_emision": "2026-09-04",
      "monto_total": 595000,
      "created_at": "2026-09-04T14:30:00Z",
      "updated_at": "2026-09-04T14:30:12Z"
    }
  ],
  "next_cursor": "eyJvIjoxNzU3..."
}

Para la página siguiente, devuelve el cursor tal cual:

curl "https://api.simplo.cl/api/v1/billing/dte?limit=2&cursor=eyJvIjoxNzU3..." \
  -H "X-Api-Key: $SIMPLO_API_KEY"

Cuando no quedan más páginas, next_cursor viene vacío o ausente. No existe un campo total_count en esta API: no preguntes cuántas páginas faltan, itera hasta que el cursor se acabe. Los cursores son opacos — nunca los parsees ni los construyas.

Con el SDK

El SDK (aún no publicado en npm, ver SDK) envuelve lo anterior en Page<T> y puede recorrer todas las páginas por ti.

El objeto Page<T>

const page = await simplo.dtes.list({ estado: 'aceptado', limit: 100 });

page.data;       // Dte[] — los items de esta página
page.hasMore;    // boolean
page.nextCursor; // string | null
page.totalCount; // number | undefined — total de coincidencias, cuando se reporta

const next = await page.getNextPage(); // Page<Dte> | null

limit va de 1 a 100 (default 20). Los filtros del listado de DTEs están documentados en ListDtesParams: tipo_dte, estado, fecha_desde, fecha_hasta, rut_receptor.

Auto-paginación con for await

Un Page es un iterable asíncrono sobre todos los items restantes; las páginas siguientes se piden de forma lazy a medida que el loop las alcanza:

for await (const dte of await simplo.dtes.list({ fecha_desde: '2026-08-01' })) {
  console.log(dte.folio, dte.monto_total);
}

Puedes cortar el loop en cualquier momento — después de eso no se piden más páginas.

Juntar todo (ojo con la memoria en rangos grandes):

const all: Dte[] = [];
for await (const dte of await simplo.dtes.list(filters)) all.push(dte);

Cursores manuales

Para checkpoints de jobs, persiste el cursor y retoma después:

let cursor: string | undefined = savedCursor;
do {
  const page = await simplo.dtes.list({ ...filters, cursor });
  await process(page.data);
  cursor = page.nextCursor ?? undefined;
  await saveCheckpoint(cursor);
} while (cursor !== undefined);

Los cursores son opacos — nunca los parsees ni los construyas.

Listas sin paginación

folios.list() y webhooks.list() devuelven arrays planos: esas colecciones son pequeñas por naturaleza (una empresa tiene un puñado de CAFs y de endpoints de webhook).