# E-invoice to JSON (eu-einvoice-canonical) > TypeScript library, command line, HTTP API, MCP server and browser converter that read any XML e-invoice sent in the EU (Peppol BIS 3, XRechnung, Factur-X/ZUGFeRD, FatturaPA, KSeF, Facturae and many national formats, 44 in all) and map it to one canonical JSON model built on EN 16931. Version 1.2.0, licence 0BSD. The browser converter runs entirely client-side: files are never uploaded. Machine interfaces: - MCP server: run `einvoice mcp` (stdio) to give an agent the tools detect_invoice_format, convert_invoice, validate_invoice, explain_finding, check_duplicates, match_purchase_order and list_formats. See [MCP server for AI agents](https://alexcatdad.github.io/eu-einvoice-canonical/docs/mcp.md). - OpenAPI 3.1 spec: https://alexcatdad.github.io/eu-einvoice-canonical/openapi/openapi.yaml (JSON: https://alexcatdad.github.io/eu-einvoice-canonical/openapi/openapi.json), served by `einvoice serve`. - JSON Schemas: https://alexcatdad.github.io/eu-einvoice-canonical/schemas/canonical-invoice.v1.schema.json, https://alexcatdad.github.io/eu-einvoice-canonical/schemas/convert-result.v1.schema.json, https://alexcatdad.github.io/eu-einvoice-canonical/schemas/inspect-result.v1.schema.json. - Complete documentation as one text file: https://alexcatdad.github.io/eu-einvoice-canonical/llms-full.txt. ## Start - [eu-einvoice-canonical documentation](https://alexcatdad.github.io/eu-einvoice-canonical/docs/index.md): Documentation for eu-einvoice-canonical, which reads XML e-invoices from the EU (Peppol BIS 3, XRechnung, Factur-X, FatturaPA, KSeF) and converts them to JSON. - [Getting started](https://alexcatdad.github.io/eu-einvoice-canonical/docs/getting-started.md): Install and use eu-einvoice-canonical: convert(bytes) in TypeScript, opt-in field provenance, and how a parser reads the source XML. - [Site languages](https://alexcatdad.github.io/eu-einvoice-canonical/docs/languages.md): The browser converter speaks English, German, French, Italian, Spanish, Dutch, Polish and Romanian. How the language is chosen and how to correct a translation. ## Use it - [Command line](https://alexcatdad.github.io/eu-einvoice-canonical/docs/cli.md): The einvoice command line: detect, inspect, convert, export, render, write, match and find duplicates in e-invoices, with exit codes for scripts. - [MCP server for AI agents](https://alexcatdad.github.io/eu-einvoice-canonical/docs/mcp.md): Run einvoice mcp, a Model Context Protocol server that lets an AI agent detect, convert, validate and match e-invoices without network access. - [Conversion API (HTTP)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/http-api.md): The einvoice serve HTTP API (OpenAPI 3.1): convert, inspect, detect, list formats and fetch schemas, with RFC 9457 errors and a Docker image. - [EU trusted lists](https://alexcatdad.github.io/eu-einvoice-canonical/docs/trusted-lists.md): Check e-invoice signers against the EU List of Trusted Lists with signed snapshots, from the library, the CLI and the browser. - [Matching invoices to purchase orders](https://alexcatdad.github.io/eu-einvoice-canonical/docs/matching.md): Match e-invoice lines to purchase orders (two-way) and goods receipts (three-way), with tolerances and a match, within-tolerance or needs-review verdict. - [Bookkeeping export](https://alexcatdad.github.io/eu-einvoice-canonical/docs/export.md): Turn a received e-invoice into a balanced journal entry and export it as SIE 4, JSON or CSV with your own account mapping. - [Human-readable rendering](https://alexcatdad.github.io/eu-einvoice-canonical/docs/rendering.md): renderHtml and renderPdf turn a canonical e-invoice into a self-contained HTML page or an A4 PDF that a person can read, print or archive. - [Writing UBL and CII](https://alexcatdad.github.io/eu-einvoice-canonical/docs/writers.md): Write a canonical invoice back to Peppol BIS 3 UBL 2.1 or EN 16931 CII D16B with toUbl and toCii: deterministic, escaped and round-trip tested. ## Model and contracts - [The canonical model](https://alexcatdad.github.io/eu-einvoice-canonical/docs/canonical-model.md): The canonical invoice model: the EN 16931 core, EU-wide additions, clearance data, country extensions and where every value came from. - [Line roles and relations](https://alexcatdad.github.io/eu-einvoice-canonical/docs/line-roles-and-relations.md): How the converter tells items from headings and surcharge lines and links them with proven arithmetic, plus an optional in-browser language model for the rest. - [JSON Schema](https://alexcatdad.github.io/eu-einvoice-canonical/docs/json-schema.md): The published JSON Schemas (draft 2020-12) for the canonical invoice, the convert result and the inspect result, and how they are versioned. - [Deliverables and versioning](https://alexcatdad.github.io/eu-einvoice-canonical/docs/deliverables-and-versioning.md): What the project publishes (library, JSON Schemas, OpenAPI spec, CLI binaries, browser converter) and the compatibility promise between v1 and v2. ## Project - [What was tested](https://alexcatdad.github.io/eu-einvoice-canonical/docs/what-was-tested.md): The test suite behind the converter: detection, parsers, hostile input, decimal values, the known-answer sweep and the real-sample runs. - [Security](https://alexcatdad.github.io/eu-einvoice-canonical/docs/security.md): How the converter treats inbound e-invoices as hostile: DOCTYPE rejection, size and nesting limits, bounded ZIP and PDF decompression. - [Design decisions](https://alexcatdad.github.io/eu-einvoice-canonical/docs/decisions.md): Why VAT stays EN-shaped, why kind is only the accounting direction, which fields are required and how extensions are typed. - [Known gaps](https://alexcatdad.github.io/eu-einvoice-canonical/docs/known-gaps.md): What the converter does not do yet: unverified detection rules, EN 16931-1:2026, signature trust, national validation, PINT and ZATCA rules. - [License](https://alexcatdad.github.io/eu-einvoice-canonical/docs/license.md): eu-einvoice-canonical is released under the 0BSD licence; third-party sample files keep their own licences. - [Supply chain](https://alexcatdad.github.io/eu-einvoice-canonical/docs/supply-chain.md): What protects releases and CI, how to verify a download, and the repository settings the owner should apply . Nothing is published to npm. - [Canonical line annotations](https://alexcatdad.github.io/eu-einvoice-canonical/docs/line-annotations.md): This example interprets invoice lines using a selected view of the library's canonical JSON. Names, descriptions, notes, identifiers and financial context… ## Formats - [EU coverage](https://alexcatdad.github.io/eu-einvoice-canonical/docs/eu-coverage.md): Which e-invoice formats you will receive from each of the 27 EU member states, with mandate dates and notes. - [Beyond the EU](https://alexcatdad.github.io/eu-einvoice-canonical/docs/beyond-the-eu.md): Peppol PINT (Singapore, Australia, New Zealand, Japan, Malaysia, UAE) and Saudi ZATCA invoices, mapped on top of the UBL parser. - [Build order and mapping notes](https://alexcatdad.github.io/eu-einvoice-canonical/docs/build-order.md): The parser families in the order they were built, with the mapping notes for each national e-invoice format. - [Mexico: CFDI](https://alexcatdad.github.io/eu-einvoice-canonical/docs/mexico-cfdi.md): How a Mexican CFDI 3.3 or 4.0 invoice maps to the canonical model: taxes, withholdings, payments, the SAT stamp, and what the model cannot say. - [Supported e-invoice formats](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/index.md): The 44 e-invoice formats eu-einvoice-canonical detects and converts: Peppol BIS 3, XRechnung, Factur-X, FatturaPA, KSeF, Facturae and more, by country. - [XRechnung (UBL)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/xrechnung-ubl.md): How XRechnung (UBL) e-invoices are detected and mapped to canonical JSON. Used in DE. German CIUS. - [NLCIUS (UBL)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/nlcius-ubl.md): How NLCIUS (UBL) e-invoices are detected and mapped to canonical JSON. Used in NL. Dutch CIUS (SI-UBL 2.0). - [RO e-Factura (CIUS-RO)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/cius-ro.md): How RO e-Factura (CIUS-RO) e-invoices are detected and mapped to canonical JSON. Used in RO. Downloaded from ANAF SPV as a ZIP holding the invoice and a… - [CIUS-PT](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/cius-pt.md): How CIUS-PT e-invoices are detected and mapped to canonical JSON. Used in PT. Portuguese CIUS for public procurement. - [HR-CIUS (Fiskalizacija 2.0)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/hr-cius.md): How HR-CIUS (Fiskalizacija 2.0) e-invoices are detected and mapped to canonical JSON. Used in HR. Croatian CIUS + HR extensions, mandatory B2B and B2G since… - [France CTC (UBL)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/fr-ctc-ubl.md): How France CTC (UBL) e-invoices are detected and mapped to canonical JSON. Used in FR. French reform (XP Z12-012), receiving obligation from 1 Sep 2026. - [OIOUBL 3.0](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/oioubl-3.md): How OIOUBL 3.0 e-invoices are detected and mapped to canonical JSON. Used in DK. Danish UBL 2.1 profile aligned with Peppol BIS 3. - [Poland PEF (Peppol BIS 3 + PL extension)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pl-pef.md): How Poland PEF (Peppol BIS 3 + PL extension) e-invoices are detected and mapped to canonical JSON. Used in PL. Public-procurement invoices via PEF… - [Peppol BIS Billing 3.0](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/peppol-bis3.md): How Peppol BIS Billing 3.0 e-invoices are detected and mapped to canonical JSON. Used in AT, BE, BG, HR, CY, CZ, DK, EE, FI, GR, HU, IE, LV, LT, LU, MT, NL,… - [Peppol BIS Self-Billing 3.0](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/peppol-bis3-selfbilling.md): How Peppol BIS Self-Billing 3.0 e-invoices are detected and mapped to canonical JSON. Self-billed invoices; seller and buyer roles stay as in EN 16931. - [Peppol PINT Singapore (InvoiceNow)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pint-sg.md): How Peppol PINT Singapore (InvoiceNow) e-invoices are detected and mapped to canonical JSON. InvoiceNow (IMDA). - [Peppol PINT Australia and New Zealand](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pint-aunz.md): How Peppol PINT Australia and New Zealand e-invoices are detected and mapped to canonical JSON. One specification for both countries; billing and… - [Peppol PINT Japan](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pint-jp.md): How Peppol PINT Japan e-invoices are detected and mapped to canonical JSON. Japanese qualified invoice (Peppol e-invoice, from Oct 2023). - [Peppol PINT Malaysia (MyInvois)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pint-my.md): How Peppol PINT Malaysia (MyInvois) e-invoices are detected and mapped to canonical JSON. Aligned with LHDN MyInvois. - [Peppol PINT United Arab Emirates](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pint-ae.md): How Peppol PINT United Arab Emirates e-invoices are detected and mapped to canonical JSON. UAE e-invoicing (five-corner model). - [Peppol PINT Oman](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pint-om.md): How Peppol PINT Oman e-invoices are detected and mapped to canonical JSON. Oman e-invoicing (Peppol PINT OM). - [Peppol PINT EU](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/pint-eu.md): How Peppol PINT EU e-invoices are detected and mapped to canonical JSON. PINT EU (urn:peppol:pint:billing-1@eu-1), the PINT specialisation for the European… - [Peppol PINT (base and other jurisdictions)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/peppol-pint.md): How Peppol PINT (base and other jurisdictions) e-invoices are detected and mapped to canonical JSON. Peppol International model: the PINT base… - [Saudi ZATCA e-invoice (UBL, KSA profile)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/zatca-ubl.md): How Saudi ZATCA e-invoice (UBL, KSA profile) e-invoices are detected and mapped to canonical JSON. FATOORA phase 2: standard (B2B/B2G, cleared) and… - [UBL.BE](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/ubl-be.md): How UBL.BE e-invoices are detected and mapped to canonical JSON. Used in BE. Belgian EN 16931 extension used before the Peppol BIS 3 B2B mandate. - [EN 16931 (UBL), no CIUS](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/en16931-ubl.md): How EN 16931 (UBL), no CIUS e-invoices are detected and mapped to canonical JSON. Used in BG, EE, FR. Bare EN 16931 or an unknown CIUS of it. - [Peppol BIS 2 / CEN BII (incl. Svefaktura BIS 5A, EHF 2)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/peppol-bis2.md): How Peppol BIS 2 / CEN BII (incl. Svefaktura BIS 5A, EHF 2) e-invoices are detected and mapped to canonical JSON. Used in NL. Pre-EN 16931 Peppol profiles,… - [OIOUBL 2.x](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/oioubl-2.md): How OIOUBL 2.x e-invoices are detected and mapped to canonical JSON. Used in DK. Danish profile on UBL 2.0 (same namespaces as UBL 2.1). - [XRechnung (CII)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/xrechnung-cii.md): How XRechnung (CII) e-invoices are detected and mapped to canonical JSON. Used in DE. German CIUS in CII syntax. - [NLCIUS (CII)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/nlcius-cii.md): How NLCIUS (CII) e-invoices are detected and mapped to canonical JSON. Used in NL. Dutch CIUS in CII syntax. - [France CTC (CII / Factur-X EXTENDED-CTC-FR)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/fr-ctc-cii.md): How France CTC (CII / Factur-X EXTENDED-CTC-FR) e-invoices are detected and mapped to canonical JSON. Used in FR. French reform uses CII D22B. - [Factur-X / ZUGFeRD 2.x](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/facturx.md): How Factur-X / ZUGFeRD 2.x e-invoices are detected and mapped to canonical JSON. Used in FR, DE. Hybrid PDF/A-3 + CII. - [EN 16931 (CII), no CIUS](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/en16931-cii.md): How EN 16931 (CII), no CIUS e-invoices are detected and mapped to canonical JSON. Used in BG, FR. Bare EN 16931 CII, or an unknown CIUS of it. - [ZUGFeRD 1.0](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/zugferd-1.md): How ZUGFeRD 1.0 e-invoices are detected and mapped to canonical JSON. Used in DE. CII D13B-era CrossIndustryDocument, usually inside a PDF… - [FatturaPA](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/fatturapa.md): How FatturaPA e-invoices are detected and mapped to canonical JSON. Used in IT. All Italian domestic B2B/B2G invoices go through SdI. - [FatturaPA semplificata](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/fatturapa-semplificata.md): How FatturaPA semplificata e-invoices are detected and mapped to canonical JSON. Used in IT. Simplified invoice (FSM10) for small amounts. - [KSeF FA(2)/FA(3)/FA_RR](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/ksef.md): How KSeF FA(2)/FA(3)/FA_RR e-invoices are detected and mapped to canonical JSON. Used in PL. Mandatory structured invoice in Poland (large taxpayers from 1… - [Facturae](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/facturae.md): How Facturae e-invoices are detected and mapped to canonical JSON. Used in ES. Spanish format, mandatory for B2G via FACe; one of the formats allowed under… - [ISDOC](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/isdoc.md): How ISDOC e-invoices are detected and mapped to canonical JSON. Used in CZ. Czech format. - [ebInterface](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/ebinterface.md): How ebInterface e-invoices are detected and mapped to canonical JSON. Used in AT. Austrian format. - [ebInterface 2.x](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/ebinterface-2.md): How ebInterface 2.x e-invoices are detected and mapped to canonical JSON. Used in AT. ebInterface 2.0-2.2 (namespaced). - [Finvoice](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/finvoice.md): How Finvoice e-invoices are detected and mapped to canonical JSON. Used in FI. Finnish bank-network format. - [TEAPPSXML](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/teappsxml.md): How TEAPPSXML e-invoices are detected and mapped to canonical JSON. Used in FI. Finnish operator format (TietoEVRY). - [Estonian e-invoice (e-arve)](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/e-arve.md): How Estonian e-invoice (e-arve) e-invoices are detected and mapped to canonical JSON. Used in EE. No namespace. - [eSLOG 2.0](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/eslog-2.md): How eSLOG 2.0 e-invoices are detected and mapped to canonical JSON. Used in SI. Slovenian EN 16931-aligned format with EDIFACT-style segment names. - [eSLOG 1.6](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/eslog-1.md): How eSLOG 1.6 e-invoices are detected and mapped to canonical JSON. Used in SI. Pre-EN Slovenian format (simple invoice, root IzdaniRacunEnostavni, no… - [Svefaktura 1.0](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/svefaktura-1.md): How Svefaktura 1.0 e-invoices are detected and mapped to canonical JSON. Used in SE. Withdrawn by SFTI in 2021 but still used B2B via operators. - [Greece myDATA invoice XML](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/gr-mydata.md): How Greece myDATA invoice XML e-invoices are detected and mapped to canonical JSON. Used in GR. AADE myDATA document (InvoicesDoc, or the RequestedDoc… - [Mexico CFDI 3.3 / 4.0](https://alexcatdad.github.io/eu-einvoice-canonical/docs/formats/mx-cfdi.md): How Mexico CFDI 3.3 / 4.0 e-invoices are detected and mapped to canonical JSON. Mexican tax-authority invoice (cfdi:Comprobante), stamped by an authorised… ## Optional - [Browser converter](https://alexcatdad.github.io/eu-einvoice-canonical/): drop an invoice, get canonical JSON. - [Conformance checklist](https://alexcatdad.github.io/eu-einvoice-canonical/conformance/): fixtures, parser, real samples, mapping source and validation per format. - [Real-world results](https://alexcatdad.github.io/eu-einvoice-canonical/corpus/): the converter run over public sample collections. - [Line labelling evaluation](https://alexcatdad.github.io/eu-einvoice-canonical/eval/): the rules and the optional language models scored on a labelled set. - [API reference](https://alexcatdad.github.io/eu-einvoice-canonical/api-reference/) and [TypeScript API](https://alexcatdad.github.io/eu-einvoice-canonical/api/). - [Source code](https://github.com/alexcatdad/eu-einvoice-canonical)