ZUGFeRD

Introduction

This documentation provides a complete overview of the xRechnung object used in the createPdf endpoint for generating ZUGFeRD-compliant invoices. The xRechnung object contains key information required to create a legally compliant electronic invoice, following the specifications of the XRechnung format.

Payload Structure

The xRechnung object is part of the main payload sent to the createPdf endpoint. Below is the structure and detailed explanation of all properties within the xRechnung object.

Main Payload Structure

{
  "report": "string",
  "reportName": "string",
  "configName": "string",
  "archive": true,
  "documentTypeId": 0,
  "culture": "string",
  "parameters": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "mainHostUrl": "string",
  "xRechnung": {
    "invoiceMain": { ... },
    "additionalReferencedDocuments": [ ... ],
    "despatchAdviceReferencedDocument": { ... },
    "profile": 1,
    "tradeLineItems": [ ... ],
    "taxes": [ ... ],
    "serviceCharges": [ ... ],
    "receivableSpecifiedTradeAccountingAccounts": [ ... ]
  }
}

xRechnung Object Details

1. invoiceMain

This object contains the main details of the invoice, including invoice number, dates, buyer, seller, and payment terms.

  • Type: object

  • Properties:

    • invoiceNo (string): The unique identifier of the invoice.

    • invoiceDate (DateTime): The date the invoice was issued.

    • paymentReference (string): Reference used for payments.

    • orderNo (string): The related order number.

    • orderDate (DateTime): The date of the related order.

    • currency (enum): The currency of the invoice. See currency enum.

    • buyer (object): Information about the buyer.

    • seller (object): Information about the seller.

    • notes (array): Notes related to the invoice.

    • paymentTerms (object): The terms of payment.

    • grandTotalAmount (decimal): The total amount of the invoice.

    • duePayableAmount (decimal): The amount due for payment.

    • Other related invoice properties.

2. additionalReferencedDocuments

This array contains documents that reference the invoice, such as orders or contracts.

  • Type: array

  • Properties:

    • id (string): Identifier of the referenced document.

    • issueDateTime (DateTime): Date and time the document was issued.

    • referenceTypeCode (enum): Reference type code. See referenceTypeCode enum.

    • attachmentBinaryObject (string): Base64 encoded binary object of the attachment.

    • filename (string): Filename of the attachment.

    • typeCode (enum): Type code for the document. See typeCode enum.

3. tradeLineItems

This array contains items or services billed in the invoice.

  • Type: array

  • Properties:

    • globalID (object): Global ID of the item or service.

    • sellerAssignedID (string): ID assigned by the seller.

    • name (string): Name of the item or service.

    • billedQuantity (decimal): Quantity billed.

    • lineTotalAmount (decimal): Total amount for the line item.

    • taxCategoryCode (enum): Tax category code. See taxCategoryCode enum.

    • netUnitPrice (decimal): Net unit price of the item.

    • unitCode (enum): Unit code for the item. See unitCode enum.

    • Other related line item properties.

4. taxes

This array contains detailed tax information applied to the invoice.

  • Type: array

  • Properties:

    • basisAmount (decimal): Amount on which the tax is calculated.

    • percent (decimal): Tax percentage.

    • typeCode (enum): Type of tax. See taxType enum.

    • categoryCode (enum): Tax category code. See taxCategoryCode enum.

    • exemptionReasonCode (enum): Reason for tax exemption. See exemptionReasonCode enum.

5. serviceCharges

This array contains additional charges applied to the invoice.

  • Type: array

  • Properties:

    • tax (object): Tax information related to the service charge (similar to taxes object).

    • amount (decimal): Amount of the service charge.

    • description (string): Description of the service charge.

6. receivableSpecifiedTradeAccountingAccounts

This array contains accounting accounts related to the trade, either receivable or payable.

  • Type: array

  • Properties:

    • tradeAccountID (string): ID of the trade account.

    • tradeAccountTypeCode (enum): Type of trade account. See tradeAccountTypeCode enum.

Enumerations

1. currency

Represents currency codes.

Value
Description

0

Euro (EUR)

1

US Dollar (USD)

2

British Pound (GBP)

3

Swiss Franc (CHF)

4

Japanese Yen (JPY)

2. schemeID

Identification schemes for IDs.

Value
Description

0

Unknown

1

GLN (Global Location Number)

2

DUNS (Data Universal Numbering System)

3

VAT ID

4

National Tax ID

5

Other

3. country

Country codes.

Value
Description

0

Germany (DE)

1

Austria (AT)

2

Switzerland (CH)

3

United States (US)

4

United Kingdom (GB)

4. subjectCode

Subject codes for notes.

Value
Description

0

General Information

1

Legal Information

2

Payment Information

5. contentCode

Content codes for notes.

Value
Description

0

Free Text

1

Legal Notice

2

Payment Instruction

3

Delivery Information

6. profile

Invoice profiles.

Value
Description

1

Basic Profile

2

Comfort Profile

3

Extended Profile

4

EN 16931 Profile (XRechnung)

7. type

Invoice types.

Value
Description

0

Invoice

1

Credit Note

2

Debit Note

3

Correction Invoice

8. referenceTypeCode

Reference type codes for documents.

Value
Description

0

Order Reference

1

Despatch Advice Reference

2

Delivery Note Reference

3

Contract Reference

9. taxCategoryCode

Tax category codes.

Value
Description

0

Standard Rate

1

Reduced Rate

2

Zero Rate

3

Exempt

4

Reverse Charge

10. taxType

Tax types.

Value
Description

0

Value-Added Tax

1

Sales Tax

2

Service Tax

11. electronicAddressSchemeID

Electronic address schemes.

Value
Description

88

Email

89

EDI (Electronic Data Interchange)

90

Web Address

12. typeCode

Document type codes.

Value
Description

50

Attachment

51

Image

52

PDF Document

13. unitCode

Unit codes for line items.

Value
Description

0

Piece (PCE)

1

Kilogram (KGM)

2

Liter (LTR)

3

Hour (HUR)

4

Day (DAY)

14. paymentMeansTypeCode

Payment means type codes.

Value
Description

0

Bank Transfer

1

Direct Debit

2

Credit Card

3

Cash

15. tradeAccountTypeCode

Trade account type codes.

Value
Description

0

Debtor Account

1

Creditor Account

2

General Ledger Account

3

Cash Account


This documentation provides a complete and structured overview of the xRechnung object, including all properties and enumerations used in the payload.

Last updated