Ein praxisnaher Leitfaden zur Erzeugung und Validierung von XRechnung-Rechnungen mit der Postscale API, mit Codebeispielen und häufigen Fehlerquellen.

XRechnung ist die deutsche Umsetzung des europäischen E-Invoicing-Standards EN 16931. Dieser Leitfaden führt durch die praktischen Schritte zur Erzeugung und Validierung von XRechnung-Rechnungen mit der Postscale API.

XRechnung verstehen

XRechnung ist eine Core Invoice Usage Specification (CIUS) — sie nimmt den breiten EN 16931-Standard und ergänzt deutschlandspezifische Einschränkungen. Stellen Sie sich EN 16931 als das Interface und XRechnung als die Implementierung vor.

Wesentliche Unterschiede zu einer reinen EN 16931-Rechnung:

Verkäuferkontakt ist Pflicht — Name, Telefon und E-Mail (BR-DE-02 bis BR-DE-04)
Käuferreferenz erforderlich — Leitweg-ID für Behördenrechnungen (BR-DE-15)
Zahlungsbedingungen als Text — menschenlesbare Zahlungskonditionen (BR-DE-18)
Eingeschränkte Typcodes — nur 380, 381, 384, 389 sind erlaubt (BR-DE-17)

Validierung zuerst

Bevor Sie Rechnungen erzeugen, validieren Sie Ihre bestehenden:

curl -X POST https://api.postscale.io/v1/invoices/validate \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/xml" \
  -d @ihre-rechnung.xml

Die Antwort sagt Ihnen genau, was falsch ist:

{
  "valid": false,
  "format": "xrechnung-ubl",
  "errors": [
    {
      "rule": "BR-DE-02",
      "path": "/Invoice/AccountingSupplierParty/Party/Contact/Name",
      "message": "The element 'Seller contact point' (BT-41) is required"
    }
  ]
}

Jeder Fehler enthält die XRechnung-Regel-ID, den XPath, wo der Verstoß auftritt, und eine Beschreibung mit Verweis auf die EN 16931 Business-Term-ID (BT-*). Das macht es einfach, Fehler auf Ihr Datenmodell zurückzuführen.

Rechnungen aus JSON erzeugen

Anstatt UBL-XML von Hand zu konstruieren, übergeben Sie strukturiertes JSON an den Sende-Endpunkt:

curl -X POST https://api.postscale.io/v1/invoices/send \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "buchhaltung@ihredomain.com",
    "to": "rechnungen@kunde.de",
    "format": "xrechnung-ubl",
    "invoice": {
      "number": "2026-0089",
      "issue_date": "2026-03-18",
      "due_date": "2026-04-17",
      "currency": "EUR",
      "seller": {
        "name": "Ihre Firma GmbH",
        "street": "Hauptstr. 42",
        "city": "München",
        "postal_code": "80331",
        "country": "DE",
        "tax_id": "DE987654321",
        "contact_name": "Buchhaltungsteam",
        "contact_email": "buchhaltung@ihredomain.com",
        "contact_phone": "+49 89 1234567"
      },
      "buyer": {
        "name": "Kunde AG",
        "street": "Berliner Str. 10",
        "city": "Berlin",
        "postal_code": "10115",
        "country": "DE"
      },
      "payment": {
        "means_code": "58",
        "iban": "DE89370400440532013000",
        "terms": "Zahlbar innerhalb von 30 Tagen"
      },
      "line_items": [
        {
          "description": "Beratung — März 2026",
          "quantity": 40,
          "unit": "HUR",
          "unit_price": "120.00",
          "tax_category": "S",
          "tax_rate": "19.00"
        }
      ]
    }
  }'

Die API erzeugt gültiges UBL 2.1 XML, validiert es und sendet es als E-Mail mit angehängter XML-Datei.

Häufige Fehlerquellen

Fehlender Verkäuferkontakt — XRechnung erfordert alle drei: Kontaktname (BT-41), Telefon (BT-42) und E-Mail (BT-43). EN 16931 macht diese optional, sodass Rechnungen, die unter dem Basisstandard gültig sind, bei der XRechnung-Validierung durchfallen können.

Falscher Zahlungsartcode — Code 58 (SEPA-Überweisung) ist der gängigste für deutsches B2B. Verwenden Sie nicht 1 (nicht definiert) oder ZZZ (gegenseitig vereinbart).

Steuerrundung — Berechnen Sie die Steuer pro Position, dann summieren Sie. Berechnen Sie die Steuer nicht auf den Gesamtnettobetrag. XRechnung erwartet eine Steuerberechnung auf Positionsebene, die mit der Rechnungssumme übereinstimmt.

Datumsformat — Verwenden Sie immer ISO 8601 (JJJJ-MM-TT). Die API akzeptiert dieses Format in JSON und erzeugt die korrekten XML-Datumsdarstellungen.

Testen

Nutzen Sie den Validierungsendpunkt, um Ihre Rechnungen vor dem Produktivstart zu testen. Gängige Testszenarien:

Standard-B2B-Rechnung mit 19 % MwSt.
Gemischte MwSt.-Sätze (19 % und 7 %)
Gutschrift (Typcode 381)
B2G-Rechnung mit Leitweg-ID
Reverse Charge / innergemeinschaftliche Lieferung

Der Validierungsendpunkt ist kostenlos und erzeugt oder sendet nichts — nutzen Sie ihn als Teil Ihrer CI/CD-Pipeline oder Pre-Send-Prüfungen.