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 customer's purchase order number comes from app_order_reference (BT-13), the contact person at the customer from the object app_buyer_contact with app_buyer_contact_name, app_buyer_contact_phone, and app_buyer_contact_email (BG-9). If app_buyer_contact is empty, the recipient's contact person is used (main_contact with given_name, family_name, tel, and email). The two sources are never mixed; empty fields are omitted.
• The recipient's VAT ID (vat_id on the organization) is taken over as BT-48 if it is structured like a VAT ID (country code plus number). Other entries, such as a tax number, are omitted.
• If the tax mode app_tax_mode (or tax_mode) is set to reverse_charge_13b, the invoice is output with VAT category AE, exemption reason and invoice note. Details in Reverse charge (Section 13b UStG) in e-invoices.
• The invoice type code defaults to 380 (commercial invoice). With app_invoice_type = storno it is 384 (corrected invoice), with credit_note 381 (credit note).
• For cancellations and credit notes, the number and date of the original invoice are taken from app_original_invoice as a reference (BT-25, BT-26). For custom data structures they can be passed via preceding_invoice_no and preceding_invoice_date instead; these take precedence.

---

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.