POST /v1/validate

Validate an e-invoice document — EN 16931 / CIUS Schematron for UBL and CII, Italy FatturaPA XSD-only for invoice XML, or Italy SDI file messaggio XSD-only when applicable.

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

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 — 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).

Quick copy examples

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

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

Request

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

Headers

Query parameters

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

Response

Success (200)

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

Validation result object

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.20",
    "peppolVersion": "PeppolBIS-Billing-3.0.20",
    "errors": [],
    "warnings": []
  }
}

Example with validation errors

{
  "success": true,
  "data": {
    "valid": false,
    "format": "cii",
    "profileDetected": "XRechnung",
    "schematronVersion": "1.3.16",
    "ciusVersion": "XRechnung-2.5.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-1",
        "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."
      }
    ]
  }
}

Response verifiability

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. 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": "7a590a263701e50305677ec253c61d83a13336c0e8b10b01674573347a52de00",
    "rulesetArtifacts": [
      { "key": "en16931_ubl_schematron", "version": "1.3.16", "fileSha256": "39f9d282867f1a49e7708d9e29a53da89643e1ee56f10cec1ebcf1277595fcbd" },
      { "key": "netherlands_nlcius_schematron", "version": "2.0.3.13", "fileSha256": "73da3db0b8cf6a37a8ad17051ac1603a83a695e2fa066820803aa1283a06e140" }
    ],
    "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.

Error responses

400 example

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

Notes

• 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, 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, and SDI file messaggio XSD violations use ruleId: "XSD" (structural). Messaggio validation does not imply FatturaPA invoice conformance or SDI operational interchange.
• See the validation artifacts page for details on which Schematron versions are currently in use.