# 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

```json
{
  "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.