# ZUGFeRD XML Field Mapping

This document describes the complete mapping between ZUGFeRD XML nodes and c-entron database fields/entities.

## Overview

The ZUGFeRD XML generation is implemented in `InvoiceZugferdBL.cs` and supports multiple ZUGFeRD versions:
- ZUGFeRD 1.0 (legacy)
- ZUGFeRD 2.0 / XRechnung 1.2
- ZUGFeRD 2.1 / XRechnung 2.0, 2.2, 2.3.1
- ZUGFeRD 2.1 / XRechnung 3.0.1 (current)

The main data flow is:
1. Load receipt data from `BookKeepingExportBL.LoadReceipt()` → returns `IBookKeepingReceipt`
2. Convert to `ZugferdExportItem` in `GetZugferdExportItem()`
3. Generate XML document with `DoGenerateZugferdXRechnungXmlDocument()`

---

## Document Context & Header

### ExchangedDocumentContext
XML structure related to document context and format identification.

| XML Node | c-entron Source | Description |
|----------|----------------|-------------|
| `rsm:GuidelineSpecifiedDocumentContextParameter/ram:ID` | Derived from `ZugferdKind` enum | Format identifier (e.g., "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0") |
| `ram:BusinessProcessSpecifiedDocumentContextParameter/ram:ID` | Static value | For v3.0.1: "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0" |

### ExchangedDocument
Basic invoice/credit voucher information.

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:ID` | `Number` | `IBookKeepingReceipt` | Invoice/receipt number |
| `ram:TypeCode` | Derived from `Type` | `IBookKeepingReceipt` | "380" = Invoice, "381" = Credit voucher |
| `ram:IssueDateTime/udt:DateTimeString` | `Date` | `IBookKeepingReceipt` | Receipt date (format: yyyyMMdd) |
| `ram:IncludedNote` | `PaymentConditionsText` | `IBookKeepingReceipt` | Payment text/notes |
| `ram:IncludedNote[@SubjectCode="REG"]` | Composed string | Multiple sources | Seller information text (Name, address, CEO, HRB) |
| `ram:IncludedNote[@SubjectCode="ABT"]` | `PayeeAssignmentNotice` | Bank info via settings | Assignment notice for bank transfer |

---

## Seller Trade Party (Own Company)

The seller represents the own company (Mandator) or branch.

| XML Node | c-entron Field | Table/Entity | Path in Code |
|----------|----------------|--------------|--------------|
| `ram:SellerTradeParty/ram:ID` | `OwnSupplierNumber` | `IBookKeepingReceipt` | Customer's supplier number for own company |
| `ram:SellerTradeParty/ram:Name` | `Name` or `Name` | `Branch` or `Mandator` | Branch name (or Mandator if setting/no branch) |
| `ram:SellerTradeParty/ram:SpecifiedLegalOrganization/ram:ID` | `HRB` | `Mandator` | Commercial register number |
| `ram:SellerTradeParty/ram:DefinedTradeContact/ram:PersonName` | `CEO` | `Mandator` | Managing director name |
| `ram:SellerTradeParty/ram:DefinedTradeContact/ram:DepartmentName` | `Department.Department` | `ContactPerson` via `Branch` or `Mandator` | Department name |
| `ram:SellerTradeParty/ram:DefinedTradeContact/ram:TelephoneUniversalCommunication/ram:CompleteNumber` | `PhoneNumber` or `Phone` | `Branch` or `Mandator` | Phone number |
| `ram:SellerTradeParty/ram:DefinedTradeContact/ram:EmailURIUniversalCommunication/ram:URIID` | `EMail` | `Branch` or `Mandator` | Email address |
| `ram:SellerTradeParty/ram:PostalTradeAddress/ram:PostcodeCode` | `ZipCode` or `PostCode` | `Branch` or `Mandator` | ZIP code |
| `ram:SellerTradeParty/ram:PostalTradeAddress/ram:LineOne` | `Street` | `Branch` or `Mandator` | Street address |
| `ram:SellerTradeParty/ram:PostalTradeAddress/ram:CityName` | `City` | `Branch` or `Mandator` | City |
| `ram:SellerTradeParty/ram:PostalTradeAddress/ram:CountryID` | `CountryCode` | `Country` | Country code (ISO 2-letter) |
| `ram:SellerTradeParty/ram:URIUniversalCommunication/ram:URIID[@schemeID="EM"]` | `EMail` | `Branch` or `Mandator` | Email (duplicate for compatibility) |
| `ram:SellerTradeParty/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="VA"]` | `TaxIDNumber` | `Mandator` | Tax identification number |

**Internal Fields (not exported to XML):**
- `OwnCountryCode`: Country code of seller (used for trade type determination: inland/EU/export)

**Data Sources:**
- If `BranchI3D` is set: Load from `Branch` table
- Otherwise: Load from `Mandator` table (default mandator)
- Country: From `Branch.CountryI3D` or `Mandator.Country` or default country (default: "DE")

---

## Buyer Trade Party (Customer)

The buyer represents the customer/recipient.

| XML Node | c-entron Field | Table/Entity | Path in Code |
|----------|----------------|--------------|--------------|
| `ram:BuyerTradeParty/ram:ID` | `AddressNumber` | `IBookKeepingReceipt` | Customer number |
| `ram:BuyerTradeParty/ram:Name` | `CompanyName` or fallback to `AddressName` | `ReceiptReceiver` or `IBookKeepingReceipt` | Recipient name |
| `ram:BuyerTradeParty/ram:DefinedTradeContact/ram:PersonName` | `ContactName` | `ReceiptReceiver` | Contact person name |
| `ram:BuyerTradeParty/ram:DefinedTradeContact/ram:DepartmentName` | `ContactDepartment` | `ReceiptReceiver` | Contact department |
| `ram:BuyerTradeParty/ram:DefinedTradeContact/ram:TelephoneUniversalCommunication/ram:CompleteNumber` | `ContactPhone` | `IBookKeepingReceipt` | Phone number |
| `ram:BuyerTradeParty/ram:DefinedTradeContact/ram:EmailURIUniversalCommunication/ram:URIID` | `ContactEMail` | `IBookKeepingReceipt` | Email address |
| `ram:BuyerTradeParty/ram:PostalTradeAddress/ram:PostcodeCode` | `Zip` | `ReceiptReceiver` | ZIP code |
| `ram:BuyerTradeParty/ram:PostalTradeAddress/ram:LineOne` | Structured from `ReceiptReceiver` | `ReceiptReceiver` | First address line (see below) |
| `ram:BuyerTradeParty/ram:PostalTradeAddress/ram:LineTwo` | Structured from `ReceiptReceiver` | `ReceiptReceiver` | Second address line (see below) |
| `ram:BuyerTradeParty/ram:PostalTradeAddress/ram:LineThree` | Structured from `ReceiptReceiver` | `ReceiptReceiver` | Third address line (see below) |
| `ram:BuyerTradeParty/ram:PostalTradeAddress/ram:CityName` | `City` | `ReceiptReceiver` | City |
| `ram:BuyerTradeParty/ram:PostalTradeAddress/ram:CountryID` | `CountryCode` | `Country` via `ReceiptReceiver.CountryI3D` | Country code (ISO 2-letter) |
| `ram:BuyerTradeParty/ram:URIUniversalCommunication/ram:URIID[@schemeID="EM"]` | `ContactEMail` | `IBookKeepingReceipt` | Email (duplicate for compatibility) |
| `ram:BuyerTradeParty/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="VA"]` | `SalesTaxIdentificationNumber` | `IBookKeepingReceipt` | VAT identification number |

**Internal Fields (not exported to XML):**
- `OwnCountryCode`: Country code of buyer (used for trade type determination: inland/EU/export)
- `IsEUTrade`: Flag indicating if buyer country is EU member

**Structured Address Line Building:**
The system intelligently builds address lines from `ReceiptReceiver` with a maximum of 3 lines:

1. **CompanyName** - Company name (first priority if available)
2. **AdditionalAddressSupplement** - Additional address supplement
3. **Department/ContactDepartment** - Department information (order configurable via `ReceiverContactDepartmentFirst` setting)
4. **ContactName** - Contact person name
5. **Street/HouseNumber or PostOfficeBox** - Either street address or P.O. Box (formatted as shown in PostOfficeBox)

The first item becomes the `Name`, subsequent items fill `AddressLine1`, `AddressLine2`, and `AddressLine3` (maximum 3 lines).

**Special Handling:**
- Post office box: If `HasPostOfficeBox` is true, uses `PostOfficeBox` instead of street address
- Street formatting: Combines `Street` and `HouseNumber` with proper trimming
- Department order: Configurable via `ReceiverContactDepartmentFirst` setting (ApplicationSettingID 10370)
- Invoice address: If alternative invoice address is used (`UsedAlternativeInvoiceAddress`), name is loaded from `Kunden` table
- Fallback: If `ReceiptReceiver` is null, falls back to legacy `IBookKeepingReceipt` fields

---

## Header Trade Agreement

Purchase order and party references.

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:ApplicableHeaderTradeAgreement/ram:BuyerReference` | `ExternalPurchaseOrderNumber` or `leitwegID` parameter | `IBookKeepingReceipt` | Leitweg-ID for XRechnung, otherwise purchase order number |
| `ram:ApplicableHeaderTradeAgreement/ram:BuyerOrderReferencedDocument/ram:IssuerAssignedID` | `ExternalPurchaseOrderNumber` | `IBookKeepingReceipt` | Purchase order number (only if not XInvoice) |

---

## Header Trade Delivery

Delivery information.

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:ApplicableHeaderTradeDelivery/ram:ActualDeliverySupplyChainEvent/ram:OccurrenceDateTime/udt:DateTimeString` | `DeliveryDate` or `Date` | `IBookKeepingReceipt` | Delivery date (fallback to receipt date if not set) |

---

## Header Trade Settlement

Payment, banking, and monetary information.

### Banking & SEPA

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:ApplicableHeaderTradeSettlement/ram:CreditorReferenceID` | `SepaIdentificationNumber` | `Mandator` | SEPA creditor reference ID (only for direct debit) |
| `ram:ApplicableHeaderTradeSettlement/ram:InvoiceCurrencyCode` | `CurrencyISOCode` | `IBookKeepingReceipt` | Currency code (e.g., "EUR") |
| `ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode` | `Untdid4461` or "ZZZ" | `IBookKeepingReceipt` | Payment means type code (UN/EDIFACT 4461) |
| `ram:SpecifiedTradeSettlementPaymentMeans/ram:Information` | `PaymentConditionsText` | `IBookKeepingReceipt` | Payment information text |
| `ram:SpecifiedTradeSettlementPaymentMeans/ram:PayerPartyDebtorFinancialAccount/ram:IBANID` | `Iban` | `BankAccount` via `BankAccountI3D` | Debtor IBAN (for direct debit) |
| `ram:SpecifiedTradeSettlementPaymentMeans/ram:PayeePartyCreditorFinancialAccount/ram:IBANID` | Selected bank IBAN | `Mandator` bank info (Bank1-4) | Creditor IBAN (for bank transfer) |
| `ram:SpecifiedTradeSettlementPaymentMeans/ram:PayeePartyCreditorFinancialAccount/ram:AccountName` | Selected bank holder or `Name` | `Mandator` bank info or `Mandator` | Account holder name |
| `ram:SpecifiedTradeSettlementPaymentMeans/ram:PayeeSpecifiedCreditorFinancialInstitution/ram:BICID` | Selected bank BIC | `Mandator` bank info (Bank1-4) | Bank BIC code |

**Bank Selection Logic:**
1. Check `ReceiptInvoiceSettings.UseMandatorBankForInvoice` (1-4)
2. For customer receipts, check `AccountCustomer.MandatorBank` override
3. Load bank details from `Mandator` (Bank1Iban/Bic, Bank2Iban/Bic, Bank3Iban/Bic, Bank4Iban/Bic)

### Tax Information

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:ApplicableTradeTax/ram:CalculatedAmount` | Calculated from positions | `BookKeepingReceiptItem` | Tax amount per tax rate |
| `ram:ApplicableTradeTax/ram:TypeCode` | Static "VAT" | - | Tax type |
| `ram:ApplicableTradeTax/ram:ExemptionReason` | Derived from tax scenario | Logic | Tax exemption reason text |
| `ram:ApplicableTradeTax/ram:BasisAmount` | Calculated from positions | `BookKeepingReceiptItem` | Net basis amount for tax |
| `ram:ApplicableTradeTax/ram:CategoryCode` | Derived from tax scenario | Logic | Tax category (S, E, K, G, AE) |
| `ram:ApplicableTradeTax/ram:RateApplicablePercent` | Grouped tax rates | `BookKeepingReceiptItem.TaxRate` | VAT percentage |

**Tax Category Codes:**
- `S` (Standard): Normal VAT rate
- `E` (Exempt): 0% VAT for domestic tax-free transactions
- `K` (Intra-community): 0% VAT for EU intra-community supply
- `G` (Export): 0% VAT for export outside EU
- `AE` (Reverse charge): Reverse charge scenario (`IsReverseCharge = true`)

**Tax Exemption Reasons:**
- Reverse charge: "Steuerschuldnerschaft des Leistungsempfängers gem. §13B Abs 2 Nr. 10 UStG."
- Tax-free domestic: "Steuerfrei"
- Intra-community: "Kein Ausweis der Umsatzsteuer bei innergemeinschaftlichen Lieferungen"
- Export: "Steuer nicht erhoben aufgrund von Export außerhalb der EU"

### Billing Period

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:BillingSpecifiedPeriod/ram:StartDateTime/udt:DateTimeString` | Min of position billing periods | `ContractBillingInfo` | Earliest billing start date |
| `ram:BillingSpecifiedPeriod/ram:EndDateTime/udt:DateTimeString` | Max of position billing periods | `ContractBillingInfo` | Latest billing end date |

### Payment Terms

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:SpecifiedTradePaymentTerms/ram:Description` | `PaymentConditionFull` + Skonto info | `IBookKeepingReceipt` + derived | Full payment condition text with line breaks |
| `ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString` | `DueDate` or `Date` | `IBookKeepingReceipt` | Payment due date |
| `ram:SpecifiedTradePaymentTerms/ram:DirectDebitMandateID` | `AuthorizationNumber` | `BankAccount` via `BankAccountI3D` | SEPA mandate ID (only for direct debit) |

**Skonto Information (BR-DE-18):**
- Generated via `AssetConditionBL.GetPaymentConditionSkontoInBR_DE_18Format()`
- Appended to description with proper XML line breaks (`
`)

### Monetary Summation

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:LineTotalAmount` | `NetPriceFCComplete` | `IBookKeepingReceipt` | Total net amount |
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:ChargeTotalAmount` | Static 0 | - | Total charges |
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:AllowanceTotalAmount` | Static 0 | - | Total allowances |
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:TaxBasisTotalAmount` | `NetPriceFCComplete` | `IBookKeepingReceipt` | Tax basis total |
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:TaxTotalAmount[@currencyID]` | `TaxPriceFCComplete` | `IBookKeepingReceipt` | Total tax amount |
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:GrandTotalAmount` | Net + Tax | Calculated | Gross total |
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:TotalPrepaidAmount` | Static 0 | - | Prepaid amount |
| `ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:DuePayableAmount` | Net + Tax | Calculated | Due payable amount |

**Validation:**
- System validates that sum of position net prices equals header net price (tolerance: ±3.00)
- System validates that sum of position gross prices equals header gross price (tolerance: ±3.00)
- Warnings are logged if differences are within tolerance, errors if exceeding

### Invoice Referenced Document (Credit Vouchers Only)

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:InvoiceReferencedDocument/ram:IssuerAssignedID` | `Number` | `ReceiptInvoice` (origin) | Original invoice number |
| `ram:InvoiceReferencedDocument/ram:FormattedIssueDateTime/qdt:DateTimeString` | `Date` | `ReceiptInvoice` (origin) | Original invoice date |

**Logic:**
- Only for credit vouchers (`Type = CreditVoucher`)
- Only if exactly one origin invoice exists
- Loaded via `ReceiptItem.OriginReceiptI3D` where `OriginKind = Invoice`

---

## Line Items (Positions)

Each invoice/credit voucher position.

### Line Item Document

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:AssociatedDocumentLineDocument/ram:LineID` | Sequential counter | Generated | Position number (1, 2, 3, ...) |

### Trade Product

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:SpecifiedTradeProduct/ram:GlobalID[@schemeID="0160"]` | `EANCode` | `BookKeepingReceiptItem` | EAN/GTIN barcode (if not disabled in settings) |
| `ram:SpecifiedTradeProduct/ram:SellerAssignedID` | `Articlecode` | `BookKeepingReceiptItem` | Article code (if not disabled in settings) |
| `ram:SpecifiedTradeProduct/ram:Name` | `Text` | `BookKeepingReceiptItem` (via compact entity) | Position text/description |
| `ram:SpecifiedTradeProduct/ram:ApplicableProductCharacteristic/ram:Description` | Static "Seriennummer {index}" | Generated | Serial number label (1, 2, 3, ...) |
| `ram:SpecifiedTradeProduct/ram:ApplicableProductCharacteristic/ram:Value` | `Barcodes[i]` | `IReceiptItemWithBarcodes` | Barcode value (serial number) |

**Barcode Handling:**
- Barcodes are loaded from receipt items that implement `IReceiptItemWithBarcodes`
- Multiple barcodes per position are supported (indexed sequentially)
- For title positions, barcodes from child items are aggregated into the parent position
- Each barcode is exported as a separate `ApplicableProductCharacteristic` node
- Code reference: `InvoiceZugferdBL.cs:625-626` (loading), `InvoiceZugferdBL.cs:648-651` (title aggregation), `InvoiceZugferdBL.cs:881-898` (XML export)

**Settings Flags:**
- `ReceiptInvoiceSettings.ZugferdExportDontExportEanCode`: Suppresses EAN export
- `ReceiptInvoiceSettings.ZugferdExportDontExportArticleCode`: Suppresses article code export

### Line Trade Agreement

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:NetPriceProductTradePrice/ram:ChargeAmount` | `NetPrice` | `InvoiceItemCompact` or `CreditVoucherItemCompact` | Unit net price (always positive) |

**Note:** If `NetPrice` is negative, the price is made positive and quantity is negated.

### Line Trade Delivery

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:BilledQuantity[@unitCode]` | `QuantityComplete` | `InvoiceItemCompact` or `CreditVoucherItemCompact` | Quantity (negated if price was negative) |
| `@unitCode` | `UNECECode` | `Article.ArticleUnit` | UN/ECE unit code (default: "C62" = piece) |

**UN/ECE Code Logic:**
- Only for article items (`Kind = Article` and `ArticleI3D` is set)
- Loaded from `Article.ArticleUnit.UNECECode`
- Fallback: "C62" (one/piece)

### Line Trade Settlement

| XML Node | c-entron Field | Table/Entity | Description |
|----------|----------------|--------------|-------------|
| `ram:ApplicableTradeTax/ram:TypeCode` | Static "VAT" | - | Tax type |
| `ram:ApplicableTradeTax/ram:CategoryCode` | Derived from tax scenario | Logic | Tax category code (see header tax) |
| `ram:ApplicableTradeTax/ram:RateApplicablePercent` | `TaxRate` or 0 | `InvoiceItemCompact`/`CreditVoucherItemCompact` | VAT percentage (0 if `ExclusiveOfVAT`) |
| `ram:SpecifiedTradeSettlementLineMonetarySummation/ram:LineTotalAmount` | `NetPriceTotalFCComplete` | `BookKeepingReceiptItem` | Line net total amount |

**Title Position Handling:**
- Title positions (`Kind = TitlePosition`, `Expanded = false`) are exported as collapsed items
- Child items (`Visible != Visible` or `Indent > 0`) are aggregated into parent title position
- Title position quantity is always 1
- Title position net price equals net total
- Mixed tax rates in title positions cause error

**Item Filtering:**
- Only exports: `Article`, `CustomerDiscount`, or collapsed `TitlePosition` items
- Must be `Visible = Visible` or `Indent = 0`
- Ordered by `InternalPosition`

---

## Data Sources Summary

### Primary Tables

| Table/Entity | Purpose | Key Fields |
|--------------|---------|------------|
| `IBookKeepingReceipt` | Receipt header | Number, Date, AddressNumber, DueDate, CurrencyISOCode, NetPriceFCComplete, TaxPriceFCComplete |
| `ReceiptReceiver` | Structured receiver address | CompanyName, AdditionalAddressSupplement, Department, ContactDepartment, ContactName, Street, HouseNumber, PostOfficeBox, Zip, City, CountryI3D |
| `BookKeepingReceiptItem` | Receipt line items | Position, Text, Articlecode, EANCode, NetPrice, QuantityComplete, TaxRate |
| `InvoiceItemCompact` | Invoice item details | NetPrice, NetPriceTotalFCComplete, TaxPriceTotalFCComplete, VATRate, QuantityComplete |
| `CreditVoucherItemCompact` | Credit voucher item details | NetPrice, NetPriceTotalFC, TaxPriceTotalFC, VATRate, QuantityComplete |
| `Mandator` | Own company | Name, CEO, TaxIDNumber, HRB, Street, City, PostCode, Phone, EMail, SepaIdentificationNumber |
| `Branch` | Own branch | Name, Street, City, ZipCode, PhoneNumber, EMail, CountryI3D |
| `Country` | Country data | CountryCode, EUMember |
| `BankAccount` | Bank account | Iban, AuthorizationNumber |
| `Article` | Article master data | ArticleUnit (for UN/ECE code) |
| `ReceiptInvoice` | Invoice entity | For credit voucher references |
| `ReceiptCreditVoucher` | Credit voucher entity | For origin tracking |

### Derived/Calculated Fields

| Concept | Calculation | Source |
|---------|-------------|--------|
| Tax category codes | Based on tax rate, reverse charge, country flags | Logic in `GetTaxCategoryCode()` |
| Tax exemption reasons | Based on tax scenario | Logic in `GetTaxExemptionReason()` |
| Structured address lines | Intelligent building from ReceiptReceiver | Logic in receiver address building (max 3 lines) |
| OwnCountryCode | Country code for trade type | Loaded from `Country` via `CountryI3D` (default: "DE") |
| Billing period | Min/Max from contract billing info | `ContractBL.GetContractBillingPeriodForInvoiceItem()` |
| Bank selection | Settings + customer override | `ReceiptInvoiceSettings.UseMandatorBankForInvoice` + `AccountCustomer.MandatorBank` |
| Skonto text | Payment condition formatting | `AssetConditionBL.GetPaymentConditionSkontoInBR_DE_18Format()` |
| UN/ECE code | Article unit lookup | `Article.ArticleUnit.UNECECode` |

---

## Special Cases & Business Logic

### Structured Receiver Address
The system uses the structured `ReceiptReceiver` entity to build multi-line addresses:
- **Maximum 3 lines** for Name and AddressLine1-3
- **Intelligent building** based on available fields (CompanyName, AdditionalAddressSupplement, Department, ContactDepartment, ContactName, Street)
- **Configurable department order** via `ReceiverContactDepartmentFirst` setting
- **Post office box handling** with `HasPostOfficeBox` flag
- **Fallback support** to legacy `IBookKeepingReceipt` fields if `ReceiptReceiver` is null

### Negative Prices
ZUGFeRD does not support negative prices. The system:
1. Makes `NetPrice` positive
2. Negates `Quantity` instead
3. Maintains correct calculation

### Title Positions
- Collapsed title positions are exported with aggregated child item values
- Expanded title positions are not supported (error)
- Mixed tax rates in title positions are not supported (error)
- Default tax rate for title positions without items: 19%
- Barcodes from child items are aggregated into the parent title position

### Payment Condition
Determined by SEPA active status:
- `IsSepaActive = true` → `DirectDebit` (BG-19)
- `IsSepaActive = false` → `BankTransfer` (BG-17)

### Country Trade Flags
Used for tax category determination:
- `IsInlandTrade`: Buyer country = Seller country
- `IsEUTrade`: Buyer country is EU member

### Validation Tolerances
- Net price difference tolerance: ±3.00 (between header and sum of positions)
- Gross price difference tolerance: ±3.00
- Within tolerance: Warning logged, value corrected
- Exceeding tolerance: Error, export fails

---

## Implementation Notes

### File Encoding
- XML files are generated with UTF-8 encoding
- BOM (Byte Order Mark) is removed from export (first 3 bytes stripped)

### Date Formats
- Standard date: `yyyyMMdd` (format code "102")
- Long date: `yyyy-MM-ddThh:mm:ss`

### Amount Formatting
- All amounts use "F2" format (2 decimal places)
- Culture: en-US (decimal separator: dot)

### Namespace Prefixes
- `rsm`: CrossIndustryInvoice
- `ram`: ReusableAggregateBusinessInformationEntity
- `udt`: UnqualifiedDataType
- `qdt`: QualifiedDataType

### Code References
- Main generator: `InvoiceZugferdBL.cs:117-158` (GenerateZugferdFile)
- Export item builder: `InvoiceZugferdBL.cs:237-434` (GetZugferdExportItem)
- XML document generator: `InvoiceZugferdBL.cs:727-750` (DoGenerateZugferdXRechnungXmlDocument)
- Tax logic: `InvoiceZugferdBL.cs:1369-1400` (GetTaxCategoryCode, GetTaxExemptionReason)

---

## Version History

| Version | Notes |
|---------|-------|
| 1.2 | Added: Structured `ReceiptReceiver` support for buyer address, `OwnCountryCode` for trade type determination |
| 1.1 | Added: Barcode/serial number export in line items via `ApplicableProductCharacteristic` |
| 1.0 | Initial documentation covering XRechnung 3.0.1 implementation |