Invoice (Header / Document Level)
Map the general invoice information here: invoice number, date, currency, totals (net/gross), payment terms, free-text notes, and global references (e.g., customer PO number). Make sure dates are normalized to YYYY-MM-DD and currency codes use ISO codes (e.g., EUR). Global tax blocks (per VAT rate: taxable basis, tax amount, rate, category) are also populated here; the rate often comes from the same field set used by the line items, but on document level it’s passed as a summarized block.
Seller (Supplier)
Select the layout that holds the billing party’s company data and map fields such as: name, legal form (optional), address (street/ZIP/city/country), VAT ID, tax number (if used), contact channels (phone/email), and bank reference (if centrally maintained). Ensure countries are stored as ISO codes (DE, AT, …) where the profile requires it or the validator recommends it.
Buyer (Customer)
Analogous to the seller: choose the layout with customer data and map fields (name, address, contact person, email, customer number if applicable). If the customer uses separate billing/shipping addresses, you can provide a different recipient address under the Delivery/Performance section (see below).
Delivery / Performance
Map the service period or delivery date here, plus (if applicable) the delivery address, delivery reference (e.g., delivery note number, delivery condition/IncoTerms), and—if your organization maintains them—project/contract IDs. Dates should again be normalized; periods can be start/end or a single date, depending on profile and practice.
Payment / Bank
Choose the layout with payment information: payment terms (e.g., 14 days net, early-payment discounts), bank details (IBAN, BIC, bank name), payment method (transfer, SEPA, card) and remittance information. If IBAN/BIC are stored separately, map both; if the customer uses alternative channels (e.g., a PayPal link), you can place that into a free-text or optional field as long as the profile allows it.
Items (Line Items)
For line items, pick a layout with the portal (or a list) containing the goods/services rows, then map the common keys, typically: line position, item name, item number (SKU), quantity, unit (code), unit price (net), VAT rate (%), and order reference. Optionally useful: tax category (S, Z, E, AE, …), line total (net), per-item delivery/performance date, buyer item ID, and allowance/charge.
Important: numbers must be decimal with a dot, and units must use UN/ECE codes (C62 = piece, HUR = hour, etc.). The per-item VAT rate belongs here; in addition, the document-level global tax blocks (summed per rate) are built—your add-on aggregates the line values so you don’t have to do the math twice.
Normalization & Quality Assurance
To keep mappings stable across customer environments, the add-on includes small but effective helpers: numbers can be auto-converted from comma to dot; dates normalized to YYYY-MM-DD; units coerced to uppercase and restricted to allowed codes; empty values are passed as truly empty (not placeholders); text is trimmed and quotes properly escaped. An integrated validator checks ZUGFeRD-required fields per area (depending on the chosen profile), highlights missing mappings immediately, and prevents faulty exports before generation.
Preview, Test Run, and Traceability
Every configuration can be tested: the add-on produces a preview of the resulting data structure (e.g., JSON/CSV) and logs which fields were taken from which layout. That way, discrepancies (wrong layout selected, empty field, unit text instead of code) are visible right away—before creating a ZUGFeRD document.
Versioned Mappings & Multi-Tenant Capability
Because many customers use multiple files/layouts, the add-on stores the mapping versioned per file/tenant. You can export/import mappings (e.g., between test and production), duplicate them (for similar customers), or switch between them (if the customer has alternative layouts)—all without altering the underlying data structure.
FAQs (concise)