> ## Documentation Index
> Fetch the complete documentation index at: https://invopop-singapore.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Factur-X Guide

> Generate compliant invoices in France (Factur-X).

## Introduction

**Factur-X** is France’s official hybrid electronic invoice standard, developed jointly by France and Germany to align with the European Norm **EN 16931**. Like **ZUGFeRD**, it combines two layers in one file:

* a **human-readable PDF/A-3 invoice** (so recipients can view it as a normal invoice), and
* an **embedded XML file** carrying the structured data for automated processing.

This dual approach makes Factur-X well suited for **B2B invoicing**, since a single document serves both business users (who need a visual invoice) and IT systems (which need structured data).

It is legally recognized in France for electronic invoicing and ensures compliance with EU standards, which means invoices in Factur-X can also be processed across other EU countries that support EN 16931.

## Prerequisites

To convert invoices to Factur-X format, ensure you have:

* A valid API key and a basic understanding of the [workflow engine](/guides/features/workflows) and [API](api-ref/introduction).
* An invoice with:
  * Supplier details (company name and required identities). Check the [French](https://docs.gobl.org/regimes/fr) regimes for specifics.
  * Line items with name, price, and applicable taxes.

## Factur-X Setup

To issue Factur-X invoices, follow these instructions in the [Invopop Console](https://console.invopop.com):

<Steps>
  <Step title="Connect the UN/CEFACT CII app">
    1. Navigate to **Configuration** → **Apps**.
    2. Locate **UN/CEFACT CII** in the app discovery list.
    3. Click **Connect** to activate.

    No additional configuration is needed.
  </Step>

  <Step title="Configure invoice workflow">
    <Tabs>
      <Tab title="Template">
        <Card iconType="duotone" title="Factur-X invoice workflow" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=fr-facturx" cta="Add to my workspace">
          This workflow will generate an Factur-X XML document and embed it into a PDF.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.

        ```json Workflow for generating a PDF with a Factur-X XML attachment  theme={"system"}
        {
            "name": "Factur-X invoice",
            "description": "Generate Factur-X invoice in France",
            "schema": "org/party",
            "steps": [
                {
                    "id": "bd7eb640-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `processing`{.state .processing}",
                    "config": {
                        "state": "processing"
                    }
                },
                {
                    "id": "58fb4ce0-6626-11f0-b9ab-1bbe1fa4398c",
                    "name": "Sign Envelope",
                    "provider": "silo.close"
                },
                {
                    "id": "3548d720-6623-11f0-b3db-e7255a5da07c",
                    "name": "Generate UN/CEFACT CII Invoice",
                    "provider": "cii.generate",
                    "summary": "FacturX CII V1",
                    "config": {
                        "doc_type": "facturx-v1"
                    }
                },
                {
                    "id": "56bda1e0-8ef7-11f0-aa0e-dd7c69b95f3c",
                    "name": "Generate PDF",
                    "provider": "pdf",
                    "summary": "French - A4",
                    "config": {
                        "logo_height": 40,
                        "locale": "fr",
                        "date_format": "%Y-%m-%d",
                        "layout": "A4",
                        "scripting": false
                    }
                },
                {
                    "id": "c6192a60-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `sent`{.state .sent}",
                    "config": {
                        "state": "sent"
                    }
                }
            ],
            "rescue": [
                {
                    "id": "c94982c0-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `error`{.state .error}",
                    "config": {
                        "state": "error"
                    }
                }
            ]
        }
        ```
      </Tab>

      <Tab title="Build from scratch">
        First, review our [workflows guide](/guides/features/workflows) to understand the basics.

        In [Console](https://console.invopop.com) create a new workflow and select [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) in the template selector, then add the essential steps:

        1. **Set State** - Select `Processing`
        2. **Sign Envelope**: The envelope must be signed before processing.
        3. **Generate UN/CEFACT CII Invoice**: In "Invoice Output Document Type" select `Factur-X CII v1`.
        4. **Generate PDF**: this step creates the PDF with the embedded XML.
        5. **Set State** - Select `Sent`.

        Finally, in the "Error Handling" area, add **Set State** and select `Error`.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Running

<Note>
  In your invoice data, make sure to include the [Factur-X addon](https://docs.gobl.org/addons/fr-facturx-v1) and state the regime as `FR`.
</Note>

Be sure to set the `regime` field to `FR` in your invoices and include the [Factur-X addon](https://docs.gobl.org/addons/fr-facturx-v1). This will add validations to ensure the document is compliant with the standard.

Some example invoices are provided below, along with an example workflow to send the invoices to. We also recommend using the [GOBL Builder](https://build.gobl.org) to create your own invoices.

## Sample Invoices

<AccordionGroup>
  <Accordion title="Factur-X B2B Invoice">
    ```json FacturX B2B Invoice theme={"system"}
    {
        "$schema": "https://gobl.org/draft-0/bill/invoice",
        "$regime": "FR",
        "$addons": [
            "eu-en16931-v2017",
            "fr-facturx-v1"
        ],
        "uuid": "019783e7-33b1-7000-a1a5-6139e214b447",
        "type": "standard",
        "series": "SAMPLE",
        "code": "2345",
        "issue_date": "2025-06-18",
        "currency": "EUR",
        "tax": {
            "ext": {
                "untdid-document-type": "380"
            }
        },
        "supplier": {
            "name": "Provide One Inc.",
            "tax_id": {
                "country": "FR",
                "code": "43498927917"
            },
            "identities": [
                {
                    "type": "SIRET",
                    "code": "49892791768734"
                }
            ],
            "addresses": [
                {
                    "num": "42",
                    "street": "Calle Pradillo",
                    "locality": "Madrid",
                    "region": "Madrid",
                    "code": "28002",
                    "country": "ES"
                }
            ],
            "emails": [
                {
                    "addr": "billing@example.com"
                }
            ]
        },
        "customer": {
            "name": "Sample Consumer",
            "tax_id": {
                "country": "FR",
                "code": "39356000000"
            },
            "identities": [
                {
                    "type": "SIRET",
                    "code": "35600000012345"
                }
            ],
            "addresses": [
                {
                    "num": "1",
                    "street": "Rue Sundacsakn",
                    "locality": "Saint-Germain-En-Laye",
                    "code": "75050",
                    "country": "FR"
                }
            ],
            "emails": [
                {
                    "addr": "email@sample.com"
                }
            ]
        },
        "lines": [
            {
                "i": 1,
                "quantity": "20",
                "item": {
                    "name": "Development services",
                    "price": "90.00",
                    "unit": "h"
                },
                "sum": "1800.00",
                "discounts": [
                    {
                        "reason": "Special discount",
                        "percent": "10%",
                        "amount": "180.00"
                    }
                ],
                "taxes": [
                    {
                        "cat": "VAT",
                        "key": "standard",
                        "rate": "general",
                        "percent": "20%",
                        "ext": {
                            "untdid-tax-category": "S"
                        }
                    }
                ],
                "total": "1620.00"
            }
        ],
        "payment": {
            "advances": [
                {
                    "description": "Paid in full",
                    "percent": "100%",
                    "amount": "1944.00"
                }
            ],
            "instructions": {
                "key": "card",
                "card": {},
                "ext": {
                    "untdid-payment-means": "48"
                }
            }
        },
        "totals": {
            "sum": "1620.00",
            "total": "1620.00",
            "taxes": {
                "categories": [
                    {
                        "code": "VAT",
                        "rates": [
                            {
                                "key": "standard",
                                "ext": {
                                    "untdid-tax-category": "S"
                                },
                                "base": "1620.00",
                                "percent": "20%",
                                "amount": "324.00"
                            }
                        ],
                        "amount": "324.00"
                    }
                ],
                "sum": "324.00"
            },
            "tax": "324.00",
            "total_with_tax": "1944.00",
            "payable": "1944.00",
            "advance": "1944.00",
            "due": "0.00"
        }
    }
    ```
  </Accordion>
</AccordionGroup>

You can now generate invoices in the Factur-X format via the API or console. For more details, visit the [GOBL docs](https://docs.gobl.org) or contact [Invopop Support](mailto:support@invopop.com).

## FAQ

<AccordionGroup>
  <Accordion title="How can I view an XML attached to a PDF?">
    In Factur-X PDFs, the XML file is embedded within the PDF itself. To extract and view it, you can use the `Attachments` section in Adobe Acrobat Reader.

    Alternatively, you can use specialized tools like the [SysTools PDF Extractor](https://www.systoolsgroup.com/pdf/extractor/) to extract the XML file.
  </Accordion>
</AccordionGroup>