Skip to navigation

Validate invoice for a specific format

Two inputs, send exactly one.

  • invoice (invoice data): generate the invoice in the given format and validate the resulting XML against its official XSD and Schematron rules. For ZUGFeRD/Factur-X every profile is validated. For ebInterface 6.1 the rules are derived from the official documentation (AUSTRIAPRO, 14 June 2023); there is no official Schematron. Billed like generation: 1 unit on that format’s create entitlement, which the API key must hold — without it the call is rejected with 403, exactly like /generate.

Three outcomes (status): passed and failed answer 200 with the verdict; an empty or malformed document (VAL-XML-001 / VAL-XML-002) answers 422. not_run (valid: null) has two cases: a format we have no pinned rulebook for answers 200 with status: not_run and reason: missing and is billed like a check — a retry gives the same answer; a rulebook that failed to load or run answers 503 VALIDATION_UNAVAILABLE with the tool findings (VAL-SYS-*) and bills nothing — retry later.

  • data (a received document, the same body as /parse: base64 of the XML, or of a PDF with the XML embedded): the document itself is checked, not an XML generated from it. Billed 1 unit on the format’s parse entitlement (403 without it). A PDF is unpacked first (extractedFromPdf: true; a PDF without embedded XML answers 400 NO_EMBEDDED_XML). A document of another country or format than the path answers 400 FORMAT_MISMATCH and bills nothing. The rulebook follows the document: at /FR/ubl a Peppol BIS document is checked against Peppol BIS 3.0, an EXTENDED-CTC-FR document against EN 16931 (UBL) and the CTC-FR rules of the FNFE-MPE, any other EN 16931 document against EN 16931 (UBL); results[].format names each rulebook. Same outcomes and status codes as above.

Sending both: invoice is checked as before and a warning DATA_IGNORED says that data was not used.

Authentication

AuthorizationBearer

API Key authentication. Use sk_live_* for production or sk_test_* for testing.

Path parameters

countryCodeenumRequired

ISO 3166-1 alpha-2 country code (lowercase). Determines country-specific validation and available e-invoice formats. Supported countries (37): ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk.

formatenumRequired

Output/input format identifier (lowercase). Valid format values depend on the country — call GET /api/v1/invoice/{countryCode}/formats to discover the exact set for a country. Overview:

  • pdf — all 37 countries.
  • ubl — generic Peppol BIS 3.0 UBL on most countries (incl. PINT flavours for AE/AU/NZ); on PL it emits the national KSeF FA(3), on PT CIUS-PT, on RO eFactura (CIUS-RO).
  • xrechnung (DE), zugferd (DE — formatOptions.profile selects EN16931/BASIC/EXTENDED; CH — Swiss CII flavour for cross-border DE/AT customers).
  • ebinterface (AT).
  • facturx (FR/BE — formatOptions.profile selects EN16931/BASIC).
  • fatturapa (IT — 6-char SDI codes for PA accepted).
  • facturae (ES) — generated only; invoice-api does not report to the AEAT (no VERI*FACTU record).
  • isdoc (CZ), nav (HU), mydata (GR), ksef (PL).
  • cii (SK — EN 16931 CII, generate and validate with invoice; checking a received SK-CII document (data) is not offered).
  • peppol-ubl — generic Peppol BIS 3.0 UBL for PL/PT/RO whose ubl slot is (or can be) occupied by the national CIUS.
  • hr-fisk (HR — HR-FISK 2.0 CIUS, validate only).
  • qr-bill (CH/LI — structured 32-line QR-Bill payload as text/plain).

Exact spelling matters — values must be lowercase. The peppol-ubl, qr-bill and hr-fisk slots are dash-separated.

Request

This endpoint expects an object.
objectRequired
OR
objectRequired

Response

Validation result - passed, failed, or not_run with reason: missing when we have no pinned rulebook for the format (valid: null).

validboolean or null

true when every checked format passed XSD + Schematron without findings, false when a check found something, null when a rulebook did not run (status: not_run).

resultslist of objects
One entry per checked spec format, each with its own verdict and findings
statusenum

passed — the rulebook ran and found nothing; failed — it found something (valid: false, see errors); not_run — it did not run (completely): valid is null and reason says why. A finding beats not_run: a real finding with another rulebook not run is failed.

Allowed values:
errorslist of objectsOptional
Flattened findings across all checked formats. Absent when there are none.
reasonenumOptional

Why the check did not run: rulebook missing (we have no pinned rulebook for this format — a retry gives the same answer), load-failed, transform-failed, time-budget (the check took longer than its time limit and was stopped — the document is delivered, it was not fully checked), sidecar-unavailable (the check service gave no answer and the document is too large to check here), not-bound (no rulebook is bound to the written version/profile), or not-applied (the rulebook is deliberately not run on this path). Only with status: 'not_run'.

extractedFromPdftrueOptional

Present (true) only when data was a PDF: the e-invoice XML embedded in it was extracted, and that XML was checked.

Errors

400
Bad Request Error
403
Forbidden Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error