{"id":16416144,"url":"https://github.com/phax/en16931-cii2ubl","last_synced_at":"2025-12-29T15:58:11.245Z","repository":{"id":43050705,"uuid":"167360653","full_name":"phax/en16931-cii2ubl","owner":"phax","description":"Converter for EN16931 invoices from CII to UBL","archived":false,"fork":false,"pushed_at":"2025-06-26T07:43:58.000Z","size":1500,"stargazers_count":34,"open_issues_count":2,"forks_count":10,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-26T08:32:19.095Z","etag":null,"topics":["cii","converter","creditnote","en16931","invoice","java","oasis","ubl"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-01-24T12:00:31.000Z","updated_at":"2025-06-26T08:20:27.000Z","dependencies_parsed_at":"2023-02-08T13:46:47.810Z","dependency_job_id":"c52bed1c-99d0-471d-91af-4402b401a10a","html_url":"https://github.com/phax/en16931-cii2ubl","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/phax/en16931-cii2ubl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phax%2Fen16931-cii2ubl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phax%2Fen16931-cii2ubl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phax%2Fen16931-cii2ubl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phax%2Fen16931-cii2ubl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phax","download_url":"https://codeload.github.com/phax/en16931-cii2ubl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phax%2Fen16931-cii2ubl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265918571,"owners_count":23849185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cii","converter","creditnote","en16931","invoice","java","oasis","ubl"],"created_at":"2024-10-11T07:08:32.669Z","updated_at":"2025-12-29T15:58:11.232Z","avatar_url":"https://github.com/phax.png","language":"Java","funding_links":[],"categories":["Electronic Invoicing","金融"],"sub_categories":["文件同步"],"readme":"# en16931-cii2ubl\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.helger/en16931-cii2ubl/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.helger/en16931-cii2ubl) \n[![javadoc](https://javadoc.io/badge2/com.helger/en16931-cii2ubl/javadoc.svg)](https://javadoc.io/doc/com.helger/en16931-cii2ubl)\n\nUnidirectional converter for EN16931 invoices from CII D16B to UBL 2.1, 2.2, 2.3 or 2.4.\n\nThis 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.\n\nSpecial 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.\n\nSee https://peppol.helger.com/public/locale-en_US/menuitem-tools-rest-api#cii2ubl for a service implementation using this library.\n\nThis library is licensed under the Apache License Version 2.0.\n\nThe binary releases are available on Maven Central at https://repo1.maven.org/maven2/com/helger/en16931-cii2ubl/ and below.\n\n# Usage\n\nThis is a pure Java library and not a self-contained conversion tool.\nYou can convert CII D16B invoices following the EN 16931 rules to different UBL versions.\nThe entrance classes are:\n* Create UBL 2.1: `com.helger.en16931.cii2ubl.CIIToUBL21Converter`\n* Create UBL 2.2: `com.helger.en16931.cii2ubl.CIIToUBL22Converter`\n* Create UBL 2.3: `com.helger.en16931.cii2ubl.CIIToUBL23Converter` (since v1.3.0)\n* Create UBL 2.4: `com.helger.en16931.cii2ubl.CIIToUBL24Converter` (since v2.1.0)\n\nThe main conversion method is called `convertCIItoUBL` and takes either a `File` as input or a pre-parsed `un.unece.uncefact.data.standard.crossindustryinvoice._100.CrossIndustryInvoiceType` object (that reading is done with class `com.helger.cii.d16b.CIID16BCrossIndustryInvoiceTypeMarshaller` from [ph-cii](https://github.com/phax/ph-cii)).\nAdditionally an `ErrorList` object must be provided as a container for all the errors that occur.\n\nThe conversion is deemed successful, if a non-`null` object is returned **and** if the error list contains no error (`errorList.containsNoError ()`).\n\n## Maven usage\n\nReplace `x.y.z` with the effective version you want to use:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.helger\u003c/groupId\u003e\n  \u003cartifactId\u003een16931-cii2ubl\u003c/artifactId\u003e\n  \u003cversion\u003ex.y.z\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Commandline usage\n\nCall it via `java -jar en16931-cii2ubl-cli-full.jar` followed by the options and parameters.\n\n```\n[INFO] CII to UBL Converter v3.0.1 (build 2025-09-19T12:55:25Z)\nUsage: CIItoUBLConverter [-hV] [--disable-wildcard-expansion] [--verbose]\n                         [--mode mode] [--output-suffix filename part] [-t\n                         directory] [--ubl version] [--ubl-cardaccountnetworkid\n                         ID] [--ubl-customizationid ID]\n                         [--ubl-defaultorderrefid ID] [--ubl-profileid ID]\n                         [--ubl-vatscheme vat scheme] source files...\nCII to UBL Converter for EN 16931 invoices\n      source files...      One or more CII file(s)\n      --disable-wildcard-expansion\n                           Disable wildcard expansion of filenames\n  -h, --help               Show this help message and exit.\n      --mode mode          Allowed values: AUTOMATIC, INVOICE, CREDIT_NOTE\n                             (default: 'AUTOMATIC')\n      --output-suffix filename part\n                           The suffix added to the output filename (default:\n                             '-ubl')\n  -t, --target directory   The target directory for result output (default: '.')\n      --ubl version        Version of the target UBL Format: '2.1', '2.2',\n                             '2.3' or '2.4' (default: '2.1')\n      --ubl-cardaccountnetworkid ID\n                           The UBL CardAccount network ID to be used (default:\n                             'mapped-from-cii')\n      --ubl-customizationid ID\n                           The UBL customization ID to be used\n      --ubl-defaultorderrefid ID\n                           The UBL default order reference ID to be used\n                             (default: '')\n      --ubl-profileid ID   The UBL profile ID to be used\n      --ubl-vatscheme vat scheme\n                           The UBL VAT scheme to be used (default: 'VAT')\n  -V, --version            Print version information and exit.\n      --verbose            Enable debug logging (default: 'false')\n```\n\n# Open issues\n\n* The migration of CII `NetPriceProductTradePrice/BasisQuantity` to UBL `Price/BaseQuantity` is not consistent for me\n    * See example files 2, 8 and 9\n    * The UBL example files use a BaseQuanity of 1 in all cases\n\n# News and noteworthy\n\nv3.1.1 - 2025-12-29\n* Fixed invalid mapping to `BillingReference/CreditNoteDocumentReference`. See [issue #43](https://github.com/phax/en16931-cii2ubl/issues/43) - thx @ycheuv-lgtm\n\nv3.1.0 - 2025-11-16\n* Updated to ph-commons 12.1.0\n* Using JSpecify annotations\n\nv3.0.1 - 2025-09-19\n* Added the mapping of BT-86 for DirectDebit case\n\nv3.0.0 - 2025-08-27\n* Requires Java 17 as the minimum version\n* Updated to ph-commons 12.0.0\n\nv2.3.1 - 2025-06-26\n* Avoid `NullPointerException` if a CII line item has no quantity\n\nv2.3.0 - 2025-03-25\n* Removed the default values for BT-24 (`CustomizationID`) and BT-23 (`ProfileID`)\n* Emitting UBL 2.4 documents correctly\n* Taking the values of BT-23 and BT-24 from the source CII fields. See [issue #37](https://github.com/phax/en16931-cii2ubl/issues/37) - thx @shenazz\n* Handling BG-17 only if `PayeePartyCreditorFinancialAccount` is present. See [issue #38](https://github.com/phax/en16931-cii2ubl/issues/38) - thx @msccip\n\nv2.2.6 - 2024-12-23\n* Supporting all values of the UNTDID 4461 code list. See [issue #34](https://github.com/phax/en16931-cii2ubl/pull/34) - thx @shenazz\n\nv2.2.5 - 2024-10-22\n* Fixed the automatic module name. See [issue #32](https://github.com/phax/en16931-cii2ubl/pull/32) - thx @toherrmann\n\nv2.2.4 - 2024-06-17\n* Fixed a regression from v2.2.3. See [issue #31](https://github.com/phax/en16931-cii2ubl/issues/31) - thx @msccip\n\nv2.2.3 - 2024-06-12\n* Added additional mapping of BT-41. See [issue #28](https://github.com/phax/en16931-cii2ubl/issues/28) - thx @bdewein\n* Fixed the mapping of the Due Date Type Code for BT-8. See [issue #29](https://github.com/phax/en16931-cii2ubl/issues/29) - thx @bdewein\n* Fixed the mapping of BT-27 and BT-28. See [issue #26](https://github.com/phax/en16931-cii2ubl/issues/26) - thx @bdewein\n* Fixed the item price mapping around BT-146, BT-147, BT-148, BT-149 and BT-150. See [issue #27](https://github.com/phax/en16931-cii2ubl/issues/27) - thx @bdewein\n\nv2.2.2 - 2024-04-12\n* Added support for providing the default UBL order reference ID, in case the empty String is not good enough. See [issue #23](https://github.com/phax/en16931-cii2ubl/issues/23) - thx @lkumai\n\nv2.2.1 - 2024-03-29\n* Updated to ph-commons 11.1.5\n* Ensured Java 21 compatibility\n\nv2.2.0 - 2024-03-08\n* Updated to ph-ubl 9.0.0\n* Tested output against EN 16931 rules v1.3.10 and v1.3.11 - no changes necessary\n* Updated to create UBL 2.4-CS01\n* Added support for BT-8 mapping. See [issue #22](https://github.com/phax/en16931-cii2ubl/issues/22)\n\nv2.1.0 - 2023-04-28\n* Updated to ph-ubl 8.0.1\n* Added support for converting to UBL 2.4\n\nv2.0.3 - 2023-04-20\n* Improved mapping of references to external documents in additional document references. See [issue #20](https://github.com/phax/en16931-cii2ubl/issues/20) - thanks @msccip\n\nv2.0.2 - 2023-03-30\n* Changed the default mode of the CLI version from `INVOICE` to `AUTOMATIC`. See [issue #19](https://github.com/phax/en16931-cii2ubl/issues/19) - thanks @msccip\n\nv2.0.1 - 2023-03-15\n* Added manual wildcard expansion of filenames\n* Added new CLI option `--disable-wildcard-expansion` to disable the wildcard expansion and stick to the old resolution logic\n\nv2.0.0 - 2023-02-20\n* Using Java 11 as the baseline\n* Updated to ph-commons 11\n* Updated to JAXB 4.0\n* Added the new CLI parameter `--verbose` for a few more details\n* Improved logging\n* Successfully tested the CLI parameter with wildcard parameters (because the Java Windows Runtime performs automatic wildcard expansion)\n\nv1.4.10 - 2022-12-16\n* Fixed the conversion of the `TypeCode` element in `AdditionalReferencedDocument`. See [issue #18](https://github.com/phax/en16931-cii2ubl/issues/18) - thanks @L3Mars\n\nv1.4.9 - 2022-11-15\n* Fixed an unnecessary division by 100 for creating `MultiplierFactorNumeric`. See [issue #17](https://github.com/phax/en16931-cii2ubl/issues/17) - thanks @L3Mars\n* Tested output against EN 16931 rules v1.3.9 - no changes necessary\n\nv1.4.8 - 2022-09-28\n* Added new option `--output-suffix` to customize the output file suffix, that is currently hard coded to `-ubl`\n* Fixed a problem with the mapping of BT-147, BT-148, BT-149 and BT-150. See [issue #15](https://github.com/phax/en16931-cii2ubl/issues/15). Thanks to @cambid for pointing that out\n\nv1.4.7 - 2022-02-15\n* Further improved `null`/empty handling to avoid creation of empty elements\n\nv1.4.6 - 2022-02-12\n* Allowing the additional Payment Means Type Codes `1`, `42` and `68`. See [issue #13](https://github.com/phax/en16931-cii2ubl/issues/13)\n* For decimal values, trailing zeroes are no longer emitted. See [issue #13](https://github.com/phax/en16931-cii2ubl/issues/13)\n* Improved not creating empty UBL elements. See [issue #13](https://github.com/phax/en16931-cii2ubl/issues/13)\n* The `SubjectCode` of `IncludedNote` elements is copied over. See [issue #13](https://github.com/phax/en16931-cii2ubl/issues/13)\n* Improved the Party ID handling and allowing for multiple seller IDs. See [issue #13](https://github.com/phax/en16931-cii2ubl/issues/13)\n\nv1.4.5 - 2021-12-20\n* Tested output against EN 16931 rules v1.3.7 - no changes necessary\n* Fixed creating invalid UBL if `SellerAssignedID` is empty. See [issue #12](https://github.com/phax/en16931-cii2ubl/issues/12) - thanks @DerHamm\n\nv1.4.4 - 2021-10-14\n* Improved sign swapping of Quantity and Price to avoid negative prices (BT-146)\n\nv1.4.3 - 2021-10-07\n* Tested output against EN 16931 rules v1.3.6 - no changes necessary\n* Changed determination if Invoice or CreditNote primarily to `rsm:ExchangedDocument/ram:TypeCode` instead of the payable amount\n\nv1.4.2 - 2021-06-10\n* Changed the default customization ID to `urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0`\n* If the UBL `LineExtensionAmount` is negative, but the line `Quantity` is positive, the `Quantity` will be changed to negative. Customizable via `setSwapQuantitySignIfNeeded(boolean)`\n\nv1.4.1 - 2021-05-02\n* Updated to ph-commons 10.1\n* Tested output against EN 16931 rules v1.3.5 - no changes necessary\n\nv1.4.0 - 2021-03-22\n* Updated to ph-commons 10\n\nv1.3.0 - 2021-01-05\n* Added support for different CII time formats (2, 3, 4, 101, 102, 103 and 105) where `102` is the default\n* The error handling for the commandline client was improved (checking errors before writing UBL) (see [issue #9](https://github.com/phax/en16931-cii2ubl/issues/9))\n* Added the possibility to create UBL 2.3\n* Made the API more open to directly convert to Invoice or CreditNote\n* Improved the handling of payment means to be more EN compliant. See [issue #7](https://github.com/phax/en16931-cii2ubl/issues/7).\n* Added a possibility to retrieve the internal converter version number\n\nv1.2.5 - 2020-11-30\n* Added Jakarta Activation dependency to the standalone CLI version. See [issue #6](https://github.com/phax/en16931-cii2ubl/issues/6).\n\nv1.2.4 - 2020-10-20\n* Tested with EN 16031 validation rules 1.3.3\n* Not emitting the `LegalMonetaryTotal/PayableRoundingAmount` if the value is `0` as a work around for https://github.com/ConnectingEurope/eInvoicing-EN16931/issues/242\n\nv1.2.3 - 2020-09-17\n* Updated to Jakarta JAXB 2.3.3\n\nv1.2.2 - 2020-08-30\n* Updated to ph-commons 9.4.7\n* Updated to ph-cii 2.3.0\n* Updated to ph-ubl 6.4.0\n\nv1.2.1 - 2020-05-26\n* Updated to new Maven groupIds\n\nv1.2.0 - 2020-03-09\n* Verified against EN 16931 validation artefacts 1.3.0 - no changes in the output\n* Added commandline interface (CLI). See [PR #3](https://github.com/phax/en16931-cii2ubl/pull/3). Thanks to @rkottmann\n* Fixed creating invalid UBL if `SellerOrderReferencedDocument` is present but `BuyerOrderReferencedDocument` is not set (see [issue #5](https://github.com/phax/en16931-cii2ubl/issues/5))\n* Made default VAT scheme, UBL `CustomizationID`, UBL `ProfileID` and the `PaymentMeans/CardAccount/NetworkID` customizable. See [issue #1](https://github.com/phax/en16931-cii2ubl/issues/1) and [issue #2](https://github.com/phax/en16931-cii2ubl/issues/2).\n* Fixed embedded attachment mapping. See [issue #4](https://github.com/phax/en16931-cii2ubl/issues/4).\n\nv1.1.5 - 2019-09-13\n* Added possibility to enforce invoice creation\n* Verified against EN 16931 validation artefacts 1.3.0\n\nv1.1.4 - 2019-07-15\n* Updated to EN 16931 validation artefacts 1.2.3\n\nv1.1.3 - 2019-05-15\n* Updated to EN 16931 validation artefacts 1.2.1\n\nv1.1.2 - 2019-04-26\n* Updated to EN 16931 validation artefacts 1.2.0\n\nv1.1.1 - 2019-02-27\n* Improved delivery date handling\n* Improved price base quantity handling\n\nv1.1.0 - 2019-02-26\n* Added support to create UBL 2.1 Invoice and CreditNote\n\nv1.0.0 - 2019-02-26\n* Initial release creating UBL 2.2 Invoice and CreditNote\n\n---\n\nMy personal [Coding Styleguide](https://github.com/phax/meta/blob/master/CodingStyleguide.md) |\nIt is appreciated if you star the GitHub project if you like it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphax%2Fen16931-cii2ubl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphax%2Fen16931-cii2ubl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphax%2Fen16931-cii2ubl/lists"}