Skip to main content

​
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 statusXML embedded in PDF?
DraftNo
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 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}
Then, use the attachment_id from the invoice to fetch the PDF metadata via the Retrieve an attachment endpoint: 
    GET https://thirdparty.qonto.com/v2/attachments/{id}
The response includes an updated_at timestamp. Wait until updated_at is strictly more recent than the invoice’s finalized_at timestamp before proceeding to the download. This confirms that the PDF has been regenerated and now contains the Factur-X XML.

​
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.