Convert an e-invoice between formats
Auto-detects and parses the source e-invoice, then regenerates it in the requested target format (zugferd, facturx, xrechnung). A PDF source is opened first: format and country come from its embedded XML; a PDF without embedded XML answers 400 NO_EMBEDDED_XML. XRechnung → ZUGFeRD is loss-free (CIUS → EN 16931); the reverse only succeeds when the XRechnung obligations (BT-10, BR-DE-*) are met — otherwise a 422 with the offending rule codes is returned. zugferd and facturx are the same hybrid PDF/A-3 standard — the seller country picks the flavour (FR/BE → Factur-X, otherwise ZUGFeRD), so both requests yield a PDF with the embedded CII XML. Any fields not carried across are listed in conversionWarnings. warnings carries every warning of the target generator and of its conformance self-check, in the same shape as /generate — among them SELF_CHECK_INCOMPLETE when a rulebook could not be applied: the document was then not fully checked against it. The target is written in ZUGFeRD 2.4 / Factur-X 1.08 — the same default as /generate — and appliedFormatOptions names the version and profile actually written. A profile the target generator cannot write, or one that conflicts with the source’s countrySpecific.facturxProfile, returns a 400 with a code. The profile is sent as options.zugferdProfile — /convert does not read formatOptions. A finding of a newly enforced rule that is still in its warning phase returns 200 with a SPEC_RULE_PENDING warning (rule or pendingKey, enforceFrom, specId) — as at /generate; options.enforcePending: true (boolean) rejects it with 422 right away. Findings of reading the source (e.g. a mandate reference outside the CII schema, read anyway) are listed in sourceErrors, in the shape of errors at /parse, only when there are any. Requires BOTH the source :parse and the target :create entitlement; usage is billed once against the target :create key (like generate).
Authentication
API Key authentication. Use sk_live_* for production or sk_test_* for testing.
Request
The source e-invoice: raw XML (starts with <) or base64 of an XML or a hybrid PDF (ZUGFeRD / Factur-X). Format and country are detected from the document.
Target format. zugferd and facturx both yield the hybrid PDF/A-3 with embedded CII XML; the seller country picks the flavour (FR/BE → Factur-X, otherwise ZUGFeRD). Case-insensitive.
Response
Converted document (base64) + conversionWarnings + warnings
Hex-encoded SHA-256 of the returned document bytes (the base64-decoded data). Empty string when no document was produced (422). NOT stable across calls for PDF outputs — the PDF carries a creation timestamp and document ID, so two calls with an identical payload yield two different values. Use it to verify the file you received; use payloadHash for idempotent filenames and duplicate detection.
The target format written (lower case).
Fields of the source that the target does not carry — lost when reading the source or when writing the target. Empty when nothing was lost.
Hex-encoded SHA-256 of the canonical JSON of the invoice you sent (object keys sorted recursively, undefined members dropped). Identical invoice data → identical value, on every call. Present on 200 and 422 responses. Use it as the key for idempotent file names and to recognise a document you already generated.
The ZUGFeRD / Factur-X version and profile the document was actually written in — the requested ones, or the defaults (2.4 / 1.08, EN16931) when none was sent. Absent for formats without a version selector (XRechnung, UBL, …).
Warnings of the target generator and of its conformance self-check, in the same shape as /generate — for example SELF_CHECK_INCOMPLETE (a rulebook could not be applied) or SPEC_RULE_PENDING (a finding still in its warning phase). The warnings of reading the source come first, in the same shape as /parse — for example PARTY_COUNTRY_ASSUMED: a party address had no country, the country of the source format was assumed and written into the target.
Findings of reading the source document, in the same shape and order as errors at /parse — for example DE_DIRECT_DEBIT_MANDATE_OUTSIDE_SCHEMA: the mandate reference (BT-89) or the creditor reference (BT-90) stood at a place the CII schema does not allow; the value was read anyway and written into the target. Present only when reading the source found something, on the 200 and on the 422 CONVERSION_FAILED.
