{"openapi":"3.1.0","info":{"title":"EU E-Invoice Validation & Repair API","description":"\nValidates EU electronic invoices (UBL 2.1 and UN/CEFACT CII) against EN 16931 and Peppol BIS\nBilling 3.0, explains every failure in plain language, and repairs the failures that can be\nrepaired deterministically.\n\n**Privacy.** Invoices are processed in memory and are never written to disk or logged. Logs\nrecord rule IDs, syntax, country and timing — never field values, never the document. Nothing\nabout your invoice is retained after the response is returned.\n\n**Determinism.** Rule artefacts are pinned to an exact upstream release. The same document\nvalidated against the same `ruleset_version` always produces the same result, and old versions\nstay available so a historical invoice can be checked against the rules as they stood then.\n\n**What this is not.** Not a Peppol Access Point, not a transmission service — no invoice is\never sent anywhere — and not an invoice generator.\n","version":"0.1.0"},"paths":{"/v1/validate":{"post":{"tags":["validation"],"summary":"Validate an invoice and explain every failure","operationId":"validate_v1_validate_post","parameters":[{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 3166-1 alpha-2 override. Normally inferred from the document.","title":"Country"},"description":"ISO 3166-1 alpha-2 override. Normally inferred from the document."},{"name":"ruleset_version","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pinned release tag. Defaults to the release in force.","title":"Ruleset Version"},"description":"Pinned release tag. Defaults to the release in force."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Validate as the rules stood on this date, for historical invoices.","title":"Date"},"description":"Validate as the rules stood on this date, for historical invoices."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_validate_v1_validate_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationOut"}}}},"401":{"description":"Missing or unrecognised API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"402":{"description":"Monthly quota exhausted on a hard-limit plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"Invoice too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"Not a supported invoice document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}}},"/v1/repair":{"post":{"tags":["repair"],"summary":"Repair the failures that can be repaired deterministically","operationId":"repair_v1_repair_post","parameters":[{"name":"ruleset_version","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ruleset Version"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepairRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepairOut"}}}},"401":{"description":"Missing or unrecognised API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"402":{"description":"Monthly quota exhausted on a hard-limit plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"Invoice too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"Not a supported invoice document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}}},"/v1/rulesets":{"get":{"tags":["reference"],"summary":"Available rule sets, versions and coverage","operationId":"rulesets_v1_rulesets_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RulesetsOut"}}}}}}},"/v1/rulesets/{country}":{"get":{"tags":["reference"],"summary":"Which ruleset version and CIUS apply for a country on a date","operationId":"ruleset_for_country_v1_rulesets__country__get","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","title":"Country"}},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolutionOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rules/{rule_id}":{"get":{"tags":["reference"],"summary":"Catalogue entry for a rule (free and unmetered)","description":"Unmetered on purpose: this doubles as the public reference for the rule set.","operationId":"rule_v1_rules__rule_id__get","parameters":[{"name":"rule_id","in":"path","required":true,"schema":{"type":"string","title":"Rule Id"}},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en","title":"Language"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleOut"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rules":{"get":{"tags":["reference"],"summary":"List catalogued rule IDs","operationId":"rules_v1_rules_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Rules V1 Rules Get"}}}}}}},"/v1/usage":{"get":{"tags":["reference"],"summary":"Usage and remaining quota for the calling key","description":"Free and unmetered — a customer must be able to see what they are being billed for.","operationId":"usage_v1_usage_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Usage V1 Usage Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/healthz":{"get":{"tags":["operations"],"summary":"Liveness and artefact readiness","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Healthz Healthz Get"}}}}}}}},"components":{"schemas":{"AppliedFixOut":{"properties":{"rule_id":{"type":"string","title":"Rule Id"},"location":{"type":"string","title":"Location"},"description":{"type":"string","title":"Description"},"before":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Before"},"after":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"After"},"inputs_used":{"items":{"type":"string"},"type":"array","title":"Inputs Used"}},"type":"object","required":["rule_id","location","description"],"title":"AppliedFixOut"},"Body_validate_v1_validate_post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File"}},"type":"object","title":"Body_validate_v1_validate_post"},"ErrorOut":{"properties":{"error":{"type":"string","title":"Error"},"detail":{"type":"string","title":"Detail"}},"type":"object","required":["error","detail"],"title":"ErrorOut"},"FindingOut":{"properties":{"rule_id":{"type":"string","title":"Rule Id"},"severity":{"type":"string","enum":["fatal","error","warning"],"title":"Severity"},"ruleset":{"type":"string","title":"Ruleset"},"location":{"type":"string","title":"Location","description":"XPath into the source document"},"message":{"type":"string","title":"Message","description":"Verbatim Schematron message"},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explanation","description":"Plain-language cause"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field","description":"Affected EN 16931 term, e.g. BT-10"},"fixability":{"anyOf":[{"type":"string","enum":["AUTO","INPUT","MANUAL"]},{"type":"null"}],"title":"Fixability"},"fix_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fix Hint"}},"type":"object","required":["rule_id","severity","ruleset","location","message"],"title":"FindingOut"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"RejectedFixOut":{"properties":{"rule_id":{"type":"string","title":"Rule Id"},"description":{"type":"string","title":"Description"},"introduced":{"items":{"type":"string"},"type":"array","title":"Introduced","description":"Rules that would have started failing had this fix been kept"}},"type":"object","required":["rule_id","description","introduced"],"title":"RejectedFixOut"},"ReleaseOut":{"properties":{"ruleset":{"type":"string","title":"Ruleset"},"release_tag":{"type":"string","title":"Release Tag"},"commit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commit"},"valid_from":{"type":"string","title":"Valid From"},"valid_until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid Until"},"current":{"type":"boolean","title":"Current"}},"type":"object","required":["ruleset","release_tag","valid_from","current"],"title":"ReleaseOut"},"RepairOut":{"properties":{"repaired":{"type":"boolean","title":"Repaired","description":"Whether anything was changed"},"still_valid_after_repair":{"type":"boolean","title":"Still Valid After Repair"},"repaired_xml":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Repaired Xml","description":"The repaired document, omitted when nothing changed"},"applied":{"items":{"$ref":"#/components/schemas/AppliedFixOut"},"type":"array","title":"Applied"},"remaining":{"items":{"$ref":"#/components/schemas/FindingOut"},"type":"array","title":"Remaining"},"rejected":{"items":{"$ref":"#/components/schemas/RejectedFixOut"},"type":"array","title":"Rejected","description":"Fixes rolled back because they would have made the document worse"},"missing_inputs":{"items":{"type":"string"},"type":"array","title":"Missing Inputs","description":"Input keys that would unlock further repairs if supplied"},"iterations":{"type":"integer","title":"Iterations"}},"type":"object","required":["repaired","still_valid_after_repair","applied","remaining","iterations"],"title":"RepairOut"},"RepairRequest":{"properties":{"xml":{"type":"string","title":"Xml","description":"The invoice document"},"inputs":{"additionalProperties":{"type":"string"},"type":"object","title":"Inputs","description":"Values for INPUT-class fixes, e.g. {'buyer_reference': 'PO-4711'}"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"}},"type":"object","required":["xml"],"title":"RepairRequest"},"ResolutionOut":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"date":{"type":"string","title":"Date"},"ruleset_version":{"type":"string","title":"Ruleset Version"},"rulesets":{"items":{"type":"string"},"type":"array","title":"Rulesets"},"known_cius":{"items":{"type":"string"},"type":"array","title":"Known Cius"},"note":{"type":"string","title":"Note"}},"type":"object","required":["country","date","ruleset_version","rulesets","known_cius","note"],"title":"ResolutionOut"},"RuleOut":{"properties":{"rule_id":{"type":"string","title":"Rule Id"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field"},"ruleset":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ruleset"},"fixability":{"type":"string","enum":["AUTO","INPUT","MANUAL"],"title":"Fixability"},"syntax":{"items":{"type":"string"},"type":"array","title":"Syntax"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explanation"},"fix_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fix Hint"},"xpath_target":{"additionalProperties":{"type":"string"},"type":"object","title":"Xpath Target"}},"type":"object","required":["rule_id","fixability","syntax"],"title":"RuleOut"},"RulesetsOut":{"properties":{"rulesets":{"items":{"$ref":"#/components/schemas/ReleaseOut"},"type":"array","title":"Rulesets"},"syntaxes":{"items":{"type":"string"},"type":"array","title":"Syntaxes"},"catalogued_rules":{"type":"integer","title":"Catalogued Rules"},"repairable_rules":{"type":"integer","title":"Repairable Rules"},"note":{"type":"string","title":"Note"}},"type":"object","required":["rulesets","syntaxes","catalogued_rules","repairable_rules","note"],"title":"RulesetsOut"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ValidationOut":{"properties":{"valid":{"type":"boolean","title":"Valid"},"syntax":{"type":"string","enum":["UBL","CII"],"title":"Syntax"},"ruleset_version":{"type":"string","title":"Ruleset Version"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"customization_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customization Id"},"profile_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Id"},"findings":{"items":{"$ref":"#/components/schemas/FindingOut"},"type":"array","title":"Findings"},"uncatalogued_rule_ids":{"items":{"type":"string"},"type":"array","title":"Uncatalogued Rule Ids","description":"Rules hit that have no catalogue entry yet"}},"type":"object","required":["valid","syntax","ruleset_version","findings"],"title":"ValidationOut"}}},"tags":[{"name":"validation","description":"Validate and explain"},{"name":"repair","description":"Deterministic repair"},{"name":"reference","description":"Rule catalogue and versions (free)"},{"name":"operations","description":"Health"}]}