vsveyko/corbum-fakturum-api repository overview

⁠fakturum — self-hosted e-invoicing API

Validate, convert, and generate European e-invoices (XRechnung, ZUGFeRD, Factur-X) from your own infrastructure. No cloud dependency, no per-request billing, no usage quotas — a single compact container you run yourself. Part of the Corbum product collection.

This image is the Free tier: XML validation for XRechnung UBL/CII against the official rules — XSD schema validation plus the EN 16931 and XRechnung Schematron rule sets published by KoSIT and CEN (not an approximation). PDF (ZUGFeRD/Factur-X), /convert, /generate, /embed (XRechnung into your own PDF/A) and async /batch require a Pro or Business license — see the product page on GitHub⁠.

⁠Quick start

docker run -d --name fakturum -p 127.0.0.1:8080:8080 vsveyko/corbum-fakturum-api:free

The port is bound to 127.0.0.1 on purpose: the service has no built-in authentication (see "Running it in production"). Every release is also available under a fixed tag, <version>-free. Stop and remove it with docker rm -f fakturum.

curl http://localhost:8080/health
# {"status":"ok","version":"<pulled tag's version>","license":"free","brand":"fakturum","collection":"corbum"}

Validate an XRechnung UBL invoice (base64-encode the XML document). No invoice at hand? Use one of the samples from the demo, e.g. a valid one:

curl -sO https://raw.githubusercontent.com/vsveyko/corbum-releases/main/demo-fakturum/www/samples/valid-ubl.xml
DOC=$(base64 -w0 valid-ubl.xml)   # macOS: base64 -i valid-ubl.xml
curl -X POST http://localhost:8080/validate \
  -H "Content-Type: application/json" \
  -d "{\"document\":\"${DOC}\",\"format\":\"auto\"}"

{
  "status": "valid",
  "valid": true,
  "format": "xrechnung-ubl",
  "errors": [],
  "warnings": [],
  "rulesChecked": 104
}

An invalid invoice is a normal result, not an HTTP error: status is invalid and errors lists every violated rule with its official rule ID, the business term, and the position in the document.

The full, live API contract is always served by the container itself — as raw OpenAPI YAML, and as an interactive Swagger UI page (fully vendored, no CDN, works offline):

curl http://localhost:8080/openapi.yaml
# or open http://localhost:8080/docs in a browser

⁠Running it in production

The image contains only the service binary: no operating system, no shell, no package manager. It runs as a non-root user (UID 10001), stores nothing, and makes no outbound network connections — the rule sets and API docs are built in. Documents are processed in memory and are never logged.

Hardened example:

docker run -d --name fakturum -p 127.0.0.1:8080:8080 \
  --read-only --tmpfs /tmp \
  --cap-drop ALL --security-opt no-new-privileges:true \
  --memory 2g --cpus 2 --pids-limit 256 \
  vsveyko/corbum-fakturum-api:free

The service has no built-in authentication. Put it behind your own reverse proxy or API gateway on a private network, and don't publish port 8080 to the internet. Don't expose /license/status publicly either.

The service protects itself against oversized or hostile documents: documents with an extreme number of elements are rejected up front, validation has a time limit, and only a limited number of requests are processed at once (the rest wait briefly, then get 503). Limits can be tuned with environment variables:

Plan for memory generously: a document with very many small elements needs far more memory than its file size suggests. A normal invoice uses well under 100 MB; a container limit of 2 GB leaves room for several large documents at once.

⁠Running with a license (Pro/Business)

The Paid image (Pro and Business are the same image — the license file decides which features are active) isn't on Docker Hub — download it as a .tar.gz from https://github.com/vsveyko/corbum-releases/releases⁠. It is unlocked by the license file you get from one of our sales partners (ask [email protected]⁠ if you need one; details on the product page⁠); without a license it runs as Free. Load it locally and run it with your license file mounted:

docker load -i fakturum-paid-<version>-amd64.tar.gz   # -arm64 on ARM servers
docker run -d -p 8080:8080 \
  -v /path/to/license.json:/app/license.json:ro \
  corbum-fakturum-api:<version>-paid

GET /license/status reports the resolved plan. An invalid, missing, or expired license degrades to Free automatically — the container never refuses to start.

⁠Why self-hosted

• No cloud dependency, no data leaves your infrastructure — DSGVO/ GDPR-friendly by construction, not by contract addendum.
• One-time purchase, not a subscription. Patches are free forever within a major.minor; feature upgrades are a flat one-time fee.
• Compact image, pure Go, no JVM. No Java toolchain to install or maintain.

⁠Links

• Product page, downloads, release notes and a local demo for integrators: github.com/vsveyko/corbum-releases⁠
• Full API reference: GET /openapi.yaml (raw spec) or GET /docs (interactive Swagger UI) on any running container
• Questions about licenses, sales partners or integration: [email protected]⁠
• Part of the Corbum collection