Adjunts de factures

Aquesta guia explica com afegir, llegir i interpretar adjunts quan es treballa amb factures via API o XML.

Trieu un flux de treball

Crear amb JSON: creeu la factura primer, i després afegiu adjunts amb add_attachment o add_attachments.
Importar XML amb adjunts incrustats: incloeu adjunts dins del XML i importeu el fitxer.
Importar PDF amb XML incrustat (factures rebudes): si el PDF conté un XML incrustat (Factur-X/ZUGFeRD), B2Brouter pot extreure’l i crear la factura rebuda.

Principis importants

El XML és la font legal i estructurada. El vostre PDF ha de ser coherent amb les dades XML. No intenteu canviar l’estructura XML per adaptar-la a una maquetació personalitzada del PDF; el XML ha de seguir esquemes estandarditzats perquè qualsevol receptor el pugui processar.
Els adjunts són complementaris. Un PDF (o qualsevol adjunt) no és una factura electrònica i no permet el processament automatitzat per si sol. Useu els adjunts com a documents de suport, no com a font de dades principal.

Afegir adjunts a una factura existent

Afegir un sol adjunt (recomanat per a la previsualització PDF)

Primer, heu de crear o importar una factura.

Després de crear la factura, s’afegeix un adjunt fent una petició POST a l’endpoint /invoices/{id}/add_attachment. La petició ha d’enviar els bytes raw del fitxer com a cos i incloure el nom del fitxer usant el paràmetre de consulta filename.

Si el PDF adjunt s’ha d’usar com a representació visual i legal de la factura, el paràmetre use_as_pdf_view=true també s’ha de proporcionar.

curl --request POST \
  --url 'https://api-staging.b2brouter.net/invoices/12345/add_attachment?filename=invoice.pdf&use_as_pdf_view=true'

Notes:

L’API espera Content-Type: application/octet-stream.
Es recomanen bytes raw; els payloads base64 o data-URI també funcionen.
use_as_pdf_view=true marca el PDF com a PDF visual/legal (només un per factura).
use_as_pdf_view=true només s’aplica a càrregues PDF. No intenteu marcar un XML (UBL/Facturae/CII/etc.) com a use_as_pdf_view=true: no es convertirà en la vista PDF.
La vista PDF està disponible per a tipus de documents basats en PDF com pdf.invoice, pdf.invoice.signed, i tipus híbrids PDF/A com pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931.
Si modifiqueu la factura més tard, s’usa el mateix PDF a menys que es substitueixi.

Afegir múltiples adjunts (ZIP)

Useu l’endpoint ZIP quan necessiteu carregar múltiples fitxers en una sola crida.

zip attachments.zip file1.pdf file2.xml
curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/12345/add_attachments

Si necessiteu definir un PDF com a previsualització de la factura, primer carregueu aquest PDF usant l’endpoint add_attachment amb el paràmetre de consulta use_as_pdf_view=true, i després carregueu la resta amb l’endpoint add_attachments.

Afegir adjunts en importar un XML de factura

Si ja genereu XML (UBL, Facturae, CII, etc.), podeu incrustar adjunts al XML i importar el fitxer. Els adjunts s’extrauran i s’emmagatzemaran automàticament.

UBL (Peppol)

<cac:AdditionalDocumentReference>
  <cbc:ID>ATT-1</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject
      mimeCode="application/pdf"
      filename="invoice.pdf">BASE64_DATA</cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>

Facturae

<AdditionalData>
  <RelatedDocuments>
    <Attachment>
      <AttachmentCompressionAlgorithm>NONE</AttachmentCompressionAlgorithm>
      <AttachmentFormat>PDF</AttachmentFormat>
      <AttachmentEncoding>BASE64</AttachmentEncoding>
      <AttachmentDescription>invoice.pdf</AttachmentDescription>
      <AttachmentData>BASE64_DATA</AttachmentData>
    </Attachment>
  </RelatedDocuments>
</AdditionalData>

CII / ZUGFeRD

<ram:AdditionalReferencedDocument>
  <ram:AttachmentBinaryObject
    mimeCode="application/pdf"
    filename="invoice.pdf">BASE64_DATA</ram:AttachmentBinaryObject>
</ram:AdditionalReferencedDocument>

Detalls de codificació:

Base64 és la codificació predeterminada.
Si el XML inclou un codi de codificació explícit, els valors admesos són BASE64, BER i DER.
A Facturae, AttachmentCompressionAlgorithm pot ser ZIP o GZIP.
Si no es defineix la compressió, el contingut es descodifica com a base64 simple.

Usar el vostre propi PDF a ZUGFeRD / Factur-X

Per enviar un PDF híbrid (PDF + XML incrustat) usant la vostra pròpia maquetació:

Trieu un tipus de document híbrid al contacte (per exemple: pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931).
Creeu la factura com de costum.
Carregueu el vostre PDF amb use_as_pdf_view=true.
Envieu la factura.

Exemple de contacte:

{
  "contact": {
    "name": "Example GmbH",
    "tin_scheme": "9930",
    "tin_value": "DE8******3",
    "transport_type_code": "email",
    "document_type_code": "pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931"
  }
}

Per llistar els tipus de documents disponibles, useu l’endpoint de tipus de documents GET /document_types.

Com apareixen els adjunts a les respostes de l’API

La matriu attachments a l’endpoint get invoice GET /invoices/{id} inclou els fitxers normals que heu carregat a la factura (no inclou el PDF marcat com a pdf_view).
En general, un PDF carregat amb use_as_pdf_view=true s’emmagatzema com a PDF visual/legal (pdf_view) i no apareix a la matriu attachments.
Excepció: per a factures rebudes, si el document original és un PDF i el seu tipus de document no és un attached_document_type, aquest PDF original també s’exposa a la matriu attachments.
Després d’enviar una factura emesa, download_legal_url apunta al PDF legal (generat per B2Brouter o el vostre pdf_view si s’ha proporcionat).

Llegir adjunts de factures rebudes

Quan recupereu una factura rebuda, la resposta inclou una matriu attachments amb enllaços de descàrrega:

{
  "attachments": [
    {
      "link": "/attachments/download/253526/2025-02-10_1_original.pdf",
      "content_type": "application/pdf"
    }
  ]
}

Per descarregar el fitxer useu l’endpoint GET /attachments/download/{id}/{filename}

Incloeu la capçalera de clau d’API en descarregar. L’id prové de l’enllaç.

Eliminar adjunts

L’eliminació és possible des de l’aplicació web, però no hi ha cap endpoint públic d’API. Si un adjunt s’ha importat incorrectament i necessiteu un flux automatitzat, l’enfocament recomanat és eliminar la factura i tornar-la a enviar sense l’adjunt incorrecte.

Límits i restriccions de transport

B2Brouter permet fins a 50 MB per fitxer. Si envieu per correu electrònic, la mida total dels adjunts es limita a 40 MB. Algunes xarxes poden imposar límits més baixos (10–20 MB), depenent del canal.
Formats esperats: PDF i XML, més fitxers d’oficina habituals (per exemple, CSV). Els formats executables o d’script estan bloquejats (per exemple, .exe, .js, .bat, .sh, .jar, .ps1, .html, .gif).
Alguns transports estan configurats com a “sense adjunts incrustats” (desacoblats), de manera que els adjunts no s’inclouen al XML enviat al receptor.
Alguns sistemes destinataris ignoren els adjunts incrustats fins i tot si hi són presents.
Si la factura no s’envia correctament, el destinatari no veurà el PDF independentment dels adjunts.
L’endpoint add_attachment requereix Content-Type: application/octet-stream i un paràmetre de consulta filename.