Repository files navigation

Converter for unidirectional EN16931 invoices from CII D16B to UBL 2.1, 2.2, 2.3 or 2.4.

This is a Java 11+ library that converts a Cross Industry Invoice (CII) into a Universal Business Language (UBL) document following the rules of the European Norm (EN) 16931 that defines a common semantic data model for electronic invoices in Europe.

Special care was given to XRechnung invoices - all the CII examples of them translate to UBL that is valid according to the EN 16931 validation rules.

Seehttps://peppol.helger.com/public/locale-en_US/menuitem-tools-rest-api#cii2ubl for a service implementation using this library.

This library is licensed under the Apache License Version 2.0.

The binary releases are available on Maven Central athttps://repo1.maven.org/maven2/com/helger/en16931-cii2ubl/ and below.

This is a pure Java library and not a self-contained conversion tool.You can convert CII D16B invoices following the EN 16931 rules to different UBL versions.The entrance classes are:

• Create UBL 2.1:com.helger.en16931.cii2ubl.CIIToUBL21Converter
• Create UBL 2.2:com.helger.en16931.cii2ubl.CIIToUBL22Converter
• Create UBL 2.3:com.helger.en16931.cii2ubl.CIIToUBL23Converter (since v1.3.0)
• Create UBL 2.4:com.helger.en16931.cii2ubl.CIIToUBL24Converter (since v2.1.0)

The main conversion method is calledconvertCIItoUBL and takes either aFile as input or a pre-parsedun.unece.uncefact.data.standard.crossindustryinvoice._100.CrossIndustryInvoiceType object (that reading is done with classcom.helger.cii.d16b.CIID16BCrossIndustryInvoiceTypeMarshaller fromph-cii).Additionally anErrorList object must be provided as a container for all the errors that occur.

The conversion is deemed successful, if a non-null object is returnedand if the error list contains no error (errorList.containsNoError ()).

Replacex.y.z with the effective version you want to use:

<dependency>  <groupId>com.helger</groupId>  <artifactId>en16931-cii2ubl</artifactId>  <version>x.y.z</version></dependency>

Call it viajava -jar en16931-cii2ubl-cli-full.jar followed by the options and parameters.

[INFO] CII to UBL Converter v2.3.0 (build 2025-03-25T07:33:32Z)Missing required parameter: 'source files'Usage: CIItoUBLConverter [-hV] [--disable-wildcard-expansion] [--verbose]                         [--mode mode] [--output-suffix filename part] [-t                         directory] [--ubl version] [--ubl-cardaccountnetworkid                         ID] [--ubl-customizationid ID]                         [--ubl-defaultorderrefid ID] [--ubl-profileid ID]                         [--ubl-vatscheme vat scheme] source files...CII to UBL Converter for EN 16931 invoices      source files...      One or more CII file(s)      --disable-wildcard-expansion                           Disable wildcard expansion of filenames  -h, --help               Show this help message and exit.      --mode mode          Allowed values: AUTOMATIC, INVOICE, CREDIT_NOTE                             (default: 'AUTOMATIC')      --output-suffix filename part                           The suffix added to the output filename (default:                             '-ubl')  -t, --target directory   The target directory for result output (default: '.')      --ubl version        Version of the target UBL Format: '2.1', '2.2',                             '2.3' or '2.4' (default: '2.1')      --ubl-cardaccountnetworkid ID                           The UBL CardAccount network ID to be used (default:                             'mapped-from-cii')      --ubl-customizationid ID                           The UBL customization ID to be used      --ubl-defaultorderrefid ID                           The UBL default order reference ID to be used                             (default: '')      --ubl-profileid ID   The UBL profile ID to be used      --ubl-vatscheme vat scheme                           The UBL VAT scheme to be used (default: 'VAT')  -V, --version            Print version information and exit.      --verbose            Enable debug logging (default: 'false')

• The migration of CIINetPriceProductTradePrice/BasisQuantity to UBLPrice/BaseQuantity is not consistent for me
  • See example files 2, 8 and 9
  • The UBL example files use a BaseQuanity of 1 in all cases

• v2.3.1 - 2025-06-26
  • AvoidNullPointerException if a CII line item has no quantity
• v2.3.0 - 2025-03-25
  • Removed the default values for BT-24 (CustomizationID) and BT-23 (ProfileID)
  • Emitting UBL 2.4 documents correctly
  • Taking the values of BT-23 and BT-24 from the source CII fields. Seeissue #37 - thx @shenazz
  • Handling BG-17 only ifPayeePartyCreditorFinancialAccount is present. Seeissue #38 - thx @msccip
• v2.2.6 - 2024-12-23
  • Supporting all values of the UNTDID 4461 code list. Seeissue #34 - thx @shenazz
• v2.2.5 - 2024-10-22
  • Fixed the automatic module name. Seeissue #32 - thx @toherrmann
• v2.2.4 - 2024-06-17
  • Fixed a regression from v2.2.3. Seeissue #31 - thx @msccip
• v2.2.3 - 2024-06-12
  • Added additional mapping of BT-41. Seeissue #28 - thx @bdewein
  • Fixed the mapping of the Due Date Type Code for BT-8. Seeissue #29 - thx @bdewein
  • Fixed the mapping of BT-27 and BT-28. Seeissue #26 - thx @bdewein
  • Fixed the item price mapping around BT-146, BT-147, BT-148, BT-149 and BT-150. Seeissue #27 - thx @bdewein
• v2.2.2 - 2024-04-12
  • Added support for providing the default UBL order reference ID, in case the empty String is not good enough. Seeissue #23 - thx @lkumai
• v2.2.1 - 2024-03-29
  • Updated to ph-commons 11.1.5
  • Ensured Java 21 compatibility
• v2.2.0 - 2024-03-08
  • Updated to ph-ubl 9.0.0
  • Tested output against EN 16931 rules v1.3.10 and v1.3.11 - no changes necessary
  • Updated to create UBL 2.4-CS01
  • Added support for BT-8 mapping. Seeissue #22
• v2.1.0 - 2023-04-28
  • Updated to ph-ubl 8.0.1
  • Added support for converting to UBL 2.4
• v2.0.3 - 2023-04-20
  • Improved mapping of references to external documents in additional document references. Seeissue #20 - thanks @msccip
• v2.0.2 - 2023-03-30
  • Changed the default mode of the CLI version fromINVOICE toAUTOMATIC. Seeissue #19 - thanks @msccip
• v2.0.1 - 2023-03-15
  • Added manual wildcard expansion of filenames
  • Added new CLI option--disable-wildcard-expansion to disable the wildcard expansion and stick to the old resolution logic
• v2.0.0 - 2023-02-20
  • Using Java 11 as the baseline
  • Updated to ph-commons 11
  • Updated to JAXB 4.0
  • Added the new CLI parameter--verbose for a few more details
  • Improved logging
  • Successfully tested the CLI parameter with wildcard parameters (because the Java Windows Runtime performs automatic wildcard expansion)
• v1.4.10 - 2022-12-16
  • Fixed the conversion of theTypeCode element inAdditionalReferencedDocument. Seeissue #18 - thanks @L3Mars
• v1.4.9 - 2022-11-15
  • Fixed an unnecessary division by 100 for creatingMultiplierFactorNumeric. Seeissue #17 - thanks @L3Mars
  • Tested output against EN 16931 rules v1.3.9 - no changes necessary
• v1.4.8 - 2022-09-28
  • Added new option--output-suffix to customize the output file suffix, that is currently hard coded to-ubl
  • Fixed a problem with the mapping of BT-147, BT-148, BT-149 and BT-150. Seeissue #15. Thanks to @cambid for pointing that out
• v1.4.7 - 2022-02-15
  • Further improvednull/empty handling to avoid creation of empty elements
• v1.4.6 - 2022-02-12
  • Allowing the additional Payment Means Type Codes1,42 and68. Seeissue #13
  • For decimal values, trailing zeroes are no longer emitted. Seeissue #13
  • Improved not creating empty UBL elements. Seeissue #13
  • TheSubjectCode ofIncludedNote elements is copied over. Seeissue #13
  • Improved the Party ID handling and allowing for multiple seller IDs. Seeissue #13
• v1.4.5 - 2021-12-20
  • Tested output against EN 16931 rules v1.3.7 - no changes necessary
  • Fixed creating invalid UBL ifSellerAssignedID is empty. Seeissue #12 - thanks @DerHamm
• v1.4.4 - 2021-10-14
  • Improved sign swapping of Quantity and Price to avoid negative prices (BT-146)
• v1.4.3 - 2021-10-07
  • Tested output against EN 16931 rules v1.3.6 - no changes necessary
  • Changed determination if Invoice or CreditNote primarily torsm:ExchangedDocument/ram:TypeCode instead of the payable amount
• v1.4.2 - 2021-06-10
  • Changed the default customization ID tourn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0
  • If the UBLLineExtensionAmount is negative, but the lineQuantity is positive, theQuantity will be changed to negative. Customizable viasetSwapQuantitySignIfNeeded(boolean)
• v1.4.1 - 2021-05-02
  • Updated to ph-commons 10.1
  • Tested output against EN 16931 rules v1.3.5 - no changes necessary
• v1.4.0 - 2021-03-22
  • Updated to ph-commons 10
• v1.3.0 - 2021-01-05
  • Added support for different CII time formats (2, 3, 4, 101, 102, 103 and 105) where102 is the default
  • The error handling for the commandline client was improved (checking errors before writing UBL) (seeissue #9)
  • Added the possibility to create UBL 2.3
  • Made the API more open to directly convert to Invoice or CreditNote
  • Improved the handling of payment means to be more EN compliant. Seeissue #7.
  • Added a possibility to retrieve the internal converter version number
• v1.2.5 - 2020-11-30
  • Added Jakarta Activation dependency to the standalone CLI version. Seeissue #6.
• v1.2.4 - 2020-10-20
  • Tested with EN 16031 validation rules 1.3.3
  • Not emitting theLegalMonetaryTotal/PayableRoundingAmount if the value is0 as a work around forConnectingEurope/eInvoicing-EN16931#242
• v1.2.3 - 2020-09-17
  • Updated to Jakarta JAXB 2.3.3
• v1.2.2 - 2020-08-30
  • Updated to ph-commons 9.4.7
  • Updated to ph-cii 2.3.0
  • Updated to ph-ubl 6.4.0
• v1.2.1 - 2020-05-26
  • Updated to new Maven groupIds
• v1.2.0 - 2020-03-09
  • Verified against EN 16931 validation artefacts 1.3.0 - no changes in the output
  • Added commandline interface (CLI). SeePR #3. Thanks to @rkottmann
  • Fixed creating invalid UBL ifSellerOrderReferencedDocument is present butBuyerOrderReferencedDocument is not set (seeissue #5)
  • Made default VAT scheme, UBLCustomizationID, UBLProfileID and thePaymentMeans/CardAccount/NetworkID customizable. Seeissue #1 andissue #2.
  • Fixed embedded attachment mapping. Seeissue #4.
• v1.1.5 - 2019-09-13
  • Added possibility to enforce invoice creation
  • Verified against EN 16931 validation artefacts 1.3.0
• v1.1.4 - 2019-07-15
  • Updated to EN 16931 validation artefacts 1.2.3
• v1.1.3 - 2019-05-15
  • Updated to EN 16931 validation artefacts 1.2.1
• v1.1.2 - 2019-04-26
  • Updated to EN 16931 validation artefacts 1.2.0
• v1.1.1 - 2019-02-27
  • Improved delivery date handling
  • Improved price base quantity handling
• v1.1.0 - 2019-02-26
  • Added support to create UBL 2.1 Invoice and CreditNote
• v1.0.0 - 2019-02-26
  • Initial release creating UBL 2.2 Invoice and CreditNote

My personalCoding Styleguide |It is appreciated if you star the GitHub project if you like it.