Listas y paginación
Todas las listas se recorren igual. Pides una página y cada respuesta te da el cursor de la siguiente y de la anterior.
Todas las listas de la API funcionan igual: tus comprobantes, tus entidades, tu numeración, tus webhooks y las solicitudes del portal. Aprendes una y ya sabes recorrerlas todas.
curl "https://api.fiscalbase.io/v1/ec/invoices?limit=20" \
-H "Authorization: Bearer fb_live_…"{
"object": "list",
"data": [{ "id": "…", "object": "invoice", "…": "…" }],
"next_cursor": "bmV4dDowMWEwZWY3Yi0xYzNhLTdkMDEtYjZiNC1iMjQ4YzZiNzM1ZGU",
"prev_cursor": null
}Cómo se recorre
Los resultados vienen del más reciente al más antiguo.
| Parámetro | Qué hace |
|---|---|
limit | Cuántos por página, de 1 a 100. Por defecto, 20 |
cursor | El next_cursor o el prev_cursor de una respuesta anterior. Sin cursor, la primera página |
| En la respuesta | Qué es |
|---|---|
next_cursor | La página siguiente, con los más antiguos. null si ya no hay más |
prev_cursor | La página anterior, con los más recientes. null en la primera página |
Para recorrer todo, pide la primera página y, mientras next_cursor no sea null, pide la siguiente con cursor igual a ese valor.
let cursor = null;
do {
const url = new URL("https://api.fiscalbase.io/v1/ec/invoices");
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const page = await fetch(url, {
headers: { Authorization: `Bearer ${key}` },
}).then((response) => response.json());
for (const invoice of page.data) {
// …
}
cursor = page.next_cursor;
} while (cursor);Las listas de comprobantes agregan además dónde cae la página: total_count, cuántos comprobantes cumplen los filtros en todas las páginas, y offset, cuántos van antes del primero de esta página. Una pantalla puede decir «1 a 8 de 1.126» (offset + 1 a offset + data.length de total_count) sin que tengas que usar números de página.
Por qué cursores
- Nunca ves un elemento dos veces ni te saltas otro, aunque se emitan comprobantes mientras recorres. Con números de página, cada comprobante nuevo empujaría todo una posición.
- No construyes nada. Los cursores son opacos: devuelves lo que recibiste. Uno que no te dimos responde
422encursor.
Filtros de los comprobantes
Las listas de comprobantes también filtran. Los filtros se mantienen mientras recorres: envíalos en cada página junto con el cursor.
| Parámetro | Qué filtra |
|---|---|
status | Un estado: pending, submitted, authorized, returned, not_authorized, annulled. Repítelo para varios: status=returned&status=not_authorized |
counterparty | La identificación del comprador (facturas y notas), del proveedor (retenciones y liquidaciones) o del transportista (guías) |
issue_date[gte], issue_date[lte] | Fecha de emisión, desde y hasta, inclusive |
created_at[gte], created_at[lte] | Momento de creación, desde y hasta, inclusive |
channel | Por dónde llegaron: api, console (emitidos en la consola), shopify, mcp (emitidos por un agente), cli (emitidos por la línea de comandos) o imported (importados de otro sistema). Repítelo para varios |
metadata[clave] | Los que tienen esa clave en su metadata con exactamente ese valor. Hasta 20 pares, y deben coincidir todos |
curl "https://api.fiscalbase.io/v1/ec/invoices?status=returned&issue_date[gte]=2026-09-01" \
-H "Authorization: Bearer fb_live_…"Encontrar un comprobante por tu propio id
Si guardas el id de tu pedido en metadata al emitir, puedes volver a encontrar el comprobante con él, aunque hayas perdido la respuesta o tu sistema haya olvidado el id que te dimos:
curl "https://api.fiscalbase.io/v1/ec/invoices?metadata[pedido]=1041" \
-H "Authorization: Bearer fb_live_…"La coincidencia es exacta: metadata[pedido]=104 no trae el pedido 1041. Cada clave va una sola vez; repetirla, o enviar un parámetro que no existe, responde 422.
Todos los tipos en una lista
GET /v1/ec/documents lista los seis tipos juntos, del más reciente al más antiguo, con los mismos filtros y además type, el object de cada tipo. Repítelo para pedir varios:
curl "https://api.fiscalbase.io/v1/ec/documents?type=invoice&type=credit_note&status=returned" \
-H "Authorization: Bearer fb_live_…"Cada comprobante trae su object, así sabes en qué recurso consultarlo, corregirlo o descargarlo. Un type que no existe responde 422 en type.