The automatic generation of e-invoices is a Beta feature. For now, only specific customers have access to it.

This feature requires XTRF version 10.1 or higher.

Introduction

The XTRF e-invoicing integration service automates e-invoice generation and processing within your XTRF projects (Smart and Classic). It replaces a PDF invoice document with a Factur-X PDF invoice document. This solution eliminates manual data entry, ensures compliance, and accelerates payment cycles.

This service can be used in countries that support Factur-X or ZUGFeRD standards.

The e-invoice generation service only applies to invoices and does not support credit notes or proforma invoices.

Key advantages:

reduction in processing costs.
built-in compliance with e-invoicing standards.
seamless integration with existing XTRF workflows.

Disclaimer

To the fullest extent permitted by law, XTRF shall not be liable for any damages arising from the use of the e-invoicing service, including but not limited to any loss of business, revenue, or data, or any legal consequences arising from incorrect or non-compliant invoices. Clients assume full responsibility for reviewing and ensuring the accuracy and compliance of invoices generated through the service.

XTRF e-invoice generation works in accordance with the Factur-X / ZUGFeRD mandatory schema. No future changes are planned in this functionality.

How does the XTRF e-invoicing integration service work?

The e-invoicing integration service is based on a macro prepared by the XTRF team. You can run this macro for every client invoice in Ready status, and it will perform the following actions:

Collect the invoice data necessary to generate a Factur-X invoice.
Download the generated PDF Factur-X invoice file.
Replace the old invoice PDF with the new Factur-X PDF invoice file.
Add the Factur-X invoice ready category to the invoice.

Invoice skipping

If an XTRF client invoice does not contain any of the data required by the Factur-X XML schema, it will be skipped and not processed.
Invoices in the status Not Ready will also be skipped as they do not contain any PDF documents.
Skipped invoices will have the Factur-X preparation failure category added.

If the client invoice's status is changed to Not Ready after the Factur-X e-invoice was generated, the macro must be rerun after changing the status back to Ready. This action is required because the e-invoice PDF would be replaced by a regular XTRF PDF document upon changing the status to Ready. We recommend removing the Factur-X invoice ready category from this invoice before reruning the macro.

Field mapping

XTRF client invoice to Factur-X invoice mapping

Data in XTRF	Factur-X invoice field	Comment
Invoice No.	ExchangedDocument → ID and ApplicableHeaderTradeSettlement → PaymentReference
Date	ExchangedDocument → IssueDateTime
Delivery period	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → BillingSpecifiedPeriod → StartDateTime and SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → BillingSpecifiedPeriod → EndDateTime	Delivery period data is calculated automatically (for details, see the Delivery period determination section below). If you include the information about the delivery period in the invoice PDFs, ensure the dates on the PDF match the dates calculated automatically.
Net Total	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementHeaderMonetarySummation → LineTotalAmount and SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementHeaderMonetarySummation → TaxBasisTotalAmount
Tax (VAT) value, calculated from Net Total for chosen Tax (VAT) calculation rule	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementHeaderMonetarySummation →TaxTotalAmount
Gross Total	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementHeaderMonetarySummation → GrandTotalAmount and SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementHeaderMonetarySummation → DuePayableAmount
Client → Branch → Full Name	SellerTradeParty → Name
Invoice Signatory → First Name + Last Name	SellerTradeParty → DefinedTradeContact → PersonName
Invoice Signatory → Phone or Client → Branch → Phone	SellerTradeParty → DefinedTradeContact → TelephoneUniversalCommunication → CompleteNumber	The client's branch phone number will be used if the 'Invoice Signatory Phone' field is empty.
Invoice Signatory → E-mail Address	SellerTradeParty → DefinedTradeContact → EmailURIUniversalCommunication → URIID
Client → Branch → Address	SellerTradeParty → PostalTradeAddress
Client → Branch → Tax No. 3 (with country symbol)	SellerTradeParty → SpecifiedTaxRegistration → ID
Client → Legal Name	BuyerTradeParty → Name
Client → Billing Address → Address	BuyerTradeParty → PostalTradeAddress
Client → Main Data → Identification Data → Tax No.	BuyerTradeParty → VatNumber
Client → Main Data → Identification Data → Contract Number	SupplyChainTradeTransaction → ApplicableHeaderTradeAgreement → BuyerReference and SupplyChainTradeTransaction → IssuerAssignedID → AdditionalReferencedDocument	Optional.
Invoice Items	List of IncludedSupplyChainTradeLineItem	For details, see the XTRF invoice item to Factur X invoice 'IncludedSupplyChainTradeLineItem' mapping section below.
Tasks → Projects → Client PO Number	ApplicableHeaderTradeAgreement → BuyerReference	Concatenation of unique Client PO Numbers (if provided).
Payment Method → Bank Account → IBAN	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementPaymentMeans → PayeePartyCreditorFinancialAccount → IBANID	The payment method type must be Wire Transfer.
Payment Method → Main Data → Account Owner Name	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementPaymentMeans → PayeePartyCreditorFinancialAccount → AccountName	The payment method type must be Wire Transfer.
Payment Method → Bank Account → SWIFT	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradeSettlementPaymentMeans → PayeeSpecifiedCreditorFinancialInstitution → BICID	Optional. The payment method type must be Wire Transfer.
Payment Terms	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradePaymentTerms → Description
Payment Due Date	SupplyChainTradeTransaction → ApplicableHeaderTradeSettlement → SpecifiedTradePaymentTerms → DueDateDateTime → DateTimeString
Included notes	list of ExchangeDocument → IncludedNote objects	Optional. For details, see the Include notes in the e-invoices section below.

Delivery period determination

The delivery period for invoices will be determined automatically based on the projects to which the invoiced tasks belong. The delivery period determination logic will be as follows:

Date determination

Invoices without tasks
The delivery period starts and ends on the date set in the Invoice Date field.
Invoices with tasks
The delivery period is calculated based on the projects associated with the tasks.
For each project, a delivery date is determined as follows:
- Classic projects
  - If the project’s First Delivery Date and Time field is filled out, it will be used as the delivery date.
  - If not, the Project's First Close Date field data will be used as the delivery date.
  - If neither of these dates are set, the project will be skipped.
- Smart projects
  - If any file has already been delivered:
    - The earliest and latest dates from the Last sent to client on field among all delivered files will be used.
  - If no files were delivered:
    - The Project's First Close Date field data will be used.
  - If no files were delivered and the Project’s First Close Date is not set, the project will be skipped.

Final delivery period calculation

After the system determines the delivery dates for all relevant projects, the following will occur:

The earliest of these dates will be set as the start of the delivery period.
The latest of these dates will be set as the end of the delivery period.
If no delivery date was determined for any project, the Invoice Date will be set as the start and end of the delivery period.

XTRF invoice item to Factur-X invoice 'IncludedSupplyChainTradeLineItem' mapping

Data in XTRF	Factur-X invoice field	Comment
Ordinal number of the item	IncludedSupplyChainTradeLineItem → AssociatedDocumentLineDocument → LineID	Items will be numbered from 1 in the same order as displayed in the XTRF' Invoice Items' table.
Item → Name	IncludedSupplyChainTradeLineItem → SpecifiedTradeProduct → Name
Item → Rate	IncludedSupplyChainTradeLineItem → SpecifiedLineTradeAgreement → NetPriceProductTradePrice → ChargeAmount
Item → Quantity	IncludedSupplyChainTradeLineItem → SpecifiedLineTradeDelivery → BilledQuantity
Item → Unit (mapped)	IncludedSupplyChainTradeLineItem → SpecifiedLineTradeDelivery → BilledQuantity → @unitCode	For details, see the Mapping of Unit of Measure Code section below.
Item → Tax Rate (VAT Rate) ID (mapped)	IncludedSupplyChainTradeLineItem → SpecifiedLineTradeSettlement → ApplicableTradeTax → CategoryCode	For details, see the Mapping of Tax Category Code section below.
Item → Tax (VAT) Percentage Rate	IncludedSupplyChainTradeLineItem → SpecifiedLineTradeSettlement → ApplicableTradeTax → RateApplicablePercent

Mapping of the Unit of Measure Code

Please refer to the https://vocabulary.uncefact.org/UnitMeasureCode for more details.

The 'Invoice Item → Unit' value mapping depends on the file named unit-codes-mapping.csv, located in the E-invoicing configuration holder vendor profile > Files & Qualifications tab > Personal Files subtab (for details, see the Configure the e-invoicing service section below).

The unit-codes-mapping.csv must have the following characteristics:

A semicolon character ; used as the column separator.
A header row with column names. Macro will read the file content starting from row 2.
Two columns, as depicted below in the example file content.

unit-codes-mapping.csv file example

Unit name in XTRF	Unit Code
pcs.	H87
source word	D68
Minimum Charge	1I

The macro will compare the Unit set for the invoice item with the mapping file content.

Comparison is case-sensitive. Unit names provided in the mapping file must match XTRF units exactly.

If a unit mapping is present in the file, the macro will use the value from the Unit Code column as the IncludedSupplyChainTradeLineItem → SpecifiedLineTradeDelivery → BilledQuantity → @unitCode in the XML file.

If the invoice item's Unit value is empty, the default Unit of Measure Code D68 – "number of words" will be used.

If the invoice item's Unit does not match any row in the file, the macro will not process the invoice. It will skip such an invoice and add the Factur-X preparation failure category to it. The macro will also return information about an error in the mapping. Before rerunning the macro, ensure that the item's Unit matches the Unit name in XTRF in the unit-codes-mapping.csv file.
If the unit-codes-mapping.csv file is absent or has an invalid data structure (e.g., a wrong column separator), the macro will not process any invoices and will return information about the missing mapping file.

Mapping of the Tax Category Code

Please refer to the https://vocabulary.uncefact.org/TaxCategoryCodeList for more details.

The ‘Tax (VAT) Rate → Tax Category' code mapping depends on the content of the tax-code-mapping.csv file, which is located in the E-invoicing configuration holder vendor profile > Files & Qualifications tab > Personal Files subtab (for details, see the Configure the e-invoicing service section below).

The tax-code-mapping.csv must have the following characteristics:

A semicolon character ; used as the column separator.
A header row with column names. Macro will read the file content starting from row 2.
Two columns, as depicted below in the example file content.

tax-code-mapping.csv file example

XTRF Tax (VAT) rate name	Tax Category Code
0%	E
19%	S
Reduced	R

The macro will compare the invoice item's Tax (VAT) Rate with the mapping file content. The Tax (VAT) Rate will be recognized by its Name.

If a Tax (VAT) Rate mapping is present, the macro will use the value from the Tax Category Code column as the IncludedSupplyChainTradeLineItem → SpecifiedLineTradeSettlement → ApplicableTradeTax → CategoryCode.

If the Tax (VAT) Rate name does not match any row in the file, the macro will not process the invoice. It will skip such an invoice and add the Factur-X preparation failure category to it. The macro will also return information about an error in the mapping.

Before rerunning the macro, ensure that the item's Tax (VAT) Rate name matches the XTRF Tax (VAT) rate name in the tax-code-mapping.csv file.

Configure the e-invoicing service

Prerequisites (by XTRF team)

A macro named 'E-Invoicing (Germany) for XTRF' with the Client Invoice scope was added to your instance.
A dummy vendor was created on your instance, and two exemplary mapping files were added as its personal files.
Two new categories were added to the system: Factur-X invoice ready and Factur-X preparation failure.

Go to the Vendors module and check whether the E-invoicing configuration holder vendor profile is available.
Prepare the mapping files for the macro:
1. Download the exemplary mapping files from the E-invoicing configuration holder vendor profile (vendor profile > Files & Qualifications tab > Personal Files subtab). You can also download these files directly from this guide:
  - .
  - .
2. Adapt the file content to your business requirements (e.g., tax rates). For details on mapping, see the Field mapping sections above.
3. Ensure the mapping files have UTF-8 encoding.

If you have doubts, check UNECE recommendations and standards for tax category codes and unit of measure codes.

Do not change the file names! They must stay the same as the original file names.

Go to the Configuration menu > System Values: Advanced > Categories and check if the Factur-X invoice ready and Factur-X preparation failure categories are available.

Home Portal administrators might restrict access to the Configuration menu. If you cannot access the Categories section, please contact your Home Portal administrator.

In the E-invoicing configuration holder vendor profile, go to the Files & Qualifications tab > Personal Files subtab and upload the adapted mapping files.
Test the macro as described below in the Use the XTRF e-invoicing integration service section. We recommend using a dummy client and test projects for such testing.

(Optional) Include notes in the e-invoices

You can optionally include a list of additional texts in the invoice structure.

To include notes to e-invoices, perform the following steps:

Create the included-notes.csv file with two columns and a header row with column names (for details, see the example below or download the example file: ).
The macro will read the file content starting from row 2.
Enter the required notes in the Included note content column.
In the Subject Code column, assign to each note a subject code listed in the UNECE Text subjects qualifier.
In the E-invoicing configuration holder vendor profile, go to the Files & Qualifications tab > Personal Files subtab and upload the included-notes.csv file.

No InternalNote object will be added to the e-invoice if the included-notes.csv file is missing.
If the included-notes.csv file has an invalid data structure (e.g., a wrong column separator), the macro will not process any invoices and will return information about the invalid file.

The included-notes.csv file must:

use a semicolon character ; as the column separator.
contain the header row with column names.
contain two columns (see the example below).

included-notes.csv file example

Included note content	Subject Code
Description of an alternative payment method	PAI
Free text contains information for regulatory authority.	REG
General information	AAI

Use the XTRF e-invoicing integration service

Invoice template fonts

We recommend using the standard PDF fonts listed below in XTRF invoice templates. Otherwise, Factur-X invoices might not be displayed properly.

Automate e-invoice generation with XTRF e-invoicing integration service