python

CII for Python: InvoiceXML API Examples

Python code samples for creating, validating, and parsing CII electronic invoices using the InvoiceXML API. Compatible with Python 3.7+ (3.10+ recommended). Runs in Django, Flask, FastAPI, Pandas pipelines, Jupyter notebooks, AWS Lambda, Google Cloud Functions, Azure Functions, or plain scripts.

For background on the CII syntax itself (what it is, when to use it standalone), see the main repository README.

Get your API key

Every example in this folder calls the InvoiceXML REST API. Sign up and generate a free API key here:

→ https://www.invoicexml.com/account/authentication

Pass it as a Bearer token on every request:

Authorization: Bearer YOUR_API_KEY

Important: set api_key in the examples to the raw key only, without the Bearer prefix. If your account page shows the full header value (e.g. Bearer ixml_a1b2c3...), copy only the part after Bearer . The code adds the prefix itself when building the Authorization header.

Requirements

• Python 3.7 or later (3.10+ recommended)
• The requests library

pip install requests

Or with uv (the modern alternative):

uv pip install requests

requests is the standard HTTP client for Python: clean multipart support, automatic JSON decoding, and the most familiar API in the ecosystem. If you prefer the modern async alternative, httpx translates almost line-for-line.

Files in this folder

File	Operation	API endpoint
create.py	Build a CII D16B XML invoice	POST /v1/create/cii
validate.py	Validate a CII file against the D16B XSD and EN 16931 rules	POST /v1/validate/cii
extract_json.py	Parse a CII XML into JSON	POST /v1/extract/json
ai_convert.py	(Experimental) Convert a plain PDF to CII with AI	POST /v1/transform/to/cii
render.py	Render CII XML into a human-readable PDF	POST /v1/render/cii/to/pdf

Each file is standalone and runnable with python create.py. Open the file, replace YOUR_API_KEY with your real key, and execute.

Note on the snippets below: they are excerpts from those files and assume api_key is already defined. When in doubt, copy the complete file.

---

Create a CII invoice in Python

import requests

payload = {
    "invoice": {
        "invoiceNumber": "CII-2026-001",
        "issueDate":     "2026-05-18",
        "currency":      "EUR",
        "seller": {
            "name":              "Acme GmbH",
            "vatIdentifier":     "DE123456789",
            "legalRegistration": {"identifier": "HRB 12345"},
            "postalAddress": {"line1": "Hauptstraße 12", "city": "Berlin", "postCode": "10115", "country": "DE"},
        },
        "buyer": {
            "name": "Globex SAS",
            "postalAddress": {"line1": "15 rue de Rivoli", "city": "Paris", "postCode": "75001", "country": "FR"},
        },
        "paymentDetails": {"paymentAccountIdentifier": "DE89370400440532013000"},
        "lines": [{
            "quantity":       10,
            "priceDetails":   {"netPrice": 150.00},
            "vatInformation": {"rate": 19.00},
            "item":           {"name": "Senior consulting"},
        }],
    },
}

response = requests.post(
    "https://api.invoicexml.com/v1/create/cii",
    headers={"Authorization": f"Bearer {api_key}"},
    json=payload,
)

with open("invoice-cii.xml", "w", encoding="utf-8") as f:
    f.write(response.text)

Totals and the VAT breakdown are calculated from the line items when omitted, and the document declares urn:cen.eu:en16931:2017 in BT-24.

The response is the CII D16B XML document, validated against the EN 16931 rules before delivery.

Full example: create.py | API reference

---

Validate a CII file in Python

import requests

response = requests.post(
    "https://api.invoicexml.com/v1/validate/cii",
    headers={"Authorization": f"Bearer {api_key}"},
    files={"file": ("invoice.xml", open("invoice.xml", "rb"), "application/xml")},
)
print(response.text)

Returns a JSON validation report listing any rule failures (EN 16931 BR-* and BR-CO-* rules).

Full example: validate.py | API reference

---

Extract CII data as JSON in Python

Useful for Pandas pipelines, Django/Flask models, or any system that prefers JSON over XML.

import requests

response = requests.post(
    "https://api.invoicexml.com/v1/extract/json",
    headers={"Authorization": f"Bearer {api_key}"},
    files={"file": ("invoice.xml", open("invoice.xml", "rb"), "application/xml")},
)

# The invoice document sits under the "invoice" key of the response.
invoice = response.json()["invoice"]
print(invoice["seller"]["name"], invoice["totals"]["grandTotalAmount"])

Full example: extract_json.py | API reference | Sample response

---

(Experimental) Convert a plain PDF to CII with AI

Experimental feature. Human verification required before any production use.

Real-world PDF invoices are often messy: scanned at low quality, irregularly formatted, multi-page, or missing fields that EN 16931 requires. AI extraction can make subtle mistakes that automated validators may not catch: wrong tax category codes, transposed amounts, missing seller VAT identifiers, incorrect currency formatting.

Always review the output before sending it to a customer or tax authority. See the AI conversion notes in the main README.

The endpoint takes the PDF alone; no extra parameters are needed.

import requests

response = requests.post(
    "https://api.invoicexml.com/v1/transform/to/cii",
    headers={"Authorization": f"Bearer {api_key}"},
    files={"file": ("plain-invoice.pdf", open("plain-invoice.pdf", "rb"), "application/pdf")},
)

with open("converted-cii.xml", "w", encoding="utf-8") as f:
    f.write(response.text)

Full example: ai_convert.py | API reference

---

Render CII as a readable PDF in Python

CII is a machine format with no visual layer, so nobody can read it without tooling. This endpoint renders the XML into a formatted PDF preview, generated fresh from the structured data rather than extracted from any existing PDF layer, which makes it a quick way to eyeball what your XML actually says. The PDF is for reading only; the XML file remains the authoritative invoice for compliance and tax purposes.

import requests

response = requests.post(
    "https://api.invoicexml.com/v1/render/cii/to/pdf",
    headers={"Authorization": f"Bearer {api_key}"},
    files={"file": ("invoice.xml", open("invoice.xml", "rb"), "application/xml")},
    data={"language": "en"},   # en, de, or fr
)

with open("invoice-preview.pdf", "wb") as f:
    f.write(response.content)

Full example: render.py | API reference

---

Framework integration

Django

Return a CII invoice from a view:

from django.http import HttpResponse

def download_cii(request, invoice_id):
    pdf_bytes = create_cii_for(invoice_id)
    response = HttpResponse(pdf_bytes, content_type="application/pdf")
    response["Content-Disposition"] = f'attachment; filename="invoice-{invoice_id}.pdf"'
    return response

Store the API key in settings.py via INVOICEXML_API_KEY = os.environ["INVOICEXML_API_KEY"].

Flask

from flask import send_file
from io import BytesIO

@app.route("/invoices/<int:invoice_id>/cii")
def get_cii(invoice_id):
    pdf_bytes = create_cii_for(invoice_id)
    return send_file(BytesIO(pdf_bytes), mimetype="application/pdf",
                     as_attachment=True, download_name=f"invoice-{invoice_id}.pdf")

FastAPI

from fastapi.responses import Response

@app.get("/invoices/{invoice_id}/cii")
async def get_cii(invoice_id: int):
    pdf_bytes = create_cii_for(invoice_id)
    return Response(
        content=pdf_bytes,
        media_type="application/pdf",
        headers={"Content-Disposition": f'attachment; filename="invoice-{invoice_id}.pdf"'},
    )

Pandas and data pipelines

The extract_json.py example fits naturally into a Pandas pipeline: walk a folder of CII PDFs, extract each to JSON, and load into a DataFrame for analysis or bulk archival.

import pandas as pd, requests, os

rows = []
for pdf in os.listdir("invoices/"):
    with open(f"invoices/{pdf}", "rb") as f:
        data = requests.post(
            "https://api.invoicexml.com/v1/extract/json",
            headers={"Authorization": f"Bearer {api_key}"},
            files={"file": (pdf, f, "application/pdf")},
        ).json()
    rows.append(data)

df = pd.DataFrame(rows)

AWS Lambda

The requests library works in Lambda directly. Include it via Lambda layers or in your deployment zip.

---

Common issues

• HTTP 401 Unauthorized: API key missing or invalid. Generate one at invoicexml.com/account/authentication and confirm you are sending Authorization: Bearer YOUR_API_KEY. A frequent cause: setting api_key to the whole Bearer xxx value, which sends Bearer Bearer xxx. Set the raw key only.
• HTTP 400 Bad Request on Create: a required field is missing or malformed. Frequent causes: IssueDate not in ISO format (YYYY-MM-DD), Currency not in ISO 4217 (EUR, USD), country codes not in ISO 3166-1 alpha-2 (DE, FR).
• SSL: CERTIFICATE_VERIFY_FAILED on macOS: run /Applications/Python\ 3.x/Install\ Certificates.command to install Python's CA bundle. Do not disable SSL verification in production.
• ConnectionError or timeout: add an explicit timeout=30 parameter to requests.post(). AI conversion in particular can take 10 to 30 seconds for larger PDFs.
• File handle warnings: the examples use inline open() for brevity. For production code, prefer with open(...) as f: to ensure file handles close deterministically.
• Schematron BR-CO- failures on Validate*: line totals do not match the header total, or tax category and tax percentage are inconsistent. Recompute totals before posting.

---

Resources

• Get an InvoiceXML API key
• Create CII API reference
• Validate CII API reference
• Extract JSON API reference
• Extract XML API reference
• Transform to CII API reference
• requests library documentation
• Main repository README