Paginación

Los listados de clientes (/customers), facturas (/invoices), recibos (/receipts), productos (/products), proveedores (/suppliers), retenciones (/retentions), organizaciones (/organizations) y webhooks (/webhooks), así como las búsquedas de catálogo (/catalogs/...), devuelven resultados paginados. En estos endpoints, Facturapi ofrece dos modos de paginación que puedes elegir con el parámetro pagination:

• pagination=page — el modo clásico, por páginas numeradas. Es el comportamiento por defecto cuando no se envía pagination.
• pagination=cursor — el modo recomendado, por cursores. Recorre los resultados de forma secuencial, sin el tope de 3,000 resultados del modo page, y con páginas estables aunque cambien los datos.

¿Qué modo usar?

	pagination=page	pagination=cursor
Navegación	Saltar a una página específica (page=3)	Secuencial: siguiente / anterior
Alcance	Hasta 3,000 resultados (30 páginas × 100)	Todos los resultados de la búsqueda
Estabilidad	Las páginas se corren si cambian los datos	Páginas estables (basadas en posición)
Uso recomendado	Compatibilidad, interfaces con saltos de página	Listas grandes, iteración, exportaciones

Para la mayoría de los casos, y en particular para listas grandes, te recomendamos usar pagination=cursor.

La diferencia práctica más importante entre ambos modos es el alcance: pagination=page solo permite acceder a los primeros 3,000 resultados (30 páginas × 100 por página), mientras que pagination=cursor puede recorrer todos los resultados de la búsqueda, incluso cuando total_results está capeado a 3,000. Si necesitas exportar o procesar más de 3,000 resultados, usa pagination=cursor.

Parámetros comunes

Parámetro	Tipo	Descripción
limit	integer	Cantidad máxima de resultados a regresar, del 1 al 100.
pagination	string	page (por defecto) o cursor.

Los parámetros page, after y before dependen del modo elegido y son mutuamente excluyentes entre modos:

• pagination=page acepta page, pero no after ni before.
• pagination=cursor acepta after o before, pero no page.

Enviar after y before al mismo tiempo devuelve un error.

Formato de los filtros en la URL

Los filtros viajan en el query string con dos formatos, los mismos que emiten los SDK oficiales:

• Objetos y rangos: notación de corchetes, por ejemplo date[gte]=2026-01-01&date[lt]=2026-02-01 (el estilo deepObject).
• Arreglos: la clave se repite, por ejemplo status=valid&status=canceled (form con explode).

La API también acepta las variantes más comunes de arreglos (status[]=valid&status[]=canceled y status[0]=valid&status[1]=canceled), de modo que las integraciones existentes siguen funcionando.

Paginación por páginas (pagination=page)

Es el modo por defecto. Además de limit, acepta:

Parámetro	Descripción
page	Número de página a regresar, empezando desde 1. El máximo depende del tope de 3,000 resultados (ver más abajo): con el limit por defecto de 100, la página máxima es 30.

En los listados (/customers, /invoices, …) page es el parámetro compartido, que empieza en 1. Las búsquedas de catálogo (/catalogs/...) aceptan los mismos parámetros de paginación, con limit del 1 al 100. El máximo de page no es fijo: sale del tope de 3,000 resultados (con el limit por defecto de 100 son 30 páginas).

Respuesta:

{
  "data": [ ... ],
  "page": 1,
  "total_pages": 3,
  "total_results": 250,
  "totals_are_capped": false
}

Paginación por cursores (pagination=cursor)

En lugar de un número de página, cada respuesta regresa dos cursores que te permiten avanzar o retroceder sobre los resultados:

Parámetro	Descripción
after	Devuelve los resultados posteriores al cursor indicado.
before	Devuelve los resultados anteriores al cursor indicado.

Respuesta:

{
  "data": [ ... ],
  "previous_cursor": null,
  "next_cursor": "d176717f4000000.i65a8282775d4e9263da48115",
  "total_results": 250,
  "totals_are_capped": false
}

total_results y totals_are_capped se incluyen únicamente en la primera página de la búsqueda (cuando no se envían after ni before): el total no cambia entre páginas, así que las siguientes solo regresan data y los cursores.

Navegar entre páginas

1. Primera página: se obtiene sin enviar after ni before. previous_cursor regresa null, indicando que no hay páginas anteriores.
2. Página siguiente: envía after con el valor de next_cursor de la respuesta anterior.
3. Página anterior: envía before con el valor de previous_cursor de la respuesta anterior.

La presencia de previous_cursor y next_cursor es la única fuente de verdad para saber si hay más resultados: si next_cursor es null, llegaste al final de la lista; si previous_cursor es null, estás en la primera página.

# Primera página
curl "https://www.facturapi.io/v2/invoices?pagination=cursor&limit=10" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY"

# Página siguiente (usa next_cursor de la respuesta anterior)
curl "https://www.facturapi.io/v2/invoices?pagination=cursor&limit=10&after=NEXT_CURSOR" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY"

# Página anterior (usa previous_cursor de la respuesta anterior)
curl "https://www.facturapi.io/v2/invoices?pagination=cursor&limit=10&before=PREVIOUS_CURSOR" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY"

Los cursores son tokens opacos y específicos de la búsqueda que los generó: no los combines con otra búsqueda ni los compartas entre distintas consultas. Usarlos con una búsqueda diferente puede regresar resultados inesperados.

Totales y límite de 3,000

Ambos modos regresan total_results con el número de elementos que coinciden con la búsqueda, con un tope de 3,000:

• Si hay 3,000 o menos resultados, total_results es exacto y totals_are_capped es false.
• Si hay más de 3,000, total_results regresa 3000 y totals_are_capped es true, indicando que el total real es "más de 3,000".

{
  "data": [ ... ],
  "previous_cursor": null,
  "next_cursor": "d176717f4000000.i65a8282775d4e9263da48115",
  "total_results": 3000,
  "totals_are_capped": true
}

En ambos modos total_results es informativo: el conteo se acota a 3,000 y no recorre toda la colección. La ventaja práctica de pagination=cursor no es la velocidad del conteo (ambos modos lo acotan), sino su alcance y la estabilidad de las páginas.