Rechnungsanhänge

Dieser Leitfaden erklärt, wie Anhänge beim Arbeiten mit Rechnungen über die API oder XML hinzugefügt, gelesen und interpretiert werden.

Workflow auswählen

Mit JSON erstellen: Erstellen Sie die Rechnung zuerst, und fügen Sie anschließend Anhänge mit add_attachment oder add_attachments hinzu.
XML mit eingebetteten Anhängen importieren: Fügen Sie Anhänge innerhalb der XML-Datei ein und importieren Sie die Datei.
PDF mit eingebettetem XML importieren (Eingangsrechnungen): Wenn das PDF ein eingebettetes XML enthält (Factur-X/ZUGFeRD), kann B2Brouter dieses extrahieren und die Eingangsrechnung erstellen.

Wichtige Grundsätze

XML ist die rechtlich verbindliche, strukturierte Quelle. Ihr PDF muss mit den XML-Daten konsistent sein. Versuchen Sie nicht, die XML-Struktur zu ändern, um sie an ein benutzerdefiniertes PDF- Layout anzupassen; die XML-Datei muss standardisierten Schemata folgen, damit jeder Empfänger sie verarbeiten kann.
Anhänge sind ergänzend. Ein PDF (oder jeder andere Anhang) ist keine elektronische Rechnung und ermöglicht allein keine automatisierte Verarbeitung. Verwenden Sie Anhänge als unterstützende Dokumente und nicht als primäre Datenquelle.

Anhänge zu einer bestehenden Rechnung hinzufügen

Einzelnen Anhang hinzufügen (empfohlen für PDF-Vorschau)

Zuerst müssen Sie eine Rechnung erstellen oder importieren.

Nach der Erstellung der Rechnung wird ein Anhang durch eine POST-Anfrage an den Endpoint /invoices/{id}/add_attachment hinzugefügt. Die Anfrage muss die rohen Dateibytes im Request-Body senden und den Dateinamen über den Query-Parameter filename enthalten.

Wenn das angehängte PDF als visuelle und rechtliche Darstellung der Rechnung verwendet werden soll, muss zusätzlich der Parameter use_as_pdf_view=true angegeben werden.

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

Hinweise:

Die API erwartet Content-Type: application/octet-stream.
Rohdaten werden empfohlen; Base64- oder Data-URI-Payloads funktionieren ebenfalls.
use_as_pdf_view=true markiert das PDF als visuelles/rechtliches PDF (nur eines pro Rechnung).
use_as_pdf_view=true gilt nur für PDF-Uploads. Versuchen Sie nicht, ein XML (UBL/Facturae/CII/etc.) als use_as_pdf_view=true zu markieren: Es wird nicht zur PDF-Ansicht.
Die PDF-Ansicht ist für PDF-basierte Dokumenttypen verfügbar wie pdf.invoice, pdf.invoice.signed und hybride PDF/A-Typen wie pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931 und pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.extended.
Wenn Sie die Rechnung später ändern, wird weiterhin dasselbe PDF verwendet, sofern es nicht ersetzt wird.

Mehrere Anhänge hinzufügen (ZIP)

Verwenden Sie den ZIP-Endpoint, wenn Sie mehrere Dateien in einem einzigen Aufruf hochladen möchten.

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

Wenn Sie ein PDF als Rechnungsvorschau festlegen möchten, laden Sie dieses PDF zuerst über den Endpoint add_attachment mit dem Query-Parameter use_as_pdf_view=true hoch und laden Sie anschließend die restlichen Dateien über den Endpoint add_attachments hoch.

Anhänge beim Importieren einer Rechnungs-XML hinzufügen

Wenn Sie bereits XML-Dateien (UBL, Facturae, CII usw.) erzeugen, können Sie Anhänge in die XML-Datei einbetten und die Datei importieren. Die Anhänge werden extrahiert und automatisch gespeichert.

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>

Details zur Kodierung:

Base64 ist die Standardkodierung.
Wenn die XML-Datei einen expliziten Kodierungscode enthält, werden folgende Werte unterstützt: BASE64, BER und DER.
In Facturae kann AttachmentCompressionAlgorithm ZIP oder GZIP sein.
Wenn keine Komprimierung definiert ist, wird der Inhalt als normales Base64 dekodiert.

Eigenes PDF in ZUGFeRD / Factur-X verwenden

Um ein hybrides PDF (PDF + eingebettetes XML) mit eigenem Layout zu versenden:

Wählen Sie einen hybriden Dokumenttyp im Kontakt aus (zum Beispiel: pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931).
Erstellen Sie die Rechnung wie gewohnt.
Laden Sie Ihr PDF hoch mit use_as_pdf_view=true.
Senden Sie die Rechnung.

Kontaktbeispiel:

{
  "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"
  }
}

Um verfügbare Dokumenttypen aufzulisten, verwenden Sie den Document Types Endpoint GET /document_types.

Wie Anhänge in API-Antworten erscheinen

Das Array attachments im Get Invoice Endpoint GET /invoices/{id} enthält die normalen Dateien, die Sie zur Rechnung hochgeladen haben (es enthält nicht das PDF, das als pdf_view markiert wurde).
Im Allgemeinen wird ein PDF, das mit use_as_pdf_view=true hochgeladen wurde, als visuelles/rechtliches PDF (pdf_view) gespeichert und erscheint nicht im attachments-Array.
Ausnahme: Bei Eingangsrechnungen wird das ursprüngliche PDF ebenfalls im attachments-Array angezeigt, wenn das Originaldokument ein PDF ist und sein Dokumenttyp kein attached_document_type ist.
Nach dem Versand einer Ausgangsrechnung verweist download_legal_url auf das rechtliche PDF (von B2Brouter generiert oder Ihr bereitgestelltes pdf_view).

Anhänge aus Eingangsrechnungen lesen

Wenn Sie eine Eingangsrechnung abrufen, enthält die Antwort ein attachments-Array mit Download-Links:

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

Um die Datei herunterzuladen, verwenden Sie den Endpoint GET /attachments/download/{id}/{filename}.

Fügen Sie beim Download Ihren API-Key-Header hinzu. Die id stammt aus dem Link.

Anhänge löschen

Das Löschen ist über die Webanwendung möglich, jedoch gibt es keinen öffentlichen API-Endpoint. Wenn ein Anhang fehlerhaft importiert wurde und Sie einen automatisierten Ablauf benötigen, besteht der empfohlene Ansatz darin, die Rechnung zu löschen und sie erneut ohne den falschen Anhang einzureichen.

Limits und Transportbeschränkungen

B2Brouter erlaubt bis zu 50 MB pro Datei. Beim Versand per E-Mail ist die gesamte Größe der Anhänge auf 40 MB begrenzt. Einige Netzwerke können niedrigere Limits erzwingen (10–20 MB), abhängig vom Kanal.
Erwartete Formate: PDF und XML sowie gängige Office-Dateien (zum Beispiel CSV). Ausführbare oder Skriptformate werden blockiert (zum Beispiel .exe, .js, .bat, .sh, .jar, .ps1, .html, .gif).
Einige Transporte sind als „ohne eingebettete Anhänge“ (detached) konfiguriert, sodass Anhänge nicht in die an den Empfänger gesendete XML-Datei eingebettet werden.
Einige Empfängersysteme ignorieren eingebettete Anhänge, selbst wenn sie vorhanden sind.
Wenn die Rechnung nicht erfolgreich gesendet wird, sieht der Empfänger das PDF unabhängig von den Anhängen nicht.
Der Endpoint add_attachment erfordert Content-Type: application/octet-stream sowie einen filename-Query-Parameter.