Map invoice data to ZUGFeRD

The "Map invoice data to ZUGFeRD" service task converts invoice data from the Pantarey form into the structured ZUGFeRD data format (EN16931, Cross-Industry Invoice). This creates the foundation for electronic invoicing according to the European standard.

---

How it works

The service takes flat invoice data (after amount calculation) and produces a structured JSON object according to the ZUGFeRD EN16931 standard:

• Seller and buyer are extracted from invoice data and mapped to the corresponding ZUGFeRD fields.
• Line items are converted into the CII (Cross-Industry Invoice) line format.
• Tax breakdowns, payment terms, and delivery dates are derived automatically.
• Units of measure are translated from plain text (e.g. "Hours", "Pieces") into standardised UN/ECE codes (e.g. HUR, C62).

---

Input parameters

The invoice object is expected as input — ideally after amount calculation by Calculate invoice amounts:

{
  "app_invoice_no": "INV-2026-001",
  "app_invoice_date": "2026-04-08",
  "app_due_date": "2026-05-08",
  "app_seller_name": "My Company Ltd",
  "app_seller_street": "Main Street 1",
  "app_seller_zip": "12345",
  "app_seller_city": "Sample City",
  "app_seller_country": "DE",
  "app_seller_vat_id": "DE123456789",
  "app_recipient_name": "Customer Corp",
  "app_recipient_street": "Client Road 5",
  "app_recipient_zip": "54321",
  "app_recipient_city": "Client City",
  "app_invoice_items_custom": [
    {
      "app_item_description": "Consulting",
      "app_amount": 10,
      "app_item_price_net": 150.00,
      "app_vat_percentage": 19,
      "app_unit": "Hours",
      "app_items_total_sum_net": 1500.00
    }
  ],
  "app_net_total": 1500.00,
  "app_vat_total": 285.00,
  "app_gross_total": 1785.00
}

Explanation:

• All fields prefixed with app_seller_* describe the invoice issuer.
• All fields prefixed with app_recipient_* describe the invoice recipient.
• Calculated amounts (app_net_total, app_vat_total, app_gross_total) are taken from the prior calculation step.

---

Output

The invoice object is enriched with an app_zugferd_data field containing the full ZUGFeRD data structure:

{
  "app_zugferd_data": {
    "exchangeddocumentcontext": { ... },
    "exchangeddocument": {
      "id": "INV-2026-001",
      "typecode": "380",
      "issuedatetime": "20260408"
    },
    "supplychaintradetransaction": {
      "includedsupplychaintradelineitem": [ ... ],
      "applicableheadertradeagreement": { ... },
      "applicableheadertradedelivery": { ... },
      "applicableheadertradesettlement": { ... }
    }
  }
}

This field is subsequently used by the Create e-invoice (ZUGFeRD) service to embed the XML data into a PDF/A-3 document.

---

Supported units of measure

Input	UN/ECE Code	Meaning
Stück, Stk, Pieces	C62	Piece
Pauschal, Flat rate	LS	Lump sum
Stunde, Stunden, Hours	HUR	Hour
Tag, Tage, Days	DAY	Day
Monat, Monate, Months	MON	Month
km	KMT	Kilometre
kg	KGM	Kilogram
Liter	LTR	Litre
m, m², m³	MTR, MTK, MTQ	Metre / Area / Volume

---

Notes

• This service is typically used between the amount calculation and the ZUGFeRD embedding step.
• Mapping is handled automatically — no ZUGFeRD-specific fields need to be filled in manually.
• Optional fields such as app_buyer_reference (routing ID), app_service_date, app_service_period_start, and app_service_period_end can be included.
• The invoice type code defaults to 380 (commercial invoice).

---

Tip

For most use cases, it is recommended to use the Complete e-invoice service instead of individual intermediate steps — it handles calculation, PDF generation, ZUGFeRD mapping, and XML embedding automatically in one step.