> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  **New to Factur-X?** Before diving into the API integration, we recommend reading our [complete guide to Factur-X](https://qonto.com/fr/blog/gestion-entreprise/facturation/factur-x).
</Tip>

## 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

<Note>
  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.
</Note>

## How to Properly Download a Factur-X Invoice

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

<Card title="Step-by-step guide: Generate and download a Factur-X invoice" icon="code" href="/get-started/business-api/use-cases#5-how-to-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.
</Card>

### Step 1 - Finalize the invoice

Use the [Finalize a client invoice](https://docs.qonto.com/api-reference/business-api/expense-management/client-quotes-notes/client-invoices/finalize-a-client-invoice) endpoint:

```bash theme={null}
    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](https://docs.qonto.com/api-reference/business-api/expense-management/client-quotes-notes/client-invoices/retrieve-a-client-invoice) endpoint:

```bash theme={null}
    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](https://docs.qonto.com/api-reference/business-api/expense-management/attachments/retrieve-an-attachment) endpoint:

```bash theme={null}
    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.

<Note>
  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.
</Note>