Formats

xTool supports several e-invoicing formats. Each document has one format; it determines validation rules and available conversions and transforms. See Document model, Format models (field reference), Validate and convert, and API Reference for Format endpoints.

Each format has a unique format code; a format model (in essence, the file as read by xTool), which can be represented as JSON; and file content in its native form — XML, PDF, IDoc or other types depending on the format.

flowchart TB
    CODE["Unique format code"]
    MODEL["Format model (JSON)"]
    CONTENT["File content: XML, PDF"]
    CODE --- MODEL
    MODEL <-->|transformation| CONTENT

xTool formats (canonical hub)

xTool uses a shared internal field model. xtool.canonical.1_0 is the central hub for format conversion, PDF recognition, and AI extraction: source formats map into canonical, then canonical maps out to the target. Invoice vs credit note is expressed by document type (e.g. type_code 380 / 381), not by a separate hub format.

xtool.invoice.1_0 and xtool.credit_note.1_0 remain first-class working formats (stricter required fields, typed invoice / credit note). You can still create, store, send, and convert them; conversion between external standards goes through canonical.

flowchart LR
    SRC["Source format"]
    CAN["xtool.canonical.1_0"]
    TGT["Target format"]
    SRC --> CAN --> TGT

Format table

SFTP (outbound): A +format code in the file name on a Raw PDF triggers automatic PDF recognition, similar to manual conversion in the web app.

How format is used

• Documents — When you create or upload a document, you choose a format (or it is detected from XML). Validation and conversion use this format.
• API — The Format endpoints (validate model/XML, transform model↔XML, model→PDF, XML→model, XML→PDF, convert, detect XML) take or return a format code. See Validate and convert.

CSV import format (not a working format)

CSV is supported only as an import source for bringing invoice data into xTool — not as a document format you create, store, send, or convert via the Format API. After import, the document uses the internal xTool model. Column specification, file rules, and examples: CSV import format. How to import: Import documents.

Understanding field meanings (semantics)

To understand what each field means (invoice number, issue date, seller, buyer, line items, totals, etc.) and how to fill the form or API request body, see Format models (field reference). For a detailed section-by-section and field-by-field reference with JSON/XML examples, see Invoice model understanding. For examples, see Base invoice model example.

Choosing a format

• Peppol — Use a Peppol-supported format (e.g. Peppol BIS Billing, XRechnung UBL). See Peppol and Send via Peppol.
• Poland (KSeF) — FA(3) XML. See Connect to KSeF.
• France — France CIUS, Peppol BIS Billing France, or Factur-X France. See France e-invoicing.
• Public sector (e.g. Germany) — XRechnung and ZUGFeRD are commonly required.

Custom formats — we can implement a format to your requirements on request. Contact support.