Read and write electronic invoices


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.


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 the following repository



as well as the following



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")
    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>";
    System.out.println("Writing ZUGFeRD-PDF");
} catch (IOException e) {


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


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


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


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

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


You can download the official XRechnung validator using something like

mkdir xr
cd xr
mkdir test/instances

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

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 while XRechnung requires .

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


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.


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.


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.

Write a ZUGFeRD-PDF file

  1. Create a new class in the src-folder, e.g. MustangWriter with the usual „Public static void main()“ .
  2. Create a run configuration: Run|Run configurations Java Application, click on the “new” icon.
  3. let the main class implement IZUGFeRDExportableTransaction like this
    public class MustangWriter implements IZUGFeRDExportableTransaction {
  4. Even before that, but after package mustangtest;, add the following classes in in the same file:
    class Contact implements IZUGFeRDExportableContact {}
    class Item implements IZUGFeRDExportableItem {
        private BigDecimal price, quantity;
        private Product product;
    class Product implements IZUGFeRDExportableProduct {
        private String description, name, unit;
        private BigDecimal VATPercent;
    class Payment implements IZUGFeRDTradeSettlementPayment {
  5. add the imports by pressing CTRL+SHIFT+O (Windows) or CMD+SHIFT+O (Mac).
  6. Left click left on the main class MustangWriter and press ALT+SHIFT+S
    (Windows)/ALT+CMD+S (Mac), select “Override/Implement Methods” and press return.
  7. Left click on the class name Contact and press ALT+SHIFT+S
    (Windows)/ALT+CMD+S (Mac), select “Override/Implement Methods” and press return.
  8. Click Item, press ALT+SHIFT+S or ALT+CMD+S, this time select „Generate Getters and Setters“. Mark all members and press return.
  9. Stay on Item, refactor again (ALT+SHIFT+S or ALT+CMD+S) and select „Generate Constructor using Fields“. Choose again all member variables and press return.
  10. Item also needs other methods besides the getter/setters, refactor again (ALT+SHIFT+S or ALT+CMD+S) and choose Override/Implement Methods
  11. „Generate Getters and Setters“ for the class (not the member „Product“: Click Product, (ALT+SHIFT+S or ALT+CMD+S) and select „Generate Getters and Setters“. Choose all members and confirm
  12. Click on Product again, press ALT+SHIFT+S and select „Generate Constructor using Fields“. Choose all members again and press return.
  13. Right-click on Payment, select Source|„Override and Implement Methods“. Choose at least getOwnBIC(), getOwnBankName() and getOwnIBAN().
  14. Your skeleton should now look like this
  15. The following methods of Contact should now return the following strings:
    • getCountry(): “DE”
    • getLocation(): “Spielkreis”
    • getName(): “Theodor Est”
    • getStreet(): “Bahnstr. 42”
    • getVATID(): “DE999999999”
    • getZIP(): “88802”;
  16. The following methods of Payment should return the following strings:
    • getOwnBIC(): “COBADEFFXXX”
    • getOwnBankName(): “Commerzbank”
    • getOwnIBAN(): “DE88200800000970375700”
  17. The following methods of the main class should return the following:
    • getCurrency(): “EUR”
    • getDeliveryDate(): newGregorianCalendar(2017,Calendar.NOVEMBER,17).getTime();
    • Pressing CTRLs+SHIFT+O (Windows) or CMD+SHIFT+O (Mac) will import the
      GregorianCalendar and Calendar class
    • getDueDate(): newGregorianCalendar(2017,Calendar.DECEMBER,9).getTime();
    • getIssueDate(): newGregorianCalendar(2017,Calendar.NOVEMBER,18).getTime();
    • getNumber(): “RE-20171118/506”
    • getOwnBIC(): “COBADEFFXXX”
    • getOwnBankName(): “Commerzbank”
    • getOwnCountry() “DE”
    • getOwnIBAN(): “DE88 2008 0000 0970 3757 00”
    • getOwnLocation() “Stadthausen”
    • getOwnOrganisationFullPlaintextInfo(): “Bei Spiel GmbH\n”+
      “Ecke 12\n”+
      “12345 Stadthausen\n”+
      “Geschäftsführer: Max Mustermann”
    • getOwnOrganisationName(): “Bei Spiel GmbH”
    • getOwnStreet() “Ecke 12”
    • getOwnTaxID(): “22/815/0815/4”
    • getOwnVATID(): “DE136695976”
    • getOwnZIP() “12345”
    • getRecipient(): new Contact();
    • IZUGFeRDTradeSettlementPayment[] getTradeSettlementPayment(): Payment P = new Payment();
      IZUGFeRDTradeSettlementPayment[] allP = new Payment[1];
      allP[0] = P;
      return allP;
  18. getZFItems() of the main class can now create products and return them as a arrays of items:
    Item[] allItems=new Item[3];
    Product designProduct=new Product("", "Künstlerische Gestaltung (Stunde): Einer Beispielrechnung",
    "HUR", new BigDecimal("7.000000"));
    Product balloonProduct=new Product("", "Luftballon: Bunt, ca. 500ml", "C62", new
    Product airProduct=new Product("", "Heiße Luft pro Liter", "LTR", new BigDecimal("19.000000"));
    allItems[0]=new Item(new BigDecimal("160"), new BigDecimal("1"), designProduct);
    allItems[1]=new Item(new BigDecimal("0.79"), new BigDecimal("400"), balloonProduct);
    allItems[2]=new Item(new BigDecimal("0.10"), new BigDecimal("200"), airProduct);
    return allItems;                        
  19. Now create a “private void” method called apply in the MustangWriter class
  20. Please instantiate this main MustangWriter class in the main method and invoke the apply() function.
  21. In the apply-method you can now
    • create a new ZUGFeRDExporterFromA1Factory, run
    • setProducer and setCreator on it (e.g. ZUGFeRDExporter ze=newZUGFeRDExporterFromA1Factory().setProducer("string").setCreator("string")) and get
      the ZUGFeRDExporter from the factories load("./MustangGnuaccountingBeispielRE-20171118_506new.pdf")
    • Feel free to use your own PDF/A-1 invoice file.
    • In this chain (.setProducer.setCreator…) you can also insert setZUGFeRDVersion(2)
    • use the PDFattachZugferdFile-method (with the IZUGFeRDExportableTransation, i.e. „this“ as parameter) on the ZUGFeRDExporter and
    • use export() to save the PDF/A-3 file.
    • Finally, add the imports by pressing CTRL+SHIFT+O (Windows) or CMD+SHIFT+O (Mac).

    The apply-method then looks – with according try/catch-blocks- as follows:

    private void apply() {
        try {
            System.out.println("Reading Blanko-PDF");
            ZUGFeRDExporter ze = new ZUGFeRDExporterFromA1Factory().setProducer("My Application")
            System.out.println("Generating and attaching ZUGFeRD-Data");
            System.out.println("Writing ZUGFeRD-PDF");
        } catch (IOException e) {
  22. „My Application“ and System.getProperty(“”) are stored in the meta data as „Producer“ (producing application) respectively „Creator“ (author). Please adjust accordingly.
  23. Instanciate a MustangWriter in public static void main and call it’s apply() method.
  24. Start it to write the ZUGFeRD invoice to the file specified in export.
  25. To be APL compliant: Adjust the NOTICE-File for and add it to your application.

Your should now look like this.

Project setup without Maven

  1. Download
    1. Mustang
      1. the JAR file
      2. the notice file
  2. In your IDE: Add the downloaded JAR files to your project (right click on project name, Properties) and add as „external Jar“ to the „Build Path“ in the „libraries“ tab.

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")
			System.out.println("Generating and attaching ZUGFeRD-Data");
			System.out.println("Writing 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


RAM:ID suffix:

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