Docs · How it works
Validation
Three layers, always in the same order. A document that satisfies one can still fail the next, so the order is what makes a report readable.
| Layer | Rules | What it checks |
|---|---|---|
xsdUBL 2.1 schema | the schema itself | Is this the right shape? Elements present, in the right order, with values of the right type. Nothing about the business rules is checked yet. |
en16931EN 16931 | 954 | The European semantic rules every compliant invoice obeys: totals that add up, a VAT breakdown that matches the lines, the terms a document cannot go without. |
peppolPeppol BIS Billing 3.0.21 | 149 | What Peppol adds on top, including the country rules that apply once a buyer or seller is in a particular market. |
A layer that cannot run because an earlier one failed is reported as skipped, never aspassed. A malformed document tells you nothing about its business rules, and saying otherwise would be a lie the next release could expose.
An invalid document is a successful request
Validation answers 200 with valid: false. The request succeeded; the invoice did not. Error statuses are kept for requests that could not be answered at all — see errors.
{ "data": { "valid": false, "ruleset": { "id": "peppol-bis-billing-3.0.21", "version": "3.0.21" }, "document": { "type": "invoice", "customization_id": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0", "profile_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0" }, "layers": [ { "name": "xsd", "status": "passed" }, { "name": "en16931", "status": "passed" }, { "name": "peppol", "status": "failed" } ], "summary": { "errors": 1, "warnings": 0 }, "findings": [ { "rule_id": "PEPPOL-EN16931-R003", "layer": "peppol", "severity": "error", "message": "A buyer reference or purchase order reference MUST be provided.", "explanation": "Peppol needs something the buyer can use to route the invoice internally. Neither a buyer reference (BT-10) nor a purchase order reference (BT-13) was present.", "fix": "Add the buyer's purchase order number as `cac:OrderReference/cbc:ID`, or their reference as `cbc:BuyerReference`.", "business_terms": [ "BT-10", "BT-13" ], "location": { "xpath": "/Invoice", "line": 2, "path": null }, "docs_url": "https://www.einvoicing.dev/rules/PEPPOL-EN16931-R003" } ] }}What a finding gives you
- The rule id, and a link to its page among the 1,103 rules.
- The official rule text, verbatim, so it can be quoted to whoever asks.
- A plain-English explanation and, where one exists, the concrete fix. 8 rules have one so far, starting with the ones real invoices fail most.
- The business terms it concerns, such as BT-10, and where in the document it was checked.
Releases, and testing against the next one
OpenPeppol publishes a rule release each May and November, and each becomes mandatory about three months later. Validation uses the release whose status is current unless you pin one with the rulesetparameter, which is how you find out what an upcoming release will say about your documents before it starts to matter.
The operation itself: parameters, report shape and errors.
Which releases can be validated against, and which is current.