An invoice a person and a machine both read

Produce an invoice a person reads, carrying inside the same file the data accounting reads on its own.

Written at the top level of a request, under "invoice"

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

An invoice has two audiences. A person looks at it and sees the lines, the amounts, the date. Accounting software wants the same figures sorted into boxes, so it can book them without anyone retyping. Both can live in one file: the page that is good to look at, and the sorted data tucked inside. France is bringing this in for businesses step by step, and the file stays a perfectly ordinary invoice to the eye.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

invoice attaches the invoicing XML to the document and states what it is: the profile of the standard it follows, its version, its relationship to the document, and when the data was last changed. The XML arrives alongside the request, in a form part carrying the name given here. An invoice wants the archiving standard that allows a file to be attached, so the request states "archive": "pdfa3b". The team has fixed the attached file's name at factur-x.xml.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

  • invoice — object, optional, absent by default.
  • invoice.xml — string, required. The name of the supplied part holding the XML. A name no part carries is refused.
  • invoice.profile — string, required, spelled as the standard spells it. Five values: "MINIMUM", "BASIC WL", "BASIC", "EN 16931", "EXTENDED".
  • invoice.version — string, optional, "1.0" by default. The version of the specification the XML follows.
  • invoice.relationship — string, required, with no default. Five values: source, alternative, data, supplement, unspecified. The profiles carrying only part of the invoice are data, those carrying all of it are alternative, and the sender alone knows which was written.
  • invoice.issued — string, required, in ISO 8601. When the invoice data was last changed, not when the PDF was built.
  • The request states "archive": "pdfa3b": with no archiving standard the invoice is refused, and under pdfa4 it is refused too, that part taking a file only if the file is itself archival.
  • The attached file is named factur-x.xml.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

One name below stands for a font file: put the encoded file in its place, or send the file itself beside the description, as a part of the same call.

{
  "archive": "pdfa3b",
  "invoice": {
    "xml": "invoice_xml",
    "profile": "MINIMUM",
    "relationship": "data",
    "issued": "2026-08-08T09:30:00+02:00"
  },
  "output_intent": { "identifier": "sRGB", "info": "sRGB IEC61966-2.1" },
  "metadata": {
    "title": "Invoice 2026-014",
    "created": "2026-08-08T09:30:00+02:00"
  },
  "fonts": [{ "name": "body", "data": "PASTE_THE_FONT_FILE_BASE64_HERE" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 768 },
      "content": ["Invoice 2026-014 — total 5 100.00 EUR"],
      "font": "body",
      "font_size": 16
    }
  ]
}

The line that sends it, in three languages

The document as a whole

The numbers the reader shows A hundred letters in a single file What the document says about itself A file still readable in thirty years The address relative links are read against The PDF version the file declares What an image says about itself

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

See the prices See the examples

Glossary

standard
A rule argued out in committee, published under a number anybody may buy and read, and identical for every firm claiming it. A claim to follow one can therefore be checked against the text. A way of working that merely spread because it worked is a habit of the trade: useful, widespread, and answerable to no text at all.
Factur-X
An invoice that is a page for a person and a data file for a machine, in one document. The page looks like any invoice; inside, the same amounts are attached in a form accounting software reads without anybody retyping them. French law requires this exchange between companies.
colour profile
A file that says what a colour actually looks like. Without one, the same red is one red on your screen and another on a press. A document meant for print carries the profile its colours were chosen against.
request
One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

Every word the site explains