Referenz

Feldreferenz

Jedes Feld des invoice-Objekts, das die Creator- und Validator-API entgegennehmen. Diese Seite wird aus der OpenAPI-Spezifikation erzeugt und kann deshalb nicht von ihr abweichen.

147
Felder
11
Pflichtfelder auf invoice
23
Objekte

Erzeugt aus Invoice.xhub API · POST /api/v1/invoice/{countryCode}/{format}/generate

Ein vollständiges Beispiel

Dieselben Daten, die im Playground auf der Startseite vorbelegt sind — vollständig, mit allen Pflichtfeldern.

json
1{
2 "invoice": {
3 "invoiceNumber": "RE-2025-001",
4 "type": "invoice",
5 "issueDate": "2025-01-15",
6 "dueDate": "2025-02-15",
7 "currency": "EUR",
8 "seller": {
9 "name": "Muster GmbH",
10 "vatId": "DE811128135",
11 "street": "Musterstraße 1",
12 "postalCode": "10115",
13 "city": "Berlin",
14 "countryCode": "DE",
15 "email": "info@muster.de",
16 "phone": "+49 30 12345678",
17 "bankAccount": {
18 "iban": "DE89370400440532013000",
19 "bic": "COBADEFFXXX"
20 }
21 },
22 "buyer": {
23 "name": "Beispiel AG",
24 "vatId": "DE136695976",
25 "street": "Beispielweg 42",
26 "postalCode": "80331",
27 "city": "München",
28 "countryCode": "DE"
29 },
30 "items": [
31 {
32 "position": 1,
33 "description": "Beratungsleistung",
34 "quantity": 10,
35 "unit": "HUR",
36 "unitPrice": 150,
37 "taxRate": 19,
38 "netAmount": 1500,
39 "taxAmount": 285,
40 "grossAmount": 1785
41 }
42 ],
43 "taxSummary": [
44 {
45 "taxRate": 19,
46 "netAmount": 1500,
47 "taxAmount": 285
48 }
49 ],
50 "subtotal": 1500,
51 "total": 1785,
52 "paymentTerms": {
53 "dueDays": 30,
54 "description": "Zahlbar innerhalb von 30 Tagen"
55 },
56 "countrySpecific": {
57 "countryCode": "DE",
58 "leitwegId": "991-12345-67"
59 }
60 }
61}

Drei Stellen, an denen Integrationen hängenbleiben

Sobald paymentMethods eine Überweisung enthält, verlangt EN 16931 (BR-61) die Zahlungskonto-Kennung. Ohne seller.bankAccount.iban wird die Rechnung abgelehnt.

Die Mengeneinheit ist ein Code nach UN/ECE Rec 20, kein Klartext: C62 (Stück), HUR (Stunde), KGM (Kilogramm), MTR (Meter), DAY (Tag). "Stk" oder "piece" fällt bei BR-CL-23 durch.

Wird countrySpecific gesetzt, ist countryCode darin Pflicht — auch wenn der Ländercode bereits im Pfad steht.

Alle Felder

invoice

Invoice data to generate document from

FeldTypPflichtBeschreibung
invoiceNumberstringPflichtfeldUnique invoice number
Beispiel: INV-2026-0042
typestringPflichtfeldInvoice type
Erlaubte Werte: invoice, credit_note, proforma, correction
issueDatestringPflichtfeldIssue date (ISO 8601: YYYY-MM-DD)
Beispiel: 2026-03-20
dueDatestringPflichtfeldDue date (ISO 8601: YYYY-MM-DD)
Beispiel: 2026-04-19
deliveryDatestringoptionalDelivery/service date (ISO 8601)
Beispiel: 2026-03-20
servicePeriodobjectoptionalService period (Leistungszeitraum). Required in DE if different from issueDate.
sellerobjectPflichtfeldSeller party information
buyerobjectPflichtfeldBuyer party information
itemsobject[]PflichtfeldInvoice line items
currencystringPflichtfeldCurrency code (ISO 4217)
Beispiel: EUR
subtotalnumberPflichtfeldTotal net amount
Beispiel: 4800
totalnumberPflichtfeldTotal gross amount
Beispiel: 5712
taxSummaryobject[]PflichtfeldTax summary per tax rate
paymentTermsobjectoptionalPayment terms
paymentMethodsobject[]optionalPayment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.
orderNumberstringoptionalPurchase order number (Bestellnummer)
Beispiel: PO-2026-0815
customerNumberstringoptionalCustomer number at the seller
Beispiel: KD-42
contractNumberstringoptionalContract number (BT-12)
Beispiel: V-2025-1234
projectNumberstringoptionalProject reference (BT-11)
Beispiel: PROJ-2026-42
roundingAmountnumberoptionalRounding amount (BT-114)
Beispiel: 0.01
allowancesChargesobject[]optionalInvoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.
deliveryobjectoptionalDelivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).
directDebitMandateobjectoptionalSEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.
notesstringoptionalAdditional notes displayed on the invoice
Beispiel: Vielen Dank für Ihren Auftrag!
profilestringoptionalXRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.
Erlaubte Werte: xrechnung, xrechnung-extension
referencedInvoiceNumberstringoptionalNumber of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.
Beispiel: INV-2026-0040
referencedInvoiceDatestringoptionalIssue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.
Beispiel: 2026-03-15
deliveryNoteobjectoptionalDespatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.
thirdPartyPaymentsobject[]optionalThird-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.
attachmentsobject[]optionalEmbedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.
serviceCategorystringoptionalService category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: "AE"`, the generator emits the §13b UStG reverse-charge note automatically.
Erlaubte Werte: construction, general
constructionTaxobjectoptionalGerman construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.
countrySpecificobjectoptionalCountry-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.

servicePeriod

Service period (Leistungszeitraum). Required in DE if different from issueDate.

FeldTypPflichtBeschreibung
startstringPflichtfeldPeriod start (ISO 8601: YYYY-MM-DD)
Beispiel: 2026-03-01
endstringPflichtfeldPeriod end (ISO 8601: YYYY-MM-DD)
Beispiel: 2026-03-31

seller

Seller party information

FeldTypPflichtBeschreibung
namestringPflichtfeldLegal name of the party
Beispiel: Muster GmbH
tradingNamestringoptionalTrading name (if different from legal name)
Beispiel: Muster Shop
streetstringoptionalStreet address
Beispiel: Hauptstraße 42
additionalStreetstringoptionalAdditional address line
Beispiel: 2. OG, Raum 5
citystringoptionalCity
Beispiel: Berlin
postalCodestringoptionalPostal code
Beispiel: 10115
countryCodestringPflichtfeldCountry code (ISO 3166-1 alpha-2)
Beispiel: DE
statestringoptionalState/region (ISO 3166-2)
Beispiel: BE
taxIdstringoptionalNational tax identification number
Beispiel: 27/123/45678
vatIdstringoptionalEU VAT identification number
Beispiel: DE136695976
emailstringoptionalEmail address
Beispiel: billing@muster.de
phonestringoptionalPhone number
Beispiel: +49 30 12345678
websitestringoptionalWebsite URL
Beispiel: https://muster.de
contactobjectoptionalStructured contact person (BG-6 for seller, BG-9 for buyer)
bankAccountobjectoptionalBank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.
Sobald paymentMethods eine Überweisung enthält, verlangt EN 16931 (BR-61) die Zahlungskonto-Kennung. Ohne seller.bankAccount.iban wird die Rechnung abgelehnt.

seller.contact

Structured contact person (BG-6 for seller, BG-9 for buyer)

FeldTypPflichtBeschreibung
namestringoptionalContact person name
Beispiel: Max Mustermann
phonestringoptionalContact phone number
Beispiel: +49 30 12345678
emailstringoptionalContact email address
Beispiel: max@muster.de

seller.bankAccount

Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.

FeldTypPflichtBeschreibung
ibanstringPflichtfeldIBAN (International Bank Account Number)
Beispiel: DE89370400440532013000
bicstringoptionalBIC/SWIFT code (8 or 11 characters)
Beispiel: COBADEFFXXX
bankNamestringoptionalName of the bank
Beispiel: Commerzbank
accountHolderstringoptionalAccount holder name (if different from party name)
Beispiel: TechCorp GmbH

buyer

Buyer party information

FeldTypPflichtBeschreibung
namestringPflichtfeldLegal name of the party
Beispiel: Muster GmbH
tradingNamestringoptionalTrading name (if different from legal name)
Beispiel: Muster Shop
streetstringoptionalStreet address
Beispiel: Hauptstraße 42
additionalStreetstringoptionalAdditional address line
Beispiel: 2. OG, Raum 5
citystringoptionalCity
Beispiel: Berlin
postalCodestringoptionalPostal code
Beispiel: 10115
countryCodestringPflichtfeldCountry code (ISO 3166-1 alpha-2)
Beispiel: DE
statestringoptionalState/region (ISO 3166-2)
Beispiel: BE
taxIdstringoptionalNational tax identification number
Beispiel: 27/123/45678
vatIdstringoptionalEU VAT identification number
Beispiel: DE136695976
emailstringoptionalEmail address
Beispiel: billing@muster.de
phonestringoptionalPhone number
Beispiel: +49 30 12345678
websitestringoptionalWebsite URL
Beispiel: https://muster.de
contactobjectoptionalStructured contact person (BG-6 for seller, BG-9 for buyer)
bankAccountobjectoptionalBank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.
Sobald paymentMethods eine Überweisung enthält, verlangt EN 16931 (BR-61) die Zahlungskonto-Kennung. Ohne seller.bankAccount.iban wird die Rechnung abgelehnt.

buyer.contact

Structured contact person (BG-6 for seller, BG-9 for buyer)

FeldTypPflichtBeschreibung
namestringoptionalContact person name
Beispiel: Max Mustermann
phonestringoptionalContact phone number
Beispiel: +49 30 12345678
emailstringoptionalContact email address
Beispiel: max@muster.de

buyer.bankAccount

Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.

FeldTypPflichtBeschreibung
ibanstringPflichtfeldIBAN (International Bank Account Number)
Beispiel: DE89370400440532013000
bicstringoptionalBIC/SWIFT code (8 or 11 characters)
Beispiel: COBADEFFXXX
bankNamestringoptionalName of the bank
Beispiel: Commerzbank
accountHolderstringoptionalAccount holder name (if different from party name)
Beispiel: TechCorp GmbH

items[]

FeldTypPflichtBeschreibung
positionintegeroptionalLine item position number (BT-126 — zero-indexed line IDs are valid)
Beispiel: 1
descriptionstringPflichtfeldItem description
Beispiel: Software Development Services — March 2026
articleNumberstringoptionalArticle/SKU number
Beispiel: SVC-DEV-001
quantitynumberPflichtfeldQuantity (negative values allowed for return/credit lines, EN 16931 BG-25)
Beispiel: 40
unitstringPflichtfeldUnit code (UN/ECE Rec 20)
Beispiel: HUR
Die Mengeneinheit ist ein Code nach UN/ECE Rec 20, kein Klartext: C62 (Stück), HUR (Stunde), KGM (Kilogramm), MTR (Meter), DAY (Tag). "Stk" oder "piece" fällt bei BR-CL-23 durch.
unitPricenumberPflichtfeldUnit price (net)
Beispiel: 120
discountobjectoptionalLine item discount (BT-136 to BT-138)
taxRatenumberPflichtfeldTax rate in percent
Beispiel: 19
taxCategoryCodestringoptionalTax category code (EN 16931: S, Z, E, AE, K, G, O, ...)
Beispiel: S
taxExemptionReasonstringoptionalTax exemption reason free text (BT-120)
Beispiel: Reverse charge — Steuerschuldnerschaft des Leistungsempfängers
taxExemptionReasonCodestringoptionalTax exemption reason code (BT-121, VATEX code)
Beispiel: VATEX-EU-AE
netAmountnumberPflichtfeldNet amount (quantity * unitPrice)
Beispiel: 4800
taxAmountnumberPflichtfeldTax amount
Beispiel: 912
grossAmountnumberoptionalGross amount (net + tax)
Beispiel: 5712
lineSubtypestringoptionalSub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.
Erlaubte Werte: DETAIL, INFORMATION, GROUP
parentLineIdstringoptionalParent line item position reference (BT-X-304, for hierarchical line items)
perPackageQuantitynumberoptionalQuantity per package unit (BT-X-561)
subItemsobject[]optionalNested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.

items[].discount

Line item discount (BT-136 to BT-138)

FeldTypPflichtBeschreibung
typestringoptionalDiscount type: percentage or absolute amount
Erlaubte Werte: percentage, absolute
valuenumberoptionalDiscount value
Beispiel: 50
reasonstringoptionalDiscount reason (BT-139)
Beispiel: Mengenrabatt

taxSummary[]

FeldTypPflichtBeschreibung
taxRatenumberPflichtfeldTax rate in percent
Beispiel: 19
taxCategoryCodestringoptionalTax category code
Beispiel: S
netAmountnumberPflichtfeldNet amount for this tax rate
Beispiel: 4800
taxAmountnumberPflichtfeldTax amount
Beispiel: 912
exemptionReasonstringoptionalTax exemption reason free text (BT-120)
Beispiel: Reverse charge
exemptionReasonCodestringoptionalTax exemption reason code (BT-121, VATEX code)
Beispiel: VATEX-EU-AE

paymentTerms

Payment terms

FeldTypPflichtBeschreibung
dueDaysnumberoptionalPayment due in days
Beispiel: 30
descriptionstringoptionalPayment terms description
Beispiel: Zahlbar innerhalb von 30 Tagen ohne Abzug
earlyPaymentDiscountobjectoptionalEarly payment discount (Skonto). E.g., 2% discount if paid within 10 days.

paymentTerms.earlyPaymentDiscount

Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.

FeldTypPflichtBeschreibung
daysnumberPflichtfeldDiscount valid within this many days
Beispiel: 10
discountPercentnumberPflichtfeldDiscount percentage (Skonto)
Beispiel: 2

paymentMethods[]

Payment method

FeldTypPflichtBeschreibung
typestringPflichtfeldPayment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.
Erlaubte Werte: bank_transfer, credit_transfer, direct_debit, credit_card, paypal, cash, danish_fik, giro, other
detailsstringoptionalAdditional details (e.g., "PayPal: invoice@example.com")
Beispiel: SEPA-Überweisung

allowancesCharges[]

Invoice-level allowance (discount) or charge (surcharge)

FeldTypPflichtBeschreibung
isChargebooleanPflichtfeldtrue = surcharge (BG-21), false = discount/allowance (BG-20)
Beispiel: false
amountnumberPflichtfeldAllowance/charge amount (BT-92 / BT-99)
Beispiel: 100
percentagenumberoptionalPercentage (BT-94 / BT-101) — alternative to fixed amount
Beispiel: 5
baseAmountnumberoptionalBase amount for percentage calculation (BT-93 / BT-100)
Beispiel: 2000
reasonstringoptionalReason text (BT-97 / BT-104)
Beispiel: Gesamtrabatt
reasonCodestringoptionalReason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)
Beispiel: 95
taxCategoryCodestringoptionalTax category code (BT-95 / BT-102)
Beispiel: S
taxRatenumberoptionalTax rate in percent (BT-96 / BT-103)
Beispiel: 19

delivery

Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).

FeldTypPflichtBeschreibung
datestringoptionalDelivery date (BT-72, ISO 8601)
Beispiel: 2026-03-20
namestringoptionalDeliver-to party name (BT-70)
Beispiel: Lager Nord
locationIdstringoptionalDelivery location identifier (BT-71)
addressobjectoptionalDelivery address (BG-15)

delivery.address

Delivery address (BG-15)

FeldTypPflichtBeschreibung
streetstringoptionalDelivery street (BT-75)
Beispiel: Lagerstraße 10
additionalStreetstringoptionalAdditional delivery address line (BT-76)
citystringoptionalDelivery city (BT-77)
Beispiel: Hamburg
postalCodestringoptionalDelivery postal code (BT-78)
Beispiel: 20457
statestringoptionalDelivery state/region (BT-79)
countryCodestringoptionalDelivery country code (BT-80)
Beispiel: DE

directDebitMandate

SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.

FeldTypPflichtBeschreibung
mandateIdstringPflichtfeldSEPA mandate reference (BT-89)
Beispiel: MANDATE-2026-001
creditorIdstringPflichtfeldSEPA creditor identifier (BT-90)
Beispiel: DE98ZZZ09999999999
debitAccountIdstringoptionalDebited account IBAN (BT-91)
Beispiel: DE89370400440532013000

deliveryNote

Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.

FeldTypPflichtBeschreibung
numberstringPflichtfeldDespatch advice / delivery note number (BT-16).
Beispiel: LS-2026-4711
datestringoptionalDespatch advice / delivery note date (BT-17, ISO 8601).
Beispiel: 2026-03-19

thirdPartyPayments[]

Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)

FeldTypPflichtBeschreibung
typestringPflichtfeldThird-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., "voucher", "loyalty", "partial").
Beispiel: voucher
paidAmountnumberPflichtfeldAmount already paid by the third party (BT-DEX-002).
Beispiel: 25
descriptionstringPflichtfeldHuman-readable description of the third-party payment (BT-DEX-003).
Beispiel: Geschenkgutschein eingelöst

attachments[]

Embedded attachment (BG-24 / BT-122..125)

FeldTypPflichtBeschreibung
filenamestringPflichtfeldAttachment filename (BT-125).
Beispiel: leistungsnachweis.pdf
mimeTypestringPflichtfeldIANA media type of the attachment (BT-125-1).
Beispiel: application/pdf
contentstringPflichtfeldBase64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).
Beispiel: JVBERi0xLjcKJeLjz9MK...
descriptionstringoptionalOptional human-readable description of the attachment (BT-123).
Beispiel: Stundennachweis März 2026

constructionTax

German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.

FeldTypPflichtBeschreibung
exemptionCertificateNumberstringoptionalFreistellungsbescheinigung number per §48b EStG. When set, the generator emits a "#FREISTELLUNG#" note documenting the construction-withholding exemption.
Beispiel: FB-2026-0042
withholdingPercentnumberoptionalConstruction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.
Beispiel: 15
recipientTaxOfficestringoptionalTax office responsible for the recipient of the construction service.
Beispiel: Finanzamt München

countrySpecific

Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.

FeldTypPflichtBeschreibung
countryCodestringPflichtfeldISO 3166-1 alpha-2 country code identifying this country-specific block.
Beispiel: DE
Wird countrySpecific gesetzt, ist countryCode darin Pflicht — auch wenn der Ländercode bereits im Pfad steht.

Die vollständige Spezifikation

Diese Seite zeigt das invoice-Objekt. Die vollständige OpenAPI-Spezifikation mit allen Endpunkten liegt als Datei bereit — für Code-Generatoren, Postman oder den eigenen Editor.

openapi-full.json öffnen