mustangproject

ZUV (ZUgferd+[VeraPDF]) is an open-source e-invoice validator for the ZUGFeRD and Factur-X standards. It performs two main types of checks:

1. PDF/A-3 Compliance: Uses VeraPDF to ensure the PDF container meets requirements.
2. XML Correctness: Validates ZUGFeRD version 1 and version 2/2.1 XMLs against official ZUGFeRD schematron files and the EN16931 UN/CEFACT SCRDM v16B uncoupled schematron from CEN.

ZUV outputs its results in an XML format. The structure contains <pdf>, <xml>, and a top-level <summary> tag.

• Valid files: The <summary status="..."> tags for pdf, xml, and the root element will all be valid.
• Invalid files: The <summary> tags will indicate invalid, and the <xml> section will contain a <messages> block detailing the specific errors. Each error includes a type, location (XPath), and a criterion explaining why the rule failed.

Use ZUGFeRDInvoiceImporter to extract invoice metadata from a PDF file into a CalculatedInvoice object. This allows you to programmatically access invoice details such as the amount due payable.

Note that extractInto may throw XPathExpressionException or ParseException.

ZUGFeRDInvoiceImporter zii = new ZUGFeRDInvoiceImporter("path/to/invoice.pdf");
CalculatedInvoice ci = new CalculatedInvoice();
try {
    zii.extractInto(ci);
    System.out.println("Pay: " + ci.getDuePayable());
} catch (XPathExpressionException | ParseException e) {
    throw new RuntimeException(e);
}

If you are working on the validator and need to generate XSLT files from new Schematron files, use the generateXSLTFromSchematron Maven profile. Note that this process can take approximately 20 minutes.

./mvnw clean package -P generateXSLTFromSchematron

If you have added new functionality and want to test it in a separate project before a formal release, you can install a specific JAR (e.g., a shaded validator JAR) into your local Maven cache.

For Maven projects:

cd validator/target
./mvnw 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

For Gradle projects: Use the files dependency syntax:

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

To use Mustangproject in a Maven project, add the following repository and dependency to your pom.xml. It is also recommended to include commons-logging and jaxb-impl for full compatibility.

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

<dependencies>
  <dependency>
    <groupId>org.mustangproject.ZUGFeRD</groupId>
    <artifactId>mustang</artifactId>
    <version>1.5.1</version>
  </dependency>
  <dependency>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
    <version>1.1.1</version>
  </dependency>
  <dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-impl</artifactId>
    <version>2.2.5</version>
  </dependency>
</dependencies>

To check a file for ZUGFeRD conformance, use the java -jar command with the --action validate flag.

You can provide either:

• A complete PDF file: The validator will check both the XML content and the PDF/A compliance.
• An XML file: The validator will only check the XML correctness.

java -jar ZUV-0.9.0.jar --action validate -f <filename of ZUGFeRD PDF.pdf>

You can integrate ZUV into your software by either embedding it as a Java library or by executing the JAR via a system call and parsing the XML output.

When using exec to run the JAR, it is recommended to:

1. Use -Dfile.encoding=UTF-8 to ensure XML files with BOM are handled correctly.
2. Redirect stderr to /dev/null to prevent logging messages from corrupting the XML output.
3. Escape filenames to handle spaces and security concerns.

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

To use Mustangproject in your Java application, add the validator artifact to your pom.xml. It is recommended to use the shaded classifier to ensure all necessary dependencies are bundled within the artifact.

Note: Ensure you check the latest version available, as the example below uses 2.25.0.

<dependency>
    <groupId>org.mustangproject</groupId>
    <artifactId>validator</artifactId>
    <version>2.25.0</version>
    <classifier>shaded</classifier>
</dependency>