Factur-X XML Embedding API for your own PDFs
Keep the invoice PDF you already render, and make it reform-ready. This endpoint promotes your PDF to PDF/A-3, attaches your CII XML as factur-x.xml, and writes the Factur-X XMP metadata French readers and PDPs expect. Your layout, fonts, and branding are never touched.
With the French e-invoicing reform phasing in from September 2026, thousands of billing systems need to attach structured data to PDFs they already produce. Doing that by hand means PDF/A-3 output intents, AFRelationship entries, and XMP extension schemas in a PDF library. Here it is one multipart request.
curl -X POST https://api.invoicexml.com/v1/embed/facturx \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]" \ -F "[email protected]" \ -o facture-facturx.pdf
// Binary PDF/A-3 response: ✓ Your visual layer, unchanged ✓ factur-x.xml attachment (your CII) ✓ Factur-X XMP metadata (fx: namespace) ✓ Profile read from your XML ✓ PDF/A-3 archival conformance
Embed your XML into a Factur-X PDF/A-3 now
This demo calls the same POST /v1/embed/facturx endpoint your integration will use. Drop your invoice PDF and your CII XML, and the finished Factur-X hybrid downloads immediately.
The fastest route from "we have a PDF" to reform-ready
Most French billing stacks are not missing invoice data or invoice documents. They are missing the hybrid container that binds the two. That container has exact technical requirements, and this endpoint owns all of them.
PDF/A-3 promotion
Your everyday PDF becomes an ISO 19005-3 archival document in place: output intent, conformance metadata, and document structure are added while every visual element stays exactly where your template put it.
The factur-x.xml attachment
Your CII payload is embedded under the standard filename with the MIME type and AFRelationship the specification requires, so any Factur-X reader, from a PDP intake system to a desktop viewer, finds and trusts the data.
French XMP branding
The fx: extension schema and urn:factur-x.eu conformance URN are written into the XMP, with the profile (MINIMUM through EXTENDED) taken from your XML's SpecificationIdentifier, never a hardcoded default.
A three-call pipeline for the French reform
Teams pass an invoice through validate, embed, and verify, and hand the result to their PDP. Each step is one endpoint.
Validate the XML
Run your CII through POST /v1/validate/cii to catch EN 16931 rule violations while they are still cheap to fix, before a container is built around them.
Embed into your PDF
This page. POST /v1/embed/facturx binds the validated XML and your rendered PDF into one Factur-X PDF/A-3, branding intact.
Verify the hybrid
Optionally run the finished file through POST /v1/validate/facturx, the same rule set a PDP or Chorus Pro applies at intake, and archive the compliance report with the invoice.
Two files in, one hybrid out
Send both files as multipart/form-data fields named pdf and xml. The response body is the binary Factur-X PDF/A-3.
$ curl -X POST https://api.invoicexml.com/v1/embed/facturx \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]" \ -F "[email protected]" \ -o facture-facturx.pdf
A UBL file in the xml field returns a clear 400 (convert it first with /v1/convert/ubl/to/cii). Serving German recipients? Use the ZUGFeRD embedding endpoint, which writes zf: branding instead.
Skip the API. Use getfacturx.com
Our online companion tool. Create and validate Factur-X invoices in your browser, no integration, no API key, no code. Perfect for freelancers, small businesses, and one-off invoices.
Complete Factur-X Toolkit
Everything you need to create, convert, validate, and extract Factur-X invoices via REST API or online.
Frequently Asked Questions
Why embed instead of letting the API generate the whole invoice?
Because in most French rollouts the visual invoice already exists. Your ERP or billing system renders a designed PDF with your branding, your layout, and often legally reviewed wording. The reform only adds the requirement that the machine-readable CII travels inside it. This endpoint adds exactly that, the PDF/A-3 container and the attachment, without regenerating or altering the document your customers already know.
What makes the output Factur-X rather than generic PDF plus XML?
Three things the API writes for you: the PDF/A-3 (ISO 19005-3) conformance that permits embedded files, the attachment under the standard name factur-x.xml with the correct relationship metadata, and the Factur-X XMP extension schema (fx: namespace with the urn:factur-x.eu:1p0 conformance URN) that declares the embedded profile. French readers, PDPs, and archive systems look for precisely these markers.
Which Factur-X profiles can I embed?
All five: MINIMUM, BASIC WL, BASIC, EN 16931, and EXTENDED. The profile is read from the SpecificationIdentifier in your CII XML and advertised in the XMP accordingly, so the container always matches the payload. Remember that MINIMUM and BASIC WL count as e-reporting extracts rather than full invoices under the French rules.
Will the output pass my PDP's intake checks?
The endpoint guarantees the container side: PDF/A-3 conformance, correct attachment, and correct XMP. Whether the invoice passes the business-rule gate depends on your XML content. The recommended pipeline is to validate the XML with POST /v1/validate/cii before embedding, or run the finished file through POST /v1/validate/facturx, which executes the same EN 16931 and FNFE-MPE checks a PDP applies.
Is this the same as ZUGFeRD embedding?
Nearly. Factur-X and ZUGFeRD share the container format and the factur-x.xml attachment name; the difference is the XMP branding. This endpoint writes the French fx: namespace and urn:factur-x.eu conformance URN. If your recipient is German and checks for ZUGFeRD branding, use POST /v1/embed/zugferd, the payload can be byte-identical.
What if my invoice XML is UBL?
Factur-X requires CII as the embedded syntax, so UBL input is rejected with a clear 400 error. Convert it first with POST /v1/convert/ubl/to/cii and embed the result, or use POST /v1/convert/ubl/to/facturx to go from UBL to a finished Factur-X hybrid in a single call (with a freshly rendered visual layer).
Ready to automate your invoices?
Validate, convert and embed compliant e-invoices through one API. Start your 30-day free trial. No credit card required.