POST /v1/convert

Convert an EN 16931-family e-invoice between formats — CII ↔ UBL, ZUGFeRD ↔ Factur-X, XRechnung CII ↔ UBL, Peppol BIS ↔ EN 16931 UBL. XML and hybrid PDF in and out.

Convert an e-invoice from one EN 16931-family format to another in a single call.

The engine routes the conversion through three primitives in order: extract embedded CII when the source is a hybrid PDF, convert between CII and UBL via Mustang (cii2ubl) or Helger en16931-ubl2cii when the syntaxes differ, rewrite the CustomizationID / guideline URN to match the target profile, and re-wrap into a PDF/A-3 hybrid when the target is ZUGFeRD or Factur-X.

When source and target carry semantics the target cannot represent, the engine fails closed with 422 CONVERSION_LOSSY_FAILCLOSED rather than silently dropping fields. The two known cases — France CTC Flux 2 BusinessProcess codes on UBL targets, and synthesising Peppol endpoints from a non-Peppol source — surface explicitly; callers can opt in to known-acceptable losses (e.g. dropping a PDF envelope when the target has no PDF spec) and read them back from the response headers.

Out of scope. FatturaPA, Facturae, KSeF, and SDI messaggio sources or targets are not supported (no published EN 16931-equivalent converter; conversion would silently lose national overlay fields). Use /v1/generate to produce these from structured JSON instead.

Quick copy examples

Convert CII → UBL:

curl -X POST "https://api.beliq.eu/v1/convert?targetFormat=ubl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.cii.xml \
  --output invoice.ubl.xml

Convert ZUGFeRD PDF → Factur-X PDF (re-wrap with the new profile URN):

curl -X POST "https://api.beliq.eu/v1/convert?targetFormat=facturx&targetProfile=en16931" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @zugferd.pdf \
  --output facturx.pdf

Convert a Peppol BIS UBL → plain EN 16931 UBL (strips the cbc:EndpointID blocks; acceptable loss recorded):

curl -X POST "https://api.beliq.eu/v1/convert?targetFormat=ubl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @peppol.xml \
  -D - \
  --output en16931.xml
# Response headers include X-Lost-Elements-Count: 2 (one per stripped endpoint).

Request

POST /v1/convert
Content-Type: application/xml | application/pdf
Authorization: Bearer <api-key>

Headers

Query parameters

Request body

The raw XML or hybrid PDF file content. Do not JSON-encode it.

Supported pairs

The engine guarantees a clean conversion path for every pair where both source and target are in the EN 16931 family. The table summarises the operational shape:

Response

Success (200)

The body is raw bytes — application/xml or application/pdf depending on the envelope. The audit metadata is in the response headers:

LostElement schema

Each entry in X-Lost-Elements has this shape:

Worked example: Peppol BIS UBL → plain EN 16931 UBL

Converting a Peppol invoice carrying both endpoint blocks to plain EN 16931 strips both as an acceptable loss:

[
  {
    "path": "/Invoice/{urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2}AccountingSupplierParty/{urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2}Party/cbc:EndpointID",
    "value": null,
    "reason": "Peppol endpoint stripped (target is not peppol-bis)",
    "severity": "info",
    "acceptableLoss": true
  },
  {
    "path": "/Invoice/{urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2}AccountingCustomerParty/{urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2}Party/cbc:EndpointID",
    "value": null,
    "reason": "Peppol endpoint stripped (target is not peppol-bis)",
    "severity": "info",
    "acceptableLoss": true
  }
]

The corresponding response carries X-Lost-Elements-Count: 2.

Lossy conversions — semantics

Beliq splits “lossy” into two buckets with very different behaviour:

• Fail-closed losses (default): the source carries a field the target cannot represent and the caller has not opted in. Returns 422 CONVERSION_LOSSY_FAILCLOSED with the un-mappable XPath(s) in error.details.unmappablePaths. No body is returned. Today this fires on two paths: France CTC Flux 2 BusinessProcess codes on a UBL-syntax target (opt-in: ?dropFranceCtcOverlay=true), and synthesising a Peppol BIS endpoint pair on a non-Peppol source (no opt-in — use /v1/generate instead).

• Acceptable losses: the loss is intrinsic to the requested conversion and the caller is implicitly asking for it. Returns 200 OK with the count surfaced in X-Lost-Elements-Count. Today this fires on: stripping Peppol cbc:EndpointID blocks when leaving peppol-bis, dropping the PDF envelope when converting a hybrid PDF to a target with no PDF spec, and dropping a France CTC code when dropFranceCtcOverlay=true was set.

Error responses

422 CONVERSION_UNSUPPORTED_PAIR example

{
  "success": false,
  "error": {
    "code": "CONVERSION_UNSUPPORTED_PAIR",
    "message": "Source format 'facturae' is not in the EN 16931 family (supported: cii / ubl / zugferd / facturx / xrechnung / peppol-bis).",
    "details": {
      "sourceFormat": "facturae",
      "targetFormat": "ubl"
    }
  }
}

422 CONVERSION_LOSSY_FAILCLOSED example (France CTC)

{
  "success": false,
  "error": {
    "code": "CONVERSION_LOSSY_FAILCLOSED",
    "message": "Source CII carries France CTC Flux 2 BusinessProcess code 'B8'; UBL has no equivalent extension and Mustang cii2ubl would silently drop it. Pass options.dropFranceCtcOverlay=true (or the ?drop_france_ctc_overlay=true query param) to accept the loss explicitly.",
    "details": {
      "unmappablePaths": [
        "/rsm:CrossIndustryInvoice/rsm:ExchangedDocumentContext/ram:BusinessProcessSpecifiedDocumentContextParameter/ram:ID"
      ]
    }
  }
}

503 CONVERSION_TOOL_UNAVAILABLE example

{
  "success": false,
  "error": {
    "code": "CONVERSION_TOOL_UNAVAILABLE",
    "message": "Mustang JAR not available",
    "details": {
      "missingTool": "mustang"
    }
  }
}

Notes

• Lost-elements audit lives in headers (not in the response body) so callers using --output file curl idioms get the converted bytes verbatim while still being able to inspect the audit trail. Browsers must read these via Access-Control-Expose-Headers (already configured on beliq-api).
• The engine resolves sourceFormat=auto by inspecting the XML root + the CustomizationID / GuidelineSpecifiedDocumentContextParameter/ID URN. Plain CII or UBL without a profile URN resolves as cii or ubl respectively.
• For ZUGFeRD vs Factur-X disambiguation (both share the same CII URN family), the engine treats them as profile labels on a CII document. Source-format resolution returns facturx by default; pass sourceFormat=zugferd explicitly when the caller’s intent is ZUGFeRD-specific.
• See Cross-format conversion on the format overview page for the conceptual map.