Mustangproject

https://github.com/zugferd/mustangproject
Admin
Open Source Java e-Invoicing library, validator and tool (Factur-X/ZUGFeRD, UNCEFACT/CII XRechnung)
Tokens:30,873
Snippets:272
Trust Score:7.1
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Complete Maven settings.xml example

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

This is an example of a complete settings.xml file, including servers, profiles, and other Maven settings. It includes placeholders for tokens and passwords.

```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                          https://maven.apache.org/xsd/settings-1.0.0.xsd">
      <localRepository/>
      <interactiveMode/>
      <usePluginRegistry/>
      <offline/>
      <pluginGroups/>
      <servers>
    <server> 
      <id>ossrh</id> 
      <username>SONATYPE TOKEN USER</username> 
      <password>SONATYPE TOKEN PASSWORD</password> 
    </server> 

      </servers>
      <mirrors/>
      <proxies/>
      <profiles>
        <profile>
          <id>ossrh</id>
          <activation>
            <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
            <gpg.passphrase>PASSPHRASE</gpg.passphrase>
          </properties>
        </profile>
      </profiles>
      <activeProfiles/>
</settings>
```

--------------------------------

### Build the project with Maven

Source: https://github.com/zugferd/mustangproject/blob/master/README.md

Run this command to build the project, run tests, and install artifacts to the local Maven cache. Requires OpenJDK 21.0.2 and Apache Maven 3.9.6.

```shell
mvn clean install
```

--------------------------------

### Tab container setup and show function

Source: https://github.com/zugferd/mustangproject/blob/master/library/src/test/resources/factur-x-vis-ubl-creditnote.en.html

Builds a tab container with five tabs (uebersicht, details, zusaetze, anlagen, laufzettel) and their corresponding menu buttons. The show function toggles visibility and button classes, and on load the first tab is set active.

```javascript
// /* Tab-Container aufbauen ******************************************************/
var a = new Array("uebersicht", "details", "zusaetze", "anlagen", "laufzettel");
var b = new Array("menueUebersicht", "menueDetails", "menueZusaetze", "menueAnlagen", "menueLaufzettel");
function show(e) {
  var i = 0;
  var j = 1;
  for (var t = 0; t < b.length; t++) {
    if (b[t] === e.id) {
      i = t;
      if (i > 0) {
        j = 0;
      } else {
        j = i + 1;
      }
      break;
    }
  }
  e.setAttribute("class", "btnAktiv");
  for (var k = 0; k < b.length; k++) {
    if (k === i && (document.getElementById(a[k]) != null)) {
      document.getElementById(a[k]).style.display = "block";
      if (i === j) j = i + 1;
    } else {
      if (document.getElementById(a[k]) != null) {
        document.getElementById(a[j]).style.display = "none";
        document.getElementById(b[j]).setAttribute("class", "btnInaktiv");
        j += 1;
      }
    }
  }
}
window.onload = function () {
  document.getElementById(b[0]).setAttribute("class", "btnAktiv");
}
```

--------------------------------

### Complete Java example for creating an e-invoice

Source: https://github.com/zugferd/mustangproject/blob/master/Release_Notes.md

This example shows how to create an Invoice object with organisation, recipient, and item details, then export it to a PDF using ZUGFeRDExporterFromA1 with ZUGFeRD version 2 and the EN16931 profile. It requires the imports listed and handles exceptions by printing the stack trace.

```java
import org.mustangproject.Contact;
import org.mustangproject.Invoice;
import org.mustangproject.Item;
import org.mustangproject.Product;
import org.mustangproject.ZUGFeRD.IZUGFeRDExporter;
import org.mustangproject.ZUGFeRD.Profiles;
import org.mustangproject.ZUGFeRD.ZUGFeRDExporterFromA1;
import java.math.BigDecimal;
import java.util.Date;

public class Main {
    public static void main(String[] args) {
    Invoice i = new Invoice().setDueDate(new Date()).setIssueDate(new Date()).setDeliveryDate(new Date()).setOwnOrganisationName("My company").setOwnStreet("teststr").setOwnZIP("12345").setOwnLocation("teststadt").setOwnCountry("DE").setOwnTaxID("4711").setOwnVATID("0815").setRecipient(new Contact("Franz Müller", "0177123456", "fmueller@test.com", "teststr.12", "55232", "Entenhausen", "DE")).setNumber("INV/123").addItem(new Item(new Product("Testprodukt", "", "C62", new BigDecimal(0)), new BigDecimal(1.0), new BigDecimal(1.0)));
        try {
            IZUGFeRDExporter ie = new ZUGFeRDExporterFromA1().load("source.pdf").setZUGFeRDVersion(2).setProfile(Profiles.EN16931);
            ie.setProfile(Profiles.EN16931).setTransaction(i).export("target.pdf");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Install local validator jar with mvn install:install-file

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Use this command to install the locally built validator jar into the local Maven cache so it is picked instead of a not-yet-released version. Run from the validator/target directory. The command uses the shaded classifier and version 2.17.0-SNAPSHOT.

```bash
cd validator/target
mvn install:install-file -Dfile="validator-2.17.0-SNAPSHOT-shaded.jar" -Dclassifier=shaded -DgroupId="org.mustangproject" -DartifactId=validator -Dversion="2.17.0" -Dpackaging=jar -DgeneratePom=true
```

--------------------------------

### Maven setup for Mustangproject

Source: https://github.com/zugferd/mustangproject/blob/master/doc/ZugferdDev.en.pdf

Maven configuration for using Mustangproject 1.5.1. Add the repository and the mustang dependency, plus optional dependencies for Apache Commons Logging and JAXB.

```xml
<repositories>
  <repository>
    <id>mustang-mvn-repo</id>
    <url>https://raw.github.com/ZUGFeRD/mustangproject/mvn-repo/</url>
  </repository>
</repositories>
```

```xml
<dependency>
  <groupId>org.mustangproject.ZUGFeRD</groupId>
  <artifactId>mustang</artifactId>
  <version>1.5.1</version>
</dependency>
```

```xml
<dependency>
  <groupId>commons-logging</groupId>
  <artifactId>commons-logging</artifactId>
  <version>1.1.1</version>
</dependency>
```

```xml
<dependency>
  <groupId>com.sun.xml.bind</groupId>
  <artifactId>jaxb-impl</artifactId>
  <version>2.2.5</version>
</dependency>
```

--------------------------------

### Create ZUGFeRD PDF with Mustangproject

Source: https://github.com/zugferd/mustangproject/blob/master/doc/ZugferdDev.en.adoc

Complete example of creating a ZUGFeRD/Factur-X PDF using Mustangproject. It loads a source PDF, sets producer and creator, builds an Invoice with sender, recipient, bank details, tax IDs, and an item, then exports to 'factur-x.pdf'. The TransactionCalculator is used to print the due payable amount for verification.

```java
package de.usegroup;

import org.mustangproject.*;
import org.mustangproject.ZUGFeRD.IZUGFeRDExporter;
import org.mustangproject.ZUGFeRD.TransactionCalculator;
import org.mustangproject.ZUGFeRD.ZUGFeRDExporterFromPDFA;
import java.io.IOException;
import java.math.BigDecimal;
import java.util.Date;

public class Main {
    public static void main(String[] args) {

        String sourcePDF="MustangGnuaccountingBeispielRE-20201121_508.pdf";
        try {
            IZUGFeRDExporter ze = new ZUGFeRDExporterFromPDFA().load(sourcePDF).setProducer("My Application").
                    setCreator(System.getProperty("user.name"));

            Invoice i=new Invoice().setDueDate(new Date()).setIssueDate(new Date()).setDeliveryDate(new Date())
                    .setSender(new TradeParty("ACME co", "teststr", "55232", "teststadt", "DE")
                            .addBankDetails(new BankDetails("777666555", "DE4321"))).setOwnTaxID("4711").setOwnVATID("DE19990815")
                    .setRecipient(new TradeParty("Franz Müller", "teststr.12", "55232", "Entenhausen", "DE")
                            .setContact(new Contact("nameRep", "phoneRep", "emailRep@test.com"))).setNumber("X12")
                    .addItem(new Item(new Product("Testproduct", "", "H87", new BigDecimal(19)),
                            new BigDecimal(2.5), new BigDecimal(1.0)));
            ze.setTransaction(i);
            ze.export("factur-x.pdf");
            TransactionCalculator tc=new TransactionCalculator(i);
            System.out.println("Confirm "+tc.getDuePayable()+ " is also the final amount in your PDF");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Build with Maven (mvn clean package)

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Use this command to build the project. It compiles the code and packages it. The target platform is Java 11.

```bash
mvn clean package
```

--------------------------------

### Build ZUV with Maven Wrapper

Source: https://github.com/zugferd/mustangproject/blob/master/validator/README.md

Compile the ZUV jar using the Maven wrapper in the pom.xml directory.

```bash
./mvnw clean package
```

--------------------------------

### Use local validator jar as Gradle dependency

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Use this Gradle dependency declaration to reference the locally installed validator jar in a Gradle project. The file path points to the jar in the libs directory.

```gradle
implementation files('libs/validator-2.17.0-shaded.jar')
```

--------------------------------

### Maven release commands

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Run these Maven commands in order to clean, verify javadoc, and perform a release. The release:prepare command will prompt for version numbers. The release:perform command creates the release and updates the Maven repository.

```bash
mvn clean install
```

```bash
mvn javadoc:javadoc
```

```bash
mvn release:clean
```

```bash
mvn release:prepare
```

```bash
mvn release:perform
```

--------------------------------

### Validation output XML for Factur-X extended invoice

Source: https://github.com/zugferd/mustangproject/blob/master/validator/README.md

Example output of a validation run for a Factur-X extended invoice. Shows a compliant PDF/A-3B report and an invalid XML report with one failed rule (BT-72/BG-14 missing for intra-community supply).

```xml
<?xml version="1.0" encoding="UTF-8"?>

<validation filename="Facture_UE_EXTENDED.pdf" datetime="2020-03-23 12:34:43">
  <pdf> 
    <report> 
      <buildInformation> 
        <releaseDetails id="core" version="1.12.1" buildDate="2018-05-08T18:57:00+02:00"/>  
        <releaseDetails id="validation-model" version="1.12.1" buildDate="2018-05-08T20:39:00+02:00"/> 
      </buildInformation>  
      <jobs> 
        <job> 
          <item size="109172"> 
            <name>/Users/jstaerk/workspace/zugferd/helper_files/../foreign_samples/fx/Facture_UE_EXTENDED.pdf</name> 
          </item>  
          <validationReport profileName="PDF/A-3B validation profile" statement="PDF file is compliant with Validation Profile requirements." isCompliant="true"> 
            <details passedRules="123" failedRules="0" passedChecks="11082" failedChecks="0"/> 
          </validationReport>  
          <duration start="1584963283448" finish="1584963284790">00:00:01.342</duration> 
        </job> 
      </jobs>  
      <batchSummary totalJobs="1" failedToParse="0" encrypted="0"> 
        <validationReports compliant="1" nonCompliant="0" failedJobs="0">1</validationReports>  
        <featureReports failedJobs="0">0</featureReports>  
        <repairReports failedJobs="0">0</repairReports>  
        <duration start="1584963283223" finish="1584963284825">00:00:01.602</duration> 
      </batchSummary> 
    </report>  
    <info>
      <signature>Factur/X Python</signature>
      <duration unit="ms">2296</duration>
    </info>
    <summary status="valid"/>
  </pdf>  
  <xml>
    <info>
      <version>2</version>
      <profile>urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended</profile>
      <validator version="0.8.4-RESTRICTED"/>
      <rules>
        <fired>97</fired>
        <failed>1</failed>
      </rules>
      <duration unit="ms">8546</duration>
    </info>
    <messages>
      <error type="4" location="/*[local-name()='CrossIndustryInvoice' and namespace-uri()='urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100']/*[local-name()='SupplyChainTradeTransaction' and namespace-uri()='urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100']/*[local-name()='ApplicableHeaderTradeSettlement' and namespace-uri()='urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100']/*[local-name()='ApplicableTradeTax' and namespace-uri()='urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100']/*[local-name()='CategoryCode' and namespace-uri()='urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100']" criterion="(/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeDelivery/ram:ActualDeliverySupplyChainEvent/ram:OccurrenceDateTime/udt:DateTimeString) or (../../ram:BillingSpecifiedPeriod/ram:StartDateTime) or (../../ram:BillingSpecifiedPeriod/ram:EndDateTime)">In an Invoice with a VAT breakdown (BG-23) where the VAT category code (BT-118) is "Intra-community supply" the Actual delivery date (BT-72) or the Invoicing period (BG-14) shall not be blank.</error> 
    </messages>
    <summary status="invalid"/>
  </xml>
  <messages></messages>
  <summary status="invalid"/>
</validation>
```

--------------------------------

### Using nodeMap.getAsString and getAsNodeMap

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Shows how to extract string values and nested node maps from a node map. Demonstrates handling optional attributes and building a map of product characteristics and classifications.

```java
nodeMap.getAsString("SellerAssignedID").ifPresent(this::setSellerAssignedID);
		nodeMap.getAsString("BuyerAssignedID").ifPresent(this::setBuyerAssignedID);
		nodeMap.getAsString("Name").ifPresent(this::setName);
		nodeMap.getAsString("Description").ifPresent(this::setDescription);

		nodeMap.getAsNodeMap("ApplicableProductCharacteristic").ifPresent(apcNodes -> {
			String key = apcNodes.getAsStringOrNull("Description");
			String value = apcNodes.getAsStringOrNull("Value");
			if (key != null && value != null) {
				if (attributes == null) {
					attributes = new HashMap<>();
				}
				attributes.put(key, value);
			}
		});

		nodeMap.getAsNodeMap("DesignatedProductClassification").ifPresent(dpcNodes -> {
			String className = dpcNodes.getAsStringOrNull("ClassName");
			dpcNodes.getNode("ClassCode").map(ClassCode::fromNode).ifPresent(classCode ->
				classifications.add(new DesignatedProductClassification(classCode, className)));
		});

		nodeMap.getAsString("OriginTradeCounty").ifPresent(this::setCountryOfOrigin);
```

--------------------------------

### Build with XSLT generation (mvn clean package -P generateXSLTFromSchematron)

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Use this command to also generate XSLT files from new schematron files for the validator. This profile takes around 20 minutes on a typical machine.

```bash
mvn clean package -P generateXSLTFromSchematron
```

--------------------------------

### Valid validation output XML

Source: https://github.com/zugferd/mustangproject/blob/master/validator/README.md

Example of a valid validation output XML file. It shows the structure with pdf and xml sections, including validation reports, batch summary, and status summaries. The file is compliant with the PDF/A-3B validation profile.

```xml
<?xml version="1.0" encoding="UTF-8"?>

<validation filename="Facture_UE_MINIMUM.pdf" datetime="2020-03-23 12:34:54">
  <pdf> 
    <report> 
      <buildInformation> 
        <releaseDetails id="core" version="1.12.1" buildDate="2018-05-08T18:57:00+02:00"/>  
        <releaseDetails id="validation-model" version="1.12.1" buildDate="2018-05-08T20:39:00+02:00"/> 
      </buildInformation>  
      <jobs> 
        <job> 
          <item size="101181"> 
            <name>/Users/jstaerk/workspace/zugferd/helper_files/../foreign_samples/fx/Facture_UE_MINIMUM.pdf</name> 
          </item>  
          <validationReport profileName="PDF/A-3B validation profile" statement="PDF file is compliant with Validation Profile requirements." isCompliant="true"> 
            <details passedRules="123" failedRules="0" passedChecks="11082" failedChecks="0"/> 
          </validationReport>  
          <duration start="1584963295227" finish="1584963296646">00:00:01.419</duration> 
        </job> 
      </jobs>  
      <batchSummary totalJobs="1" failedToParse="0" encrypted="0"> 
        <validationReports compliant="1" nonCompliant="0" failedJobs="0">1</validationReports>  
        <featureReports failedJobs="0">0</featureReports>  
        <repairReports failedJobs="0">0</repairReports>  
        <duration start="1584963294997" finish="1584963296679">00:00:01.682</duration> 
      </batchSummary> 
    </report>  
    <info>
      <signature>Factur/X Python</signature>
      <duration unit="ms">2361</duration>
    </info>
    <summary status="valid"/>
  </pdf>  
  <xml>
    <info>
      <version>2</version>
      <profile>urn:factur-x.eu:1p0:minimum</profile>
      <validator version="0.8.4-RESTRICTED"/>
      <rules>
        <fired>26</fired>
        <failed>0</failed>
      </rules>
      <duration unit="ms">2772</duration>
    </info>
    <summary status="valid"/>
  </xml>
  <summary status="valid"/>
</validation>
```

--------------------------------

### Using ZUGFeRDInvoiceImporter to extract and verify invoice data

Source: https://github.com/zugferd/mustangproject/blob/master/Release_Notes.md

The new ZUGFeRDInvoiceImporter extracts an Invoice object from a PDF. The example shows how to handle exceptions and includes assertions that verify the extracted data, such as organisation name, item quantities, prices, product details, invoice number, dates, recipient address, and total gross amount.

```java
ZUGFeRDInvoiceImporter zii=new ZUGFeRDInvoiceImporter(TARGET_PDF);

Invoice invoice=null;
try {
    invoice=zii.extractInvoice();
} catch (XPathExpressionException | ParseException e) {
// handle Exceptions
}
assertFalse(hasExceptions);
// Reading ZUGFeRD
assertEquals("Bei Spiel GmbH", invoice.getOwnOrganisationName());
assertEquals(3, invoice.getZFItems().length);
assertEquals("400.0000", invoice.getZFItems()[1].getQuantity().toString());

assertEquals("160.0000", invoice.getZFItems()[0].getPrice().toString());
assertEquals("Heiße Luft pro Liter", invoice.getZFItems()[2].getProduct().getName());
assertEquals("LTR", invoice.getZFItems()[2].getProduct().getUnit());
assertEquals("7.00", invoice.getZFItems()[0].getProduct().getVATPercent().toString());
assertEquals("RE-20170509/505", invoice.getNumber());

SimpleDateFormat sdf=new SimpleDateFormat("yyyy-MM-dd");
assertEquals("2017-05-09",sdf.format(invoice.getIssueDate()));

assertEquals("Bahnstr. 42", invoice.getRecipient().getStreet());
assertEquals("88802", invoice.getRecipient().getZIP());
assertEquals("DE", invoice.getRecipient().getCountry());
assertEquals("Spielkreis", invoice.getRecipient().getLocation());

TransactionCalculator tc=new TransactionCalculator(invoice);
assertEquals(new BigDecimal("571.04"),tc.getTotalGross());
```

--------------------------------

### Create EN16931 Schematron

Source: https://github.com/zugferd/mustangproject/blob/master/validator/README.md

Clones the eInvoicing-EN16931 repository and builds the schematron using Maven.

```bash
git clone https://github.com/ConnectingEurope/eInvoicing-EN16931.git 
mvn -f pom-xslt.xml package
```

--------------------------------

### Initial Java main class

Source: https://github.com/zugferd/mustangproject/blob/master/doc/ZugferdDev.en.adoc

A minimal Java class with a main method that prints "Hello, World!". This is the initial code in the Maven project before adding the ZUGFeRD reading code.

```java
public class Main {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```

--------------------------------

### Maven settings.xml servers section

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Add this servers section to Maven's settings.xml (e.g., ~/.m2/settings.xml on Linux/MacOS) to configure credentials for GitHub and OSSRH repositories. The GitHub token is used as the password.

```xml
   <servers> 
    <server> 
      <id>github</id> 
      <password>GITHUB-TOKEN</password> 
    </server> 
    <server> 
      <id>ossrh</id> 
      <username>jstaerk</username> 
      <password>JIRA-PASSWORD</password> 
    </server> 
   </servers> 
```

--------------------------------

### Show Mustang CLI help

Source: https://github.com/zugferd/mustangproject/blob/master/Release_Notes.md

Outputs the parameters which can be used for non-interactive (i.e., batch) processing.

```bash
java -jar Mustang-CLI-2.14.0.jar --help
```

--------------------------------

### Execute ZUV validator from PHP with exec()

Source: https://github.com/zugferd/mustangproject/blob/master/validator/README.md

Shows a PHP exec() call to run the ZUV jar with UTF-8 encoding and validation action. Redirect stderr to /dev/null to avoid XML well-formedness issues, escape file names, and set UTF-8 because exec loses environment variables.

```php
exec('java -Dfile.encoding=UTF-8 -jar /path/to/ZUV-0.9.0.jar --action validate -f '.escapeshellarg($uploadfile).' 2>/dev/null', $output);
```

--------------------------------

### Write ZUGFeRD PDF with ZUGFeRDExporterFromPDFA

Source: https://github.com/zugferd/mustangproject/blob/master/doc/ZugferdDev.en.adoc

Creates a ZUGFeRD PDF by loading a PDF/A source, setting producer and creator, building an Invoice with sender, recipient, and item details, then exporting to factur-x.pdf. Requires a PDF/A file as sourcePDF.

```java
            IZUGFeRDExporter ze = new ZUGFeRDExporterFromPDFA().load(sourcePDF).setProducer("My Application").
                    setCreator(System.getProperty("user.name"));

            Invoice i=new Invoice().setDueDate(new Date()).setIssueDate(new Date()).setDeliveryDate(new Date())
                    .setSender(new TradeParty("ACME co", "teststr", "55232", "teststadt", "DE")
                            .addBankDetails(new BankDetails("777666555", "DE4321"))).setOwnTaxID("4711").setOwnVATID("DE19990815")
                    .setRecipient(new TradeParty("Franz Müller", "teststr.12", "55232", "Entenhausen", "DE")
                            .setContact(new Contact("nameRep", "phoneRep", "emailRep@test.com"))).setNumber("X12")
                    .addItem(new Item(new Product("Testproduct", "", "H87", new BigDecimal(19)),
                            new BigDecimal(2.5), new BigDecimal(1.0)));
            ze.setTransaction(i);
            ze.export("factur-x.pdf");
```

--------------------------------

### Combine XML into PDF using Mustang CLI

Source: https://github.com/zugferd/mustangproject/blob/master/Release_Notes.md

Embeds an XML into a PDF (A-1) file and exports as PDF/A-3.

```bash
java -jar Mustang-CLI-2.14.0.jar --action=combine
```

--------------------------------

### Maven settings.xml profiles section

Source: https://github.com/zugferd/mustangproject/blob/master/doc/development_documentation.md

Add this profiles section to settings.xml to enable the OSSRH profile by default and set the GPG passphrase for signing artifacts.

```xml
  <profiles>
    <profile>
      <id>ossrh</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <gpg.passphrase>PASSPHRASE</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
```
Tokens:
Raw