Overview

Supported e-invoice formats, XML syntaxes, and output types in the Beliq API.

Beliq supports the main EN 16931–based e-invoice formats used in Europe, plus Italy FatturaPA, Spain Facturae, Slovenia e-SLOG and Poland KSeF FA(3) (national XML formats, not EN 16931). This page explains standards, formats, profiles, and outputs in practical terms.

EN 16931 is the European baseline for e-invoicing. It defines:

• A common invoice data model
• Business rules every compliant invoice must satisfy
• Two XML syntaxes: UBL 2.1 and CII D16B

All EN 16931–derived formats on this page share the same semantic baseline. Italy FatturaPA (FPR12 ordinaria, Agenzia delle Entrate XSD), Spain Facturae (3.2.2, MINECO XSD), Slovenia e-SLOG (2.0, GZS/ePOS XSD) and Poland KSeF FA(3) (Ministerstwo Finansów XSD) are separate national XML formats validated against their authority XSD artifacts, not against EN 16931 Schematron.

Both XML syntaxes represent the same business data. The right choice depends on your target standard:

• XRechnung accepts both UBL and CII
• ZUGFeRD/Factur-X require CII (embedded in PDF)
• Peppol BIS 3.0 requires UBL
• Italy FatturaPA uses the authority FatturaElettronica XML schema (FPR12 ordinaria and related types), not UBL or CII
• Spain Facturae uses the authority Facturae 3.2.2 XML schema, not UBL or CII
• Slovenia e-SLOG uses the authority e-SLOG 2.0 XML schema (root Invoice in urn:eslog:2.00), not UBL or CII
• Poland KSeF FA(3) uses the authority FA(3) XML schema (root Faktura in http://crd.gov.pl/wzor/2025/06/25/13775/), not UBL or CII

Profiles control how much detail is included in the generated invoice. Not all profiles apply to all standards:

For Italy FatturaPA, use standard: "fatturapa" with profile: "ordinaria" (or omit profile; it defaults to ordinaria). Beliq performs XSD validation against the published schema graph and does not run EN 16931 Schematron on this route. Beliq does not sign the document or submit it to SDI today: you integrate with your own channel provider. The SDI lane of managed delivery is in build.

For Spain Facturae, use standard: "facturae" with profile: "ordinaria" (or omit profile). Beliq performs XSD validation against the MINECO 3.2.2 schema and does not run EN 16931 Schematron. VeriFactu real-time reporting, FACe B2G submission, and XAdES signing are out of product scope: you integrate with your own intermediary.

For Slovenia e-SLOG, use standard: "eslog" with profile: "eracun" (or omit profile). Beliq performs XSD validation against the GZS/ePOS e-SLOG 2.0 schema and does not run EN 16931 Schematron. UJP submission, e-route provider services, and XML-DSig signing are out of product scope; you integrate with your own intermediary. See the Slovenia e-SLOG format reference.

For Poland KSeF FA(3), use standard: "ksef" with profile: "fa3" (or omit profile). Beliq performs XSD validation against the Ministerstwo Finansów FA(3) schema and does not run EN 16931 Schematron. The generator covers ordinary VAT invoices in PLN between Polish parties; the Poland KSeF FA(3) format reference lists its full scope. Beliq does not operate KSeF submission: transmission goes via your chosen intermediary.

For best EU-wide interoperability, use the peppol profile with standard: "peppol-bis". For Germany-only invoicing, use xrechnung. The Factur-X profiles let you trade structured detail for simpler payloads when the receiver supports it; pick extended-ctc-fr when the recipient requires the French B2B reform overlay.

Document types: invoice vs. credit note

Beliq currently supports two document types, selected via the documentType field on the invoice payload (defaults to "invoice" when omitted):

Within either document, typeCode sets a type code (BT-3) other than the default, such as 384 for a corrected invoice or 389 for a self-billed one. It is accepted on facturx, zugferd, xrechnung and peppol-bis, and has to be a code the document type admits (BR-CL-01).

Credit notes against a standard that does not accept them (today: fatturapa, facturae and ksef) are rejected at /v1/generate with DOCUMENT_TYPE_STANDARD_MISMATCH. The error details.creditNoteCapableStandards lists the standards that accept CreditNote payloads in the deployed engine.

If you omit profile, Beliq picks the default for the chosen standard (xrechnung for xrechnung, peppol for peppol-bis, ordinaria for fatturapa and facturae, eracun for eslog, fa3 for ksef, en16931 for ZUGFeRD/Factur-X). Combinations that cannot satisfy the standard’s rules (for example standard: "peppol-bis" with profile: "extended") are rejected with the PROFILE_STANDARD_MISMATCH error.

Factur-X 1.09.2 profile coverage: all five profiles

Beliq supports all five Factur-X 1.09.2 profiles (MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED) plus the EXTENDED-CTC-FR overlay. 1.08 stays selectable on the previous channel until 2027-05-16 (see ruleset versioning). The Schematron and per-profile XSDs come from two sources, both pinned by Beliq with per-file SHAs:

• Primary source: the FNFE-MPE / FeRD joint pack at fnfe-mpe.org/factur-x/. It covers BASIC_WL, EN 16931, EXTENDED, and the EXTENDED-CTC-FR overlay through public unauthenticated download.
• Secondary source: Mustangproject core-2.26.0 (Apache-2.0). It re-publishes the MINIMUM and BASIC profile artifacts that FNFE-MPE distributes only behind an email-gated information-package download. Mustangproject is listed by FNFE-MPE itself as a recommended downstream consumer; the SHA-pinned per-file paths are recorded in facturx_schematron.secondarySource.

Documents arriving with one of the four factur-x.eu CustomizationIDs (MINIMUM, BASIC_WL, BASIC, EXTENDED) are validated against the matching profile rules through the same XSD + Schematron pipeline. The EN 16931 profile’s CustomizationID is the bare urn:cen.eu:en16931:2017, which non-Factur-X CII documents carry as well, so those documents run the generic EN 16931 Schematron. Either way there is no operator action needed, and the response’s rulesetArtifacts names what judged the document.

Promotion of any Factur-X profile to fully-verified in Beliq’s status taxonomy still requires a public negative unit-test corpus from FNFE-MPE. That gap is tracked as an upstream gap and reviewed quarterly.

Hybrid PDF output (a PDF/A-3 with the legal XML embedded inside it) applies only to ZUGFeRD and Factur-X. Every other standard can still return a visualization PDF from /v1/generate: a human-readable rendering with no embedded XML, which requires a template or pdfTemplateId. The x-pdf-kind response header says which kind you received.

PDF/A-3 hybrid invoices

ZUGFeRD and Factur-X produce PDF/A-3b documents that contain:

• A visual PDF rendering of the invoice (human-readable)
• An embedded XML attachment (factur-x.xml) containing the structured data (machine-readable)

This lets people read the invoice as a PDF while systems process the embedded XML from the same file.

Every invoice processed by Beliq is validated using the path that matches its format:

• EN 16931 routes (UBL / CII / Factur-X / XRechnung / Peppol / ZUGFeRD XML): XSD, then EN 16931 Schematron, then CIUS/profile Schematron, then optional France CTC overlay as described below.
• Schema-checked national formats (FatturaPA, Facturae, e-SLOG, KSeF FA(3)): XSD only against the authority schema graph bundled in the engine. EN 16931 Schematron and BR-* rule IDs do not apply; no machine-readable business rules are published for these formats, so XSD structural validation is the highest check available.

For EN 16931–based documents, processing follows:

Input → XSD Schema Validation → EN 16931 Schematron → CIUS / Profile Schematron → France CTC overlay (optional) → Result

1. XSD validation, for structural correctness: UBL 2.1, CII D16B, Factur-X 1.09.2 / ZUGFeRD 2.x CII D22B (per-profile XSD subset where applicable), or the Schema-checked national formats: Italy FatturaPA (VFPR12 and related authority XSD), Spain Facturae (MINECO 3.2.2 XSD), Slovenia e-SLOG (GZS/ePOS e-SLOG 2.0 XSD), Poland KSeF FA(3) (MF CRD pattern 2025/06/25/13775 XSD). For FatturaPA, Facturae, e-SLOG and KSeF FA(3), validation ends after this step (no Schematron layer exists for these formats).
2. EN 16931 Schematron: core business rules (BR-01 through BR-72 and beyond)
3. CIUS / profile Schematron: country- or network-specific rules (e.g. BR-DE-* for XRechnung, PEPPOL-EN16931-R* for Peppol BIS 3.0, FX-* for the five Factur-X 1.09.2 profiles)
4. France CTC overlay: when you send franceCtc=true to POST /v1/validate, when BT-24 is the EXTENDED-CTC-FR CustomizationID, or when BT-23 carries a cadre de facturation code from the closed list of AFNOR XP Z12-012 rule BR-FR-08, Beliq additionally runs the FNFE-MPE BR-FR-CTC Flux 2 Schematron. When it does, and the document is on the Factur-X EXTENDED profile or declares the EXTENDED-CTC-FR CustomizationID, Beliq also runs the EXTENDED-CTC-FR overlay. The France guide lists the codes.

The CIUS / profile layer that runs depends on the document’s CustomizationID: a Peppol BIS 3.0 URN triggers the OpenPeppol Schematron, an XRechnung URN triggers the KoSIT Schematron, and a Factur-X 1.09.2 URN triggers the matching FX profile Schematron. FatturaPA documents are identified by FatturaElettronica XML roots and the authority schema set, not by CustomizationID. See validation artifacts for the specific versions in use, and the Peppol BIS Billing 3.0 reference for what the peppol profile produces.

Beliq can convert an invoice from one EN 16931-family format to another via POST /v1/convert. Supported pairs:

• CII ↔ UBL (any profile): round-trip via Mustang cii2ubl and Helger en16931-ubl2cii.
• ZUGFeRD ↔ Factur-X: same syntax, profile-URN swap only. The content is not changed, and the result is validated under the new profile: a move the content does not fit, such as an invoice with lines to MINIMUM or BASIC WL, answers 422 CONVERSION_OUTPUT_INVALID, and a move from EXTENDED to EN 16931 is refused with 422 CONVERSION_UNSUPPORTED_PAIR.
• XRechnung CII → XRechnung UBL, when the request declares sourceFormat=cii. With auto-detection the source already is the target and comes back unchanged, once it has passed validation.
• Peppol BIS UBL → plain EN 16931 UBL: strips cbc:EndpointID blocks as an acceptable loss (the count is reported back in X-Lost-Elements-Count).
• Hybrid ZUGFeRD / Factur-X PDF in: the engine extracts the embedded CII and converts it. For an XML target the PDF is dropped. For a zugferd or facturx target the PDF comes back: as sent, with only its annotation flags set as PDF/A asks, when its embedded XML already is the target, and otherwise re-wrapped around the converted XML and checked by veraPDF against its PDF/A-3b profile.

The route validates the XML it returns and refuses a conversion whose result fails, with 422 CONVERSION_OUTPUT_INVALID. It also fails closed on the two losses it detects: a French cadre de facturation code (BT-23) on a UBL-syntax target (opt-in: ?dropFranceCtcOverlay=true) and synthesising Peppol endpoints from a non-Peppol source (no opt-in; use /v1/generate instead). Losses that come with the requested conversion, such as Peppol endpoints stripped when leaving Peppol BIS, are listed in the X-Lost-Elements header. It detects no other loss, because the converters between CII and UBL are not checked field by field, apart from the invoice total VAT amount (BT-110), which a UBL to CII conversion writes back from the source where the converter left it out. POST /v1/convert says what a returned document has and has not been checked for.

Out of scope. FatturaPA, Facturae, KSeF, and SDI messaggio sources or targets are not supported: those are national formats with no published EN 16931-equivalent converter. Use /v1/generate to produce FatturaPA, Facturae, e-SLOG or KSeF FA(3) from structured JSON, and /v1/validate to check existing FatturaPA, Facturae, e-SLOG, KSeF FA(3) or SDI messaggio documents.