Docentric e-Invoice Validator

A REST API and web-based validation tool for ZuGFeRD and Factur-X e-invoices, built with ASP.NET Core and React.

Overview

This project provides a simple, user-friendly interface for validating ZuGFeRD and Factur-X e-invoices (both PDF and XML formats). It wraps the Mustang Project validation engine in a modern web application with both API and UI access.

Purpose: This tool is primarily used for unit testing and quality assurance in the development of Docentric AX, our document generation and distribution solution. It helps ensure that e-invoices generated by Docentric AX comply with ZuGFeRD and Factur-X standards.

Features

• Web UI: Modern React-based interface for uploading and validating invoices
• REST API: Programmatic access for automated testing and integration
• Multiple Formats: Supports PDF (hybrid) and XML (Factur-X, UBL) e-invoice formats
• Extraction and Conversion: Extracts embedded XML from PDF and converts XML to PDF
• Standards Compliance: Validates ZuGFeRD, Factur-X and UBL invoices using Mustang Project CLI 2.26.0
• Docker Ready: Pre-built Docker images available on Docker Hub
• CI/CD: Automated builds and testing with GitHub Actions

Technology Stack

• Backend: ASP.NET Core 10 (minimal API)
• Frontend: React + Vite + TypeScript
• UI Components: shadcn/ui with Tailwind CSS
• Validation Engine: Mustang Project CLI 2.26.0 (Java-based)
• Runtime: .NET 10 + OpenJDK 17

Quick Start

Using Docker (Recommended)

The easiest way to run the validator is using Docker:

docker pull docentric/e-invoice-validator:latest
docker run -p 18889:8080 docentric/e-invoice-validator:latest

Then open your browser to http://localhost:18889

Running on a random host port

Docker publishes no host port unless you ask for one, so docker run docentric/e-invoice-validator:latest starts the service (listening on port 8080 inside the container) but it is not reachable from the host. To let Docker pick a free host port, use -P (publish all exposed ports) or -p 8080:

docker run -d --name e-invoice-validator -P docentric/e-invoice-validator:latest

Look up the mapped host port with:

docker port e-invoice-validator 8080

or check the PORTS column of docker ps (for example 0.0.0.0:32768->8080/tcp). Then open http://localhost:<mapped-port>.

Explicit mappings such as -p 18889:8080 work as before.

Installation & Usage

Prerequisites

For local development, you need:

• .NET 10 SDK
• Node.js 20.x or later
• Java Runtime Environment (JRE) 11 or later
• Docker (for containerized deployment)
• Visual Studio 2026 or JetBrains Rider (recommended IDEs)
• Git

Running the Release Packages (Windows, macOS, Linux)

Each GitHub release contains ZIP packages for every platform:

Platform	Framework-dependent (needs .NET 10 runtime)	Self-contained
Linux x64 / arm64	Docentric.EInvoice.Validator.RestServer-linux-<x64|arm64>-<version>.zip	Docentric.EInvoice.Validator.RestServer-Self-Contained-linux-<x64|arm64>-<version>.zip
Windows x64 / arm64	Docentric.EInvoice.Validator.RestServer-win-<x64|arm64>-<version>.zip	Docentric.EInvoice.Validator.RestServer-Self-Contained-win-<x64|arm64>-<version>.zip
macOS x64 / arm64 (Apple Silicon)	Docentric.EInvoice.Validator.RestServer-osx-<x64|arm64>-<version>.zip	Docentric.EInvoice.Validator.RestServer-Self-Contained-osx-<x64|arm64>-<version>.zip

The Linux package names changed: they previously had no OS in the name (for example RestServer-x64-<version>.zip).

The validator needs a Java runtime (JRE 11 or later). Every package contains a script that checks for Java and installs it if it is missing. The scripts are never run automatically:

• Windows: .\install-java.ps1 (add -Force for non-interactive mode). Uses winget, otherwise a checksum-verified Temurin 21 JRE download installed per user.
• macOS: ./install-java.sh (add --yes for non-interactive mode). Uses Homebrew, otherwise a checksum-verified Temurin 21 JRE download installed to ~/Library/Java/JavaVirtualMachines.
• Linux: ./install-java.sh (add --yes for non-interactive mode). Uses apt, dnf, yum, zypper or apk; requires root or sudo.

Exit codes: 0 Java 11+ available, 1 installation failed, 2 cancelled or unsupported system.

macOS note: the binaries are not signed or notarized. Gatekeeper may block the first start; remove the quarantine flag with xattr -dr com.apple.quarantine <folder> or allow the app in System Settings.

Building from Source

1. Clone the repository:

   git clone https://github.com/Docentric/docentric-e-invoice-validator.git
   cd docentric-e-invoice-validator
   

2. Restore dependencies:

   dotnet restore src/Docentric.EInvoice.Validator.slnx
   cd src/WebUI
   npm install
   cd ../..
   

3. Build the solution:

   dotnet build src/Docentric.EInvoice.Validator.slnx --configuration Release
   

4. Run the application:

   dotnet run --project src/Server/RestServer.csproj
   

The application will be available at https://localhost:57456 or http://localhost:57457.

Note: When running locally (not via Docker), ensure you have Java Runtime Environment (JRE) 11 or later installed, as it's required for the Mustang Project validation engine.

Building Docker Image Locally

To build the Docker image yourself:

# Windows
cd src
.\docker-build.ps1

Then run it:

# Windows
.\docker-run.ps1

The application will be available at http://localhost:18889.

Using Docker Compose

src/docker-compose.yml publishes the service on a random free host port (- "8080"). Look up the port with docker compose port e-invoice-validator 8080. To pin a host port, change the mapping to "<host-port>:8080".

API Usage

For detailed API documentation and interactive testing, visit the Swagger UI at:

http://localhost:18889/api/docs/swagger/index.html

The API provides the following endpoints (all POST endpoints accept multipart/form-data with a single file, up to 100 MB, and time out after 300 seconds):

Endpoint	Description
POST /api/pdf/validate-zugferd	Validates a ZuGFeRD / Factur-X PDF
POST /api/pdf/extract-zugferd-xml	Extracts the embedded XML from a ZuGFeRD / Factur-X PDF
POST /api/xml/validate	Validates a Factur-X or UBL XML file
POST /api/xml/convert-to-pdf	Converts a Factur-X or UBL XML file to PDF. Optional query parameter language (en, fr or de, default en)
GET /api/health	Reports Java and Mustang CLI availability and versions

Error responses carry an ErrorCode; see ErrorCode.Examples.md. ReDoc is also available at /api/docs/redoc.

Architecture

The solution consists of two main components:

Backend (src/Server)

ASP.NET Core REST API that:

• Accepts file uploads (PDF or XML)
• Invokes Mustang Project CLI for validation
• Parses validation results
• Returns structured JSON responses

Frontend (src/WebUI)

React SPA that:

• Provides a user-friendly upload interface
• Displays validation results
• Calls the REST API
• Built into static assets served from Server/wwwroot in production

Docker Image

The Docker image bundles:

• .NET 10 runtime
• OpenJDK 17 headless (for Mustang CLI)
• Mustang-CLI-2.26.0.jar, published next to the application in /app
• Published ASP.NET Core application
• Built React SPA

Project Structure

docentric-e-invoice-validator/
├── .github/
│   ├── copilot-instructions.md
│   ├── prompts/                # Reusable Copilot Chat prompts
│   └── workflows/
│       └── build.yml           # GitHub Actions CI/CD pipeline
├── samples/                    # Sample e-invoice files for testing
│   ├── ZuGFeRD e-Invoice.pdf
│   ├── factur-x e-invoice.pdf
│   └── *.xml
├── scripts/                    # Development scripts
├── src/
│   ├── Directory.Build.props   # Shared project properties
│   ├── Docentric.EInvoice.Validator.slnx
│   ├── Dockerfile              # Multi-stage Docker build
│   ├── docker-compose.yml
│   ├── Server/                 # ASP.NET Core REST API
│   │   ├── RestServer.csproj
│   │   ├── Program.cs
│   │   ├── Mustang-CLI-2.26.0.jar
│   │   ├── Configuration/
│   │   ├── Contracts/
│   │   ├── Endpoints/
│   │   ├── IO/
│   │   └── Services/
│   ├── Server.Tests/           # xUnit v3 tests
│   └── WebUI/                  # React + Vite frontend
│       ├── package.json
│       ├── vite.config.ts
│       ├── src/
│       └── ...
├── LICENSE
└── README.md

Docker Hub

Pre-built Docker images are automatically published to Docker Hub:

Repository: docentric/e-invoice-validator

Available Tags:

• latest - Latest stable release from the main branch
• 20XX.Y.Z - Specific version tags
• main - Latest build from main branch
• develop - Latest development build

Pull Image:

docker pull docentric/e-invoice-validator:latest
docker pull docentric/e-invoice-validator:latest

Development

Running in Development Mode

1. Start the backend:

   cd src/Server
   dotnet run
   

   The backend listens on https://localhost:57456 and http://localhost:57457.

2. Start the frontend (optional, hot reload):

   cd src/WebUI
   npm run dev
   

   The frontend dev server runs on http://localhost:53365 with hot reload enabled.

Running Tests

dotnet test src/Docentric.EInvoice.Validator.slnx

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License
Copyright (c) 2026 Docentric d.o.o.

Acknowledgments

This project builds upon the excellent work of several open-source projects:

• Mustang Project - The ZuGFeRD and Factur-X validation engine that powers this tool
• ASP.NET Core - Microsoft's cross-platform web framework
• React - Facebook's UI library
• Vite - Next-generation frontend build tool
• shadcn/ui - Beautifully designed UI components
• Tailwind CSS - Utility-first CSS framework

Special thanks to the Mustang Project team for creating and maintaining the comprehensive ZuGFeRD/Factur-X validation library.

About Docentric

Docentric contributes to the Dynamics 365 and Power Platform community through free apps, knowledge platforms, and by organizing events that bring professionals together on both local and international levels – proving ourselves as community-first and community-driven Microsoft ISV Partner.

Questions & Feedback

Reach out to us at [email protected] if you have any questions or feedback.