einvoicekit

Validate any EN 16931 e-invoice (Factur-X, ZUGFeRD, XRechnung, UBL or CII) against the full official rule set, from one command or one function call. No Java, no Saxon, no rule files to download.

pipx run einvoicekit invoice.pdf

invoice.pdf  INVALID  (cii, urn:cen.eu:en16931:2017)
  BR-CO-15  /Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]
            [BR-CO-15]-Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).

Exit code 0 means every file is valid, 1 means at least one is not, 2 means at least one could not be validated. That is the whole integration for a CI pipeline.

What this package is, honestly

It is a thin client. Each call sends the invoice over HTTPS to einvoicekit's validator, which processes it in memory to produce the verdict and drops it; nothing is stored. What you get in exchange is the real thing: the official rule sets, EN 16931, XRechnung 3.0.2, Factur-X 1.09 and Peppol BIS 3.0, run by the reference validator, not a hand-written subset of them.

Two promises follow from that:

• A verdict is a verdict. valid=False lists every broken rule with its official id, the official message and the XPath of the element at fault.
• No silent green. If the service cannot be reached, you get an exception, never valid=True. The package has no fallback and no retry; a retry policy is yours to write.

Install

pip install einvoicekit

Python 3.10 or later. No dependencies.

Renamed in 0.2.0: the command was facturx and the error class FacturxError. The package name and the import name are unchanged.

Use it from code

from einvoicekit import validate, EinvoicekitError

with open("invoice.pdf", "rb") as f:
    result = validate(f.read())

result.valid  # True or False
result.errors  # [Finding(rule, message, path), ...]
result.warnings  # same shape, never change the verdict
result.syntax  # 'cii' or 'ubl'
result.profile  # the profile URN the document declares, or None
result.raw  # the API's JSON as a dict, untouched

validate(data, ...) takes the bytes of an XML invoice, or of a Factur-X / ZUGFeRD PDF, which is unwrapped first so its embedded XML is what gets validated. The result carries the API's JSON, field for field.

Keyword arguments:

Use it from the command line

einvoicekit invoice.pdf
einvoicekit a.xml b.pdf --target france
einvoicekit invoice.pdf --json
einvoicekit invoice.pdf --warnings
EINVOICEKIT_API_KEY=eik_live_... einvoicekit invoice.pdf

--json prints the API's verdict as JSON on stdout, an array when several files are given, and nothing else there; refusals go to stderr. --help lists every option.

Limits, plainly

• Without a key: 10 validations a day per IP address, shared with the free tools on einvoicekit.com. The eleventh call is refused with the time the pool resets (midnight UTC) and a link to the free key.
• With a free key: 100 validations a month, plus 20 generated invoices in an allowance of their own. No card. Get one by signing in with GitHub.
• Pro: 29 € a month for 1,000 pooled credits, a validation spending one. Details.

Only a delivered verdict counts. A document the API cannot assess, a refused call and an error on the service's side cost nothing.

Errors

Everything that is not a verdict raises EinvoicekitError with a stable code:

A wrong key is never a fallback into the free pool: send no key at all to use it.

Scope

Validation checks the invoice XML: the schema and every business rule of the profile the document declares. It does not check the PDF container's own PDF/A conformance; that check runs on the generation side of the API.

Full API documentation, the French rules and the generation endpoint: einvoicekit.com/docs.

Licence

MIT.