Consultar y listar, con cursor

Dos rutas de lectura, para dos preguntas distintas. GET /v1/dte/{codigoGeneracion} responde «¿qué pasó con ESTE documento?», sea cual sea su estado. GET /v1/dte responde «¿qué he sellado en este rango de fechas?» — y solo eso, porque es el libro de lo sellado.

Consultar contesta también por los rechazados

Un documento rechazado no tiene fila en el índice de la empresa, pero sí tiene una reserva de correlativo. Devolver 404 para un número que Hacienda negó mandaría a buscar un error que no existe, así que consultar responde con estado: "rechazado" en vez de un 404.

curl "$FACTA_API_BASE_URL/v1/dte/7875BC7A-9580-441D-94E4-FA455E9D8BD0" \
  -H "X-Facta-Key: $FACTA_API_KEY"

Los estados posibles: sellado, firmado, rechazado, contingencia, invalidado, reservado, liberado, descartado — un solo vocabulario, en español, responda el índice o la reserva.

Listar es el libro de lo sellado, no de todo lo intentado

GET /v1/dte filtra por desde, hasta, estado y tipoDte, y devuelve las filas más nuevas primero. Un documento rechazado no aparece aquí — no es un olvido: un rechazo no es un documento fiscal, y su fila dejaría el numeroControl retenido para siempre en una lista que no le corresponde.

curl "$FACTA_API_BASE_URL/v1/dte?desde=2026-09-01&hasta=2026-09-30&estado=sellado&limit=100" \
  -H "X-Facta-Key: $FACTA_API_KEY"

Por qué la paginación es por cursor

?pagina=2 asume que la tabla no cambia entre una llamada y la siguiente. La suya sí cambia: entre pedir la página 1 y la página 2 pueden entrar filas nuevas, y con paginación por número eso repite un documento o se salta otro.

El siguiente que devuelve la respuesta es la posición exacta de la última fila entregada. Páselo tal cual en ?cursor= y la frontera no se mueve pase lo que pase — es opaco a propósito: interpretarlo o reconstruirlo es lo que se rompe el día que cambie el orden interno.

let cursor: string | null = null;

do {
  const pagina = await facta.listDocuments({ desde: "2026-09-01", hasta: "2026-09-30", limit: 100, ...(cursor ? { cursor } : {}) });
  for (const fila of pagina.documentos) console.log(fila.numeroControl, fila.totales?.totalPagar);
  cursor = pagina.siguiente;   // null cuando no hay más
} while (cursor !== null);

Reconciliar un hueco en su numeración

Si al recorrer listDocuments nota que faltan números entre dos filas consecutivas, el hueco casi siempre es un rechazo: pregunte por ese código de generación con consultar, que sí responde por los rechazados. La guía Contingencia y resultados inciertos cuenta el procedimiento completo de reconciliación tras una caída.

Otras guías