Implementation of ZUGFeRD in Coresuite Designer

Table of Contents

I Introduction

II Prerequisites

III Supported ZUGFeRD Versions and Marketing Documents

IV Enabling PDF/A File Generation and ZUGFeRD Profiles

V ZUGFeRD-related User-Defined Tables

1. Mapping - User-Defined Fields
2. Mapping - Unit of Measure (UOM)
3. Mapping - Tax Categories
4. Mapping - Delivery Terms Code (BT-X-145)
5. Configuration - Various Settings

VI Specific Logic

1. BT-10 & BT-13 - NumAtCard - Buyer Reference/Leitweg ID and Purchase Order Reference
2. BT-132 / BT-X-21 - BuyerOrderReferencedDocument
3. Determination of Bill To/Ship To Addresses
4. BT-84 - IBAN Determination
5. BT-72, BT-73 & BT-74 - Delivery Date, Service Date and Billing Period Determination
6. BT-49 - Determination of Buyer Electronic Address
7. BT-30 - Legal Registration Number Determination
8. BT-56 / BT-58 - Buyer Contact Name and E-Mail Determination
9. BT-81 - Payment Means Determination
10. Company Info Note - Manager Field Determination

VII Changelog

I Introduction (Back to Table of Contents)

In this section, we would like to highlight some general background and information in relation to the new ZUGFeRD implementation in Coresuite Designer.

In response to the legal changes in Germany, which took effect in January 2025, and the increasing adoption of the ZUGFeRD standard, we introduced the possibility of generating the PDF/A format in Coresuite Designer. This format combines both human-readable and machine-readable components by integrating PDF with XML.

The main difference between a standard PDF and a PDF/A file is that PDF/A includes an embedded XML file, which enables automated data processing. Additionally, when you open a PDF/A file in a PDF viewer, a notification may appear, indicating that the document is optimized for long-term archiving (PDF/A).

Coresuite Designer 8.30 introduced the first iteration and with this version, you could generate ZUGFeRD PDF/A files with ZUGFeRD version 2.2 for Sales AR invoices. In this article, you can find the consolidated implementation as delivered up to and including Coresuite Designer 8.55.

For more detailed information on ZUGFeRD and electronic invoicing in Germany, please visit the FeRD - Forum elektronische Rechnung Deutschland.

II Prerequisites (Back to Table of Contents)

 - Coresuite Designer min 8.40 is installed (see the changelog below for changes; some of the functionality described in this article require latest version of Coresuite Designer)

III Supported ZUGFeRD Versions and Marketing Documents (Back to Table of Contents)

With Coresuite Designer 8.55, we support generating ZUGFeRD files of version 2.0 and 2.3.

The PDF/A format file generation is supported on the following marketing documents in SAP Business One:

• Sales AR Invoices
• Sales AR - Credit Memos
• Sales AR - AR Down Payment Invoice
• Sales AR Reserve Invoice
• AR Down Payment Request
• AP Credit Notes
• AP Invoices
• AP Down Payments

Support for the three AP document types (AP Credit Notes, AP Invoices, AP Down Payments) was introduced with Coresuite Designer 8.55. This brings AP documents in line with the same archival and compliance standards previously only available for the AR documents above.

IV Enabling PDF/A File Generation and ZUGFeRD Profiles (Back to Table of Contents)

PDF/A generation is configurable at the PrintDefinition level for each supported marketing document.

1. Open any supported marketing document (e.g., A/R Invoice).

2. Click the pen icon to open the printdefinition.

3. Locate the "PDF Type" dropdown.

4. Select "PDF/A format" to enable the generation of a compliant PDF/A format file for this printdefinition.

Configuring the Global ZUGFeRD Version

You can configure the general/default ZUGFeRD version for all PDF/A format files on supported documents system-wide.

Important: Starting with Coresuite Designer 8.55, all ZUGFeRD-related configuration (version and profile) has moved to its own dedicated tab:

1. Go to Administration → Add-Ons → Coresuite → Coresuite Designer → Configuration → "ZUGFeRD" tab.

2. Pick the desired value from the "ZUGFeRD Version" selection field.

Available Options in the "ZUGFeRD Version" Dropdown:

• Latest - Always uses the most recent version supported by the 3rd party library (automatically applied when the Designer is updated).

• 200 - 2.0 - Forces use of ZUGFeRD 2.0, the initial release version.

• 230 - 2.3 - Forces use of ZUGFeRD 2.3, currently the latest supported version.

Note: Coresuite Designer uses an external library to generate PDF/A format files. Supported ZUGFeRD versions depend on the capabilities of this library and will be extended as new versions are released and integrated.

Overriding the Global Version Per Business Partner

To meet customer-specific e-invoicing requirements, you can override the general ZUGFeRD version for individual customers:

• Location: Business Partner Master Data
• Field: User-Defined Field (UDF) named "ZUGFeRD Version"

When this UDF is populated, it takes priority over the global configuration for any documents generated for that business partner.

Configuring the ZUGFeRD Profile

In addition to the ZUGFeRD version, Coresuite Designer supports different ZUGFeRD profiles, which determine how much detail is included in the generated XML and which electronic invoicing standard the file complies with. Support for profiles was introduced progressively: the Comfort profile was added in Coresuite 8.50, and the XRechnung profile followed in Coresuite 8.55, when configuration also moved to the dedicated "ZUGFeRD" tab described above.

The available profiles are:

- XRechnung - generates a KosIT-compatible PDF/A file with an attached XML file, following the KosIT electronic invoicing standard
- Extended - generates a ZUGFeRD 2.x PDF/A file with an attached XML file. This profile is targeted at medium and large businesses, but it is recommended for SAP Business One in general, due to the number of fields and options it covers
- Comfort - uses the EN 16931 profile and generates a basic ZUGFeRD 2.x PDF/A file with an attached XML file. This profile is aimed at small and medium businesses (SMBs)

A corresponding business partner UDF is also available, allowing selection of a specific profile per business partner. If a profile is defined on the business partner, it overrides the company-level setting.

ZUGFeRD and XRechnung use almost the same XML structure. However, some fields are optional in one format but required in the other, and the formatting rules can differ. Because of this, it is important to choose the correct profile for each customer - a file may be rejected by validation tools for the other format if the wrong profile is used.

V ZUGFeRD-related User-Defined Tables (Back to Table of Contents)

To enhance flexibility in handling ZUGFeRD format, we implemented data mapping tables to define customers' own user-specific UDFs (User-Defined Fields), VAT categories, Units of Measure (UOMs), and delivery terms codes.

1. Mapping - User-Defined Fields (Back to Table of Contents)

The UDTs SWA_LD_ZUGFERDMAP and SWA_LD_ZUGFERDMAP90 map customer User-Defined Fields (UDFs) from SAP Business One into the XML structure used by ZUGFeRD. 
 

How this data mapping works

Customers can define their own UDFs using these mapping tables:

• SWA_LD_ZUGFERDMAP - for data source Document_88

• SWA_LD_ZUGFERDMAP90 - for data source Document_90

Coresuite Designer retrieves data using the B1_Data datasource, which is used to populate the ZUGFeRD XML file. The mapping between B1_Data elements and the XML structure is stored in the @SWA_LD_ZUGFERDMAP or SWA_LD_ZUGFERDMAP90 table.

• Property - This field in the UDT must not be modified. It serves as a static identifier that links layout fields with their corresponding XML tags and ensures the correct functioning of the mapping logic.

• Datasource - This field determines the source table used by the layout designer. It specifies which internal SAP Business One data table is accessed during layout generation.
  Example: OINV for invoice headers, INV1 for invoice lines, etc.

• Field - This is the specific column within the chosen datasource that is mapped to the corresponding element in the ZUGFeRD XML. Here, users may also specify UDFs (User-Defined Fields) if custom data points need to be integrated.

• Datasource Override - Allows specifying a different datasource than the default one in the "Datasource" column.

• Field Override - Enables specifying a different field than the default one in the "Field" column.

• EN16931 ID - The values are populated with the appropriate codes from the ZUGFeRD documentation.
  Note that not all values require codes, so some fields will remain empty.
  Additionally, many values, especially those related to VAT, are calculated dynamically and therefore not explicitly listed in the table. This does not mean they are missing.

• Hide - When set to “Y”, the specific field will not be output to the ZUGFeRD XML file.

Important: If overriding either the datasource or field, both "Datasource Override" and "Field Override" must be set to ensure proper functionality.

For each XML element, the "Datasource Override" and "Field Override" values must exist in the B1_Data datasource within the Designer layout.

Warning: Only the "Datasource Override" and "Field Override" columns should be modified. All other columns are system-managed and may be updated automatically during Coresuite Designer upgrades. Changing system columns could lead to unexpected behavior.

Example Use Case

If you need to replace Document.DocNum with a user-defined field (U_SampleUDF), you can set:

• Datasource Override → "Document"

• Field Override → "U_SampleUDF"

Considerations for Datasource Changes

If overriding the default datasource, ensure you do not mix header and row tables. Headers typically contain a single row, whereas row tables can have multiple entries, making it difficult to determine the correct line. For row datasources, the Datasource Override should always match the default datasource.

2. Mapping - Unit of Measure (UOM) (Back to Table of Contents)

The configuration table SWA_LD_ZUGFERDUOM - SWA_LD Zugferd UOM Map enables mapping for Unit of Measure (UOM).
It allows customers to define custom mappings between the INV1.unitMsr field in SAP Business One and the UnitCode used in the TradeLineItem section of the ZUGFeRD XML document.

How to Create a Mapping

1. Add a new row in the UDT "SWA_LD_ZUGFERDUOM" from the SAP Business One to define a mapping.
2. Fill in the relevant columns:

• SAP Unit Measure - INV1.unitMsr value as is defined in your SAP Business One.

• Zugferd Unit Code - Corresponding ZUGFeRD Unit Code.

• Both fields Code and Name must be filled. Use a zero-padded row number, eight characters long.
  Example: 00000001, 00000002, etc.

Note: If no mapping is found for a unit of measure used in an invoice line, the system will default to the ZUGFeRD UnitCode H87 (piece).

To assist with correct mapping, a reference file containing valid ZUGFeRD unit codes is provided at the end of this article in a file UOM_Codes.xlsx.

3. Mapping - Tax Categories (Back to Table of Contents)

The mapping table SWA_LD_ZUGFERDTAX - SWA_LD Zugferd Tax Map allows flexible and precise control over how SAP Business One VAT codes are translated into ZUGFeRD-compliant tax categories.

How VAT Categories Are Determined

Coresuite Designer does not assume a standard VAT group or VAT rate within a given SAP Business One system, as these can vary significantly between installations and local customizations. Instead, the system dynamically reads the VAT group and VAT rate for each line item on the invoice at runtime.

• The VAT rate is directly included in the ZUGFeRD XML document for each invoice line.

• The VAT group is used to determine the ZUGFeRD tax category by checking against the SWA_LD_ZUGFERDTAX mapping table.

Default Behavior and Custom Mapping

If no explicit mapping is found for a given VAT group, the system defaults to using the "S" (Standard) tax category in the ZUGFeRD document.

To support scenarios where local or customized VAT groups do not align with the default "S" category, the mapping table allows users to define specific relationships between SAP VAT groups and the appropriate ZUGFeRD tax categories.

• The "S" tax category is used as a fallback when no mapping is defined.

• Only non-standard VAT groups - those that should not be treated as "S" - need to be explicitly mapped in the SWA_LD_ZUGFERDTAX table.

• Both fields Code and Name must be filled. Use a zero-padded row number, eight characters long.
  Example: 00000001, 00000002, etc.

4. Mapping - Delivery Terms Code (BT-X-145) (Back to Table of Contents)

Introduced with Coresuite Designer 8.55, the mapping table SWA_LD_ZUGFERDDT lets you define the delivery terms code (BT-X-145) that should be output for each SAP Business One Shipping Type.

Fill this table with the desired mapping type for each Shipping Type, using the values from the UNTDID 4053 code list and the INCOTERMS list:

5. Configuration - Various Settings (Back to Table of Contents)

The configuration table SWA_LD_ZUGFERDSET - SWA_LD Zugferd Settings allows you to control specific behaviors of the ZUGFeRD implementation. The keys give users finer control over how lines, discounts, and delivery dates are represented in the generated ZUGFeRD XML.

• HideLineUDF: Specifies the line-level UDF used to determine whether a document line should be hidden.

• HideLineValue: Defines the UDF value (for the field specified in HideLineUDF) that indicates the line should be omitted.

• IgnoreNegativeLineDiscounts: When set to “Y”, negative line discounts will not be included in the output.

• UseCustomDeliveryDates: Introduced with Coresuite Designer 8.55. When set to "Y", the delivery date, service date, and billing period dates (BT-72, BT-73, BT-74) are taken from custom fields you define in the SWA_LD_ZUGFERDMAP mapping table, instead of the default determination logic. See VI.5. BT-72, BT-73 & BT-74 - Delivery Date, Service Date and Billing Period Determination for the exact steps.

VI Specific Logic (Back to Table of Contents)

This section documents ZUGFeRD-specific logic implemented in Coresuite Designer that may not be immediately visible in the standard configuration or UI. These behaviors are driven by internal logic and mapping conventions to support the ZUGFeRD XML structure.

1. BT-10 & BT-13 - NumAtCard - Buyer Reference/Leitweg ID and Purchase Order Reference (Back to Table of Contents)

BT-10 - BuyerReference
BT-10 will be set based on the Leitweg Id defined on the Business Partner. This value is user-defined in the mapping table under the key Header.BPLeitwegId, and is typically stored as a UDF on the Business Partner master data.

Solution:
• The system will first attempt to use the Leitweg Id (as per the mapping table).
• If the Leitweg Id is not defined, NumAtCard will be used.
• If both Leitweg Id and NumAtCard are defined, Leitweg Id will take priority.
• If you prefer to use NumAtCard regardless, this behavior can be customized within the mapping table. Please see the section V.1. Mapping - User-Defined Fields.

BT-13 - Purchase Order Reference
By default, the NumAtCard value will be used. Partners can override this field by specifying a UDF or custom value in the mapping table.

BT-10 and BT-13 are separate properties to respect their distinct purposes in the X-invoice.

Overriding via the mapping table remains fully supported, so partners can map custom UDFs to either field without changing the default behavior.

2. BT-132 / BT-X-21 - BuyerOrderReferencedDocument (Back to Table of Contents)

Properties BuyerOrderReferencedDocumentLineId (BT-132) and BuyerOrderReferencedDocumentIssuerAssignedId (BT-X-21) have been added to the mapping table ZUGFERDMAP and SWA_LD_ZUGFERDMAP90.
 - When the UDF U_NameOfUDF (from U_DatasourceO=Row, U_FieldO) contains data, it populates BuyerOrderReferencedDocument (BT-132) or BuyerOrderReferencedDocumentIssuerAssignedId (BT-X-21) accordingly.
- By default, these properties do nothing. They must be overridden in the mapping table to take effect.

3. Determination of Bill To/Ship To Addresses (Back to Table of Contents)

The Bill To/Ship To addresses included in the ZUGFeRD XML are determined based on the document-level addresses first, with a fallback to the Business Partner master data if necessary.

This logic ensures that the XML reflects the most specific and complete address available, while maintaining consistency with the Business Partner master data when document-level information is incomplete.

Bill To Address:
• If the document’s Bill To address contains a postcode, this address is used.
• If the document’s Bill To address does not contain a postcode, the Business Partner’s master data address is used instead. 

Ship To Address:
• If the document’s Ship To address contains a postcode, this address is used.
• If the document’s Ship To address does not contain a postcode, the Business Partner’s master data address is used instead.

4. BT-84 - IBAN Determination (Back to Table of Contents)

When no payment term is defined on the document, the system now automatically uses the house bank account defined on the Business Partner to determine the IBAN.
This ensures correct IBAN selection and consistent payment information generation, even when payment terms are not explicitly set at the document level.

5. BT-72, BT-73 & BT-74 - Delivery Date, Service Date and Billing Period Determination (Back to Table of Contents)

These three fields follow the priority order below for BT-72 (ActDelDate), BT-73 (BillingStartDate) and BT-74 (BillingEndDate):

BT-72 - Delivery Date Determination:
If the document is based on a delivery note, we use the delivery note's date as the actual delivery date.

BT-73 - ActualDeliverySupplyChainEvent - Service Date Determination
The Service Date is chosen using this order of priority:
Priority 1: Use the ShipDate from the delivery note, if the invoice is based on a delivery note
Priority 2: Use the DocDueDate from the delivery note, if the invoice is based on a delivery note
Priority 3: Use the ActDelDate from the invoice, if the invoice is not based on a delivery note
Priority 4: Use the DocDueDate from the invoice, if the invoice is not based on a delivery note

Using Custom Fields for These Dates
If you want to use a custom field for BT-72, BT-73, or BT-74 instead of the default determination logic above, you can follow these steps:

1. Go to the Zugferd Settings table SWA_LD_ZUGFERDSET from Tools > User-Defined Windows
2. Set UseCustomDeliveryDates to 'Y'
3. Go to the Zugferd Mapping table SWA_LD_ZUGFERDMAP
4. At the bottom, you will find the entries Header.Custom.ActualDeliveryDate, Header.Custom.BillingStartDate and Header.Custom.BillingEndDate. Update the Datasource and Field columns to point to the data you want to use. No further changes are needed. In our example, we selected the Row Datasource for demo purposes, but the fields already come filled in with RowBaseDocument.

6. BT-49 - Determination of Buyer Electronic Address (Back to Table of Contents)

BT-49 defines the electronic address to which a business document should be delivered. Because of how the ElectonicAddressSchemeIdentifier enum is defined in the ZugFerd library, the system checks whether a VAT Structure is defined in the business partner's master data.

If this value exists, the electronic address is generated using the identifier from the VAT Structure field and the Participant ID.
If this value does not exist, the address is generated based on the Shipping GLN instead. This is because PEPPOL identifiers are different from country to country, and an international company must have different entities in every country.

Note: If the VAT Structure does not match any value of the ElectonicAddressSchemeIdentifier, the system will default to the GLN approach.

7. BT-30 - Legal Registration Number Determination (Back to Table of Contents)

Coresuite Designer supports BT-30 (Seller's legal registration identifier). This adds the company's registration number to the ZUGFeRD XML file, using the correct identifier scheme for each country.

Each country uses a different identification scheme (schemeID). A mapping table automatically selects the correct schemeID based on the country of the seller. If the country is not found in this table, the system uses the GLN scheme (0088) by default.

In addition, if an Alias Name is defined under Company Details > General, it is also included in the XML as TradingBusinessName (BT-28).

For example, for a German company with registration number "HRA3320" and an Alias Name of "OEC", the XML output looks like this:

<ram:SpecifiedLegalOrganization>
  <ram:ID schemeID="0204">HRA3320</ram:ID>
  <ram:TradingBusinessName>OEC</ram:TradingBusinessName>
</ram:SpecifiedLegalOrganization>

The table below shows the schemeID used for each supported country. If a country is not listed, the GLN scheme is used instead.

8. BT-56 / BT-58 - Buyer Contact Name and E-Mail Determination (Back to Table of Contents)

The ZUGFeRD library currently does not support the BuyerAgentTradeParty node, which would be needed to output BT-X-418 (Invoice recipient e-mail address).

As a temporary solution, two mapping fields are available in the Zugferd Mapping table (SWA_LD_ZUGFERDMAP), pointing to the Buyer's contact name and e-mail address instead:

- Header.BuyerContactName - maps to DocumentContactPerson.Name - outputs as BT-56
- Header.BuyerContactEmail - maps to DocumentContactPerson.E_MailL - outputs as BT-58

Both fields are output under BuyerTradeParty > DefinedTradeContact in the XML:

<ram:BuyerTradeParty>
  ...
  <ram:DefinedTradeContact>
    <ram:PersonName>Alexandra Deuber</ram:PersonName>
    <ram:EmailURIUniversalCommunication>
      <ram:URIID>alexandra.deuber@microchips.sap.com</ram:URIID>
    </ram:EmailURIUniversalCommunication>
  </ram:DefinedTradeContact>
  ...
</ram:BuyerTradeParty>

The same approach can be used on the Seller side (BT-41 / BT-43) if needed.

If this mapping is not wanted, it can be turned off by clearing the Datasource and Field columns for these two rows in the Zugferd Mapping table.

9. BT-81 - Payment Means Determination (Back to Table of Contents)

Up to Coresuite Designer 8.50, the value for BT-81 - SpecifiedTradeSettlementPaymentMeans in the ZUGFeRD export was hardcoded to 30 (credit transfer).

The Payment Means value is defined as BT-81 in the mapping table SWA_LD_ZUGFERDMAP or SWA_LD_ZUGFERDMAP90.

The value comes from a UDF named U_SWA_LD_ZUGFERD_PMTCODE on the OPYM table. Each Payment Method has to be set up with the desired code, as specified by the customer, according to the official list of payment means codes defined in the UNCL4461 code list: https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4461/

If no value is set, the default remains 30 (credit transfer).

10. Company Info Note - Manager Field Determination (Back to Table of Contents)

The company's Managing Director is set by the admin in SAP Business One, under the company settings (the Geschäftsführer / OADM.Manager field). This value is included in the ZUGFeRD company info note, labeled "Geschäftsführer".

This label is populated from the PrintHeadr column in the OADM table (company settings). The company info note in the XML looks like this:

<ram:IncludedNote>
  <ram:Content>Geschäftsführer: John Doe, Jane Doe; Firmensitz: Musterstadt; Musterfirma GmbH, Musterstraße 1, 12345 Musterstadt</ram:Content>
  <ram:SubjectCode>REG</ram:SubjectCode>
</ram:IncludedNote>

VII Changelog (Back to Table of Contents)

Please subscribe to this FAQ to receive automatic notifications when we update this FAQ. We will update this FAQ whenever we release a fix or an improvement in respect of ZUGFeRD Implementation in Coresuite Designer or have additional information related to this topic.

(Back to Table of Contents)