Paginación

Ningún listado te devuelve todo de golpe. Te devuelve una página y, si hay más, un cursor para pedir la siguiente.

Funcionan así GET /v1/documents, GET /v1/webhook-events, GET /v1/documents/{id}/artifacts, GET /v1/deliveries/{id}/attempts y los catálogos, entre otros.

{
  "items": [],
  "next_cursor": "eyJhZnRlciI6…",
  "as_of": "2026-09-20T15:00:00Z"
}

Cuando next_cursor llega en null, se acabó.

Recorrer un listado completo

# Primera página
curl -s -G https://api-sandbox.cufy.co/v1/documents \
  -H "X-API-Key: TU_API_KEY" \
  --data-urlencode "limit=100"

# Siguientes (pega el next_cursor de la respuesta anterior)
curl -s -G https://api-sandbox.cufy.co/v1/documents \
  -H "X-API-Key: TU_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=EL_NEXT_CURSOR"

const API = 'https://api-sandbox.cufy.co';
const headers = { 'X-API-Key': process.env.CUFY_API_KEY };

async function* allDocuments() {
  let cursor = null;
  do {
    const url = new URL(`${API}/v1/documents`);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const page = await fetch(url, { headers }).then((r) => r.json());
    yield* page.items;
    cursor = page.next_cursor;
  } while (cursor);
}

Reglas del cursor

• Es opaco. No lo leas, no lo modifiques, no construyas uno. Solo se devuelve.
• Está atado a sus filtros. Cambiar limit o cualquier filtro a mitad del recorrido invalida el cursor: empieza otra vez desde la primera página.
• No se comparte entre empresas, ambientes ni recursos. Un cursor de tus documentos no sirve en otra cuenta ni en otro listado.
• Caduca a las 24 horas. Uno vencido responde CURSOR_EXPIRED y te obliga a reiniciar el listado.

Qué esperar mientras recorres

GET /v1/documents recorre una instantánea: las facturas que emitas después de pedir la primera página no aparecen hasta que reinicies el listado. Es lo que quieres para exportar o conciliar.

En los demás listados pueden aparecer elementos nuevos entre páginas. Deduplica por id (o por event_id en los eventos de webhook) para no procesar dos veces lo mismo.

Si guardas listados en tu sistema, guarda también el as_of de la respuesta: es el momento al que corresponde lo que leíste.