Factur-X Invoices

Download successfully Factur-X invoices format

What is Factur-X?

Factur-X is a hybrid e-invoicing standard available for French accounts, in line with France’s e-invoicing reform. It embeds a structured XML file directly into a PDF document, producing a single file that is both human-readable and machine-processable.

New to Factur-X? Before diving into the API integration, we recommend reading our complete guide to Factur-X.

Key Behavior: Draft vs. Finalized Invoices

Understanding the invoice lifecycle is essential to retrieving a valid Factur-X file.

Invoice status	XML embedded in PDF?
Draft	No
Finalized (unpaid, paid)	Yes

The Factur-X XML is only generated and embedded once an invoice is finalized. Downloading a PDF from a draft invoice will return a standard PDF without any embedded XML. This is the expected behavior.

Asynchronous PDF Generation

PDF generation at Qonto is asynchronous. This means that after you finalize an invoice via the API, the updated PDF (with the embedded Factur-X XML) is not immediately available. A delay of 10 seconds occurs between:

1. The moment the invoice transitions to unpaid status (after finalization)
2. The moment the new PDF (with embedded XML) is ready for download

If you request the PDF attachment immediately after finalizing an invoice, you may receive the previous draft PDF, which does not contain the Factur-X XML.

How to Properly Download a Factur-X Invoice

Follow these 3 steps to reliably retrieve a Factur-X invoice with its embedded XML.

Step-by-step guide: Generate and download a Factur-X invoice

Looking for a full end-to-end walkthrough? Our use case guide covers the complete flow with code examples in Python and Node.js. From finding or creating a client, drafting and finalizing the invoice, to polling for the attachment and downloading the Factur-X PDF.

Step 1 - Finalize the invoice

Use the Finalize a client invoice endpoint:

    POST https://thirdparty.qonto.com/v2/client_invoices/{id}/finalize

The response will return the invoice object with status: unpaid and a finalized_at timestamp. Note down both the invoice id and the attachment_id returned in the response body, you will need them in the next steps.

Step 2 - Poll until the PDF is regenerated

Do not fetch the PDF immediately after finalization, a delay of 10 seconds can occur for the PDF generation. Instead, implement a polling loop using the Retrieve a client invoice endpoint:

    GET https://thirdparty.qonto.com/v2/client_invoices/{id}

Once attachment_id is set on the invoice, fetch the attachment via the Retrieve an attachment endpoint:

    GET https://thirdparty.qonto.com/v2/attachments/{id}

A 200 response is your signal that the Factur-X PDF is ready to download. If attachment_id is still null on the invoice, wait and re-fetch the invoice before calling the attachment endpoint.

Step 3 - Download the Factur-X PDF

Once the upload’s updated_at is more recent than finalized_at, retrieve the url field from the upload response. This is a pre-signed URL pointing directly to the Factur-X-compliant PDF (PDF/A-3 with embedded XML).

The downloaded file is your Factur-X invoice, containing both the human-readable PDF and the embedded factur-x.xml structured data.

Verifying the Embedded XML

To confirm the XML is correctly embedded, you can open the PDF in Adobe Acrobat Reader (free) and navigate to the Attachments panel via the paperclip icon in the left sidebar. A valid Factur-X invoice will show a file named factur-x.xml in that list, if it is present, the format is confirmed. If the panel is empty, the invoice was likely downloaded too early; refer to the polling steps above and retry.

The Qonto web application handles the asynchronous delay internally, which is why Factur-X files downloaded from the UI always include the XML. When using the API directly, you need to account for this delay yourself.