Introduction

This guide describes what a new project must do to use the IOM ZUGFeRD feature. It covers two scenarios:

• Onboarding: A customer wants to use the feature as delivered, without project-specific changes.

• Extension: A customer wants to modify or extend the standard mapping for project-specific business or integration requirements.

The general principle is to keep the standard IOM ZUGFeRD implementation unchanged wherever possible. Onboarding is primarily a configuration and validation task. An extension should reuse the standard mapping and customize only the data that is genuinely project-specific.

References

• Concept - IOM eInvoice (ZUGFeRD)

Prerequisites

Before starting, the project should confirm:

• The IOM version contains the ZUGFeRD feature.

• The required invoice and credit note document processes are configured.

• The relevant shops are known, including their shop IDs.

• Seller master data is available for each shop.

• The applicable requirements are based on the German specification in addition to EN 16931.

• The recipient system can process a PDF/A-3 file with embedded ZUGFeRD XML.

• The project has identified business, shop administration, operations, integration, and technical contacts.

The customer does not need to implement a mapper for the onboarding scenario. IOM uses the standard ZUGFeRD-capable invoice mapper when no project-specific mapper is configured.

Scenario A: Onboarding

Determine the Rollout Scope

The project must define:

• Which shops will use ZUGFeRD

• Which environments will be activated first, for example development, test, acceptance, and production

• Whether invoices, credit notes, and manual credit notes are required

• Which recipient and archiving systems are in scope

• Which contacts are responsible for configuration, testing, operations, and approval

The feature is enabled per shop. It is not automatically enabled for all shops in an environment.

Configure Seller Data

Create or update one ZUGFeRD shop configuration for every participating shop. Set enabled to true and provide the seller information required by the German specification and EN 16931.

Format requirement for sellerCountryCode:

• Use an ISO 3166-1 alpha-2 country code.

• Use exactly two uppercase letters.

• For German sellers, use DE.

• Do not use lowercase, three-letter codes, or region-style values such as DE-DE.

At least the seller name, seller country, and one suitable seller identifier must be available. Use real production seller data only in the production environment. Do not copy the test values from the example database migration.

IOM supports the following seller data sources, in priority order:

1. Shop-specific ZugferdShopConfigurationDO values

2. Application properties such as zugferd.seller.name, zugferd.seller.vatId, and zugferd.seller.iban

3. Available shop master data, such as the shop name and country

The project should decide which source is authoritative and document the decision. Shop-specific configuration is required for multi-shop deployments.

Verify the Document Configuration

Confirm that the configured document mapper can be resolved for the invoice and credit note document flow. No project mapper is required when the standard mapper is used.

ZUGFeRD enrichment is applied only when all of the following conditions are met:

• The document type is an invoice or credit note.

• The document format is PDF.

• A non-empty PDF has been generated.

• ZUGFeRD is enabled for the shop.

• Structured ZUGFeRD XML can be generated from the document.

Manual credit notes are supported when they result in a supported CREDIT_NOTE document and contain the required invoice, buyer, seller, amount, tax, and reference data.

Execute the Onboarding Test

At minimum, test the following documents for every relevant shop:

1. A regular invoice

2. A regular credit note with a reference to the original invoice

3. A manual credit note, if the shop uses manual credit notes

4. A consolidated invoice, if the shop uses consolidated billing

5. An invoice containing multiple tax rates, if applicable

6. Each relevant payment method and payment reference variant

For every test document, verify:

• The PDF can be opened and remains visually correct.

• The file is a PDF/A-3 with embedded ZUGFeRD XML.

• The XML contains the expected seller, buyer, invoice, item, tax, payment, and reference data.

• The XML and PDF pass the configured ZUGFeRD validation.

• The recipient system can import the XML data from the PDF.

• The document is transmitted and archived through the existing process.

Operate the Feature

IOM writes ZUGFeRD processing and validation information to the application logs. Operations must monitor the relevant log.error, log.info, and log.debug entries according to the environment's logging configuration.

Find any invalid eInvoice in the OMT using the order search business query invalid invoice pdfs.

A validation error must be handled as follows:

1. Identify the affected document and shop.

2. Inspect the validation and application log details.

3. Correct the source data or shop configuration.

4. Generate the document again.

5. Validate the corrected PDF and XML before transmission.

Onboarding Completion Checklist

• Rollout shops and environments are approved.

• Seller data is configured for every participating shop.

• The feature switch is enabled only for approved shops.

• Invoice, credit note, and required manual credit note scenarios pass validation.

• Recipient import and archiving have been tested.

• Logging and operational responsibilities are documented.

• Production seller data has been reviewed and is not copied from test data.

• Business and technical acceptance has been recorded.

Scenario B: Extension

Criteria for Using an Extension

Consider an extension only when the standard mapping cannot provide a required result, for example:

• A project-specific seller or VAT identifier must be supplied.

• A payment reference requires a customer-specific format.

• A project-specific note or legal disclaimer must be added.

• Seller data must be selected dynamically from an external or project-specific source.

• A supported standard field must be mapped differently for the customer process.

Do not use an extension to compensate for missing or incorrect master data that should be fixed in the shop configuration or source invoice.

The current scope does not require project-specific fields or customizations. An extension is therefore only required when a future project requirement explicitly changes that decision.

Extension Architecture

A project mapper should:

1. Implement ZugferdCapableMapper.

2. Reuse the standard IOM mapping service through ZugferdInvoiceMappingService.

3. Apply project-specific changes through ZugferdInvoiceCustomizer.

4. Be registered in the project document mapper configuration.

5. Be tested with representative invoices, credit notes, and manual credit notes.

The standard mapper already implements ZugferdCapableMapper. A project mapper does not need to rebuild the complete invoice mapping. It should delegate to the standard mapping and apply the smallest necessary customization.

Blueprint

The following blueprint illustrates the intended structure:

@Stateless
public class CustomInvoiceDocumentMapperBean implements ZugferdCapableMapper
{
    @EJB(lookup = ZugferdInvoiceMappingService.MAPPING_INVOICEDOCUMENTMAPPERBEAN)
    private ZugferdInvoiceMappingService standardMappingService;

    @Override
    public InvoiceCreditNote map(DocumentLO documentLO)
    {
        return standardMappingService.map(documentLO);
    }

    @Override
    public byte[] mapToZugferdXml(DocumentLO documentLO)
    {
        return standardMappingService.mapToZugferdXml(documentLO, this);
    }

    @Override
    public void customizeZugferdInvoice(Invoice invoice, DocumentLO documentLO)
    {
        TradeParty seller = invoice.getSender();
        if (seller != null)
        {
            seller.setVATID(loadProjectSpecificVatId(documentLO));
        }
    }

    private String loadProjectSpecificVatId(DocumentLO documentLO)
    {
        return "DE000000000";
    }
}

The example is a blueprint, not production-ready code. The placeholder value must be replaced by a validated source, and the mapper must follow the project's dependency injection, naming, and configuration conventions.

Customization Hook

customizeZugferdInvoice(Invoice invoice, DocumentLO documentLO) is called after the standard ZUGFeRD invoice has been built. It can be used to override selected values such as the following:

• Seller name or VAT ID

• Payment reference

• Notes and comments

• Project-specific seller data

The hook should not alter unrelated standard fields. Changes must preserve the consistency of totals, taxes, payment information, and mandatory references.

Mapper Registration

The project must configure the custom mapper for the document flow that should use it. The exact configuration depends on the project's document mapper definitions and deployment setup. Verify the following:

• The custom mapper is available in the deployed application.

• The configured mapper implements ZugferdCapableMapper.

• The invoice and credit note flows resolve the intended mapper.

• Shops that do not require the extension continue to use the standard mapper or their existing mapper.

If the configured mapper is not ZUGFeRD-capable, IOM falls back to the standard ZUGFeRD mapping service for XML generation. This fallback must be explicitly tested and must not be confused with successful registration of a custom mapper.

Extension Test Strategy

Add focused unit tests for the customization and integration tests for the resulting document.

Unit tests should verify:

• The standard mapper is delegated to.

• The customizer changes only the intended fields.

• Null or missing optional data is handled correctly.

• Invoice and credit note paths use the expected customization.

Integration tests should verify:

• The configured project mapper is resolved.

• A regular invoice produces valid ZUGFeRD XML and PDF/A-3.

• A regular credit note produces the correct original-invoice reference.

• A manual credit note remains valid when the extension is applied.

• Net, tax, gross, discount, surcharge, and payment values remain consistent.

• The recipient system accepts the customized document.

Run the standard ZUGFeRD document tests as well as the project-specific tests after every mapper change.

Extension Review Checklist

• The business requirement cannot be fulfilled by shop configuration or source-data correction.

• The affected document types and shops are identified.

• The custom mapper reuses the standard mapping service.

• Customization is limited to the required fields.

• Totals, tax data, payment data, and mandatory references remain consistent.

• The mapper is registered in the correct document configuration.

• Unit and integration tests cover invoice, credit note, and relevant manual credit note cases.

• Recipient import and archiving have been retested.

• Operations and support documentation describe the customized behavior.

Responsibilities