Back to Changelog

API v1.1.0

7. April 2026

Extended invoice fields, PDF template system, country-specific parse endpoints and improved auto-detect parsing.

6 New Invoice Fields

orderNumber, customerNumber, contractNumber, servicePeriod, paymentMethods, countrySpecific

PDF-Template-API

templateId, inline BlockTemplate with 9 block types, ZUGFeRD profile selection

19 Parse-Endpoints

Explicit endpoints per country and format instead of just a generic parameter endpoint

Auto-Detect v2

detection object with confidence score, detection method and ambiguity info

Extended Invoice Fields

The invoice object now supports additional optional fields for complete e-invoices per EN 16931. Seller and buyer have been extended with bank account, trading name and additional address fields.

New Invoice Fields

  • orderNumberPurchase order number
  • customerNumberCustomer number at seller
  • contractNumberContract number
  • servicePeriodService period (start/end)
  • paymentMethodsSEPA, direct debit, credit card
  • countrySpecificDE: buyerReference, leitwegId, isKleinunternehmer

New Seller/Buyer Fields

  • bankAccountIBAN, BIC, bank name, account holder
  • tradingNameTrading name (if ≠ legal name)
  • additionalStreetAdditional address line
  • stateState/region (ISO 3166-2)
  • websiteWebsite URL

Example: Complete request with new fields

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

Full control over PDF layout directly via API. Three options with clear priority:

1

templateId

Reference to a saved template by UUID — highest priority

2

formatOptions.template

Inline BlockTemplate with 9 block types: Text, Table, KeyValue, Columns, Summary, Image, QR Code, Spacer, Line

3

Default-Template

If no template is specified, the API uses the built-in “Gumbonaut” template

Example: Inline template with ZUGFeRD profile

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 Country-Specific Parse Endpoints

In addition to the auto-detect endpoint, there is now a dedicated endpoint for each country and format. This enables targeted parsing without auto-detection.

Auto-Detect

POST /api/v1/invoice/parse

Automatically detects format and country — ideal when the format is unknown

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

Improved Auto-Detect Parsing

The auto-detect endpoint now returns a comprehensive detection object with format detection information.

Detection Fields

  • 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}

New Country Formats

Four countries receive additional e-invoice formats for parsing. Generation continues as PDF.

CountryGenerationParsing NEW
Portugal (PT)PDFSAF-T
Poland (PL)PDFKSeF
Romania (RO)PDFeFactura, UBL
Bulgaria (BG)PDFUBL

Migration from v1.0.0

No Breaking Changes

v1.1.0 is fully backward compatible. All new fields are optional. Existing API calls work without changes. The generic parse endpoint /api/v1/invoice/parse remains available — the 19 country-specific endpoints are an additional option.

All Changelog EntriesAPI Documentation