Pagination

List endpoints use cursor pagination: each page returns an opaque next_cursor that you send back to get the next page.

With the REST API

This is what the API actually returns. limit ranges from 1 to 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..."
}

For the next page, send the cursor back verbatim:

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

When there are no more pages, next_cursor comes back empty or absent. There is no total_count field in this API: don’t ask how many pages are left, iterate until the cursor runs out. Cursors are opaque — never parse or build them.

With the SDK

The SDK (not published on npm yet, see SDK) wraps the above in Page<T> and can walk every page for you.

The Page<T> object

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

page.data;       // Dte[] — the items on this page
page.hasMore;    // boolean
page.nextCursor; // string | null
page.totalCount; // number | undefined — total matches, when reported

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

limit ranges from 1 to 100 (default 20). The DTE listing filters are documented in ListDtesParams: tipo_dte, estado, fecha_desde, fecha_hasta, rut_receptor.

Auto-pagination with for await

A Page is an async iterable over all remaining items; subsequent pages are fetched lazily as the loop reaches them:

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

You can break out of the loop at any point — no further pages are requested after that.

Collecting everything (watch memory on large ranges):

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

Manual cursors

For job checkpoints, persist the cursor and resume later:

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);

Cursors are opaque — never parse or construct them yourself.

Non-paginated lists

folios.list() and webhooks.list() return plain arrays: those collections are small by nature (a company has a handful of CAFs and webhook endpoints).