Descarregar factures

Quan treballeu amb factures, és important diferenciar entre:

• Fitxer de factura legal: el fitxer oficial final que s’ha lliurat (factures emeses) o rebut (factures rebudes).
• Fitxer de factura original: el primer fitxer rebut per B2Brouter per a aquesta factura (per a factures emeses, normalment és un fitxer font importat; per a factures rebudes, és la factura rebuda de l’emissor).
• Exportar una factura a un format específic: B2Brouter genera un document a partir de les dades de la factura (pot diferir del fitxer legal/original).
• Adjunts: fitxers addicionals vinculats a la factura (PDFs, etc.). Els adjunts no són la factura en si mateixa.

Depenent del que necessiteu, haureu de:

• Cridar un endpoint de descàrrega directa (per exemple, /invoices/{INVOICE_ID}/as/original o /invoices/{INVOICE_ID}/as/legal), o
• Utilitzar una ruta de descàrrega retornada al JSON de la factura (per exemple, download_legal_url o attachments[].link).

GET /invoices/{id}/as/legal retorna el document legal arxivat (p. ex., la versió signada i segellada) tal com s’ha emmagatzemat, sense regenerar-lo. Igual que /as/original, aquesta crida no genera cap transacció facturable — vegeu Transaction: View_as.

Per a un procés desatès, com ara un arxiu, una sincronització periòdica o l’exportació de tot un històric, crideu directament /invoices/{INVOICE_ID}/as/legal. Només necessita l’id de la factura, funciona tant per a factures emeses com rebudes, i evita els paranys de download_legal_url que es descriuen més avall. Exportar l’històric de factures mostra el bucle complet.

Prerequisits

• Una clau d’API amb accés al projecte/compte de la factura.
• L’invoice.id intern de B2Brouter (podeu obtenir-lo des dels endpoints de llista).

Pas 1: Obtenir el payload de la factura (opcional però recomanat)

Crideu Get invoice per recuperar el JSON de la factura i localitzar els camps rellevants:

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

Aquest endpoint només retorna JSON

L’endpoint de la factura no serveix la factura com a fitxer. A les versions de l’API 2025-10-13 i posteriors, GET /invoices/{INVOICE_ID}.xml respon 406 Not Acceptable amb el codi d’error not_acceptable, i una capçalera Accept: application/xml s’ignora: la resposta és JSON igualment. Per obtenir l’XML o el PDF d’una factura, feu servir les rutes de descàrrega que es descriuen a continuació.

Factures emeses: fitxer legal via download_legal_url (IssuedInvoice / IssuedSelfInvoice)

Després d’enviar una factura emesa, la resposta inclou download_legal_url, que apunta al fitxer legal lliurat al receptor (per exemple, l’XML exacte enviat a una xarxa/plataforma, o el PDF legal).

El camp només té valor per a factures emeses (IssuedInvoice i IssuedSelfInvoice), i només un cop la factura s’ha enviat. En qualsevol altre cas, incloses totes les factures rebudes, el camp hi és amb el valor null (la versió de l’API 2025-01-01 l’omet). Un null no vol dir que el fitxer falti: per a una factura rebuda, descarregueu-lo amb /invoices/{INVOICE_ID}/as/original o /invoices/{INVOICE_ID}/as/legal, que es descriuen a continuació. Comproveu el valor del camp, no la seva presència.

download_legal_url és una ruta relativa (no una URL completa), per exemple:

{
  "invoice": {
    "download_legal_url": "/attachments/download/{ATTACHMENT_ID}/{FILENAME}"
  }
}

Feu servir la ruta exactament tal com es retorna:

• {ATTACHMENT_ID} és l’id intern del fitxer emmagatzemat. No té cap relació amb l’id de la factura, el número, la sèrie ni la data, i no es pot calcular des del vostre costat.
• {FILENAME} es comprova: l’id correcte amb un nom de fitxer diferent respon 404 Not Found.

Factures rebudes: fitxer original/legal via /invoices/{id}/as/original

Per a les factures rebudes, el fitxer original és també el fitxer legal. Descarregueu-lo directament amb:

GET /invoices/{INVOICE_ID}/as/original

Factures emeses o rebudes: fitxer legal via /invoices/{id}/as/legal

Com a alternativa directa d’un sol pas a download_legal_url, podeu cridar /invoices/{INVOICE_ID}/as/legal directament tant per a factures emeses com rebudes. Retorna el document legal arxivat (p. ex., la versió signada i segellada) tal com s’ha emmagatzemat, sense regenerar-lo:

GET /invoices/{INVOICE_ID}/as/legal

Si la factura encara no té document legal, per exemple una factura emesa que no s’ha enviat, la crida respon 422 amb un missatge d’error que ho indica.

Adjunts (emesos i rebuts): attachments[].link

El JSON de la factura pot incloure una matriu attachments. Cada entrada conté un link que podeu utilitzar per descarregar l’adjunt emmagatzemat.

attachments[].link és una ruta relativa (no una URL completa), per exemple:

{
  "invoice": {
    "attachments": [
      {
        "link": "/attachments/download/{ATTACHMENT_ID}/{FILENAME}",
        "content_type": "application/pdf"
      }
    ]
  }
}

attachments[].link segueix la mateixa regla que download_legal_url: feu-lo servir exactament tal com es retorna. El segment numèric és l’id del fitxer emmagatzemat i no es pot deduir de la factura, i el segment del nom de fitxer es comprova.

Per a una explicació més detallada dels adjunts i PDFs legals, vegeu: Gestionar adjunts de factures.

Pas 2: Descarregar el fitxer

Els camps URL retornats per l’API (download_legal_url, attachments[].link) són rutes relatives. Afegiu-hi el prefix de la URL base del vostre entorn, i no canvieu res més de la ruta.

Descarregar usant download_legal_url (factures emeses, legal)

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

Descarregar usant attachments[].link (adjunts)

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

Descarregar usant /invoices/{id}/as/original (original)

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

Descarregar usant /invoices/{id}/as/legal (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}'

Notes

• Per a les factures rebudes, /invoices/{INVOICE_ID}/as/original retorna el fitxer rebut de l’emissor (original = legal).
• Per a les factures rebudes, download_legal_url és null. És el comportament esperat: feu servir /invoices/{INVOICE_ID}/as/original o /invoices/{INVOICE_ID}/as/legal.
• GET /invoices/{INVOICE_ID} només retorna JSON. El fitxer de la factura s’obté amb les rutes de descàrrega, no amb un sufix de format en aquesta crida.
• Per a les factures emeses, /invoices/{INVOICE_ID}/as/original només funciona quan la factura té un fitxer original (per exemple, XML importat). Si la factura es va crear directament des d’un payload JSON, pot no haver-hi cap fitxer original per descarregar.
• /invoices/{INVOICE_ID}/as/legal funciona tant per a factures emeses com rebudes i no requereix cap crida prèvia per obtenir download_legal_url.
• Ni /as/original ni /as/legal generen cap transacció facturable, ja que no té lloc cap regeneració del document. Vegeu Transaction: View_as.

Endpoints relacionats

• Get invoice
• Get an invoice with a specific document type
• Get received invoice (list)