Adjunts de factures

Disponible a partir de la versió 2025-10-13

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

Tria un flux de treball

• Crear amb JSON: crea la factura primer, i després afegeix adjunts amb add_attachment o add_attachments.
• Importar XML amb adjunts incrustats: inclou adjunts dins del XML i importa 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 teu PDF ha de ser coherent amb les dades XML. No intentis 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. Usa 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, has 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 intentis 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 modifiques la factura més tard, s’usa el mateix PDF a menys que es substitueixi.

Afegir múltiples adjunts (ZIP)

Usa l’endpoint ZIP quan necessitis 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 necessites definir un PDF com a previsualització de la factura, primer carrega aquest PDF usant l’endpoint add_attachment amb el paràmetre de consulta use_as_pdf_view=true, i després carrega la resta amb l’endpoint add_attachments.

Afegir adjunts en importar un XML de factura

Si ja generes XML (UBL, Facturae, CII, etc.), pots 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 teu propi PDF a ZUGFeRD / Factur-X

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

1. Tria un tipus de document híbrid al contacte (per exemple: pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931).
2. Crea la factura com de costum.
3. Carrega el teu PDF amb use_as_pdf_view=true.
4. Envia la factura.

La vista PDF pròpia només es pot fixar per API. Si adjuntes el PDF a la web, des de la secció «Fitxers addicionals» de la factura, viatja com a fitxer addicional, al costat del PDF que genera B2Brouter.

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, usa l’endpoint de tipus de documents GET /document_types.

VeriFactu

B2Brouter lliura el teu PDF tal com l’has carregat i no hi afegeix el codi QR. El PDF ha de portar el QR i la menció «VERI*FACTU» abans de carregar-lo.

Pots generar el QR abans d’enviar la factura. El seu contingut és la URL de validació de l’AEAT, https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR, amb quatre paràmetres:

• nif: NIF de l’emissor.
• numserie: sèrie i número separats per /, o només el número si la factura no té sèrie.
• fecha: data de la factura, en format dd-mm-aaaa.
• importe: total amb impostos, amb 2 decimals.

Tots quatre han de coincidir amb les dades de la factura a B2Brouter. B2Brouter declara la factura a l’AEAT quan l’envies: no la declaris per cap altra via. Consulta la guia de VeriFactu.

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 has 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 teu pdf_view si s’ha proporcionat). També el pots obtenir directament amb GET /invoices/{id}/as/legal, que retorna el document legal arxivat tal com està emmagatzemat i no genera cap transacció facturable — consulta Descarregar factures i Transaction: View_as.

Llegir adjunts de factures rebudes

Quan recuperes 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 usa l’endpoint GET /attachments/download/{id}/{filename}

Inclou 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 necessites 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 envies 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.