Read and write electronic invoices

License

Mustangproject is licensed under the permissive Apache 2 license and can be used for free in commercial and noncommercial projects.

Source code

The git repository of the Mustangproject source code lives on Github.

Architecture

You can use Mustang from the command line application, or in your java software by referring (via Maven or Gradle) to or downloading the according jars.
You can combine, extract and/or validate PDF+XML. On the command line, to write Factur-X,
you have to provide a PDF/A-1 file and XML, when using in your software and writing Factur-X you (have to provide at least a PDF/A-file and you)
can provide XML on your own as well, or use the invoice classes which use the invoice interfaces, or use the
invoice interfaces directly. Parsing Factur-X is currently only available in “library mode” where you can use the
invoice class reader,
or the basic ZUGFeRDImporter.
Using a different artifact you can also embed the validator in your software.

In the commandline tool you can also get some statistics on directories with Factur-X files,
upgrade ZUGFeRD 1 to 2, migrate from PDF/A-1 to PDF/A-3,
or visualize xml which are details omitted from this diagram:
Mustang architectural diagram

New project

Feel free to use any IDE but for the keyboard shortcuts this example assumes you use Eclipse as IDE.

Start Eclipse, create a new Maven project, e.g. „MustangSample“, as “simple project”, group ID “org.mustangproject”, artifact ID “mustangtest”.

You will need a

  • ZUGFeRD PDF/A-3 sample file for the reader example. Save it in the same directory where your pom.xml file lives.
  • and a PDF/A-1 without ZUGFeRD data for the writer which you can
    • either download
    • or create yourself using Libreoffice on this source: Just say File|Export as PDF, set the checkbox PDF/A-1a in the export options and save the PDF file as MustangGnuaccountingBeispielRE-20190610_507blanko.pdf.
    • Please also save this PDF in the same directory where your pom.xml file resides.

With Maven

Open your pom.xml and add


<dependencies>
    <dependency>
        <groupId>org.mustangproject</groupId>
        <artifactId>library</artifactId>
        <version>2.0.2</version>
    </dependency>
</dependencies>

                        

We will need Maven to download Mustangproject and add it in the Eclipse project properties: In the pom.xml right click and say Run as| Maven build. Specify eclipse:eclipse as goal and run. Right-click on the project and click refresh.

Read ZUGFeRD data

  1. Create a new class in the src/main/java folder, called Reader. Check the “Public static void main()” checkbox.
  2. Create a run configuration: Run|Run configurations Java Application, click on the “new” icon.
  3. Within the main method, enter ZUGFeRDImporter zu=new ZUGFeRDImporter("MustangGnuaccountingBeispielRE-20190610_507.pdf"); and
  4. add the imports by pressing CTRL+SHIFT+O (Windows) or CMD+SHIFT+O (Mac).
  5. you should now be able to access the getter-Methods like getAmount()
  6. There are only getters for few properties but additional ones can be added easily. Which data is available can be seen in the ZUGFeRD invoice.xml file embedded any ZUGFeRD compliant PDF
  7. Complete example
    
    ZUGFeRDImporter zu=new ZUGFeRDImporter("MustangGnuaccountingBeispielRE-20190610_507.pdf"); 
    System.out.println("Total amount: "+zu.getAmount());                                    
    
                                    

Write custom XML

The idea is that Mustangprojects creates the XML for you. However, you can also specify your own XML.

Create a class XMLWriter with a static main method. Use


ZUGFeRDExporter ze;
try {
    System.out.println("Converting to PDF/A-3u");

    /*
    * Add .setZUGFeRDVersion and .setZUGFeRDConformanceLevel
    * in the next lines to set the ZUGFeRD version respective profile of the XML
    * you are inserting.
    */
    ze = new ZUGFeRDExporterFromA1Factory().setProducer("My Application")
    .setCreator(System.getProperty("user.name"))
    .load("./MustangGnuaccountingBeispielRE-20190610_507blanko.pdf");
    System.out.println("Attaching ZUGFeRD-Data");

    /*
    * Mustangproject checks if the input PDF/A file looks halfway valid and the XML
    * data contains „<rsm:CrossIndustry“ which is the case for both ZF1
    * (CrossIndustryDocument) and ZF2 files (CrossIndustryInvoice).
    * Insert your (validated) XML here.
    */
    String ownZUGFeRDXML = "<rsm:CrossIndustryDocument></rsm:CrossIndustryDocument>";
    ze.setZUGFeRDXMLData(ownZUGFeRDXML.getBytes());
    System.out.println("Writing ZUGFeRD-PDF");
    ze.export("./Target.pdf");
} catch (IOException e) {
    e.printStackTrace();
}
        
                

and import classes (CTRL+SHIFT+O on Windows or CMD+SHIFT+O on the Mac).
Create a run configuration: Run|Run configurations Java Application, click on the “new” icon.

Writing EN16931 XML starts with the

Schema

The EN16931 schema file for UN/CEFACT is the “SCRDM uncoupled” from 2016 (“16B”) version
available from https://www.unece.org/cefact/xml_schemas/ .
The schema file which comes with the ZUGFeRD “info packet” should be pretty much equivalent.

CIUS

ZUGFeRD/Factur-X profile-wise you can e.g. just use EN16931, CIUS wise you can use XRechnung as far as possible.

Sample

You might have a look at the XML of the official Mustangproject sample.

The reason why it fails in the XRechnung validator is interesting:

Validators

You can download the official XRechnung validator using something like


mkdir xr
cd xr
wget https://github.com/itplr-kosit/validator/releases/download/v1.0.2/validationtool-1.0.2-full.zip
wget https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/release-2018-12-19/validator-configuration-xrechnung_1.2.0_2018-12-19.zip
unzip validationtool-1.0.2-full.zip
unzip validator-configuration-xrechnung_1.2.0_2018-12-19.zip
mkdir test/instances

then copy your test files into test/instances and you can get your XRechnung report HTMLs into test/reports
using


java -jar validationtool-1.0.2-standalone.jar -s scenarios.xml -o test/reports -h test/instances/*.xml

Now the EN16931 ZF profile requests the RAM:ID element to be exactly
urn:cen.eu:en16931:2017 while XRechnung requires urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_1.2 .

So feel free to add #compliant#urn:xoev-de:kosit:standard:xrechnung_1.2 to the Mustangproject sample in order to have the XRechnung validator pick it up. It should not complain about anything else.

Or remove the fragment from the XRechnung and throw it through the ZUGFeRD Validator.

The output of


wget https://github.com/ZUGFeRD/ZUV/releases/download/v0.8.0/ZUV-0.8.0.jar

java -jar ZUV-0.8.0.jar -x 

should be “valid”.

Please note that the schema file may tell you which elements you can use.
But it may not be sufficient to check your XML, the schematron files
are something completely different: a schematron uses XPath and can compare and calculate.
E.g. a schematron can check if the invoice date is not before the delivery date as required by
the specs or if the total amount matches the sum of the items.
The validators will also run against schematron and you are on the safe side only if both schema and schematron validates.

Rules

If you are in question how many
decimals you may use, or how the calculation works at all, please note that that
is covered in the first part of the standard, EN16931-1.

Codelists

But you might sell articles not by
piece but e.g. in five packs. Or you don’t have a german VAT ID. Or you want to identify
organizations differently, send an invoice to Malaysia etc..

In that case you would need to use different identifying attributes, “codes” in your file.

The CEF has a very handy summary of all “codelists” you can use in EN16931.

Project setup without Maven

  1. Download
    1. Mustang
      1. the JAR file http://mustangproject.org/deploy/library-2.0.2-shaded.jar
      2. the notice file http://mustangproject.org/deploy/NOTICE
  2. In your IDE: Add the downloaded JAR files to your project (right click on project name, Properties) and add http://mustangproject.org/deploy/mustang-2.0.2-shaded.jar as „external Jar“ to the „Build Path“ in the „libraries“ tab.

Write ZUGFeRD PDFs

You can implement own invoices without the need to write XML yourself using ordinary fluent style setter classes or using interfaces.

Supplementary functions

Returns a ZUGFeRDExporter in ZUGFeRD 2 mode
new ZUGFeRDExporterFromA1Factory().setZUGFeRDVersion(2).setZUGFeRDConformanceLevel(ZUGFeRDConformanceLevel.EN16931).load(SOURCE_PDF)
Creates a Factur-X file (same content but different embedded file name)
ZUGFeRDExporter ze = new ZUGFeRDExporterFromA1Factory().setProducer("My Application")
					.setCreator(System.getProperty("user.name"))
					.load("./MustangGnuaccountingBeispielRE-20170509_505blanko.pdf");
			ze.setFacturX();
			System.out.println("Generating and attaching ZUGFeRD-Data");
			ze.PDFattachZugferdFile(this);
			System.out.println("Writing Factur-X-PDF");
			ze.export("./factur-x.pdf");
Returns EN1931 compliant UN/CEFACT XML only from a class implementing the interface. If you specify a buyerReference and a seller contact the only difference to a XRechnung is the missing

#compliant#urn:xoev-de:kosit:standard:xrechnung_1.2

RAM:ID suffix:


ZUGFeRDExporter ze = new ZUGFeRDExporter();                
ze.setZUGFeRDVersion(2);        
ze.getProvider().generateXML(this);        
System.out.println("XML "+new String(ze.getProvider().getXML()));
Sets a attribute in the XML structure used to identify test invoices
ZUGFeRDExporter.setTest()
skips the check of the input file whether it’s valid PDF/A-1
ZUGFeRDExporter.ignoreA1Errors()
Returns PDF Metadata
ZUGFeRDImpoter().getMeta()
Extracts XML from PDF file but also removes a potential UTF8 BOM
ZUGFeRDImpoter().getUTF8()

Embedding the validator

If you use the validator as dependency in your pom.xml


<dependency>
  <groupId>org.mustangproject</groupId>
  <artifactId>validator</artifactId>
  <version>2.0.2</version>
</dependency>

you can still use all Mustang library functions but additionally invoke the validator as follows:


ZUGFeRDValidator zfv=new ZUGFeRDValidator();
System.out.println(zfv.validate("factur-x.pdf"));