POST /v1/validate

Validate an e-invoice: EN 16931 and CIUS Schematron for UBL and CII; XSD only for FatturaPA, Facturae, e-SLOG, KSeF FA(3) and the SDI file messaggio.

Upload an invoice file (XML or PDF) and receive a validation result.

A PDF is judged by the invoice XML embedded in it, and only by that. Beliq looks for an embedded file named factur-x.xml, zugferd-invoice.xml or xrechnung.xml: first among the files the PDF lists as associated files (/AF), then among all its embedded files. Failing those it takes the first .xml file whose content starts like an invoice. When a PDF holds more than one such file, one is read and the others are not looked at. The response says which file was read, how it was found and how many there were, in pdfInput. The PDF itself is not checked: there is no PDF/A-3 conformance check, no check of how the XML is attached (AFRelationship), and no comparison of the XMP metadata with the XML. A PDF that carries no invoice XML returns 400.

For UBL and CII documents in the EN 16931 family, checks include:

1. XML structure (XSD)
2. EN 16931 business rules (Schematron)
3. Country- or network-specific rules when applicable: XRechnung for Germany, Peppol BIS Billing 3.0 for cross-border / Peppol Network invoices

For Italy FatturaPA XML (Agenzia namespaces: FatturaElettronica / FatturaElettronicaSemplificata), Beliq validates against the published W3C XML Schema graph bundled in the engine. That path is XSD only (no EN 16931 Schematron; no BR-* rule IDs). Additional normative constraints from the Italian technical specification (tables / regole) are not implemented as code in this release.

For Italy SDI file messaggio XML (namespace http://www.fatturapa.gov.it/sdi/messaggi/v1.0, roots such as NotificaScarto, RicevutaConsegna, … per MessaggiTypes_v1.1), Beliq validates against the authority Messaggi XSD vendored in the engine. Use format=sdi_messaggio or rely on auto-detect when the root element matches. This is interchange notification / receipt structural validation only. It is not FatturaPA invoice-body validation and not a substitute for SDI transport (which remains outside Beliq; SDI submission is not implemented).

For Spain Facturae XML (MINECO namespace http://www.facturae.gob.es/formato/Versiones/Facturaev3_2_2.xml, root Facturae), Beliq validates against the published Facturae 3.2.2 XSD bundled in the engine. Use format=facturae or rely on auto-detect. That path is XSD only (no EN 16931 Schematron; no BR-* rule IDs). VeriFactu / FACe submission and XAdES signing remain outside Beliq (BYOC).

For Slovenia e-SLOG 2.0 XML (namespace urn:eslog:2.00, root Invoice wrapping M_INVOIC), Beliq validates against the GZS/ePOS e-SLOG 2.0 XSD bundled in the engine. Use format=eslog or rely on auto-detect. That path is XSD only (no EN 16931 Schematron; no BR-* rule IDs). UJP submission, e-route provider services, and XML-DSig signing remain outside Beliq (BYOC).

For Poland KSeF FA(3) XML (namespace http://crd.gov.pl/wzor/2025/06/25/13775/, root Faktura), Beliq validates against the Ministerstwo Finansów FA(3) XSD bundled in the engine. Use format=poland_ksef_fa3 or rely on auto-detect. That path is the XSD plus the MF’s document-level KSeF acceptance checks (no EN 16931 Schematron; no BR-* rule IDs), and KSeF applies its business rules only at submission, which Beliq does not operate: transmission goes via your chosen intermediary. An FA(2) document (namespace http://crd.gov.pl/wzor/2023/06/29/12648/) is recognised but never passes: FA(2) is superseded by FA(3) and rejected by KSeF, so the result is valid: false with a leading POLAND_KSEF_FA2_SUPERSEDED error.

Validate XML:

curl -X POST "https://api.beliq.eu/v1/validate?format=auto" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

import { readFile } from 'node:fs/promises';

import { Beliq } from '@beliq/sdk';

const beliq = new Beliq({ apiKey: process.env.BELIQ_API_KEY! });

const result = await beliq.validate(await readFile('invoice.xml'), { format: 'auto' });

console.log(result.valid, result.format, result.schematronVersion);
for (const issue of result.errors) console.log(issue.ruleId, issue.message);

import os
from pathlib import Path

from beliq import Beliq

beliq = Beliq(api_key=os.environ["BELIQ_API_KEY"])

result = beliq.validate(Path("invoice.xml").read_bytes(), format="auto")

print(result.valid, result.format, result.schematron_version)
for issue in result.errors:
    print(issue.rule_id, issue.message)

Validate PDF:

curl -X POST https://api.beliq.eu/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @invoice.pdf

import { readFile } from 'node:fs/promises';

import { Beliq } from '@beliq/sdk';

const beliq = new Beliq({ apiKey: process.env.BELIQ_API_KEY! });

const result = await beliq.validate(await readFile('invoice.pdf'));

console.log(result.valid, result.format, result.schematronVersion);
for (const issue of result.errors) console.log(issue.ruleId, issue.message);

import os
from pathlib import Path

from beliq import Beliq

beliq = Beliq(api_key=os.environ["BELIQ_API_KEY"])

result = beliq.validate(Path("invoice.pdf").read_bytes())

print(result.valid, result.format, result.schematron_version)
for issue in result.errors:
    print(issue.rule_id, issue.message)

POST /v1/validate
Content-Type: application/xml | application/octet-stream
Authorization: Bearer <api-key>

Headers

Query parameters

A query parameter this table does not list answers 400 VALIDATION_ERROR, and error.details.fields names it as a JSON Pointer, such as /formt.

Request body

The raw XML or PDF file content as the request body. Do not JSON-encode it.

curl -X POST "https://api.beliq.eu/v1/validate?format=auto" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

import { readFile } from 'node:fs/promises';

import { Beliq } from '@beliq/sdk';

const beliq = new Beliq({ apiKey: process.env.BELIQ_API_KEY! });

const result = await beliq.validate(await readFile('invoice.xml'), { format: 'auto' });

console.log(result.valid, result.format, result.schematronVersion);
for (const issue of result.errors) console.log(issue.ruleId, issue.message);

import os
from pathlib import Path

from beliq import Beliq

beliq = Beliq(api_key=os.environ["BELIQ_API_KEY"])

result = beliq.validate(Path("invoice.xml").read_bytes(), format="auto")

print(result.valid, result.format, result.schematron_version)
for issue in result.errors:
    print(issue.rule_id, issue.message)

Alongside the JSON body below, the response carries the verdict, the detected syntax and profile, and the ruleset seal as headers. See the Response headers reference.

Success (200)

{
  "success": true,
  "data": {
    "valid": true,
    "format": "cii",
    "profileDetected": "XRechnung",
    "schematronVersion": "1.3.16",
    "ciusVersion": "XRechnung-2.6.0",
    "errors": [],
    "warnings": []
  }
}

Validation result object

PDF input object

Sent as pdfInput when the request body was a PDF, with a valid verdict and with an invalid one.

"pdfInput": {
  "containerChecked": false,
  "attachmentName": "factur-x.xml",
  "attachmentFoundBy": "associated-file",
  "attachmentCandidates": 1
}

Validation error object

Peppol BIS Billing 3.0 example

When the input declares the Peppol BIS Billing 3.0 customization, Beliq runs the OpenPeppol Schematron in addition to EN 16931 and reports the Peppol version explicitly:

{
  "success": true,
  "data": {
    "valid": true,
    "format": "ubl",
    "profileDetected": "peppol",
    "schematronVersion": "1.3.16",
    "ciusVersion": "PeppolBIS-Billing-3.0.21",
    "peppolVersion": "PeppolBIS-Billing-3.0.21",
    "errors": [],
    "warnings": []
  }
}

Example with validation errors

{
  "success": true,
  "data": {
    "valid": false,
    "format": "cii",
    "profileDetected": "XRechnung",
    "schematronVersion": "1.3.16",
    "ciusVersion": "XRechnung-2.6.0",
    "errors": [
      {
        "ruleId": "BR-01",
        "severity": "error",
        "location": "/rsm:CrossIndustryInvoice/rsm:ExchangedDocumentContext",
        "message": "An Invoice shall have a Specification identifier (BT-24)."
      },
      {
        "ruleId": "BR-DE-15",
        "severity": "error",
        "location": "/rsm:CrossIndustryInvoice",
        "message": "An XRechnung invoice must contain a buyer reference (BT-10)."
      }
    ],
    "warnings": [
      {
        "ruleId": "BR-CL-01",
        "severity": "warning",
        "location": "/rsm:CrossIndustryInvoice/...",
        "message": "The currency code should be a valid ISO 4217 code."
      }
    ]
  }
}

A validation artifact does not always implement every rule its standard’s text carries. Where a rule is in the normative text, is absent from every artifact that judged your document, and is still enforced by other validators your invoice may reach, Beliq reports the violation as an advisory: severity: "info", in warnings.

An advisory never changes valid. That flag reflects only the artifacts that actually ran, so a document is never failed here by a rule the pinned artifacts do not carry. rulesetArtifacts names and rulesetSha256 fingerprints those of them that judged the document. Advisory IDs are deliberately not official rule IDs, so you can tell them apart: they read <STANDARD>_<RULE>_NOT_ENFORCED.

One rule qualifies today.

{
  "ruleId": "EN16931_BR_CO_25_NOT_ENFORCED",
  "severity": "info",
  "location": "/rsm:CrossIndustryInvoice",
  "message": "Amount due for payment (BT-115) is positive but neither the Payment due date (BT-9) nor the Payment terms (BT-20) is present. ..."
}

Supplying a payment due date or payment terms clears it. Credit notes are out of scope for this rule and never draw the advisory. Neither does a Factur-X MINIMUM document: that profile has no element for a due date or payment terms, so it cannot carry either.

You will not see the advisory when an artifact that ran already enforces the rule. A Factur-X EXTENDED document is judged by a pack that carries BR-CO-25, so the violation arrives as an ordinary error from that pack instead. A BASIC or BASIC-WL document validated on the previous ruleset channel (Beliq-Ruleset: previous) gets it as an error too, under the pack’s own rule ID, while that channel runs the Factur-X 1.08 packs. The same happens to the documents any other artifact judges once a release of it reinstates the rule. For the full background, see Validation artifacts.

Every response carries two hashes so you can confirm the result yourself: sha256 (the exact bytes you sent) and rulesetSha256 (the rule artifacts that judged them), plus the rulesetArtifacts rows the ruleset hash is built from. For an EN 16931 document those rows include the syntax schema, because a document the schema rejects is judged by the schema alone and no business rule runs. Responses may also carry driftCheckedAt, a UTC timestamp reporting when those artifacts were last confirmed against their upstream authority sources.

{
  "success": true,
  "data": {
    "valid": false,
    "format": "ubl",
    "profileDetected": "netherlands-nlcius",
    "sha256": "8b508d3648dbee66ca6798e6bc812842204974328fd626e3d9cdf60c98782cd1",
    "rulesetSha256": "9f539954095415c7d9e8f1fb8459afe532d3ce3395fdd626d0e2fa73a4e4a887",
    "rulesetArtifacts": [
      { "key": "en16931_ubl_schematron", "version": "1.3.16", "fileSha256": "39f9d282867f1a49e7708d9e29a53da89643e1ee56f10cec1ebcf1277595fcbd" },
      { "key": "netherlands_nlcius_schematron", "version": "2.0.3.13", "fileSha256": "73da3db0b8cf6a37a8ad17051ac1603a83a695e2fa066820803aa1283a06e140" },
      { "key": "ubl_xsd", "version": "2.1", "fileSha256": "40fae8cb436f3a9506d7acce65ba162caef3b0bed4d5cbc0992b2153ded4edf4" }
    ],
    "driftCheckedAt": "2026-07-03T04:12:07Z"
  }
}

sha256sum your file to match sha256; sort the rulesetArtifacts "<key>@<version>=<fileSha256>" lines, join with newlines, and SHA-256 to reproduce rulesetSha256; then cross-check each component against GET /v1/rulesets. driftCheckedAt, when present, reports how recently that ruleset was drift-checked against its authority sources. Full walkthrough: Verify a hash.

400 example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body must contain an XML or PDF file"
  }
}

• valid: false is not an API error. It means validation ran successfully and found rule violations.
• format tells you which syntax family was detected (cii, ubl, fatturapa, facturae, eslog, poland_ksef_fa3, or sdi_messaggio).
• Rule IDs follow the official naming conventions where Schematron is used: BR-* for EN 16931 core rules, BR-DE-* for XRechnung rules, PEPPOL-* for Peppol-specific rules. FatturaPA, Facturae, e-SLOG, KSeF FA(3), and SDI file messaggio XSD violations use ruleId: "XSD" (structural). KSeF FA(3) acceptance-check failures use KSEF_* rule IDs, listed in the format reference. Messaggio validation does not imply FatturaPA invoice conformance or SDI operational interchange.
• A document in no syntax Beliq recognises comes back as a normal validation result, not an error: HTTP 200, valid: false, format: "unknown", and a single fatal finding with ruleId: "UNSUPPORTED_FORMAT". Match on errors[].ruleId, not on error.code, which is absent on a 200.
• See the validation artifacts page for details on which Schematron versions are currently in use.