Exportar l'històric de factures

Aquesta guia explica com exportar un històric complet de factures a través de l’API: totes les factures d’un compte, amb els seus documents. Respon la mateixa pregunta que es fa als dos extrems d’un contracte — podem endur-nos tot l’històric abans de tancar el compte? i una clau d’API pot llegir tot el que ja tenim abans de signar? El procediment és el mateix en tots dos casos.

No hi ha cap endpoint d’exportació massiva

L’API no té cap crida que retorni totes les factures, ni tots els documents, d’una sola vegada. No hi ha cap ZIP, cap tasca d’exportació asíncrona ni cap ruta de descàrrega massiva de factures. La descàrrega massiva disponible a l’aplicació web és una funcionalitat de l’aplicació web; no està publicada com a operació de l’API.

Per exportar un històric, pagineu el llistat de factures i després baixeu els documents de cada factura, tal com es descriu a continuació. Preveieu aquest bucle a la vostra integració des del principi.

Requisits previs

• Una clau d’API amb accés a tots els comptes que vulgueu exportar.
• L’ACCOUNT_ID de cada compte — consulteu Identificadors de compte.

Pas 1: Llistar les factures d’un compte

Useu Llistat de factures:

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'

Exemple de resposta (fragment):

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

La resposta retorna la paginació que s’ha aplicat:

• limit — elements per pàgina. Per defecte són 25 i el màxim és 500. Un valor més gran es redueix a 500.
• offset — el primer element que es retorna. Per defecte és 0.
• total_count — quantes factures compleixen els filtres.

Augmenteu offset en limit i torneu a cridar, fins que offset arribi a total_count.

Pas 2: Repetir-ho per a cada tipus de document

type té per defecte el valor IssuedInvoice, de manera que una crida que l’ometi només retorna factures emeses. Una exportació completa necessita una passada per tipus:

• 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'

Pas 3: Incloure les factures marcades com a rebudes conformes

Per defecte, el llistat amaga les factures marcades com a rebudes conformes (acknowledged). Això és el que convé al dia a dia, on marcar una factura la treu de la llista de pendents. En una exportació és una omissió silenciosa: les pàgines semblen completes i falta part de l’històric.

Afegiu ack=true per llistar les factures marcades juntament amb la resta:

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 llistat també inclou les factures de les unitats organitzatives que pengen del compte. Afegiu exclude_offices=1 si només voleu les factures del compte mateix.

Pas 4: Partir un històric llarg en finestres

Una sola passada sobre offset és fràgil: les factures que es creen mentre corre desplacen les pàgines. Filtrar per data us dona finestres fixes que podeu repetir i reprendre una per una.

• date_from i date_to — la data de la factura.
• due_date_from i due_date_to — la data de venciment.
• updated_at_from — factures modificades després d’una data. És el filtre de les passades incrementals que segueixen una primera exportació completa.
• state_updated_at_from — factures que han canviat d’estat després d’una data.

Mes a mes, cada finestra és una passada curta, i una finestra que falli es pot reintentar tota sola.

Pas 5: Baixar els documents de cada factura

Els passos anteriors us donen identificadors i metadades, no fitxers. Els documents es baixen d’una factura en una. Baixar factures explica totes les rutes amb detall; en un bucle desatès, la que convé és /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}'

Retorna el document legal arxivat tal com està desat, tant per a factures emeses com rebudes, només a partir de l’identificador de la factura. Useu /as/original per al fitxer d’origen a partir del qual es va crear la factura, i attachments[].link per als fitxers adjunts a la factura, que no són el document de la factura.

Ni /as/legal ni /as/original regeneren res, de manera que cap de les dues genera una transacció facturable — consulteu Transacció: View_as. La mida d’una exportació és una qüestió de ritme, no del vostre comptador de transaccions.

Pas 6: Documents de resposta i esdeveniments

Hi ha dues col·leccions que queden fora del payload de la factura. Afegiu-les quan l’exportació hagi de servir com a registre del que ha passat, i no només del que s’ha emès i rebut.

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

GET /invoices/{INVOICE_ID}/responses llista els documents de resposta rebuts per a una factura: acusaments de rebuda i rebuigs retornats per una xarxa o per una autoritat fiscal. Consulteu Llistar els documents de resposta rebuts per a una factura. Com els documents, es recuperen d’una factura en una.

GET /accounts/{ACCOUNT_ID}/events retorna el rastre d’esdeveniments del compte — consulteu Llistat d’esdeveniments. Es pagina amb els mateixos limit i offset, i filtra per date_from, date_to, invoice_id i tax_report_id.

Marqueu el ritme de l’exportació

Una exportació acostuma a ser el procés més pesant d’una integració, de manera que els límits de ritme decideixen quant triga. A Límits de ritme de l’API hi trobareu les xifres publicades i la resposta 429 Too Many Requests.

Dos punts importen en una passada completa:

• El límit compta totes les peticions que venen de la mateixa adreça IP de client, no les peticions d’una clau d’API ni d’un compte. Una exportació que corri des de la màquina que porta la resta del vostre trànsit comparteix pressupost amb ell.
• Davant d’un 429, feu un retard exponencial i reprengueu des del mateix offset. No es perd res.

Feu l’exportació abans de tancar el compte

Un cop el compte està arxivat, els seus endpoints de factures responen 403 i la via d’API descrita aquí deixa d’estar disponible. Feu l’exportació mentre el compte encara és actiu, i tracteu-la com un pas previ al tancament, no posterior.