einvoice

PYTHONPATH=$HOME/.local/lib/python3.10/site-packages python3 prove.py

Free on-ramp

New here? The fastest way in is the 5-minute worked walkthrough: it takes a broken XRechnung invoice, runs the checker, shows the real report it prints, and applies the two-element fix until the invoice passes.

Or go straight to a verdict on an invoice of your own — Python 3.10+, zero dependencies, two lines:

python3 -m pip install verifyhash-einvoice
einvoice validate --profile xrechnung invoice.xml

Exit code 0 means no implemented fatal rule fired, 1 means at least one did (the first is named on stdout), 3 means the file could not be read as XML. --profile xrechnung adds the German KoSIT layer on top of EN 16931; drop it for the European core rules alone. Add --format json for the full finding list, and einvoice --explain BR-DE-15 prints the remediation entry for any rule id you get back.

A ZUGFeRD 2.x / Factur-X PDF is valid input. The hybrid container is not a separate product to us: a PDF/A-3 e-invoice carries the very same rsm:CrossIndustryInvoice XML as an embedded attachment, so you hand the container to the command you already know. einvoice validate invoice.pdf pulls that attachment out with the Python standard library alone — no PyPDF, no Ghostscript, no network — and grades it under exactly the rules it would apply to the same XML on its own. It is not a second engine: the extracted CII runs through the identical rules.ALL_RULES core, with the same --profile values and the same exit codes as a loose .xml. validate-batch walks PDFs the same way:

einvoice validate --profile xrechnung invoice.pdf

On the Factur-X fixture that ships in this repository (corpus/pdf/facturx-valid.pdf, a repository checkout file, not a wheel file), einvoice validate exits 0 under the CLI’s default en16931 profile and 1 with --profile xrechnung — three fatal violations (BR-DE-23-b, BR-DE-31, BR-TMP-3) and two warnings. The German CIUS layer applies to a container’s payload exactly as it does to loose XML; the packaging changes nothing about which rules fire.

The extractor is a PDF reader for the classic case, and it says so instead of guessing. An encrypted PDF (/Encrypt), a cross-reference-stream / object-stream layout (PDF 1.5+ with no classic trailer), a truncated file and an unknown stream filter cannot be opened: each of those runs ends with exit code 3, the literal token unsupported-container, and one line naming the concrete cause — never a guess, and never a false 0. In practice the PDF/A-3 files real ERP exporters write are the classic case; a PDF rewritten by an optimiser may not be. Two further limits worth knowing before you wire this into CI: only the first embedded invoice file specification is read, and the FX-CONTAINER-* checks (/AFRelationship, /AF, the XMP Factur-X profile and whether it agrees with the CII’s CustomizationID, the PDF/A-3 marker) grade the packaging rather than the invoice — they are reported by python3 -m einvoice.report <invoice.pdf>, by validate-batch and by einvoice validate --format <fmt> <invoice.pdf>, but not in single-file validate’s default text output or its --json, which carry the invoice verdict.

Turning the checker on over invoices you already have is a different job from validating one new file, and two mechanisms exist for it. The validate-batch subcommand takes a directory or a glob, walks it recursively, validates every .xml and .pdf invoice it finds (dotfiles and dot-directories skipped) and prints one aggregate verdict — a PASS/FAIL/ERROR line per file, the totals, and a “most violated rules” ranking — while --fail-on=fatal|warning|information sets the severity at which the exit code turns non-zero, so your team picks its own gate height instead of inheriting ours (fatal is the default: warnings and information findings are reported but do not fail the build; the other two values make them fail it):

einvoice validate-batch --profile xrechnung --fail-on=fatal invoices/

Three things to know before you write that job. --profile xrechnung is not decoration — batch obeys the same default profile as every other subcommand (en16931), so omitting it grades the European core rules without the German KoSIT layer. The aggregate shape exists for json, junit and text only; the other six formats describe a single invoice, and asking for one over a directory is refused with exit 2 and a message naming the three — exactly the split einvoice --help prints. And a legacy corpus is gated file-by-file in a CI loop: --baseline, the regression diff that fails a run only on findings that are new since a stored report, is deliberately refused on the batch subcommand (exit 2 — one stored single-invoice report has nothing to diff against an aggregate), so there is no single call that freezes a whole archive. Loop einvoice validate --baseline prev.json invoice.xml per file if you want that, or hold the batch gate at --fail-on=fatal and raise it once the backlog is clean. Either way, a green aggregate means “no implemented fatal rule fired”, not “certified legally conformant”.

Freeze what is already broken; fail on what breaks next. That file-by-file loop deserves a closer look, because it is the mechanism that makes an existing archive adoptable at all. --baseline <prev-report.json> turns einvoice validate into a regression gate: it validates the invoice now, diffs the findings against a JSON report you captured earlier, and turns the exit code non-zero only for a violation that is new since that report. Nothing new — exit 0, even if the invoice still carries every fatal it carried yesterday. One new fatal — exit 1, and the einvoice-conformance-diff/v1 document names it in new_violations; the findings you fixed show up in resolved_violations, so progress is visible in the same artifact. A supplier archive that fails four rules per invoice can go into CI this afternoon and still block the fifth:

python3 -m einvoice.report --profile xrechnung --format json invoice.xml > prev-report.json
einvoice validate --baseline prev-report.json --profile xrechnung invoice.xml

Three details about those two lines, then the two limits that decide whether this is the right tool. The capture runs python3 -m einvoice.report rather than einvoice validate --json because only that entry point writes profile into the report it produces — a baseline that declares none still diffs, but a profile mismatch can no longer be caught: you get one note: line on stderr saying the profile could not be checked, not the refusal. That capture exits 1 on an invoice that fails and writes the full report anyway; the non-zero capture exit is the expected outcome, not an error, so do not let a set -e shell swallow the run. And both lines carry the same --profile xrechnung: capture and gate must agree, or the run is refused with exit 2 naming both profiles, rather than grading your flag change as a regression. Now the limits. The diff tolerates pre-existing fatals by design — that is the entire point of the flag — so a green --baseline run means “nothing got worse”, never “this invoice conforms”: it is a migration instrument, and the conformance verdict is the same command with the flag left off. And it diffs one invoice against one stored report: validate-batch --baseline is refused with exit 2, so a legacy corpus is gated file-by-file in a CI loop with one stored report per invoice — there is no single call that freezes a whole archive.

Pin the policy once, in the repository. The same three choices — output form, gate height, message language — end up typed in three places: the CI job, the pre-commit hook, and whatever a developer runs locally. They drift, and the first symptom is a build that fails on a machine where it passed. Drop a .einvoice.toml in the project root — or add a [tool.einvoice] table to the pyproject.toml you already have — and it sets the defaults for exactly three keys: format, fail-on and lang. Those three are the whole vocabulary; there is no fourth key and no key that turns rules on or off. einvoice --show-config then prints each resolved value together with where it came from — flag, the config filename, or default — reading no invoice and running no validation, so “why is CI stricter than my laptop?” is one command to settle:

einvoice --show-config

On a project with no config file that prints format: text (source: default), fail-on: fatal (source: default) and lang: en (source: default); a two-line .einvoice.toml containing lang = "de" is enough to make a flagless einvoice validate --profile xrechnung invoice.xml report its findings in German. Four limits are worth knowing before you commit the file. When both files exist, .einvoice.toml wins outright — the [tool.einvoice] table is not merged into it and is not even read, so a broken table sitting beside a good .einvoice.toml changes nothing and fixing the table changes nothing either. The config layer belongs to the einvoice console script only: python3 -m einvoice.report reads no .einvoice.toml and no [tool.einvoice] table at all, which is worth saying out loud because the recommended way to capture a --baseline report runs on exactly that entry point — pass those settings on its command line. A misconfigured file is a usage error, exit 2, naming the offending file and key: an unknown key, a non-string value or an unparseable file stops the run rather than quietly falling back to the built-in defaults. And an explicit flag on the command line still wins: the order is flag > config file > built-in default, so the file changes what you get when you say nothing, never what you get when you say something.

A receipt for the verdict. A validation run is ephemeral: the exit code scrolls past, and nothing is left beside the archived invoice recording what was actually checked. einvoice receipt <invoice.xml> emits a small deterministic JSON document that pins which bytes were graded — input_sha256, the SHA-256 of the input document's raw bytes — under which profile and which engine version, to what verdict, with the id and message of every fatal rule that fired, all wrapped with a content_sha256 taken over the canonicalised body; and einvoice receipt --verify <receipt.json> recomputes that digest and compares it in one command, offline, with no server and nothing uploaded:

einvoice receipt invoice.xml > receipt.json
einvoice receipt --verify receipt.json

Read that as tamper-evident, and no stronger. content_sha256 is a digest of the body only and is not part of its own pre-image, so editing any body field — or corrupting the stored hash itself — is caught, while a coordinated rewrite that edits the body and recomputes the hash over the forgery is internally consistent and verifies clean. Closing that gap needs an anchor outside the document: compare content_sha256 against an independently held copy of it, or re-run validation on the original bytes the receipt identifies via input_sha256 and check the body matches. The exact recompute recipe, in any language, is written out in RECEIPT-VERIFICATION.md in a source checkout. The document deliberately carries no wall-clock time by default: identical input bytes and profile produce a byte-identical receipt on every run, so it records what was graded, not when. And it is a record, not a certificate — a green verdict inside it means “no implemented fatal rule fired”, not “certified legally conformant”.

A report you can forward. The terminal summary is for you. The person who has to act on it is usually someone else — the supplier who sent the file, or the accountant who has to file it — and neither of them is going to run a CLI. --format html turns the same run into a self-contained conformance document: one HTML file on stdout with all of its styling inline and no external reference at all — no script, no image, no web font, no CDN, no tracker — and no wall-clock timestamp, so it renders the same way offline out of an archive folder in five years, and two runs over the same invoice produce byte-identical files. Add --lang de and it is a German document: German title, headings, status banner and field labels, <html lang="de"> so the declaration matches the content, and on every finding a German rule title and a German Behebung fix instruction. Its footer records the provenance of the verdict — the engine version, the number of business rules asserted, and the full 64-character attestation digest, never truncated, because a shortened hash cannot be recomputed — and those values are not typed into the report but read from the same payload einvoice info --json prints, so the recipient runs einvoice info --json on their own installation and checks the numbers instead of trusting ours. A value a build genuinely cannot determine is left out as a whole line rather than filled in with “unknown”: the footer gets shorter, never wrong:

einvoice validate --profile xrechnung --lang de --format html invoice.xml > bericht.html

Two different numbers govern how German that document is, and they are about two different fields. Exactly 50 of the 297 rules carry an official German message: the catalog entries tagged de_source == "kosit", whose vendored KoSIT <sch:assert> text is itself German (the German-authored BR-DE-* / BR-DE-CVD-* / BR-TMP-* / BR-DEX family), taken over word for word. A finding outside those 50 keeps the authoritative English sentence and says so: the paragraph is marked [en], tagged lang="en", and a note in the document explains the marker — showing the binding original is more honest than inventing a German sentence for a rule the standard never wrote one for. The rule titles and the Behebung fix hints are a separate matter: those are German for all 297 rules, and the report records per rule where that German came from — official KoSIT wording for the 50, a translation this project wrote for the remaining 247 (every one of the 297 fix hints is ours, the 50 included). That per-rule marking is the whole point: our prose is never handed to a reader as the standard's. And a green report is not legal conformance — it means “no implemented fatal rule fired”, not “certified legally conformant”.

Everything is free and open source (Apache-2.0). Start here:

• Repository README — install (pip install verifyhash-einvoice from PyPI, or pip install . / copy the package dir from a checkout when you need an offline, exactly-pinned copy), the CLI, and the full honest scope.
• CI conformance gate recipe (einvoice/ci/) — copy-paste POSIX sh + GitHub Actions / GitLab CI that fails a build on any non-conformant invoice and names the violated rule ID.
• GitHub Action (einvoice/action/) — a uses:-pinnable composite action that surfaces each finding as an inline PR annotation via SARIF.