E-Rechnung: ZUGFeRD und XRechnung

1. 1

   Was FrankKi macht und was nicht

   FrankKi erzeugt aus einer Rechnung zwei Dinge: den gedruckten Brief, der per Post zugestellt wird, und die elektronische Rechnung zum Herunterladen. Die E-Rechnung gibt es in zwei Formaten, ZUGFeRD (eine PDF/A-3 mit eingebettetem EN-16931-XML) und XRechnung (reines XML). Beides ist ausdruecklich download-only: FrankKi uebermittelt keine E-Rechnung an ein Portal, es gibt keinen Peppol-Versand und keine Zustellung an eine Leitweg-ID. Wenn deine Empfaengerin einen Portalweg vorschreibt, laedst du die Datei herunter und reichst sie dort selbst ein.

2. 2

   Drei Aufrufe, ein Beleg

   Die E-Rechnung ist kein eigener Tool-Aufruf, sie faellt am Ende des normalen Ablaufs an. document_create nimmt die strukturierten Belegdaten (Positionen, USt-Saetze, Zahlungsziel), rechnet alles nach und legt den Brief als Entwurf an. order_send verschickt genau diesen Brief mit der letterId aus Schritt 1. Danach liefert document_get unter exports die signierten Download-Links. Wichtig ist die Reihenfolge: das XML entsteht aus derselben geprueften Nutzlast wie der Druck, nicht aus dem PDF, deshalb kann es zwischen Papier und Datei keine Abweichung geben.

   1) document_create  ->  { documentId, letterId, previewUrl, totalCents, ... }
   2) order_send       ->  { orderId, status }            (letterId aus Schritt 1)
   3) document_get     ->  { exports: { zugferdPdfUrl, xrechnungXmlUrl } }

3. 3

   Was document_get zurueckgibt

   exports hat zwei Slots mit derselben Form: available, url, code und message. Ist available true, ist url ein signierter Link auf die fertige Datei, gueltig fuer sieben Tage. Der Link wird bei jedem document_get neu signiert, du musst ihn also nicht speichern, ein erneuter Aufruf liefert einfach einen frischen. Existiert die Datei beim ersten Abruf noch nicht, baut FrankKi sie in genau diesem Aufruf und antwortet dann fertig; dieser eine Aufruf dauert etwas laenger als die spaeteren.

   {
     "documentId": "9f1c...",
     "documentType": "rechnung",
     "documentNumber": "RE-2026-014",
     "letterId": "2b7e...",
     "orderId": "5a90...",
     "exports": {
       "zugferdPdfUrl": {
         "available": true,
         "url": "https://storage.frankki.app/...",
         "code": null,
         "message": null
       },
       "xrechnungXmlUrl": {
         "available": true,
         "url": "https://storage.frankki.app/...",
         "code": null,
         "message": null
       }
     }
   }

4. 4

   Was in der Datei steht

   Die ZUGFeRD-Datei ist ein PDF/A-3b mit eingebettetem EN-16931-XML im Profil COMFORT. Die eingebettete Datei heisst factur-x.xml und traegt die Beziehung Data, so wie es die Spezifikation verlangt, damit die Buchhaltungssoftware deiner Empfaengerin sie findet. Das PDF ist gegen veraPDF und den Mustang-Validator geprueft, das XML gegen die EN-16931-Regeln. Betraege stehen im XML als Dezimalwerte, in der API als ganze Cent. Eine Gutschrift behaelt im XML ihre Vorzeichen aus der Nutzlast, auch wenn der gedruckte Beleg Betraege ohne Vorzeichen zeigt.

   ZUGFeRD-PDF     PDF/A-3b, EN 16931 (COMFORT), Profil-ID urn:cen.eu:en16931:2017
                   Eingebettete Datei heisst factur-x.xml, AFRelationship = Data
                   XMP traegt die ZUGFeRD-Kennung, sRGB-ICC-Profil, alle Schriften eingebettet
   XRechnung-XML   dieselben Daten, standalone, ohne PDF-Huelle
                   BT-24 traegt die XRechnung-3.0-Kennung statt der blanken EN-16931-Profil-ID

5. 5

   Die XRechnung-Variante

   xrechnungXmlUrl liefert dieselben Daten als eigenstaendige XML-Datei, ohne PDF-Huelle. Der einzige inhaltliche Unterschied ist BT-24: dort steht die XRechnung-3.0-Kennung statt der blanken EN-16931-Profil-ID. Alles, was zur PDF-Huelle gehoert, faellt damit weg: kein factur-x.xml, kein XMP, kein PDF/A-Durchlauf. Nimm die XRechnung, wenn eine Behoerde oder ein Portal ausdruecklich XRechnung verlangt, und ZUGFeRD, wenn ein Mensch die Rechnung auch lesen koennen soll.

6. 6

   Fuer welche Belege es das gibt

   Nur Rechnung und Gutschrift, und erst nachdem der Brief versendet ist. Eine Mahnung und eine Zahlungserinnerung wiederholen eine Forderung, die bereits in Rechnung gestellt wurde, und sind nach EN 16931 keine Rechnungen; sie bekommen deshalb nie eine Datei. Brauchst du dort eine E-Rechnung, ist es die Rechnung, auf die sich die Mahnung bezieht: document_get auf die referenzierte documentId.

7. 7

   Wenn kein Link da ist, sagt der Slot warum

   Ist available false, nennt code den Grund, und der Code sagt dir, ob sich ein zweiter Versuch lohnt. DOCUMENT_EXPORT_NOT_SUPPORTED heisst nie: die Belegart kann keine E-Rechnung tragen, oder du arbeitest im Sandbox-Modus, in dem keine echten Belege entstehen. Ein Wiederholen aendert daran nichts. DOCUMENT_EXPORT_NOT_READY heisst spaeter: der Brief ist noch nicht versendet, oder die Funktion ist auf deinem Konto noch nicht freigeschaltet. Versende den Brief und frage danach erneut ab; baue keine Warteschleife, die auf NOT_SUPPORTED weiterprobiert.

   {
     "exports": {
       "zugferdPdfUrl": {
         "available": false,
         "url": null,
         "code": "DOCUMENT_EXPORT_NOT_READY",
         "message": "Die E-Rechnung entsteht erst mit dem Versand. ..."
       },
       "xrechnungXmlUrl": {
         "available": false,
         "url": null,
         "code": "DOCUMENT_EXPORT_NOT_READY",
         "message": "Die E-Rechnung entsteht erst mit dem Versand. ..."
       }
     }
   }

8. 8

   Aufbewahrung

   Jede erzeugte E-Rechnung wird zusaetzlich in FrankKis unveraenderbares Archiv geschrieben, mit Pruefsumme und Verkettung, nach denselben Regeln wie der Brief selbst und der Einlieferungsbeleg. Das ersetzt deine eigene Aufbewahrung nicht: die GoBD verlangt, dass DU das strukturierte Original aufbewahrst. Lade die Datei also herunter und lege sie in dein Archiv, der Download hier ist der bequeme Weg dorthin und keine Auslagerung deiner Pflicht.

9. 9

   Verfuegbarkeit pruefen, bevor du darauf baust

   Die Exporte werden nach und nach freigeschaltet. Ob dein Konto sie hat, siehst du ohne Rateversuch am exports-Slot eines versendeten Belegs: NOT_READY mit dem Hinweis auf die Freischaltung heisst noch nicht da. Im Dashboard zeigt die Liste unter Dokumente dieselbe Antwort als Download-Buttons mit Begruendung. Die vollstaendige Beschreibung beider Fehlercodes steht im Fehlerkatalog.

Strukturierte Briefinhalte (blocks) →Tool-Referenz ansehen →Fehlerkatalog ansehen →