Factur-X Creation API Reference

Technical reference for generating Factur-X hybrid invoices from a structured JSON request. Submit seller, buyer and line items, totals and the tax breakdown are calculated automatically. The API returns a Factur-X EN 16931 (Comfort) PDF/A-3 with embedded factur-x.xml, validated against the full EN 16931 rule set before delivery, ready for exchange in France, Germany, and across the EU.

Two ways to get a compliant PDF

Let InvoiceXML design the document from your data, or keep your own PDF layout and have us make it Factur-X compliant. Either way you get back a valid PDF/A-3 with the structured XML embedded.

We generate the PDF

Send only your invoice data and the API renders a clean, branded Factur-X PDF for you. Tune the look with options.brandColor, your logo (options.logoUrl or options.logo) and options.language.

Bring your own PDF

Already have a designed invoice PDF? Pass its public URL as options.pdfUrl and we embed the compliant Factur-X XML into it, keeping your exact layout, fonts, and branding.

POST https://api.invoicexml.com/v1/create/facturx

Quickstart

A minimal request, copy, paste, get a compliant invoice back.

curl -X POST https://api.invoicexml.com/v1/create/facturx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o invoice-facturx.pdf \
  -d '{
  "invoice": {
    "invoiceNumber": "INV-2025-001",
    "issueDate": "2025-07-01",
    "currency": "EUR",
    "seller": {
      "name": "Acme GmbH",
      "vatIdentifier": "DE123456789",
      "legalRegistration": { "identifier": "HRB98765" },
      "postalAddress": {
        "line1": "Musterstr. 1",
        "city": "Berlin",
        "postCode": "10115",
        "country": "DE"
      }
    },
    "buyer": {
      "name": "Example Corp",
      "postalAddress": {
        "line1": "12 Rue de Rivoli",
        "city": "Paris",
        "postCode": "75001",
        "country": "FR"
      }
    },
    "paymentDetails": {
      "paymentAccountIdentifier": "DE89370400440532013000"
    },
    "lines": [
      {
        "quantity": 10,
        "priceDetails": { "netPrice": 150.00 },
        "vatInformation": { "rate": 19 },
        "item": { "name": "Consulting Services" }
      }
    ]
  },
  "options": {
    "language": "en",
    "brandColor": "#173a40",
    "logoUrl": "https://example.com/logo.png",
    "validationLanguage": "fr"
  }
}'

That's the whole request, the API fills in the rest.

invoice.totals and invoice.vatBreakdowns are calculated from line items.
invoice.typeCode defaults to 380 (commercial invoice), specificationId is set per standard.
The options object is optional. Every field has a sensible default, see Options below.

French mandate rules on demand

For invoices bound for the French exchange network (a Plateforme Agréée or the PPF), add options.rules with br-fr and the generated invoice is additionally validated against the BR-FR Flux 2 rules of the French CTC mandate, the same rule set the French platforms apply to every domestic invoice:

"options": {
  "rules": ["br-fr"]
}

The declared profile stays in charge: the specification identifier (BT-24) is not changed, the profile's own validation still runs, and the mandate rules are checked on top. Violations come back as regular 4001 findings whose rule ids start with BR-FR, for example a missing SIREN legal registration, a missing coded payment-terms mention, or an invalid French VAT rate. The mandate reads header-only documents as booking aids rather than invoices, so requests declaring the MINIMUM or BASIC WL profile are rejected with a 400; use BASIC, EN 16931 or EXTENDED.

Validation messages in German or French

When a request is rejected, every finding carries a plain-language message you can show to your users. They are written in English unless options.validationLanguage asks for German or French:

"options": {
  "validationLanguage": "fr"
}

Only the message changes. rule, btCodes, fields and raw stay the same in every language, so keep matching on them. The option is independent of options.language, which sets the language of the invoice itself, and a value other than en, de or fr is rejected with a 400 (errorCode 4002). Localized error messages lists which rules have German and French wording.

Try it out online, no coding required

Fill in the form and download a compliant invoice instantly, right in your browser.

Try It Online

Request body

Send invoice data as application/json. The body has two top-level keys: invoice (required) and options (optional). Browse the fields below; toggle Required only for the minimal payload, or filter by name.

POST /v1/create/facturx Request body

invoiceobjectrequired26 fields · 7 requiredThe invoice document. Holds all business terms and groups defined by EN 16931.

invoiceNumberstringrequiredBT-1Unique invoice identifier.

issueDatedaterequiredBT-2Date the invoice was issued, in YYYY-MM-DD format.

currencystringrequiredBT-5ISO 4217 currency code (e.g. EUR, USD, GBP).

buyerReferencestringoptionalBT-10Free-text reference used by the buyer's accounting system.

sellerobjectrequired10 fields · 2 requiredBG-4The party issuing the invoice.

namestringrequiredBT-27Legal business name.

vatIdentifierstringoptionalBT-31VAT identification number, including country prefix (e.g. DE123456789). At least one seller identifier (this, legalRegistration.identifier, or an identifiers[] entry) is required by EN 16931 BR-CO-26.

postalAddressobjectrequired7 fields · 1 requiredBG-5Seller's postal address.

line1stringoptionalBT-35Street address, line 1.

citystringoptionalBT-37City name.

postCodestringoptionalBT-38Postal or ZIP code.

countrystringrequiredBT-40ISO 3166-1 alpha-2 country code (e.g. DE, FR).

line2stringoptionalBT-36Address line 2.

line3stringoptionalBT-162Address line 3.

countrySubdivisionstringoptionalBT-39Region or state (e.g. Bayern).

contactobjectoptional3 fieldsBG-6Seller contact person.

namestringoptionalBT-41Contact person's name.

phonestringoptionalBT-42Contact phone number.

emailstringoptionalBT-43Contact email address.

electronicAddressobjectoptional2 fieldsBT-34Electronic routing endpoint, used by Peppol and similar networks.

identifierstringoptionalBT-34Endpoint identifier (email, GLN, VAT number, etc.).

schemeIdstringoptionalBT-34-1Peppol Electronic Address Scheme (EAS) code. Common values: 9930 (German VAT), 0204 (German Leitweg-ID), 0088 (GS1 GLN), 0192 (Norwegian Organisasjonsnummer), 9957 (French VAT). The full set is large and country-specific, so see the official EAS code list for every value.

legalRegistrationobjectoptional2 fieldsBT-30Legal company registration (e.g. SIRET in France, HRB in Germany).

identifierstringoptionalBT-30Registration number (e.g. HRB98765). Required when legalRegistration is present.

schemeIdstringoptionalBT-30-1Scheme code for the registration number (e.g. 0002 SIRENE, 0007 Sweden Bolagsverket).

tradingNamestringoptionalBT-28Trading name, if different from the legal business name.

taxRegistrationIdentifierstringoptionalBT-32National tax registration ID, when distinct from the VAT ID.

additionalLegalInformationstringoptionalBT-33Free-text additional legal information (e.g. share capital, registration court).

identifiersobject[]optional2 fieldsBT-29Additional seller identifiers (e.g. GLN, DUNS). 0..n entries.

identifierstringoptionalBT-29Identifier value. Required when an identifiers entry is included.

schemeIdstringoptionalBT-29-1Scheme code for the identifier (e.g. 0088 GLN, 0060 DUNS).

buyerobjectrequired8 fields · 2 requiredBG-7The party receiving the invoice.

namestringrequiredBT-44Legal business name.

vatIdentifierstringoptionalBT-48Buyer VAT ID. Required for EU cross-border and reverse-charge invoices.

postalAddressobjectrequired7 fields · 1 requiredBG-8Buyer's postal address.

line1stringoptionalBT-50Street address, line 1.

citystringoptionalBT-52City name.

postCodestringoptionalBT-53Postal or ZIP code.

countrystringrequiredBT-55ISO 3166-1 alpha-2 country code.

line2stringoptionalBT-51Address line 2.

line3stringoptionalBT-163Address line 3.

countrySubdivisionstringoptionalBT-54Region or state.

electronicAddressobjectoptional2 fieldsBT-49Electronic routing endpoint for the buyer.

identifierstringoptionalBT-49Endpoint identifier.

schemeIdstringoptionalBT-49-1Peppol EAS scheme code. See seller.electronicAddress.schemeId for common values and the full EAS code list.

tradingNamestringoptionalBT-45Trading name, if different from the legal name.

legalRegistrationobjectoptional2 fieldsBT-47Buyer's legal company registration.

identifierstringoptionalBT-47Registration number. Required when legalRegistration is present.

schemeIdstringoptionalBT-47-1Scheme code for the registration number.

identifiersobject[]optional2 fieldsBT-46Additional buyer identifiers (e.g. GLN, DUNS). 0..n entries.

identifierstringoptionalBT-46Identifier value. Required when an identifiers entry is included.

schemeIdstringoptionalBT-46-1Scheme code for the identifier (e.g. 0088 GLN, 0060 DUNS).

contactobjectoptional3 fieldsBG-9Buyer contact person.

namestringoptionalBT-56Contact person's name.

phonestringoptionalBT-57Contact phone number.

emailstringoptionalBT-58Contact email address.

paymentDetailsobjectrequired8 fields · 1 requiredBG-16Payment instructions for the buyer. Defaults to a SEPA credit transfer.

paymentAccountIdentifierstringrequiredBT-84IBAN or other account identifier (e.g. DE89370400440532013000).

paymentMeansCodestringoptionalBT-81UNTDID 4461 payment means code. Defaults to 30 (credit transfer). Common values: 30 (credit transfer), 58 (SEPA credit transfer), 59 (SEPA direct debit), 48 (bank card), 49 (direct debit), 10 (cash). Accepts any code from the UNTDID 4461 code list; the readable names (e.g. CreditTransfer) also work.

paymentMeansTextstringoptionalBT-82Free-text description of the payment means.

remittanceInformationstringoptionalBT-83Remittance reference shown on the bank transfer.

paymentAccountNamestringoptionalBT-85Account holder name.

bicstringoptionalBT-86BIC / SWIFT code.

mandateReferencestringoptionalBT-89SEPA direct debit mandate reference.

paymentTermsstringoptionalBT-20Free-text payment terms (e.g. Net 30 days).

linesobject[]required14 fields · 4 requiredBG-25Invoice line items. At least one line is required (rule BR-16). Each line is independently VAT-categorised.

quantitydecimalrequiredBT-129Invoiced quantity. Negative values are allowed, e.g. a returned item or a credit note line.

itemobjectrequired8 fields · 1 requiredBG-31The good or service being invoiced.

namestringrequiredBT-153Item name shown on the invoice.

descriptionstringoptionalBT-154Longer item description (e.g. a components list).

sellerIdentifierstringoptionalBT-155Item identifier in the seller's catalogue.

buyerIdentifierstringoptionalBT-156Item identifier in the buyer's catalogue.

countryOfOriginstringoptionalBT-159ISO 3166-1 alpha-2 country code.

standardIdentifierobjectoptional2 fieldsBT-157Standardised item identifier, e.g. GTIN.

identifierstringoptionalBT-157Identifier value (e.g. a GTIN).

schemeIdstringoptionalBT-157-1Scheme code (e.g. 0160 for GTIN).

classificationsobject[]optional3 fieldsBT-158Item classifications (UNSPSC, eClass, etc.). 0..n entries.

identifierstringoptionalBT-158Classification code value.

schemeIdstringoptionalBT-158-1Classification scheme (e.g. TST).

schemeVersionstringoptionalBT-158-2Scheme version.

attributesobject[]optional2 fieldsBG-32Free-form name/value pairs describing the item, e.g. Colour = Red or a serial number. Shown on the invoice under the item. 0..n entries.

namestringoptionalBT-160Attribute name. Required when an attributes entry is included.

valuestringoptionalBT-161Attribute value. Required when an attributes entry is included.

priceDetailsobjectrequired5 fieldsBG-29Per-unit pricing for this line.

netPricedecimaloptionalBT-146Net unit price, excluding VAT. Required unless grossPrice is given, in which case it is calculated as gross price minus discountAmount.

discountAmountdecimaloptionalBT-147Discount applied to the unit price.

grossPricedecimaloptionalBT-148Unit price before discount.

priceBaseQuantitydecimaloptionalBT-149Quantity the unit price refers to (e.g. price per 100 units). Defaults to 1.

priceBaseUnitstringoptionalBT-150Unit-of-measure code for the base quantity. Same UN/ECE Rec 20 values as unitCode.

vatInformationobjectrequired2 fields · 1 requiredBG-30VAT treatment for this line. Drives how lines are grouped into the document-level VAT breakdown.

ratedecimalrequiredBT-152VAT rate as a percentage (e.g. 19 for 19%, 0 for zero-rated).

categoryCodestringoptionalBT-151VAT category code. Defaults to S (standard rated).

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

lineIdstringoptionalBT-126Line identifier. Auto-generated as 1, 2, … when omitted.

lineNotestringoptionalBT-127Free-text note shown on the invoice line.

unitCodestringoptionalBT-130UN/ECE Rec 20 unit-of-measure code. Defaults to H87 (piece). Common values: H87 (piece), HUR (hour), DAY (day), KGM (kilogram), MTR (metre), LTR (litre). C62 (one) is accepted as well. The list runs to several hundred codes, so see the official UN/ECE Rec 20 code list for every value.

lineNetAmountdecimaloptionalBT-131Line total before VAT. Auto-calculated when omitted as quantity × priceDetails.netPrice, plus any line charges and minus any line allowances.

buyerOrderLineReferencestringoptionalBT-132Buyer purchase order line reference.

lineBuyerAccountingReferencestringoptionalBT-133Buyer's accounting cost-centre reference for this line.

objectIdentifierobjectoptional2 fieldsBT-128Identifier of the object this line refers to (e.g. a subscription or asset ID).

identifierstringoptionalBT-128Identifier value.

schemeIdstringoptionalBT-128-1Scheme code for the identifier.

linePeriodobjectoptional2 fieldsBG-26Service period this line covers, when different from the document-level invoicingPeriod.

startDatedateoptionalBT-134Line period start date, YYYY-MM-DD.

endDatedateoptionalBT-135Line period end date, YYYY-MM-DD.

allowancesobject[]optional5 fieldsBG-27Discounts that apply to this one line only, deducted before VAT. They inherit the line's VAT category. 0..n entries.

amountdecimaloptionalBT-136Allowance amount. Required unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

baseAmountdecimaloptionalBT-137Base amount the percentage is calculated from.

percentagedecimaloptionalBT-138Allowance as a percentage of the base amount.

reasonstringoptionalBT-139Free-text reason for the allowance.

reasonCodestringoptionalBT-140UNTDID 5189 allowance reason code.

chargesobject[]optional5 fieldsBG-28Surcharges that apply to this one line only (e.g. a per-item handling fee). They inherit the line's VAT category. For invoice-wide shipping, use the document-level charges instead. 0..n entries.

amountdecimaloptionalBT-141Charge amount. Required unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

baseAmountdecimaloptionalBT-142Base amount the percentage is calculated from.

percentagedecimaloptionalBT-143Charge as a percentage of the base amount.

reasonstringoptionalBT-144Free-text reason for the charge.

reasonCodestringoptionalBT-145UNTDID 7161 charge reason code.

totalsobjectoptional10 fieldsBG-22Document totals. Every amount is computed from your lines, charges and allowances, so the whole object is optional. paidAmount and roundingAmount are inputs rather than results; set any other field to override the calculation.

paidAmountdecimaloptionalBT-113Amount already paid, e.g. a deposit, down payment or prepaid amount. Carries no VAT and is subtracted from the grand total to give the amount due. A deposit belongs here, not in the lines.

roundingAmountdecimaloptionalBT-114Rounding adjustment added to the grand total when computing the amount due.

sumOfLineNetAmountsdecimaloptionalBT-106Sum of all line net amounts.

sumOfAllowancesdecimaloptionalBT-107Sum of document-level allowances.

sumOfChargesdecimaloptionalBT-108Sum of document-level charges.

taxBasisTotalAmountdecimaloptionalBT-109Total without VAT: line nets minus allowances plus charges.

taxTotalAmountdecimaloptionalBT-110Total VAT amount across all breakdowns.

taxTotalAmountInAccountingCurrencydecimaloptionalBT-111Total VAT in the accounting currency, when taxCurrency differs from currency.

grandTotalAmountdecimaloptionalBT-112Total with VAT: tax basis plus total VAT.

duePayableAmountdecimaloptionalBT-115Amount due: grand total minus paidAmount plus roundingAmount.

vatBreakdownsobject[]optional6 fieldsBG-23VAT breakdown per category and rate. Auto-generated from lines, document charges and document allowances grouped by (categoryCode, rate). Entries with amounts replace the generated breakdown. To only add an exemption reason, send an entry without amounts, e.g. { "categoryCode": "E", "exemptionReasonText": "..." }: the breakdown is still generated and the reason goes on the matching category (and rate, if given). 0..n entries.

taxableAmountdecimaloptionalBT-116Net amount taxed at this category and rate.

taxAmountdecimaloptionalBT-117VAT charged on the taxable amount.

categoryCodestringoptionalBT-118VAT category for this breakdown.

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

ratedecimaloptionalBT-119VAT rate as a percentage.

exemptionReasonTextstringoptionalBT-120Reason the amount is exempt or zero-rated. Auto-filled for reverse charge, intra-community, export and not subject to VAT (AE, K, G, O). Required for exempt (E), which covers many legal bases.

exemptionReasonCodestringoptionalBT-121Coded exemption reason (e.g. VATEX-EU-AE). Auto-resolved for AE, K, G and O.

dueDatedateoptionalBT-9Payment due date, YYYY-MM-DD. Never invented: when omitted, no due date is written and the payment terms (BT-20) state that the invoice is payable on receipt, unless you supply paymentDetails.paymentTerms yourself.

typeCodestringoptionalBT-3UNTDID 1001 document type. Defaults to 380. Progress and instalment invoices use 875 (construction, Abschlagsrechnung) or 326 (other trades); 386 is a request for payment before delivery. 389 is a self-billed invoice, issued by the buyer on the seller's behalf, and 261 credits one. Credit notes (381, 261) carry positive amounts and reference the original invoice in precedingInvoiceReferences. XRechnung's BR-DE-17 expects one of 326, 380, 381, 384, 389, 875, 876 or 877 and flags any other code with a warning.

Allowed values

380Commercial invoice (default)

381Credit note

384Corrected invoice

326Partial invoice

875Partial construction invoice

876Partial final construction invoice

877Final construction invoice

386Prepayment invoice

383Debit note

389Self-billed invoice

261Self-billed credit note

specificationIdstringoptionalBT-24EN 16931 specification identifier. Auto-set per standard, override only if you know what you are doing. An official Factur-X/ZUGFeRD profile URN selects that profile. For the header-only booking-aid profiles (urn:factur-x.eu:1p0:minimum, :basicwl, or their zugferd.de:2p0 equivalents) the embedded XML carries the profile's official header subset while the rendered PDF, the legal invoice for those profiles, shows the full line data; line items remain required and the header totals must be internally consistent.

taxCurrencystringoptionalBT-6VAT accounting currency, if different from currency.

vatPointDateCodestringoptionalBT-8UNTDID 2005 code stating when VAT becomes due.

Allowed values

3Invoice issue date

35Delivery date

432Paid to date

businessProcessTypestringoptionalBT-23Business process identifier (e.g. urn:fdc:peppol.eu:2017:poacc:billing:01:1.0).

contractReferencestringoptionalBT-12Number of the contract the invoice is issued under.

purchaseOrderReferencestringoptionalBT-13Buyer purchase order reference.

despatchAdviceReferencestringoptionalBT-16Delivery note number of the shipment this invoice covers.

notes(string | object)[]optionalBT-22Invoice notes, 0..n entries. Each entry is either a plain string, or an object { "subjectCode": "PMT", "note": "..." } carrying a UNTDID 4451 subject code (BT-21). The coded form is how the French mandate's mandatory mentions travel: PMT recovery costs, PMD late-payment penalties, AAB discount terms.

invoicingPeriodobjectoptional2 fieldsBG-14Billing or service period the whole invoice covers.

startDatedateoptionalBT-73Period start date, YYYY-MM-DD.

endDatedateoptionalBT-74Period end date, YYYY-MM-DD.

precedingInvoiceReferencesobject[]optional2 fieldsBG-3References to the invoice(s) this document amends. Expected on a credit note (381) or corrected invoice (384). 0..n entries.

referencestringoptionalBT-25Preceding invoice number. Required when an entry is included.

issueDatedateoptionalBT-26Issue date of the preceding invoice, YYYY-MM-DD.

supportingDocumentsobject[]optional8 fieldsBG-24References to documents that substantiate the invoice (a timesheet, a purchase order copy, an annexe PDF), optionally with the file itself embedded as base64. 0..n entries.

referencestringoptionalBT-122Identifier of the supporting document. Required when a supportingDocuments entry is included.

documentTypeCodestringoptionalBT-122-0UNTDID 1001 document type code. Defaults to 916.

Allowed values

916Related document (default)

50Tender or lot reference (BT-17)

130Invoiced object identifier (BT-18)

schemeIdstringoptionalBT-18-1Identification scheme of the reference. Only meaningful for invoiced object identifiers (documentTypeCode 130).

descriptionstringoptionalBT-123Free-text description of the supporting document.

externalUristringoptionalBT-124URL where the document can be downloaded.

attachmentstringoptionalBT-125The embedded document, base64 encoded.

attachmentMimeCodestringoptionalBT-125-1MIME type of the attached document. EN 16931 allows only the listed values.

Allowed values

application/pdfPDF

image/pngPNG image

image/jpegJPEG image

text/csvCSV

application/vnd.openxmlformats-officedocument.spreadsheetml.sheetExcel spreadsheet (xlsx)

application/vnd.oasis.opendocument.spreadsheetOpenDocument spreadsheet (ods)

attachmentFilenamestringoptionalBT-125-2Filename of the attached document, e.g. timesheet-july.pdf.

allowancesobject[]optional7 fieldsBG-20Discounts applied to the whole invoice (e.g. a loyalty discount), deducted from the tax basis before VAT. Unlike line allowances, each carries its own VAT category and rate. 0..n entries.

amountdecimaloptionalBT-92Allowance amount. Required unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

vatCategoryCodestringoptionalBT-95VAT category the allowance is taxed under. Required when an allowances entry is included.

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

vatRatedecimaloptionalBT-96VAT rate as a percentage (e.g. 19). Required when the category is S.

baseAmountdecimaloptionalBT-93Base amount the percentage is calculated from.

percentagedecimaloptionalBT-94Allowance as a percentage of the base amount.

reasonstringoptionalBT-97Free-text reason for the allowance.

reasonCodestringoptionalBT-98UNTDID 5189 allowance reason code.

chargesobject[]optional7 fieldsBG-21Invoice-wide shipping, freight, packaging or handling fees belong here (not in the lines). Each charge is added to the tax basis and taxed at its own VAT rate. The reason becomes the label on the PDF and in the XML. 0..n entries.

amountdecimaloptionalBT-99Charge amount. Required unless baseAmount and percentage are given, in which case it is calculated as base amount × percentage / 100.

vatCategoryCodestringoptionalBT-102VAT category the charge is taxed under. Required when a charges entry is included.

Allowed values

SStandard rated

ZZero rated

EExempt from VAT

AEReverse charge

KIntra-Community supply (EU)

GExport outside the EU

ONot subject to VAT

vatRatedecimaloptionalBT-103VAT rate as a percentage (e.g. 19). Required when the category is S. Usually matches the rate of the goods being shipped.

baseAmountdecimaloptionalBT-100Base amount the percentage is calculated from.

percentagedecimaloptionalBT-101Charge as a percentage of the base amount.

reasonstringoptionalBT-104Free-text reason for the charge, e.g. Shipping. Shown as the line label on the PDF.

reasonCodestringoptionalBT-105UNTDID 7161 charge reason code (e.g. FC for freight).

deliveryobjectoptional5 fieldsBG-13Delivery information, when different from the buyer's billing address.

receiverNamestringoptionalBT-70Deliver-to party name.

locationIdentifierstringoptionalBT-71Deliver-to location identifier (e.g. GLN).

locationIdentifierSchemeIdstringoptionalBT-71-1ISO 6523 ICD scheme of the location identifier, e.g. 0088 for a GLN or 0009 for a French SIRET.

actualDeliveryDatedateoptionalBT-72Actual delivery date, YYYY-MM-DD.

deliveryAddressobjectoptional7 fieldsBG-15Delivery postal address.

line1stringoptionalBT-75Street address, line 1.

citystringoptionalBT-77City name.

postCodestringoptionalBT-78Postal or ZIP code.

countrystringoptionalBT-80ISO 3166-1 alpha-2 country code.

line2stringoptionalBT-76Address line 2.

line3stringoptionalBT-165Address line 3.

countrySubdivisionstringoptionalBT-79Region or state.

optionsobjectoptional9 fieldsBehaviour switches that change how the output is built. Every field has a sensible default, so the whole object is optional.

languagestringoptionalLanguage of the invoice. Sets the labels and date formatting of the rendered PDF (unless pdfUrl supplies the visual layer) and the wording of the texts the API fills in for you when the JSON leaves them empty: the payment terms (BT-20) and the VAT exemption reason (BT-120) of reverse charge, intra-Community, export and out-of-scope breakdowns, for example Autoliquidation on a French invoice. Your own paymentTerms and exemptionReasonText always take precedence. Defaults to en.

Allowed values

enEnglish

deGerman

frFrench

validationLanguagestringoptionalLanguage of the validation findings when the request is rejected: the message of every entry in the errors and warnings arrays. rule, btCodes, fields and raw stay the same in every language, so match on those, never on the message text. Independent of language, which sets the language of the invoice itself. Defaults to en; any other value, regional tags such as de-DE included, is rejected with a 400 (errorCode 4002).

Allowed values

enEnglish

deGerman

frFrench

brandColorstringoptionalPrimary brand colour applied to PDF headings, table headers, totals box and section accents. 6-digit hex (e.g. #0F766E). Falls back to the default theme when omitted.

logoUrlstringoptionalPublic URL of your logo, printed top-left on the built-in PDF template; the document title and dates move to the right to make room. PNG or JPEG, no larger than 2 MB and 4 megapixels, scaled to fit a 170 × 48 pt box with its aspect ratio preserved. The API fetches it with the same protections as pdfUrl and re-encodes the image before embedding it, so only the pixels reach the PDF. To send the image itself instead, use logo; a request may carry one of the two, not both. Ignored when pdfUrl supplies the visual layer.

logostringoptionalYour logo as the image file itself, for a logo that is not at a public URL: the PNG or JPEG file as plain base64, without a data: prefix. Printed exactly as a logoUrl would be, with the same limits (2 MB once decoded, 4 megapixels). Sending it together with logoUrl, or as invalid base64, is rejected with a 400 (errorCode 4002). Ignored when pdfUrl supplies the visual layer.

pdfUrlstringoptionalPublic URL of a PDF to use as the visual layer of the hybrid invoice. When set, the API downloads it and embeds the generated XML into it instead of rendering the built-in template, so language, brandColor, logo and logoUrl no longer apply. Must be a publicly reachable absolute http/https URL pointing at a PDF no larger than 20 MB.

includeAdvancedPropertiesbooleanoptionalAdds an "Electronic invoice details" section at the bottom of the rendered PDF, listing the technical XML properties that otherwise do not belong in the classic (legacy) PDF invoice: specification and business process identifiers (BT-24, BT-23), party identifiers and legal registrations with their scheme codes (BT-29/BT-46, BT-30/BT-47), electronic addresses (BT-34/BT-49), supporting document metadata (BG-24) and line-level references and identifiers. Defaults to false. Only affects the built-in template, so it is ignored when pdfUrl supplies the visual layer.

includeQrCodebooleanoptionalAdds an EPC QR code (GiroCode) to the payment section of the rendered PDF. Scanned with a banking app, it pre-fills a SEPA credit transfer with the IBAN (BT-84), the BIC (BT-86), the payee (BT-85, else the seller name BT-27), the amount due (BT-115) and the payment reference (BT-83, else the invoice number BT-1). The code is printed when the invoice is in EUR, BT-84 is a valid IBAN, the payment means code (BT-81) is a credit transfer (30, 42 or 58) and an amount is due. Credit notes and self-billed invoices never carry one, and on any other invoice the option changes nothing, so it is safe to set on every request. Defaults to false. Only affects the built-in template, so it is ignored when pdfUrl supplies the visual layer.

rulesstring[]optionalExtra national rule sets to validate ON TOP of the profile's own rule set, without changing the declared specification identifier (BT-24). br-fr runs the BR-FR Flux 2 rules of the French CTC mandate, the same set the Plateformes Agréées and the PPF apply to every domestic invoice, so you can prove mandate readiness whatever profile the invoice declares. Violations come back as regular validation findings whose rule ids start with BR-FR. Requires at least the BASIC profile: the header-only booking aids MINIMUM and BASIC WL are rejected with a 400. An unknown value is rejected rather than skipped, so a requested compliance check never silently fails to run.

Allowed values

br-frFrench CTC mandate rules (BR-FR Flux 2)

Example payload all fields

Headers

Header	Value
Authorization *	Bearer YOUR_API_KEY
Content-Type	application/json

Response

200 Generated PDF

The invoice was generated. The response body is the PDF, returned as a binary download.

Content-Type: application/pdf

400 Model validation error

One or more request fields are missing or invalid, so generation never started.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errorCode": 4002,
  "valid": false,
  "detail": "The request failed validation with 1 error(s).",
  "errors": [
    {
      "rule": "BR-06",
      "layer": null,
      "line": null,
      "message": "Enter the seller name.",
      "btCodes": ["BT-27"],
      "fields": ["seller.name"],
      "raw": null
    }
  ],
  "warnings": []
}

400 Schematron validation error

The request was well-formed, but the generated invoice failed EN 16931 Schematron business rules.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "XML Validation Failed",
  "status": 400,
  "detail": "The generated invoice contains 2 validation error(s).",
  "errors": [
    {
      "rule": "BR-CO-15",
      "line": null,
      "message": "The invoice total with VAT does not match. Expected 1500.00 + 285.00 = 1785.00.",
      "btCodes": ["BT-112"],
      "fields": ["totals.grandTotalAmount"],
      "raw": "[BR-CO-15] EN16931: Invoice total amount with VAT = 1785.00 expected 1500.00 + 285.00. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:ApplicableHeaderTradeSettlement)"
    },
    {
      "rule": "BR-S-08",
      "line": null,
      "message": "The VAT breakdown for Standard rate must have a positive taxable amount and the correct rate. Check the tax breakdown.",
      "btCodes": ["BT-116", "BT-117"],
      "fields": ["taxBreakdown[0].taxableAmount"],
      "raw": "[BR-S-08] EN16931: VAT category tax amount must equal category basis × rate. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:ApplicableHeaderTradeSettlement/*:ApplicableTradeTax)"
    }
  ],
  "warnings": [
    {
      "rule": "BR-CL-25",
      "line": null,
      "message": "The seller country code should be a valid ISO 3166-1 alpha-2 value.",
      "btCodes": ["BT-40"],
      "fields": ["seller.postalAddress.country"],
      "raw": "[BR-CL-25] EN16931: Country codes should follow ISO 3166-1 alpha-2. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:ApplicableHeaderTradeAgreement/*:SellerTradeParty)"
    }
  ],
  "traceId": "00-54efc3135dd95c21098f45b67ae2b5ab-c894e992bbcccfd7-00",
  "errorCode": 4001
}

Error Reference

Errors are returned as RFC 7807 ProblemDetails. The errorCode field indicates the error category.

errorCode	Meaning	errors key
4001	XML validation, the generated XML violates EN 16931 Schematron rules. `errors` is a flat array of finding objects, each with `rule`, `line`, `message`, `btCodes`, `fields`, and `raw`. A parallel `warnings` array carries non-blocking advisory findings of the same shape.	errors[] warnings[]
4002	Model validation, one or more request fields are missing or invalid. Returned as the same flat `errors` array of finding objects as 4001, with `fields` pointing at the offending input.	errors[]
4011	Remote fetch error, returned only when `options.pdfUrl` or `options.logoUrl` is set. The supplied URL could not be fetched: it is not a valid `http`/`https` URL, resolves to a blocked or private address, or the host was unreachable. A resource whose content is not a PDF (or not a PNG/JPEG for `logoUrl`) is rejected as `4004` instead, and one over the size limit as `4005`.	none
4000	General error, check `detail` for more information.	none

Useful resources

Companion material for integrating against the API.

Code examples on GitHub

Runnable Factur-X integration samples in C#, Java, PHP, Python, Node.js, and browser JavaScript, ready to clone and adapt.

InvoiceXML/facturx-api-examples

Try it online

Fill in a form, no code required, and download a compliant invoice straight from your browser.

www.invoicexml.com/api/create/facturx

OpenAPI specification

The full OpenAPI 3.1 document. Drop it into Postman, Insomnia, or any code generator to scaffold a client.

api.invoicexml.com/v1/openapi

Interactive API explorer

Browse and call every endpoint directly from the browser, powered by Scalar.

api.invoicexml.com/v1/scalar

Frequently Asked Questions

Which Factur-X profile is generated?

By default the EN 16931 (Comfort) profile, the standard choice for B2B invoicing in France and Germany: the embedded XML declares urn:cen.eu:en16931:2017 and is validated against exactly that rule set before delivery, so the stamp always matches what was checked. Declaring an official profile URN in invoice.specificationId selects that profile instead. For the header-only booking-aid profiles (MINIMUM, BASIC WL) the embedded XML carries the profile's official header subset while the rendered PDF, the legal invoice for those profiles, shows the full line data; line items therefore stay required. The BASIC profile is accepted for payloads that stay within its element set, and EXTENDED-CTC-FR is supported with the French mandate's content: SIREN legal registrations, the billing-mode identifier in businessProcessType, French VAT rates, and the mandatory coded note mentions (notes entries with subjectCode PMT, PMD, and AAB). If your workflow needs a property or profile nuance you do not find here, contact us and we will add it.

Can I use my own PDF as the visual layer?

Yes. Set options.pdfUrl to an absolute http(s) URL of your PDF and the API downloads it (with size, content-type and SSRF protections) and embeds the generated XML into it. Without pdfUrl, the API renders its own invoice template, which you can localize with options.language (en, de, fr) and brand with options.brandColor (hex #RRGGBB) and options.logoUrl (a public PNG or JPEG, up to 2 MB, printed top-left). Language, brandColor and logoUrl only affect the rendered template, so they are ignored when pdfUrl is set.

Is the output validated automatically?

Yes. Every generated invoice is validated against the EN 16931 Schematron rules before delivery. If validation fails (e.g. mismatched totals), the API returns a 400 response with errorCode 4001 and the violated rules as findings, each carrying the rule id, layer, a friendly message, and the JSON field paths to correct.

Do I need to calculate totals myself?

No. The entire invoice.totals object and the invoice.vatBreakdowns array are auto-calculated from your line items when omitted. You can still provide them explicitly if you need to override the computed result, your values are used as-is (still rounded to 2 decimals).

Can I include multiple VAT rates?

Yes. Each line item specifies its own vatInformation.rate and vatInformation.categoryCode. The API automatically computes invoice.vatBreakdowns by grouping lines with the same category and rate, as required by EN 16931.

Why is the request a JSON body and not multipart/form-data?

The /create endpoints accept a nested JSON document modelled directly on the EN 16931 semantic model (business terms and groups). This keeps deep structures like postal addresses, line price details, and VAT information clean to express, and matches what most modern HTTP clients expect. Set Content-Type: application/json.

Is the generated PDF accepted by Chorus Pro?

Yes. The output is a Factur-X EN 16931 PDF/A-3 with embedded XML, the format accepted by Chorus Pro (France's B2G portal) and one of the core formats of the French B2B e-invoicing reform phasing in from September 2026.