API v1.1.0

7. April 2026

Erweiterte Rechnungsfelder, PDF-Template-System, länderspezifische Parse-Endpoints und verbessertes Auto-Detect Parsing.

6 neue Invoice-Felder

orderNumber, customerNumber, contractNumber, servicePeriod, paymentMethods, countrySpecific

PDF-Template-API

templateId, Inline-BlockTemplate mit 9 Block-Typen, ZUGFeRD-Profil-Auswahl

19 Parse-Endpoints

Explizite Endpoints pro Land und Format statt nur generischem Paramter-Endpoint

Auto-Detect v2

detection-Objekt mit Confidence-Score, Erkennungsmethode und Ambiguitäts-Info

Erweiterte Rechnungsfelder

Das Invoice-Objekt unterstützt jetzt zusätzliche optionale Felder für vollständige E-Rechnungen nach EN 16931. Seller und Buyer wurden um Bankverbindung, Handelsname und weitere Adressfelder erweitert.

Neue Invoice-Felder

orderNumberBestellnummer (Purchase Order)
customerNumberKundennummer beim Verkäufer
contractNumberVertragsnummer
servicePeriodLeistungszeitraum (start/end)
paymentMethodsSEPA, Lastschrift, Kreditkarte
countrySpecificDE: buyerReference, leitwegId, isKleinunternehmer

Neue Seller/Buyer-Felder

bankAccountIBAN, BIC, Bankname, Kontoinhaber
tradingNameHandelsname (wenn ≠ juristischer Name)
additionalStreetZusätzliche Adresszeile
stateBundesland/Region (ISO 3166-2)
websiteWebsite-URL

Beispiel: Vollständiger Request mit neuen Feldern

json

1{
2  "invoice": {
3    "invoiceNumber": "RE-2026-042",
4    "type": "invoice",
5    "issueDate": "2026-04-07",
6    "dueDate": "2026-05-07",
7    "currency": "EUR",
8    "orderNumber": "PO-2026-100",
9    "customerNumber": "KD-12345",
10    "servicePeriod": {
11      "start": "2026-03-01",
12      "end": "2026-03-31"
13    },
14    "seller": {
15      "name": "Acme GmbH",
16      "street": "Musterstraße 1",
17      "city": "Berlin",
18      "postalCode": "10115",
19      "countryCode": "DE",
20      "vatId": "DE123456789",
21      "bankAccount": {
22        "iban": "DE89370400440532013000",
23        "bic": "COBADEFFXXX"
24      }
25    },
26    "buyer": {
27      "name": "Kunde AG",
28      "street": "Kundenweg 42",
29      "city": "München",
30      "postalCode": "80331",
31      "countryCode": "DE",
32      "vatId": "DE987654321"
33    },
34    "countrySpecific": {
35      "buyerReference": "BUYER-REF-001",
36      "leitwegId": "991-12345-67"
37    },
38    "paymentMethods": [
39      { "type": "bank_transfer" }
40    ],
41    "items": [
42      {
43        "position": 1,
44        "description": "Beratungsleistung März 2026",
45        "quantity": 40,
46        "unit": "HUR",
47        "unitPrice": 150.00,
48        "taxRate": 19,
49        "netAmount": 6000.00,
50        "taxAmount": 1140.00,
51        "grossAmount": 7140.00
52      }
53    ],
54    "subtotal": 6000.00,
55    "total": 7140.00,
56    "taxSummary": [
57      { "taxRate": 19, "netAmount": 6000.00, "taxAmount": 1140.00 }
58    ],
59    "paymentTerms": { "dueDays": 30 }
60  },
61  "templateId": "550e8400-e29b-41d4-a716-446655440000"
62}

PDF-Template-System

Volle Kontrolle über das PDF-Layout direkt per API. Drei Optionen mit klarer Priorität:

templateId

Referenz auf ein gespeichertes Template per UUID — höchste Priorität

formatOptions.template

Inline-BlockTemplate mit 9 Block-Typen: Text, Table, KeyValue, Columns, Summary, Image, QR-Code, Spacer, Line

Default-Template

Wird kein Template angegeben, nutzt die API das eingebaute “Gumbonaut”-Template

Beispiel: Inline-Template mit ZUGFeRD-Profil

json

1{
2  "invoice": { ... },
3  "formatOptions": {
4    "zugferdProfile": "EN16931",
5    "template": {
6      "version": "1.0.0",
7      "name": "custom-invoice",
8      "page": {
9        "size": "A4",
10        "margins": { "top": 40, "right": 40, "bottom": 60, "left": 40 }
11      },
12      "header": {
13        "height": 80,
14        "blocks": [
15          { "type": "text", "data": { "content": "{{seller.name}}", "fontSize": 18, "bold": true } }
16        ]
17      },
18      "body": {
19        "blocks": [
20          { "type": "text", "data": { "content": "Rechnung {{invoiceNumber}}" } },
21          { "type": "table", "data": { "dataSource": "items" } },
22          { "type": "summary", "data": { "dataSource": "taxSummary" } }
23        ]
24      }
25    }
26  }
27}

19 länderspezifische Parse-Endpoints

Neben dem Auto-Detect-Endpoint gibt es jetzt für jedes Land und Format einen eigenen Endpoint. Das ermöglicht gezieltes Parsing ohne Auto-Erkennung.

Auto-Detect

POST /api/v1/invoice/parse

Erkennt Format und Land automatisch — ideal wenn das Format unbekannt ist

DE / XRECHNUNG

/de/xrechnung/parse

DE / ZUGFERD

/de/zugferd/parse

DE / FACTURX

/de/facturx/parse

DE / UBL

/de/ubl/parse

AT / EBINTERFACE

/at/ebinterface/parse

AT / ZUGFERD

/at/zugferd/parse

FR / FACTURX

/fr/facturx/parse

FR / UBL

/fr/ubl/parse

IT / FATTURAPA

/it/fatturapa/parse

ES / FACTURAE

/es/facturae/parse

NL / UBL

/nl/ubl/parse

BE / UBL

/be/ubl/parse

PT / SAFT

/pt/saft/parse

PL / KSEF

/pl/ksef/parse

CZ / ISDOC

/cz/isdoc/parse

HU / NAV

/hu/nav/parse

RO / EFACTURA

/ro/efactura/parse

RO / UBL

/ro/ubl/parse

BG / UBL

/bg/ubl/parse

Verbessertes Auto-Detect Parsing

Der Auto-Detect-Endpoint liefert jetzt ein umfangreiches detection-Objekt mit Informationen zur Formaterkennung.

Detection-Felder

format — z.B. XRECHNUNG_UBL, ZUGFERD_EN16931
formatVersion — z.B. 3.0.2
countryCode — ISO 3166-1 alpha-2
confidence — 0–100 Erkennungssicherheit
formatMethod — NAMESPACE, ROOT_ELEMENT, CUSTOMIZATION_ID, PROFILE_ID, HEURISTIC
countrySource — DOCUMENT, FORMAT_MAPPING, UNKNOWN
isAmbiguous — Format für mehrere Länder gültig?
alternativeCountries — Mögliche alternative Länder

Auto-Detect Response

json

1{
2  "success": true,
3  "detection": {
4    "format": "XRECHNUNG_UBL",
5    "formatVersion": "3.0.2",
6    "countryCode": "DE",
7    "confidence": 98,
8    "formatMethod": "CUSTOMIZATION_ID",
9    "countrySource": "DOCUMENT",
10    "isAmbiguous": false,
11    "alternativeCountries": []
12  },
13  "invoice": { ... },
14  "hash": "sha256:a1b2c3..."
15}

Neue Länder-Formate

Vier Länder erhalten zusätzliche E-Invoice-Formate für das Parsing (Einlesen). Die Generierung erfolgt weiterhin als PDF.

Land	Generierung	Parsing NEU
Portugal (PT)	PDF	SAF-T
Polen (PL)	PDF	KSeF
Rumänien (RO)	PDF	eFactura, UBL
Bulgarien (BG)	PDF	UBL

Migration von v1.0.0

Keine Breaking Changes

v1.1.0 ist vollständig abwärtskompatibel. Alle neuen Felder sind optional. Bestehende API-Aufrufe funktionieren ohne Änderung. Der generische Parse-Endpoint /api/v1/invoice/parse bleibt verfügbar — die 19 länderspezifischen Endpoints sind eine zusätzliche Option.

Alle Changelog-Einträge API-Dokumentation