ZUGFeRD 2.2-2.3.x import for Dynamics 365 for Finance

ZUGFeRD (Zentraler User Guide des Forums elektronische Rechnung Deutschland) is an e-invoicing format combining a human-readable PDF/A-3 and an embedded XML file using the CII (Cross-Industry Invoice) syntax. The CII syntax may also be used in the xRechnung, which is a pure XML version of the German e-Invoice. From 2025, the ability to receive and process electronic invoices becomes mandatory for B2B transactions in Germany.

Microsoft’s current solution in Dynamics 365 for Finance provides support specifically for the UBL (Universal Business Language) format of the xRechnung: Import vendor electronic invoices – Finance | Dynamics 365 | Microsoft Learn. It enables the import of vendor invoices received in this format, mapping them as pending vendor invoices in D365. The invoice may be uploaded directly into the system or placed in a SharePoint folder for unattended processing.

We are happy to announce the release of the CII (Cross-Industry Invoice) dialect of the xRechnung / ZUGFeRD electronic invoice. This solution is implemented via Electronic Reporting (ER) configurations, which means it does not require any customisations and can be easily installed across all active versions of D365. It sits on top of the standard Invoice model v280, Vendor Invoice Mapping to Destination v280.46, side by side with the configuration Vendor Invoice Import ~~v280.7~~ v280.9 (state: Jan. 2025).

The functionality aligns with the standard Microsoft UBL import, utilizing the key data elements for processing and ensuring PO matching:

Header: Invoice ID, Invoice date, Due date, Vendor ID, Currency code, PO number, a header-level note and header attachments (in XML embedded MIME documents).
Lines: Line number, Item ID, Quantity, Sales unit of measure, Sales price, Discount (percentage discounts are converted to absolute values as the XML schema doesn’t support percentages), Price unit, Name, Description, and Line amount (excluding VAT).

The solution supports the ZUGFeRD 2.1, ZUGFeRD 2.2 or ZUGFeRD 2.3.x / Factur-X 1.0x with the profile EN16931 (also known as the “COMFORT” profile), XRECHNUNG profile or the EXTENDED profile. All three meet the tax law requirements and must be accepted by e-invoice recipients.

In contrary, ZUGFeRD 1.0 (easily recognised by the ~~<rsm:CrossIndustryDocument>~~ root node instead of the proper <rsm:CrossIndustryInvoice>) is no longer permitted in Germany when it comes to complying with the current legal requirements for electronic invoices, and therefore not supported. The same applies to the BASIC and BASIC WL profiles of the ZUGFeRD 2.x, announced by the <ram:GuidelineSpecifiedDocumentContextParameter> tag in the header.

Price

The solution is offered at a fixed fee per end customer / D365 tenant:

Version	Price	Deliverables	Notes
Light	€890	The Vendor invoice import CII Electronic Reporting configuration	This option does not require any X++ customisations or 3rd party software and can be installed and used right away.
Light+	€1200	Same as the Light version but with 5 hours of prepaid support and installation

You can acquire the solution on the official Microsoft AppSource marketplace: ZUGFeRD CII import (microsoft.com)

Setup and use

1. Follow the steps outlined in the Microsoft’s guidance Import vendor electronic invoices – Finance | Dynamics 365 | Microsoft Learn:
2. Import the same three configurations from Microsoft (Prerequisites);
3. Import the configuration Vendor invoice import CII.xml provided to you (menu Organisation administration > Electronic reporting > Configurations, button Exchange / Load from XML file);
4. Open Accounts payable > Setup > Accounts payable parameters; on the Electronic documents tab, select the imported Vendor invoice import CII format.
5. To run either one of the formats – UBL or CII – by choice, you may download and import a complimentary X++ extension with an additional parameter CII vendor invoice and an own menu item AP > Periodic tasks > Import vendor invoices CII underneath the standard one: VendImportInvoice_CII.axpp. In the batch execution mode this does not matter, because each of the formats becomes its own Electronic source with a set of SharePoint folders etc.
6. Prepare the master data: make sure the vendors are stored with proper VAT numbers in Dynamics 365 for Finance. They must have the proper country prefix “DE” and may not contain any spaces or special characters.
7. Make sure that the vendor’s external item ID mapping exists. Any Buyer Assigned ID (our item number) potentially sent by the vendor is neglected by the Microsoft’s mapping, and the conversion to the internal Item ID is always handled via the external item IDs. Under these conditions, the import works as expected and the PO lines may be matched.
8. Make sure that the units of measure are properly mapped to the UNECE Recommendation No. 20 list called “Codes for Units of Measure Used in International Trade”. For instance, the UNECE unit H87 should be mapped to PCS or STK, while C62 may become EA in our system; see also a longer list in https://erconsult.eu/de/blog/aktueller-stand-der-erechnung-in-d365-for-finance-deutschland/. You may need to introduce new units of measure, because the External codes table (ExtCodeValueTable in particular) assumes the 1:1 relation between the system units in D365 and the external unit codes.
9. Perform an interactive test upload by using the function Accounts payable > Periodic tasks > Import vendor invoices (or Import vendor invoices CII if you installed and configured the above extension from step 5). Beware: contrary to the UBL format, the CII (“COMFORT”) invoice does not include any line-by-line reference to the purchase order lines. Just the PO number is sent in the header. We assume that the numeration of the invoice lines mostly follows the PO lines numeration. If not, the standard mapping will fall back to the matching by the line purchase price.
10. Configure the batch mode with Electronic reporting sources i.e. SharePoint folders as outlined in the above Microsoft’s guidance: Import vendor electronic invoices – Configure the sources to import files in batch mode.
11. The standard UBL import from Microsoft and our CII import may be “daisy-chained”: set the error folder (Electronic reporting sources -> Settings / Document type for failed files) of the CII import the same as the input folder (Settings / Document type for input sources) for the UBL. If the XML starts with the <rsm:CrossIndustryInvoice> tag and features the <rsm:>, <ram:> namespaces, then it is a ZUGFeRD and it will be processed regularly by the CII import. If the XML starts with the <ubl:Invoice> or <ubl:CreditNote> tag and features <cbc:>, <cac:> namespaces, the CII parsing is going to fail early, and the XML file will be passed to the UBL parser, which takes it from there.

Cardinality of the external item number

In Dynamics 365 Supply Chain Management, the relationship between an external item number and an internal item ID is strictly 1:1. Each external ID points to exactly one internal product. This can cause issues when using Microsoft’s Vendor invoice mapping to destination, especially if Procurement categories were converted into service items during the vendor invoice import implementation. For example, spare parts that were once all booked under the procurement category “Maintenance and repair” now require separate released products, and every type of stationery once grouped under “Office supplies” must be split into multiple products. With mapping based on vendor external item numbers, this means creating a separate released product record for every sheet of paper or pen type.

To reduce this complexity, we recommend a small extension to the CustVendExternalItem table. Vendor invoice mapping to destination relies on the method CustVendExternalItem.getItemIdForInvoiceAccount_BR() , which could theoretically return the same internal item ID for different external IDs. However, the table’s unique index blocks multiple external numbers from being linked to the same product and vendor. Fortunately, Microsoft provided an extension point fieldIdsToHash() that allows you to add new fields into the uniqueness constraint, compressed into a hash. The code below extends this index with the Description field, so multiple vendor external item numbers can point to the same internal product.

				
					/// <summary>
/// Allow for internal ItemId 1 : N ExternalItemId
/// </summary>
[ExtensionOf(tableStr(CustVendExternalItem))]
final public class CustVendExternalItem_CII_Extension
{
    /// <summary>
    /// Add the Description to the list of fields that define the uniqueness of a record
    /// </summary>
    /// <returns>The set of field Ids.</returns>
    protected Set fieldIdsToHash()
    {
        Set hashFields = next fieldIdsToHash();

        if (this.ModuleType != ModuleInventPurchSalesVendCustGroup::Vend && 
            this.ModuleType != ModuleInventPurchSalesVendCustGroup::VendGroup)
        {
            return hashFields;
        }
        if (! this.Description)
        {
            return hashFields;
        }

        PurchParameters purchParameters = PurchParameters::find();
        if (purchParameters.ERModelMappingVendInvoice != 0 ||
            purchParameters.ERModelMappingVendInvoiceCII != 0)
        {
            hashFields.add(fieldNum(CustVendExternalItem, Description));
        }
        return hashFields;
    }

}

Use this code carefully: if you already rely on the Description field for other purposes, conflicts may arise. Records with an empty description will still behave as in the standard system and act as a fallback when matching external vendor numbers.

Useful links

End user license agreement: ZUGfERD_Import_EULA
You may download sample invoices here: ZUGFeRD 2.3 | Forum elektronische Rechnung Deutschland (ferd-net.de). To extract an XML attachment suitable for the import, you may use Adobe Reader or Adobe Acrobat.
Splitting ZUGFeRD hybrid invoices may be achieved with the Encodian’s PDF – Extract Attachments flow action for Power Automate. Once extracted, put the XML into the SharePoint input folder from step 10 above.
A rich interactive ZUGFeRD schema navigator is hosted here: EN 16931 – FacturX 1.03 – ZUGFeRD 2.0.1 – COMFORT (gefeg.com) , for the German ‘dialect’ refer to XRechnung_CII; v1.2.1; 28.06.2019

Daily Archives: September 24, 2024