Exportar el histórico de facturas

Esta guía explica cómo exportar un histórico completo de facturas a través de la API: todas las facturas de una cuenta, con sus documentos. Responde a la misma pregunta que se plantea en los dos extremos de un contrato — ¿podemos llevarnos todo el histórico antes de cerrar la cuenta? y ¿una clave de API puede leer todo lo que ya tenemos antes de firmar? El procedimiento es el mismo en ambos casos.

No existe ningún endpoint de exportación masiva

La API no tiene ninguna llamada que devuelva todas las facturas, ni todos los documentos, de una sola vez. No hay ZIP, ni tarea de exportación asíncrona, ni ruta de descarga masiva de facturas. La descarga masiva disponible en la aplicación web es una funcionalidad de la aplicación web; no está publicada como operación de la API.

Para exportar un histórico, pagina el listado de facturas y después descarga los documentos de cada factura, tal como se describe a continuación. Prevé ese bucle en tu integración desde el principio.

Requisitos previos

• Una clave de API con acceso a todas las cuentas que quieras exportar.
• El ACCOUNT_ID de cada cuenta — consulta Identificadores de cuenta.

Paso 1: Listar las facturas de una cuenta

Usa Listado de facturas:

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?limit=500&offset=0' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Ejemplo de respuesta (fragmento):

{
  "invoices": [
    {
      "id": 105337,
      "number": "F-2025-1",
      "state": "sent",
      "total": 107.1,
      "currency": "EUR"
    }
  ],
  "total_count": 1840,
  "offset": 0,
  "limit": 500
}

La respuesta devuelve la paginación que se ha aplicado:

• limit — elementos por página. Por defecto son 25 y el máximo es 500. Un valor mayor se reduce a 500.
• offset — el primer elemento que se devuelve. Por defecto es 0.
• total_count — cuántas facturas cumplen los filtros.

Aumenta offset en limit y vuelve a llamar, hasta que offset alcance total_count.

Paso 2: Repetirlo para cada tipo de documento

type tiene por defecto el valor IssuedInvoice, de modo que una llamada que lo omita solo devuelve facturas emitidas. Una exportación completa necesita una pasada por tipo:

• IssuedInvoice
• IssuedSelfInvoice
• IssuedSimplifiedInvoice
• ReceivedInvoice
• ReceivedSelfInvoice

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?type=ReceivedInvoice&limit=500&offset=0' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Paso 3: Incluir las facturas marcadas como recibidas conformes

Por defecto, el listado oculta las facturas marcadas como recibidas conformes (acknowledged). Eso es lo que conviene en el día a día, donde marcar una factura la saca de la lista de pendientes. En una exportación es una omisión silenciosa: las páginas parecen completas y falta parte del histórico.

Añade ack=true para listar las facturas marcadas junto con el resto:

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?type=ReceivedInvoice&ack=true&limit=500&offset=0' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

El listado también incluye las facturas de las unidades organizativas que dependen de la cuenta. Añade exclude_offices=1 si solo quieres las facturas de la cuenta en sí.

Paso 4: Partir un histórico largo en ventanas

Una sola pasada sobre offset es frágil: las facturas que se crean mientras corre desplazan las páginas. Filtrar por fecha te da ventanas fijas que puedes repetir y retomar una a una.

• date_from y date_to — la fecha de la factura.
• due_date_from y due_date_to — la fecha de vencimiento.
• updated_at_from — facturas modificadas después de una fecha. Es el filtro de las pasadas incrementales que siguen a una primera exportación completa.
• state_updated_at_from — facturas que han cambiado de estado después de una fecha.

Mes a mes, cada ventana es una pasada corta, y una ventana que falle se puede reintentar por sí sola.

Paso 5: Descargar los documentos de cada factura

Los pasos anteriores te dan identificadores y metadatos, no ficheros. Los documentos se descargan de una factura en una. Descargar facturas explica todas las rutas con detalle; en un bucle desatendido, la que conviene es /as/legal:

curl --request GET \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/as/legal \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Devuelve el documento legal archivado tal como está almacenado, tanto para facturas emitidas como recibidas, solo a partir del identificador de la factura. Usa /as/original para el fichero de origen a partir del cual se creó la factura, y attachments[].link para los ficheros adjuntos a la factura, que no son el documento de la factura.

Ni /as/legal ni /as/original regeneran nada, de modo que ninguna de las dos genera una transacción facturable — consulta Transacción: View_as. El tamaño de una exportación es una cuestión de ritmo, no de tu contador de transacciones.

Paso 6: Documentos de respuesta y eventos

Hay dos colecciones que quedan fuera del payload de la factura. Añádelas cuando la exportación tenga que servir como registro de lo que ha pasado, y no solo de lo que se ha emitido y recibido.

Disponible a partir de la versión 2026-03-02

GET /invoices/{INVOICE_ID}/responses lista los documentos de respuesta recibidos para una factura: acuses de recibo y rechazos devueltos por una red o por una autoridad fiscal. Consulta Listar los documentos de respuesta recibidos para una factura. Como los documentos, se recuperan de una factura en una.

GET /accounts/{ACCOUNT_ID}/events devuelve el rastro de eventos de la cuenta — consulta Listado de eventos. Se pagina con los mismos limit y offset, y filtra por date_from, date_to, invoice_id y tax_report_id.

Marca el ritmo de la exportación

Una exportación suele ser el proceso más pesado de una integración, de modo que los límites de solicitudes deciden cuánto tarda. En Límite de solicitudes de la API encontrarás las cifras publicadas y la respuesta 429 Too Many Requests.

Dos puntos importan en una pasada completa:

• El límite cuenta todas las peticiones que vienen de la misma dirección IP de cliente, no las peticiones de una clave de API ni de una cuenta. Una exportación que corra desde la máquina que lleva el resto de tu tráfico comparte presupuesto con él.
• Ante un 429, aplica una espera exponencial y retoma desde el mismo offset. No se pierde nada.

Haz la exportación antes de cerrar la cuenta

Una vez la cuenta está archivada, sus endpoints de facturas responden 403 y la vía de API descrita aquí deja de estar disponible. Haz la exportación mientras la cuenta todavía está activa, y trátala como un paso previo al cierre, no posterior.