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.
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.
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": 178541 }42 ],43 "taxSummary": [44 {45 "taxRate": 19,46 "netAmount": 1500,47 "taxAmount": 28548 }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
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
invoiceNumber | string | Pflichtfeld | Unique invoice number Beispiel: INV-2026-0042 |
type | string | Pflichtfeld | Invoice type Erlaubte Werte: invoice, credit_note, proforma, correction |
issueDate | string | Pflichtfeld | Issue date (ISO 8601: YYYY-MM-DD) Beispiel: 2026-03-20 |
dueDate | string | Pflichtfeld | Due date (ISO 8601: YYYY-MM-DD) Beispiel: 2026-04-19 |
deliveryDate | string | optional | Delivery/service date (ISO 8601) Beispiel: 2026-03-20 |
servicePeriod | object | optional | Service period (Leistungszeitraum). Required in DE if different from issueDate. |
seller | object | Pflichtfeld | Seller party information |
buyer | object | Pflichtfeld | Buyer party information |
items | object[] | Pflichtfeld | Invoice line items |
currency | string | Pflichtfeld | Currency code (ISO 4217) Beispiel: EUR |
subtotal | number | Pflichtfeld | Total net amount Beispiel: 4800 |
total | number | Pflichtfeld | Total gross amount Beispiel: 5712 |
taxSummary | object[] | Pflichtfeld | Tax summary per tax rate |
paymentTerms | object | optional | Payment terms |
paymentMethods | object[] | optional | Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set. |
orderNumber | string | optional | Purchase order number (Bestellnummer) Beispiel: PO-2026-0815 |
customerNumber | string | optional | Customer number at the seller Beispiel: KD-42 |
contractNumber | string | optional | Contract number (BT-12) Beispiel: V-2025-1234 |
projectNumber | string | optional | Project reference (BT-11) Beispiel: PROJ-2026-42 |
roundingAmount | number | optional | Rounding amount (BT-114) Beispiel: 0.01 |
allowancesCharges | object[] | optional | Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead. |
delivery | object | optional | Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15). |
directDebitMandate | object | optional | SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit. |
notes | string | optional | Additional notes displayed on the invoice Beispiel: Vielen Dank für Ihren Auftrag! |
profile | string | optional | XRechnung 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 |
referencedInvoiceNumber | string | optional | Number 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 |
referencedInvoiceDate | string | optional | Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`. Beispiel: 2026-03-15 |
deliveryNote | object | optional | Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL. |
thirdPartyPayments | object[] | optional | Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL. |
attachments | object[] | optional | Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL. |
serviceCategory | string | optional | Service 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 |
constructionTax | object | optional | German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate. |
countrySpecific | object | optional | 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. |
servicePeriod
Service period (Leistungszeitraum). Required in DE if different from issueDate.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
start | string | Pflichtfeld | Period start (ISO 8601: YYYY-MM-DD) Beispiel: 2026-03-01 |
end | string | Pflichtfeld | Period end (ISO 8601: YYYY-MM-DD) Beispiel: 2026-03-31 |
seller
Seller party information
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
name | string | Pflichtfeld | Legal name of the party Beispiel: Muster GmbH |
tradingName | string | optional | Trading name (if different from legal name) Beispiel: Muster Shop |
street | string | optional | Street address Beispiel: Hauptstraße 42 |
additionalStreet | string | optional | Additional address line Beispiel: 2. OG, Raum 5 |
city | string | optional | City Beispiel: Berlin |
postalCode | string | optional | Postal code Beispiel: 10115 |
countryCode | string | Pflichtfeld | Country code (ISO 3166-1 alpha-2) Beispiel: DE |
state | string | optional | State/region (ISO 3166-2) Beispiel: BE |
taxId | string | optional | National tax identification number Beispiel: 27/123/45678 |
vatId | string | optional | EU VAT identification number Beispiel: DE136695976 |
email | string | optional | Email address Beispiel: billing@muster.de |
phone | string | optional | Phone number Beispiel: +49 30 12345678 |
website | string | optional | Website URL Beispiel: https://muster.de |
contact | object | optional | Structured contact person (BG-6 for seller, BG-9 for buyer) |
bankAccount | object | optional | Bank 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)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
name | string | optional | Contact person name Beispiel: Max Mustermann |
phone | string | optional | Contact phone number Beispiel: +49 30 12345678 |
email | string | optional | Contact 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.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
iban | string | Pflichtfeld | IBAN (International Bank Account Number) Beispiel: DE89370400440532013000 |
bic | string | optional | BIC/SWIFT code (8 or 11 characters) Beispiel: COBADEFFXXX |
bankName | string | optional | Name of the bank Beispiel: Commerzbank |
accountHolder | string | optional | Account holder name (if different from party name) Beispiel: TechCorp GmbH |
buyer
Buyer party information
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
name | string | Pflichtfeld | Legal name of the party Beispiel: Muster GmbH |
tradingName | string | optional | Trading name (if different from legal name) Beispiel: Muster Shop |
street | string | optional | Street address Beispiel: Hauptstraße 42 |
additionalStreet | string | optional | Additional address line Beispiel: 2. OG, Raum 5 |
city | string | optional | City Beispiel: Berlin |
postalCode | string | optional | Postal code Beispiel: 10115 |
countryCode | string | Pflichtfeld | Country code (ISO 3166-1 alpha-2) Beispiel: DE |
state | string | optional | State/region (ISO 3166-2) Beispiel: BE |
taxId | string | optional | National tax identification number Beispiel: 27/123/45678 |
vatId | string | optional | EU VAT identification number Beispiel: DE136695976 |
email | string | optional | Email address Beispiel: billing@muster.de |
phone | string | optional | Phone number Beispiel: +49 30 12345678 |
website | string | optional | Website URL Beispiel: https://muster.de |
contact | object | optional | Structured contact person (BG-6 for seller, BG-9 for buyer) |
bankAccount | object | optional | Bank 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)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
name | string | optional | Contact person name Beispiel: Max Mustermann |
phone | string | optional | Contact phone number Beispiel: +49 30 12345678 |
email | string | optional | Contact 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.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
iban | string | Pflichtfeld | IBAN (International Bank Account Number) Beispiel: DE89370400440532013000 |
bic | string | optional | BIC/SWIFT code (8 or 11 characters) Beispiel: COBADEFFXXX |
bankName | string | optional | Name of the bank Beispiel: Commerzbank |
accountHolder | string | optional | Account holder name (if different from party name) Beispiel: TechCorp GmbH |
items[]
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
position | integer | optional | Line item position number (BT-126 — zero-indexed line IDs are valid) Beispiel: 1 |
description | string | Pflichtfeld | Item description Beispiel: Software Development Services — March 2026 |
articleNumber | string | optional | Article/SKU number Beispiel: SVC-DEV-001 |
quantity | number | Pflichtfeld | Quantity (negative values allowed for return/credit lines, EN 16931 BG-25) Beispiel: 40 |
unit | string | Pflichtfeld | Unit code (UN/ECE Rec 20) Beispiel: HURDie 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. |
unitPrice | number | Pflichtfeld | Unit price (net) Beispiel: 120 |
discount | object | optional | Line item discount (BT-136 to BT-138) |
taxRate | number | Pflichtfeld | Tax rate in percent Beispiel: 19 |
taxCategoryCode | string | optional | Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...) Beispiel: S |
taxExemptionReason | string | optional | Tax exemption reason free text (BT-120) Beispiel: Reverse charge — Steuerschuldnerschaft des Leistungsempfängers |
taxExemptionReasonCode | string | optional | Tax exemption reason code (BT-121, VATEX code) Beispiel: VATEX-EU-AE |
netAmount | number | Pflichtfeld | Net amount (quantity * unitPrice) Beispiel: 4800 |
taxAmount | number | Pflichtfeld | Tax amount Beispiel: 912 |
grossAmount | number | optional | Gross amount (net + tax) Beispiel: 5712 |
lineSubtype | string | optional | Sub-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 |
parentLineId | string | optional | Parent line item position reference (BT-X-304, for hierarchical line items) |
perPackageQuantity | number | optional | Quantity per package unit (BT-X-561) |
subItems | object[] | optional | Nested 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)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
type | string | optional | Discount type: percentage or absolute amount Erlaubte Werte: percentage, absolute |
value | number | optional | Discount value Beispiel: 50 |
reason | string | optional | Discount reason (BT-139) Beispiel: Mengenrabatt |
taxSummary[]
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
taxRate | number | Pflichtfeld | Tax rate in percent Beispiel: 19 |
taxCategoryCode | string | optional | Tax category code Beispiel: S |
netAmount | number | Pflichtfeld | Net amount for this tax rate Beispiel: 4800 |
taxAmount | number | Pflichtfeld | Tax amount Beispiel: 912 |
exemptionReason | string | optional | Tax exemption reason free text (BT-120) Beispiel: Reverse charge |
exemptionReasonCode | string | optional | Tax exemption reason code (BT-121, VATEX code) Beispiel: VATEX-EU-AE |
paymentTerms
Payment terms
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
dueDays | number | optional | Payment due in days Beispiel: 30 |
description | string | optional | Payment terms description Beispiel: Zahlbar innerhalb von 30 Tagen ohne Abzug |
earlyPaymentDiscount | object | optional | Early 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.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
days | number | Pflichtfeld | Discount valid within this many days Beispiel: 10 |
discountPercent | number | Pflichtfeld | Discount percentage (Skonto) Beispiel: 2 |
paymentMethods[]
Payment method
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
type | string | Pflichtfeld | Payment 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 |
details | string | optional | Additional details (e.g., "PayPal: invoice@example.com") Beispiel: SEPA-Überweisung |
allowancesCharges[]
Invoice-level allowance (discount) or charge (surcharge)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
isCharge | boolean | Pflichtfeld | true = surcharge (BG-21), false = discount/allowance (BG-20) Beispiel: false |
amount | number | Pflichtfeld | Allowance/charge amount (BT-92 / BT-99) Beispiel: 100 |
percentage | number | optional | Percentage (BT-94 / BT-101) — alternative to fixed amount Beispiel: 5 |
baseAmount | number | optional | Base amount for percentage calculation (BT-93 / BT-100) Beispiel: 2000 |
reason | string | optional | Reason text (BT-97 / BT-104) Beispiel: Gesamtrabatt |
reasonCode | string | optional | Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105) Beispiel: 95 |
taxCategoryCode | string | optional | Tax category code (BT-95 / BT-102) Beispiel: S |
taxRate | number | optional | Tax 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).
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
date | string | optional | Delivery date (BT-72, ISO 8601) Beispiel: 2026-03-20 |
name | string | optional | Deliver-to party name (BT-70) Beispiel: Lager Nord |
locationId | string | optional | Delivery location identifier (BT-71) |
address | object | optional | Delivery address (BG-15) |
delivery.address
Delivery address (BG-15)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
street | string | optional | Delivery street (BT-75) Beispiel: Lagerstraße 10 |
additionalStreet | string | optional | Additional delivery address line (BT-76) |
city | string | optional | Delivery city (BT-77) Beispiel: Hamburg |
postalCode | string | optional | Delivery postal code (BT-78) Beispiel: 20457 |
state | string | optional | Delivery state/region (BT-79) |
countryCode | string | optional | Delivery country code (BT-80) Beispiel: DE |
directDebitMandate
SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
mandateId | string | Pflichtfeld | SEPA mandate reference (BT-89) Beispiel: MANDATE-2026-001 |
creditorId | string | Pflichtfeld | SEPA creditor identifier (BT-90) Beispiel: DE98ZZZ09999999999 |
debitAccountId | string | optional | Debited account IBAN (BT-91) Beispiel: DE89370400440532013000 |
deliveryNote
Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
number | string | Pflichtfeld | Despatch advice / delivery note number (BT-16). Beispiel: LS-2026-4711 |
date | string | optional | Despatch 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)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
type | string | Pflichtfeld | Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., "voucher", "loyalty", "partial"). Beispiel: voucher |
paidAmount | number | Pflichtfeld | Amount already paid by the third party (BT-DEX-002). Beispiel: 25 |
description | string | Pflichtfeld | Human-readable description of the third-party payment (BT-DEX-003). Beispiel: Geschenkgutschein eingelöst |
attachments[]
Embedded attachment (BG-24 / BT-122..125)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
filename | string | Pflichtfeld | Attachment filename (BT-125). Beispiel: leistungsnachweis.pdf |
mimeType | string | Pflichtfeld | IANA media type of the attachment (BT-125-1). Beispiel: application/pdf |
content | string | Pflichtfeld | Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment). Beispiel: JVBERi0xLjcKJeLjz9MK... |
description | string | optional | Optional 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.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
exemptionCertificateNumber | string | optional | Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a "#FREISTELLUNG#" note documenting the construction-withholding exemption. Beispiel: FB-2026-0042 |
withholdingPercent | number | optional | Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented. Beispiel: 15 |
recipientTaxOffice | string | optional | Tax 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.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
countryCode | string | Pflichtfeld | ISO 3166-1 alpha-2 country code identifying this country-specific block. Beispiel: DEWird 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