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
-
Clone the repository:
git clone https://github.com/Docentric/docentric-e-invoice-validator.git
cd docentric-e-invoice-validator
-
Restore dependencies:
dotnet restore src/Docentric.EInvoice.Validator.slnx
cd src/WebUI
npm install
cd ../..
-
Build the solution:
dotnet build src/Docentric.EInvoice.Validator.slnx --configuration Release
-
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 branch20XX.Y.Z - Specific version tagsmain - Latest build from main branchdevelop - Latest development build
Pull Image:
docker pull docentric/e-invoice-validator:latest
docker pull docentric/e-invoice-validator:latest
Development
Running in Development Mode
-
Start the backend:
cd src/Server
dotnet run
The backend listens on https://localhost:57456 and http://localhost:57457.
-
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.
