---
title: "Generate compliant invoice XML"
method: POST
path: "/v1/generate"
tags: ["Invoices"]
---

# Generate compliant invoice XML

`POST /v1/generate`

## Request

- Base URL: `https://api.attestwire.com`
- URL: `https://api.attestwire.com/v1/generate`
- Auth: HTTP bearer

Validates first: a fatal rule failure returns 422 with the same teaching errors as /v1/validate, and does not consume a document. Supported profiles in this build: en16931, xrechnung-ubl, peppol-bis-3, xrechnung-cii, facturx-en16931.

THE PROFILE CHOOSES THE SYNTAX. xrechnung-cii and facturx-en16931 come back as UN/CEFACT CII; every other profile comes back as UBL 2.1. The JSON response says which in its `syntax` field.

**`"profile": "auto"` — the API chooses.** Deterministic rules on the invoice's buyer, no network call, first match wins: a Leitweg-ID (electronic address scheme 0204, or a German buyer reference that is one) → `xrechnung-ubl`; a Belgian buyer or a Peppol electronic address (any Peppol scheme but 0225) → `peppol-bis-3`; a French buyer → `facturx-en16931`; a business in Germany or Austria → `xrechnung-cii`, or `facturx-en16931` with `?format=pdf`; anything else → `en16931`, or `facturx-en16931` with `?format=pdf`. The answer names the choice: `profile_choice` in the JSON envelope and the 422, and `Attestwire-Profile` / `Attestwire-Profile-Rule` headers on every response, the XML and the PDF included. When the choice is a profile the PDF cannot carry (XRechnung, Peppol) and `?format=pdf` was asked for, the answer is `400 unsupported_profile` with the reason, free. Naming a profile always overrides `auto`.

**CII output is XML, not a PDF — unless you ask for the PDF.** Factur-X and ZUGFeRD files are CII XML inside a PDF/A-3 container. By default this endpoint returns the XML only: no container, no `factur-x.xml` attachment, no `/AFRelationship`, so a `facturx-en16931` JSON or XML response is the payload and not a Factur-X document.

**`?format=pdf` — the Factur-X / ZUGFeRD PDF (EN 16931 profile).** With profile `facturx-en16931` (the only profile it accepts), the response is `application/pdf`: an A4 invoice drawn from your JSON — parties, lines, VAT breakdown, totals, payment details — written as PDF/A-3B, with the CII embedded as `factur-x.xml`, `/AFRelationship /Alternative`, and the Factur-X XMP (`fx:ConformanceLevel` EN 16931). Every amount on the page comes from the same computation as the XML. It is validated first and metered as ONE document, exactly like the XML. On the free plan it is a PREVIEW: the same file with "PREVIEW – not for sending" across every page, and the response carries `Attestwire-Preview: watermarked`. A key on a paid plan (Solo, Starter, Scale) gets it without the watermark or the header; moving the key to one is how the watermark is removed.

**The page, and its options.** The body may be the invoice alone, as for every other format, or `{"invoice": …, "pdf": {…}}` with `PdfOptions` beside it; the simple options are also query parameters. The page is in English, German or French — the seller's country decides (DE and AT German, FR French, anything else English) unless `language` says otherwise — with numbers and dates written that language's way, and `Content-Language` names the one used. The embedded XML is identical in every language. PDF options are read only with `?format=pdf`; a malformed wrapper or option is `400 bad_request`, charged nothing. Glyphs cover Latin (incl. Latin Extended-A), Greek and Cyrillic; any other character is drawn as "?" and counted in `X-Unrendered-Characters` — the embedded XML is unaffected. You cannot supply your own PDF to wrap. The generated file passed veraPDF's PDF/A-3B profile in release testing; that is a check of the generator on sample invoices, not of each response.

**Output verification is not uniform, and is never per-request.** The generator's `xrechnung-cii` fixture documents are run through the official KoSIT validator on release and accepted. The `facturx-en16931` fixtures are not: that profile's BT-24 is the core EN 16931 one, which matches no XRechnung scenario, so KoSIT answers "no scenario matched" instead of a verdict, and an absence of a verdict is not a pass. Neither case says anything about YOUR document: this endpoint does not send anything to KoSIT.

The JSON envelope carries `provenance`: the engine version and rule set that cleared this document. `?format=xml` returns the bytes alone and therefore carries none — an XML document has nowhere to put it, and this API does not write its own metadata into a customer's tax document. Read GET /v1/versions if you need it for a raw-XML pipeline.

## Query parameters

- `format` 'json' | 'xml' | 'pdf'
- `language` 'en' | 'de' | 'fr': The language of the page: its labels, and the way it formats numbers and dates. Default: the seller country's — DE and AT German, FR French, anything else English. The invoice's own text (names, descriptions, notes) and the embedded XML are the same in every language. Query parameter: `language`.
- `payment_qr` boolean: The EPC payment QR code ("GiroCode"), printed beside the payment details so a banking app can fill in the transfer: payee, IBAN, amount due and reference. Default: printed whenever the invoice can carry one — currency EUR, payment means 30, 42 or 58 (credit transfer), a valid IBAN, an amount due from 0.01 EUR, and not a credit note — and left out otherwise. `false` leaves it out; `true` requires it, and an invoice that cannot carry it is then a 400 that says why. The reference in the code is the payment reference (BT-83), or else the invoice number. Query parameter: `payment_qr=true|false`.
- `payment_link` string, uri: An https:// address where the invoice can be paid online, such as a payment page from your payment provider. It is printed under the payment details and is clickable in the PDF (a link annotation, which PDF/A permits; no script). At most 500 characters, no user name or password. It is on the page only: EN 16931 has no field for it, so the embedded XML does not carry it. Query parameter: `payment_link` (URL-encoded).

## Request body

- union
  - InvoiceInput: The invoice as JSON: the body of POST /v1/validate (as `application/json`) and of POST /v1/generate, and the `invoice` POST /v1/parse returns. Field names map to EN 16931 business terms. The fields in `required` are the only ones the model needs; every other field and group is optional, and one you leave out is not written. Types are the model's and nothing more: the rules judge the values and report what is wrong as findings, so a value this schema allows can still fail validation. Mirrors `InvoiceInput` in @attestwire/en16931.
    - `profile` 'en16931' | 'xrechnung-ubl' | 'xrechnung-cii' | 'facturx-en16931' | 'peppol-bis-3' | 'auto', required: Selects the rule set, and on POST /v1/generate the syntax. Narrower profiles add rules; they never remove core ones. "auto" (POST /v1/validate and /v1/generate) has the API choose from the buyer, without any network call: a Leitweg-ID (electronic address scheme 0204, or a German buyer reference) is xrechnung-ubl; a Belgian buyer or a Peppol electronic address is peppol-bis-3; a French buyer is facturx-en16931; a German or Austrian business is xrechnung-cii, or facturx-en16931 with ?format=pdf; anything else is en16931 (facturx-en16931 with ?format=pdf). The answer names the choice and the rule in `profile_choice` and the Attestwire-Profile headers.
    - `invoiceNumber` string, required: BT-1 invoice number.
    - `issueDate` string, date, required: BT-2 issue date, ISO 8601.
    - `currency` string, required: BT-5 invoice currency code, ISO 4217.
    - `invoiceTypeCode` string: BT-3 document type code, UNTDID 1001: "380", the default, is a commercial invoice and "381" a credit note. It decides the document type: "381" makes a UBL `CreditNote` or a CII document with type code 381, from the same fields. State a credit note's amounts positively; the type code carries the direction. BR-DE-17 restricts XRechnung to 326/380/381/384/389/875/876/877.
    - `dueDate` string, date: BT-9 payment due date, ISO 8601. A UBL credit note carries it inside the payment means (`cac:PaymentMeans/cbc:PaymentDueDate`), so there it needs `payment`; without that group it is dropped and reported as ATW-CREDIT-NOTE-DUE-DATE-UNBOUND.
    - `note` string: BT-22 invoice note, free text.
    - `noteSubjectCode` string: BT-21 invoice note subject code, UNCL 4451. Written into the note itself as `#CODE#text`, so it only means something when `note` is set.
    - `buyerReference` string: BT-10 buyer reference, which XRechnung requires (BR-DE-15). A German public-sector buyer's is its Leitweg-ID.
    - `orderReference` string: BT-13 purchase order reference.
    - `salesOrderReference` string: BT-14 sales order reference: your own order number, not the buyer's.
    - `projectReference` string: BT-11 project reference. `UBL-CreditNote-2.1.xsd` has no element for it, so on a UBL credit note it is dropped and reported as ATW-CREDIT-NOTE-PROJECT-REFERENCE-UNBOUND. CII keeps it.
    - `contractReference` string: BT-12 contract reference.
    - `despatchAdviceReference` string: BT-16 despatch advice reference.
    - `receivingAdviceReference` string: BT-15 receiving advice reference.
    - `tenderOrLotReference` string: BT-17 tender or lot reference.
    - `invoicedObjectIdentifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
      - `value` string, required: The identifier.
      - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
    - `buyerAccountingReference` string: BT-19 buyer accounting reference: the buyer's cost centre or ledger account.
    - `taxPointDate` string, date: BT-7 value added tax point date, ISO 8601. BR-CO-03 does not allow it together with `invoicingPeriod.descriptionCode` (BT-8).
    - `invoicingPeriod` InvoicingPeriod: BG-14 invoicing period, or BG-26 when it is a line's `period`. The first term of each pair is the document's.
      - `startDate` string, date: BT-73 / BT-134 period start date, ISO 8601.
      - `endDate` string, date: BT-74 / BT-135 period end date, ISO 8601.
      - `descriptionCode` string: BT-8 value added tax point date code, UNTDID 2005 (3, 35 or 432). Document level only: ignored on a line period. BR-CO-03 does not allow it together with `taxPointDate`.
    - `precedingInvoices` PrecedingInvoiceReference[]: BG-3 preceding invoice references: the invoices this document corrects, credits or settles against. BR-DE-26 requires one for a corrected invoice (BT-3 = 384). A credit note is not required to carry one; leaving it out raises ATW-CREDIT-NOTE-NO-PRECEDING-INVOICE at severity `information`.
      - `invoiceNumber` string, required: BT-25 the number of the invoice being corrected or referenced.
      - `issueDate` string, date: BT-26 the issue date of that invoice, ISO 8601.
    - `seller` Party, required: BG-4 seller or BG-7 buyer. Where a field names two terms, the first is the seller's and the second the buyer's; a field with one term exists for the seller only.
      - `name` string, required: BT-27 / BT-44 name, written as both the legal name and the trading name (BT-28 / BT-45) unless `legalName` or `tradingName` says otherwise.
      - `vatId` string: BT-31 / BT-48 VAT identifier, with its country prefix.
      - `taxRegistrationId` string: BT-32 seller tax registration identifier, such as the German Steuernummer.
      - `legalRegistrationId` string: BT-30 / BT-47 legal registration identifier, such as an HRB number.
      - `legalRegistrationSchemeId` string: BT-30-1 / BT-47-1 ISO 6523 ICD scheme of the legal registration identifier.
      - `identifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `additionalLegalInformation` string: BT-33 seller additional legal information: legal form, share capital and the like.
      - `tradingName` string: BT-28 / BT-45 trading name, when the party trades under a name other than its legal one.
      - `legalName` string: BT-27 / BT-44 registered legal name, when it differs from `name`.
      - `address` PostalAddress, required: A postal address: BG-5 seller, BG-8 buyer or BG-12 tax representative. The terms are listed in that order.
        - `line1` string: BT-35 / BT-50 / BT-64 address line 1.
        - `line2` string: BT-36 / BT-51 / BT-65 address line 2.
        - `line3` string: BT-162 / BT-163 / BT-164 address line 3.
        - `city` string, required: BT-37 / BT-52 / BT-66 city.
        - `postalCode` string, required: BT-38 / BT-53 / BT-67 post code.
        - `countrySubdivision` string: BT-39 / BT-54 / BT-68 country subdivision: a Bundesland, a région, a county.
        - `countryCode` string, required: BT-40 / BT-55 / BT-69 country code, ISO 3166-1 alpha-2.
      - `electronicAddress` ElectronicAddress: BT-34 seller or BT-49 buyer electronic address: where the network delivers the document. Both halves are required.
        - `schemeId` string, required: BT-34-1 / BT-49-1 scheme identifier, from the Peppol EAS code list.
        - `value` string, required: BT-34 / BT-49 the address itself.
      - `contact` Contact: BG-6 seller contact or BG-9 buyer contact.
        - `name` string: BT-41 / BT-56 contact point: a person or a department.
        - `email` string: BT-43 / BT-58 contact email address.
        - `phone` string: BT-42 / BT-57 contact telephone number.
    - `buyer` Party, required: BG-4 seller or BG-7 buyer. Where a field names two terms, the first is the seller's and the second the buyer's; a field with one term exists for the seller only.
      - `name` string, required: BT-27 / BT-44 name, written as both the legal name and the trading name (BT-28 / BT-45) unless `legalName` or `tradingName` says otherwise.
      - `vatId` string: BT-31 / BT-48 VAT identifier, with its country prefix.
      - `taxRegistrationId` string: BT-32 seller tax registration identifier, such as the German Steuernummer.
      - `legalRegistrationId` string: BT-30 / BT-47 legal registration identifier, such as an HRB number.
      - `legalRegistrationSchemeId` string: BT-30-1 / BT-47-1 ISO 6523 ICD scheme of the legal registration identifier.
      - `identifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `additionalLegalInformation` string: BT-33 seller additional legal information: legal form, share capital and the like.
      - `tradingName` string: BT-28 / BT-45 trading name, when the party trades under a name other than its legal one.
      - `legalName` string: BT-27 / BT-44 registered legal name, when it differs from `name`.
      - `address` PostalAddress, required: A postal address: BG-5 seller, BG-8 buyer or BG-12 tax representative. The terms are listed in that order.
        - `line1` string: BT-35 / BT-50 / BT-64 address line 1.
        - `line2` string: BT-36 / BT-51 / BT-65 address line 2.
        - `line3` string: BT-162 / BT-163 / BT-164 address line 3.
        - `city` string, required: BT-37 / BT-52 / BT-66 city.
        - `postalCode` string, required: BT-38 / BT-53 / BT-67 post code.
        - `countrySubdivision` string: BT-39 / BT-54 / BT-68 country subdivision: a Bundesland, a région, a county.
        - `countryCode` string, required: BT-40 / BT-55 / BT-69 country code, ISO 3166-1 alpha-2.
      - `electronicAddress` ElectronicAddress: BT-34 seller or BT-49 buyer electronic address: where the network delivers the document. Both halves are required.
        - `schemeId` string, required: BT-34-1 / BT-49-1 scheme identifier, from the Peppol EAS code list.
        - `value` string, required: BT-34 / BT-49 the address itself.
      - `contact` Contact: BG-6 seller contact or BG-9 buyer contact.
        - `name` string: BT-41 / BT-56 contact point: a person or a department.
        - `email` string: BT-43 / BT-58 contact email address.
        - `phone` string: BT-42 / BT-57 contact telephone number.
    - `payee` Payee: BG-10 payee: where the money goes, when that is not the seller.
      - `name` string, required: BT-59 payee name. Must differ from the seller name (BR-17).
      - `identifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `legalRegistrationId` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
    - `taxRepresentative` TaxRepresentative: BG-11 seller tax representative party.
      - `name` string, required: BT-62 tax representative name.
      - `vatId` string, required: BT-63 tax representative VAT identifier. BR-56 requires it once BG-11 exists.
      - `address` PostalAddress, required: A postal address: BG-5 seller, BG-8 buyer or BG-12 tax representative. The terms are listed in that order.
        - `line1` string: BT-35 / BT-50 / BT-64 address line 1.
        - `line2` string: BT-36 / BT-51 / BT-65 address line 2.
        - `line3` string: BT-162 / BT-163 / BT-164 address line 3.
        - `city` string, required: BT-37 / BT-52 / BT-66 city.
        - `postalCode` string, required: BT-38 / BT-53 / BT-67 post code.
        - `countrySubdivision` string: BT-39 / BT-54 / BT-68 country subdivision: a Bundesland, a région, a county.
        - `countryCode` string, required: BT-40 / BT-55 / BT-69 country code, ISO 3166-1 alpha-2.
    - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened, in business terms, for every line, document level allowance and charge that does not say otherwise: the engine writes the VAT category (BT-151, BT-95, BT-102), the rate and the exemption reason (BT-120, BT-121) from it. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes. An item's own `vatScenario` or `vatCategory` overrides this default. The document is byte for byte the one the explicit codes produce.
    - `lines` InvoiceLine[], required: BG-25 invoice lines, at least one (BR-16). An empty list is answered with that finding.
      - `id` string, required: BT-126 invoice line identifier.
      - `description` string, required: BT-153 item name.
      - `longDescription` string: BT-154 item description, when it should say more than the item name.
      - `quantity` number, required: BT-129 invoiced quantity.
      - `unitCode` string, required: BT-130 unit of measure code, UN/ECE Recommendation 20.
      - `unitPrice` number, required: BT-146 item net price.
      - `grossUnitPrice` number: BT-148 item gross price, before the BT-147 price discount.
      - `priceDiscount` number: BT-147 item price discount: the difference between BT-148 and BT-146.
      - `baseQuantity` number: BT-149 item price base quantity, 1 when absent.
      - `vatCategory` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: BT-151 invoiced item VAT category code, UNCL 5305: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L IGIC (Canary Islands), M IPSI (Ceuta and Melilla). Left out, it comes from the line's `vatScenario` or the invoice's.
      - `vatRate` number: BT-152 invoiced item VAT rate, in percent.
      - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened on this line, instead of its VAT code: the engine writes `vatCategory`, the rate (except for "domestic", whose rate you give in `vatRate`) and the exemption reason from it. It overrides the invoice's `vatScenario`. A `vatCategory` stated beside it must be the one it stands for: disagreeing is the fatal ATW-VAT-SCENARIO-CONFLICT. With a scenario, `vatCategory` may be left out of the request although this schema lists it as required (the schema describes the explicit model, which POST /v1/parse returns); the response reports each code it filled in as ATW-VAT-SCENARIO-APPLIED, at severity information. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes.
      - `note` string: BT-127 invoice line note.
      - `objectIdentifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `buyerAccountingReference` string: BT-133 invoice line buyer accounting reference.
      - `period` InvoicingPeriod: BG-14 invoicing period, or BG-26 when it is a line's `period`. The first term of each pair is the document's.
        - `startDate` string, date: BT-73 / BT-134 period start date, ISO 8601.
        - `endDate` string, date: BT-74 / BT-135 period end date, ISO 8601.
        - `descriptionCode` string: BT-8 value added tax point date code, UNTDID 2005 (3, 35 or 432). Document level only: ignored on a line period. BR-CO-03 does not allow it together with `taxPointDate`.
      - `orderLineReference` string: BT-132 referenced purchase order line reference.
      - `allowances` LineAllowanceCharge[]: BG-27 invoice line allowances: discounts on this line only.
        - `amount` number, required: BT-136 / BT-141 amount, always positive.
        - `baseAmount` number: BT-137 / BT-142 base amount.
        - `percentage` number: BT-138 / BT-143 percentage.
        - `reason` string: BT-139 / BT-144 reason, free text.
        - `reasonCode` string: BT-140 / BT-145 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
      - `charges` LineAllowanceCharge[]: BG-28 invoice line charges: surcharges on this line only.
        - `amount` number, required: BT-136 / BT-141 amount, always positive.
        - `baseAmount` number: BT-137 / BT-142 base amount.
        - `percentage` number: BT-138 / BT-143 percentage.
        - `reason` string: BT-139 / BT-144 reason, free text.
        - `reasonCode` string: BT-140 / BT-145 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
      - `sellerItemId` string: BT-155 item seller's identifier.
      - `buyerItemId` string: BT-156 item buyer's identifier.
      - `standardItemId` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `itemClassifications` ItemClassification[]: BT-158 item classification identifiers.
        - `code` string, required: BT-158 the classification code.
        - `schemeId` string, required: BT-158-1 the scheme it is drawn from, UNTDID 7143.
        - `schemeVersion` string: BT-158-2 the version of that scheme.
      - `originCountryCode` string: BT-159 item country of origin, ISO 3166-1 alpha-2.
      - `itemAttributes` ItemAttribute[]: BG-32 item attributes: name and value pairs describing the item.
        - `name` string, required: BT-160 item attribute name.
        - `value` string, required: BT-161 item attribute value.
    - `allowances` DocumentAllowanceCharge[]: BG-20 document level allowances: discounts on the whole invoice.
      - `amount` number, required: BT-92 / BT-99 amount, always positive.
      - `baseAmount` number: BT-93 / BT-100 base amount.
      - `percentage` number: BT-94 / BT-101 percentage.
      - `vatCategory` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: BT-95 / BT-102 VAT category code, UNCL 5305: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L IGIC (Canary Islands), M IPSI (Ceuta and Melilla). Left out, it comes from the entry's `vatScenario` or the invoice's.
      - `vatRate` number: BT-96 / BT-103 VAT rate, in percent.
      - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened, instead of the VAT code of this allowance or charge: the engine writes `vatCategory`, the rate (except for "domestic", whose rate you give in `vatRate`) and the exemption reason from it. It overrides the invoice's `vatScenario`. A `vatCategory` stated beside it must be the one it stands for: disagreeing is the fatal ATW-VAT-SCENARIO-CONFLICT. With a scenario, `vatCategory` may be left out of the request although this schema lists it as required (the schema describes the explicit model, which POST /v1/parse returns); the response reports each code it filled in as ATW-VAT-SCENARIO-APPLIED, at severity information. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes.
      - `reason` string: BT-97 / BT-104 reason, free text.
      - `reasonCode` string: BT-98 / BT-105 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
    - `charges` DocumentAllowanceCharge[]: BG-21 document level charges: freight, packing, surcharges.
      - `amount` number, required: BT-92 / BT-99 amount, always positive.
      - `baseAmount` number: BT-93 / BT-100 base amount.
      - `percentage` number: BT-94 / BT-101 percentage.
      - `vatCategory` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: BT-95 / BT-102 VAT category code, UNCL 5305: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L IGIC (Canary Islands), M IPSI (Ceuta and Melilla). Left out, it comes from the entry's `vatScenario` or the invoice's.
      - `vatRate` number: BT-96 / BT-103 VAT rate, in percent.
      - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened, instead of the VAT code of this allowance or charge: the engine writes `vatCategory`, the rate (except for "domestic", whose rate you give in `vatRate`) and the exemption reason from it. It overrides the invoice's `vatScenario`. A `vatCategory` stated beside it must be the one it stands for: disagreeing is the fatal ATW-VAT-SCENARIO-CONFLICT. With a scenario, `vatCategory` may be left out of the request although this schema lists it as required (the schema describes the explicit model, which POST /v1/parse returns); the response reports each code it filled in as ATW-VAT-SCENARIO-APPLIED, at severity information. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes.
      - `reason` string: BT-97 / BT-104 reason, free text.
      - `reasonCode` string: BT-98 / BT-105 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
    - `paymentTerms` string: BT-20 payment terms, free text.
    - `payment` PaymentInstructions: BG-16 payment instructions. Required for XRechnung profiles by BR-DE-1.
      - `meansCode` string, required: BT-81 payment means type code, UNTDID 4461: "58" SEPA credit transfer, "30" credit transfer, "59" SEPA direct debit, "48" card, "57" standing order, "97" clearing. Left out of a request, it is inferred from the account, as the engine's `applyDefaults` does: "59" for a direct debit mandate in euro and "49" in another currency, else "58" for an IBAN in the SEPA scheme paid in euro and "30" for any other IBAN; the response reports it as ATW-PAYMENT-MEANS-INFERRED, at severity information.
      - `meansName` string: BT-82 payment means text.
      - `iban` string: BT-84 payment account identifier (BG-17): the IBAN, for a credit transfer.
      - `accountName` string: BT-85 payment account name (BG-17).
      - `bic` string: BT-86 payment service provider identifier (BG-17): the BIC.
      - `remittanceInformation` string: BT-83 remittance information: the payment reference.
      - `card` PaymentCard: BG-18 payment card information.
        - `primaryAccountNumber` string, required: BT-87 payment card primary account number: at most its first six and last four digits. BR-51 warns above ten characters; never put a full card number on an invoice.
        - `holderName` string: BT-88 payment card holder name.
      - `directDebit` DirectDebit: BG-19 direct debit information.
        - `mandateReference` string: BT-89 mandate reference identifier.
        - `creditorIdentifier` string: BT-90 bank assigned creditor identifier: the SEPA creditor identifier. Written as the seller's identifier with scheme "SEPA", where BR-DE-30 looks for it.
        - `debitedAccount` string: BT-91 debited account identifier: the payer's IBAN. Required by BR-DE-31.
    - `supportingDocuments` SupportingDocument[]: BG-24 additional supporting documents.
      - `reference` string, required: BT-122 supporting document reference.
      - `description` string: BT-123 supporting document description.
      - `externalUri` string: BT-124 external document location: a URL.
      - `attachment` EmbeddedAttachment: BT-125 attached document, embedded in the invoice.
        - `filename` string, required: BT-125-2 attached document filename. Must be unique across the invoice (BR-DE-22).
        - `mimeCode` string, required: BT-125-1 attached document MIME code. BR-CL-24 admits only application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet and application/vnd.oasis.opendocument.spreadsheet.
        - `content` string, required: BT-125 the document bytes, base64-encoded. Written as given, not re-encoded.
    - `deliveryDate` string, date: BT-72 actual delivery date, ISO 8601. Required with BT-80 by BR-IC-11 for category K. On XRechnung profiles, an invoice with no time of supply at all (no BT-72, no `invoicingPeriod`, no line `period`) raises BR-DE-TMP-32 at severity `information`.
    - `deliverTo` DeliverToAddress: BG-15 deliver-to address. Only the country code is required by the model; XRechnung also requires the city and post code once the group is present.
      - `line1` string: BT-75 deliver-to address line 1.
      - `line2` string: BT-76 deliver-to address line 2.
      - `city` string: BT-77 deliver-to city. Mandatory under XRechnung once BG-15 is present.
      - `postalCode` string: BT-78 deliver-to post code. Mandatory under XRechnung once BG-15 is present.
      - `countrySubdivision` string: BT-79 deliver-to country subdivision.
      - `countryCode` string, required: BT-80 deliver-to country code, ISO 3166-1 alpha-2.
    - `deliverToName` string: BT-70 deliver-to party name.
    - `deliverToLocationId` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
      - `value` string, required: The identifier.
      - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
    - `vatAccountingCurrency` string: BT-6 VAT accounting currency, ISO 4217, when VAT is reported in a currency other than BT-5. Supplying it obliges you to supply `taxAmountInAccountingCurrency` (BR-53).
    - `taxAmountInAccountingCurrency` number: BT-111 invoice total VAT amount in the VAT accounting currency. It depends on the exchange rate the tax authority requires for the tax point, which is not on the invoice, so it cannot be derived: you supply it.
    - `paidAmount` number: BT-113 paid amount: a prepayment or deposit already received. It is subtracted from the amount due (BT-115).
    - `roundingAmount` number: BT-114 rounding amount, added to the total to produce a payable round figure.
    - `vatExemptionReasons` object: BT-120 VAT exemption reason text, keyed by VAT category, such as `{"E": "…"}`. Defaults are applied for AE, K, G and O; category E has no standard text, so BR-E-10 requires you to supply one.
    - `vatExemptionReasonCodes` object: BT-121 VAT exemption reason code from the CEF VATEX list, keyed by VAT category.
    - `declaredTotals` DeclaredTotals: Totals as someone else computed them, checked against the computed ones under BR-CO-10/11/12/13/14/15/16. Generation always writes the computed values: these exist so you can catch a mismatch in your own accounting system before a tax authority does, and omitting one is never an error. The readers (POST /v1/parse, and POST /v1/validate with a document) also record here what a document states, including the fields described as set by the readers, which a caller building the model leaves out. On that path a document must state its totals: one that omits BT-106, BT-109, BT-112 or BT-115 fails BR-12, BR-13, BR-14 or BR-15, and one that states a total that cannot be read as a number fails ATW-DECLARED-TOTAL-NOT-A-NUMBER.
      - `syntax` 'ubl' | 'cii': Set by the readers: the syntax the document was read from. It decides how BR-S-08 and its per-category siblings compare the stated taxable amount: exactly in CII, within ±1 in UBL.
      - `taxTotalsInInvoiceCurrency` number: Set by the readers: how many VAT totals carry the invoice currency (BT-5). BR-CO-15 requires exactly one.
      - `specificationIdentifier` string: BT-24 specification identifier as the document states it, trimmed; empty when absent. Set by the readers, so BR-01 can be judged.
      - `lineNetAmounts` number[]: BT-131 invoice line net amounts as each line states them, in document order; null where a line states none. Set by the readers.
      - `subtotals` DeclaredTaxSubtotal[]: BG-23 VAT breakdown as the document states it, in document order. Set by the readers.
        - `category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M': BT-118 VAT category code, as written.
        - `rate` number: BT-119 VAT category rate, as written.
        - `taxableAmount` number: BT-116 VAT category taxable amount, as written.
        - `taxAmount` number: BT-117 VAT category tax amount, as written.
      - `lineExtensionAmount` number: BT-106 sum of invoice line net amounts.
      - `allowanceTotalAmount` number: BT-107 sum of allowances on document level.
      - `chargeTotalAmount` number: BT-108 sum of charges on document level.
      - `taxExclusiveAmount` number: BT-109 invoice total amount without VAT.
      - `taxAmount` number: BT-110 invoice total VAT amount.
      - `taxInclusiveAmount` number: BT-112 invoice total amount with VAT.
      - `payableAmount` number: BT-115 amount due for payment.
      - `defects` DeclaredTotalDefect[]: Set by the readers: document totals the document was supposed to state and did not state readably, one entry per term. On the JSON model an omitted total means "compute it" and is never a defect.
        - `key` 'lineExtensionAmount' | 'allowanceTotalAmount' | 'chargeTotalAmount' | 'taxExclusiveAmount' | 'taxAmount' | 'taxInclusiveAmount' | 'payableAmount' | 'taxAmountInAccountingCurrency', required: Which total it is, as a key of DeclaredTotals. `taxAmountInAccountingCurrency` names BT-111, which the model carries on the invoice itself.
        - `field` string, required: The business term, such as BT-115.
        - `state` 'absent' | 'empty' | 'unreadable', required: Why it could not be read: `absent` fails a BR presence rule, while `empty` and `unreadable` fail XML Schema validation at the official validator before any business rule, and this API reports them as ATW-DECLARED-TOTAL-NOT-A-NUMBER.
        - `text` string: What the element held, verbatim, cut at 200 characters. Only for `unreadable`.
        - `xpath` string, required: Where the value is in the document, or where it should have been.
      - `overPrecise` OverPreciseAmount[]: Set by the readers: amounts the document wrote with more than two decimal places, in document order, which the BR-DEC rules report.
        - `field` string, required: The business term, which selects the BR-DEC rule.
        - `decimals` number, required: Digits after the decimal point, trailing zeros included.
        - `text` string, required: The amount exactly as the document writes it.
        - `xpath` string, required: Where it was found.
        - `line` number: 1-based invoice line, for a line-level term (BT-131).
        - `group` number: 1-based VAT breakdown group, for BT-116 and BT-117.
  - GenerateRequest: The invoice with options for its PDF page. Any body with an `invoice` key is this wrapper; any other body is the invoice itself.
    - `invoice` InvoiceInput, required: The invoice as JSON: the body of POST /v1/validate (as `application/json`) and of POST /v1/generate, and the `invoice` POST /v1/parse returns. Field names map to EN 16931 business terms. The fields in `required` are the only ones the model needs; every other field and group is optional, and one you leave out is not written. Types are the model's and nothing more: the rules judge the values and report what is wrong as findings, so a value this schema allows can still fail validation. Mirrors `InvoiceInput` in @attestwire/en16931.
      - `profile` 'en16931' | 'xrechnung-ubl' | 'xrechnung-cii' | 'facturx-en16931' | 'peppol-bis-3' | 'auto', required: Selects the rule set, and on POST /v1/generate the syntax. Narrower profiles add rules; they never remove core ones. "auto" (POST /v1/validate and /v1/generate) has the API choose from the buyer, without any network call: a Leitweg-ID (electronic address scheme 0204, or a German buyer reference) is xrechnung-ubl; a Belgian buyer or a Peppol electronic address is peppol-bis-3; a French buyer is facturx-en16931; a German or Austrian business is xrechnung-cii, or facturx-en16931 with ?format=pdf; anything else is en16931 (facturx-en16931 with ?format=pdf). The answer names the choice and the rule in `profile_choice` and the Attestwire-Profile headers.
      - `invoiceNumber` string, required: BT-1 invoice number.
      - `issueDate` string, date, required: BT-2 issue date, ISO 8601.
      - `currency` string, required: BT-5 invoice currency code, ISO 4217.
      - `invoiceTypeCode` string: BT-3 document type code, UNTDID 1001: "380", the default, is a commercial invoice and "381" a credit note. It decides the document type: "381" makes a UBL `CreditNote` or a CII document with type code 381, from the same fields. State a credit note's amounts positively; the type code carries the direction. BR-DE-17 restricts XRechnung to 326/380/381/384/389/875/876/877.
      - `dueDate` string, date: BT-9 payment due date, ISO 8601. A UBL credit note carries it inside the payment means (`cac:PaymentMeans/cbc:PaymentDueDate`), so there it needs `payment`; without that group it is dropped and reported as ATW-CREDIT-NOTE-DUE-DATE-UNBOUND.
      - `note` string: BT-22 invoice note, free text.
      - `noteSubjectCode` string: BT-21 invoice note subject code, UNCL 4451. Written into the note itself as `#CODE#text`, so it only means something when `note` is set.
      - `buyerReference` string: BT-10 buyer reference, which XRechnung requires (BR-DE-15). A German public-sector buyer's is its Leitweg-ID.
      - `orderReference` string: BT-13 purchase order reference.
      - `salesOrderReference` string: BT-14 sales order reference: your own order number, not the buyer's.
      - `projectReference` string: BT-11 project reference. `UBL-CreditNote-2.1.xsd` has no element for it, so on a UBL credit note it is dropped and reported as ATW-CREDIT-NOTE-PROJECT-REFERENCE-UNBOUND. CII keeps it.
      - `contractReference` string: BT-12 contract reference.
      - `despatchAdviceReference` string: BT-16 despatch advice reference.
      - `receivingAdviceReference` string: BT-15 receiving advice reference.
      - `tenderOrLotReference` string: BT-17 tender or lot reference.
      - `invoicedObjectIdentifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `buyerAccountingReference` string: BT-19 buyer accounting reference: the buyer's cost centre or ledger account.
      - `taxPointDate` string, date: BT-7 value added tax point date, ISO 8601. BR-CO-03 does not allow it together with `invoicingPeriod.descriptionCode` (BT-8).
      - `invoicingPeriod` InvoicingPeriod: BG-14 invoicing period, or BG-26 when it is a line's `period`. The first term of each pair is the document's.
        - `startDate` string, date: BT-73 / BT-134 period start date, ISO 8601.
        - `endDate` string, date: BT-74 / BT-135 period end date, ISO 8601.
        - `descriptionCode` string: BT-8 value added tax point date code, UNTDID 2005 (3, 35 or 432). Document level only: ignored on a line period. BR-CO-03 does not allow it together with `taxPointDate`.
      - `precedingInvoices` PrecedingInvoiceReference[]: BG-3 preceding invoice references: the invoices this document corrects, credits or settles against. BR-DE-26 requires one for a corrected invoice (BT-3 = 384). A credit note is not required to carry one; leaving it out raises ATW-CREDIT-NOTE-NO-PRECEDING-INVOICE at severity `information`.
        - `invoiceNumber` string, required: BT-25 the number of the invoice being corrected or referenced.
        - `issueDate` string, date: BT-26 the issue date of that invoice, ISO 8601.
      - `seller` Party, required: BG-4 seller or BG-7 buyer. Where a field names two terms, the first is the seller's and the second the buyer's; a field with one term exists for the seller only.
        - `name` string, required: BT-27 / BT-44 name, written as both the legal name and the trading name (BT-28 / BT-45) unless `legalName` or `tradingName` says otherwise.
        - `vatId` string: BT-31 / BT-48 VAT identifier, with its country prefix.
        - `taxRegistrationId` string: BT-32 seller tax registration identifier, such as the German Steuernummer.
        - `legalRegistrationId` string: BT-30 / BT-47 legal registration identifier, such as an HRB number.
        - `legalRegistrationSchemeId` string: BT-30-1 / BT-47-1 ISO 6523 ICD scheme of the legal registration identifier.
        - `identifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
          - `value` string, required: The identifier.
          - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
        - `additionalLegalInformation` string: BT-33 seller additional legal information: legal form, share capital and the like.
        - `tradingName` string: BT-28 / BT-45 trading name, when the party trades under a name other than its legal one.
        - `legalName` string: BT-27 / BT-44 registered legal name, when it differs from `name`.
        - `address` PostalAddress, required: A postal address: BG-5 seller, BG-8 buyer or BG-12 tax representative. The terms are listed in that order.
          - `line1` string: BT-35 / BT-50 / BT-64 address line 1.
          - `line2` string: BT-36 / BT-51 / BT-65 address line 2.
          - `line3` string: BT-162 / BT-163 / BT-164 address line 3.
          - `city` string, required: BT-37 / BT-52 / BT-66 city.
          - `postalCode` string, required: BT-38 / BT-53 / BT-67 post code.
          - `countrySubdivision` string: BT-39 / BT-54 / BT-68 country subdivision: a Bundesland, a région, a county.
          - `countryCode` string, required: BT-40 / BT-55 / BT-69 country code, ISO 3166-1 alpha-2.
        - `electronicAddress` ElectronicAddress: BT-34 seller or BT-49 buyer electronic address: where the network delivers the document. Both halves are required.
          - `schemeId` string, required: BT-34-1 / BT-49-1 scheme identifier, from the Peppol EAS code list.
          - `value` string, required: BT-34 / BT-49 the address itself.
        - `contact` Contact: BG-6 seller contact or BG-9 buyer contact.
          - `name` string: BT-41 / BT-56 contact point: a person or a department.
          - `email` string: BT-43 / BT-58 contact email address.
          - `phone` string: BT-42 / BT-57 contact telephone number.
      - `buyer` Party, required: BG-4 seller or BG-7 buyer. Where a field names two terms, the first is the seller's and the second the buyer's; a field with one term exists for the seller only.
        - `name` string, required: BT-27 / BT-44 name, written as both the legal name and the trading name (BT-28 / BT-45) unless `legalName` or `tradingName` says otherwise.
        - `vatId` string: BT-31 / BT-48 VAT identifier, with its country prefix.
        - `taxRegistrationId` string: BT-32 seller tax registration identifier, such as the German Steuernummer.
        - `legalRegistrationId` string: BT-30 / BT-47 legal registration identifier, such as an HRB number.
        - `legalRegistrationSchemeId` string: BT-30-1 / BT-47-1 ISO 6523 ICD scheme of the legal registration identifier.
        - `identifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
          - `value` string, required: The identifier.
          - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
        - `additionalLegalInformation` string: BT-33 seller additional legal information: legal form, share capital and the like.
        - `tradingName` string: BT-28 / BT-45 trading name, when the party trades under a name other than its legal one.
        - `legalName` string: BT-27 / BT-44 registered legal name, when it differs from `name`.
        - `address` PostalAddress, required: A postal address: BG-5 seller, BG-8 buyer or BG-12 tax representative. The terms are listed in that order.
          - `line1` string: BT-35 / BT-50 / BT-64 address line 1.
          - `line2` string: BT-36 / BT-51 / BT-65 address line 2.
          - `line3` string: BT-162 / BT-163 / BT-164 address line 3.
          - `city` string, required: BT-37 / BT-52 / BT-66 city.
          - `postalCode` string, required: BT-38 / BT-53 / BT-67 post code.
          - `countrySubdivision` string: BT-39 / BT-54 / BT-68 country subdivision: a Bundesland, a région, a county.
          - `countryCode` string, required: BT-40 / BT-55 / BT-69 country code, ISO 3166-1 alpha-2.
        - `electronicAddress` ElectronicAddress: BT-34 seller or BT-49 buyer electronic address: where the network delivers the document. Both halves are required.
          - `schemeId` string, required: BT-34-1 / BT-49-1 scheme identifier, from the Peppol EAS code list.
          - `value` string, required: BT-34 / BT-49 the address itself.
        - `contact` Contact: BG-6 seller contact or BG-9 buyer contact.
          - `name` string: BT-41 / BT-56 contact point: a person or a department.
          - `email` string: BT-43 / BT-58 contact email address.
          - `phone` string: BT-42 / BT-57 contact telephone number.
      - `payee` Payee: BG-10 payee: where the money goes, when that is not the seller.
        - `name` string, required: BT-59 payee name. Must differ from the seller name (BR-17).
        - `identifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
          - `value` string, required: The identifier.
          - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
        - `legalRegistrationId` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
          - `value` string, required: The identifier.
          - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `taxRepresentative` TaxRepresentative: BG-11 seller tax representative party.
        - `name` string, required: BT-62 tax representative name.
        - `vatId` string, required: BT-63 tax representative VAT identifier. BR-56 requires it once BG-11 exists.
        - `address` PostalAddress, required: A postal address: BG-5 seller, BG-8 buyer or BG-12 tax representative. The terms are listed in that order.
          - `line1` string: BT-35 / BT-50 / BT-64 address line 1.
          - `line2` string: BT-36 / BT-51 / BT-65 address line 2.
          - `line3` string: BT-162 / BT-163 / BT-164 address line 3.
          - `city` string, required: BT-37 / BT-52 / BT-66 city.
          - `postalCode` string, required: BT-38 / BT-53 / BT-67 post code.
          - `countrySubdivision` string: BT-39 / BT-54 / BT-68 country subdivision: a Bundesland, a région, a county.
          - `countryCode` string, required: BT-40 / BT-55 / BT-69 country code, ISO 3166-1 alpha-2.
      - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened, in business terms, for every line, document level allowance and charge that does not say otherwise: the engine writes the VAT category (BT-151, BT-95, BT-102), the rate and the exemption reason (BT-120, BT-121) from it. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes. An item's own `vatScenario` or `vatCategory` overrides this default. The document is byte for byte the one the explicit codes produce.
      - `lines` InvoiceLine[], required: BG-25 invoice lines, at least one (BR-16). An empty list is answered with that finding.
        - `id` string, required: BT-126 invoice line identifier.
        - `description` string, required: BT-153 item name.
        - `longDescription` string: BT-154 item description, when it should say more than the item name.
        - `quantity` number, required: BT-129 invoiced quantity.
        - `unitCode` string, required: BT-130 unit of measure code, UN/ECE Recommendation 20.
        - `unitPrice` number, required: BT-146 item net price.
        - `grossUnitPrice` number: BT-148 item gross price, before the BT-147 price discount.
        - `priceDiscount` number: BT-147 item price discount: the difference between BT-148 and BT-146.
        - `baseQuantity` number: BT-149 item price base quantity, 1 when absent.
        - `vatCategory` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: BT-151 invoiced item VAT category code, UNCL 5305: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L IGIC (Canary Islands), M IPSI (Ceuta and Melilla). Left out, it comes from the line's `vatScenario` or the invoice's.
        - `vatRate` number: BT-152 invoiced item VAT rate, in percent.
        - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened on this line, instead of its VAT code: the engine writes `vatCategory`, the rate (except for "domestic", whose rate you give in `vatRate`) and the exemption reason from it. It overrides the invoice's `vatScenario`. A `vatCategory` stated beside it must be the one it stands for: disagreeing is the fatal ATW-VAT-SCENARIO-CONFLICT. With a scenario, `vatCategory` may be left out of the request although this schema lists it as required (the schema describes the explicit model, which POST /v1/parse returns); the response reports each code it filled in as ATW-VAT-SCENARIO-APPLIED, at severity information. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes.
        - `note` string: BT-127 invoice line note.
        - `objectIdentifier` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
          - `value` string, required: The identifier.
          - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
        - `buyerAccountingReference` string: BT-133 invoice line buyer accounting reference.
        - `period` InvoicingPeriod: BG-14 invoicing period, or BG-26 when it is a line's `period`. The first term of each pair is the document's.
          - `startDate` string, date: BT-73 / BT-134 period start date, ISO 8601.
          - `endDate` string, date: BT-74 / BT-135 period end date, ISO 8601.
          - `descriptionCode` string: BT-8 value added tax point date code, UNTDID 2005 (3, 35 or 432). Document level only: ignored on a line period. BR-CO-03 does not allow it together with `taxPointDate`.
        - `orderLineReference` string: BT-132 referenced purchase order line reference.
        - `allowances` LineAllowanceCharge[]: BG-27 invoice line allowances: discounts on this line only.
          - `amount` number, required: BT-136 / BT-141 amount, always positive.
          - `baseAmount` number: BT-137 / BT-142 base amount.
          - `percentage` number: BT-138 / BT-143 percentage.
          - `reason` string: BT-139 / BT-144 reason, free text.
          - `reasonCode` string: BT-140 / BT-145 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
        - `charges` LineAllowanceCharge[]: BG-28 invoice line charges: surcharges on this line only.
          - `amount` number, required: BT-136 / BT-141 amount, always positive.
          - `baseAmount` number: BT-137 / BT-142 base amount.
          - `percentage` number: BT-138 / BT-143 percentage.
          - `reason` string: BT-139 / BT-144 reason, free text.
          - `reasonCode` string: BT-140 / BT-145 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
        - `sellerItemId` string: BT-155 item seller's identifier.
        - `buyerItemId` string: BT-156 item buyer's identifier.
        - `standardItemId` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
          - `value` string, required: The identifier.
          - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
        - `itemClassifications` ItemClassification[]: BT-158 item classification identifiers.
          - `code` string, required: BT-158 the classification code.
          - `schemeId` string, required: BT-158-1 the scheme it is drawn from, UNTDID 7143.
          - `schemeVersion` string: BT-158-2 the version of that scheme.
        - `originCountryCode` string: BT-159 item country of origin, ISO 3166-1 alpha-2.
        - `itemAttributes` ItemAttribute[]: BG-32 item attributes: name and value pairs describing the item.
          - `name` string, required: BT-160 item attribute name.
          - `value` string, required: BT-161 item attribute value.
      - `allowances` DocumentAllowanceCharge[]: BG-20 document level allowances: discounts on the whole invoice.
        - `amount` number, required: BT-92 / BT-99 amount, always positive.
        - `baseAmount` number: BT-93 / BT-100 base amount.
        - `percentage` number: BT-94 / BT-101 percentage.
        - `vatCategory` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: BT-95 / BT-102 VAT category code, UNCL 5305: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L IGIC (Canary Islands), M IPSI (Ceuta and Melilla). Left out, it comes from the entry's `vatScenario` or the invoice's.
        - `vatRate` number: BT-96 / BT-103 VAT rate, in percent.
        - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened, instead of the VAT code of this allowance or charge: the engine writes `vatCategory`, the rate (except for "domestic", whose rate you give in `vatRate`) and the exemption reason from it. It overrides the invoice's `vatScenario`. A `vatCategory` stated beside it must be the one it stands for: disagreeing is the fatal ATW-VAT-SCENARIO-CONFLICT. With a scenario, `vatCategory` may be left out of the request although this schema lists it as required (the schema describes the explicit model, which POST /v1/parse returns); the response reports each code it filled in as ATW-VAT-SCENARIO-APPLIED, at severity information. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes.
        - `reason` string: BT-97 / BT-104 reason, free text.
        - `reasonCode` string: BT-98 / BT-105 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
      - `charges` DocumentAllowanceCharge[]: BG-21 document level charges: freight, packing, surcharges.
        - `amount` number, required: BT-92 / BT-99 amount, always positive.
        - `baseAmount` number: BT-93 / BT-100 base amount.
        - `percentage` number: BT-94 / BT-101 percentage.
        - `vatCategory` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: BT-95 / BT-102 VAT category code, UNCL 5305: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L IGIC (Canary Islands), M IPSI (Ceuta and Melilla). Left out, it comes from the entry's `vatScenario` or the invoice's.
        - `vatRate` number: BT-96 / BT-103 VAT rate, in percent.
        - `vatScenario` 'domestic' | 'intra-eu-goods' | 'intra-eu-services' | 'export' | 'small-business-exemption': What happened, instead of the VAT code of this allowance or charge: the engine writes `vatCategory`, the rate (except for "domestic", whose rate you give in `vatRate`) and the exemption reason from it. It overrides the invoice's `vatScenario`. A `vatCategory` stated beside it must be the one it stands for: disagreeing is the fatal ATW-VAT-SCENARIO-CONFLICT. With a scenario, `vatCategory` may be left out of the request although this schema lists it as required (the schema describes the explicit model, which POST /v1/parse returns); the response reports each code it filled in as ATW-VAT-SCENARIO-APPLIED, at severity information. "domestic": a taxed sale inside the seller's own country — category S at the rate you state in `vatRate`, which is never guessed. "intra-eu-goods": goods shipped to a VAT-registered business in another EU member state — K, rate 0, VATEX-EU-IC; the invoice also needs both parties' VAT identifiers, `deliverTo.countryCode` and a delivery date or invoicing period. "intra-eu-services": a service to a business in another EU member state, which accounts for the VAT itself (reverse charge) — AE, rate 0, VATEX-EU-AE; needs both VAT identifiers. "export": goods leaving the EU — G, rate 0, VATEX-EU-G; needs the seller's VAT identifier. "small-business-exemption": the seller does not charge VAT under its small-business scheme, Germany's § 19 UStG or France's franchise en base — E, rate 0, with the wording each country prescribes; a seller elsewhere is refused with ATW-VAT-SCENARIO-UNSUPPORTED. The exemption text is written in German for a seller in DE or AT, in French for FR, in English otherwise. It is not a tax determination: you decide which scenario applies, and the engine only writes its codes.
        - `reason` string: BT-97 / BT-104 reason, free text.
        - `reasonCode` string: BT-98 / BT-105 reason code: UNCL 5189 for an allowance, UNCL 7161 for a charge.
      - `paymentTerms` string: BT-20 payment terms, free text.
      - `payment` PaymentInstructions: BG-16 payment instructions. Required for XRechnung profiles by BR-DE-1.
        - `meansCode` string, required: BT-81 payment means type code, UNTDID 4461: "58" SEPA credit transfer, "30" credit transfer, "59" SEPA direct debit, "48" card, "57" standing order, "97" clearing. Left out of a request, it is inferred from the account, as the engine's `applyDefaults` does: "59" for a direct debit mandate in euro and "49" in another currency, else "58" for an IBAN in the SEPA scheme paid in euro and "30" for any other IBAN; the response reports it as ATW-PAYMENT-MEANS-INFERRED, at severity information.
        - `meansName` string: BT-82 payment means text.
        - `iban` string: BT-84 payment account identifier (BG-17): the IBAN, for a credit transfer.
        - `accountName` string: BT-85 payment account name (BG-17).
        - `bic` string: BT-86 payment service provider identifier (BG-17): the BIC.
        - `remittanceInformation` string: BT-83 remittance information: the payment reference.
        - `card` PaymentCard: BG-18 payment card information.
          - `primaryAccountNumber` string, required: BT-87 payment card primary account number: at most its first six and last four digits. BR-51 warns above ten characters; never put a full card number on an invoice.
          - `holderName` string: BT-88 payment card holder name.
        - `directDebit` DirectDebit: BG-19 direct debit information.
          - `mandateReference` string: BT-89 mandate reference identifier.
          - `creditorIdentifier` string: BT-90 bank assigned creditor identifier: the SEPA creditor identifier. Written as the seller's identifier with scheme "SEPA", where BR-DE-30 looks for it.
          - `debitedAccount` string: BT-91 debited account identifier: the payer's IBAN. Required by BR-DE-31.
      - `supportingDocuments` SupportingDocument[]: BG-24 additional supporting documents.
        - `reference` string, required: BT-122 supporting document reference.
        - `description` string: BT-123 supporting document description.
        - `externalUri` string: BT-124 external document location: a URL.
        - `attachment` EmbeddedAttachment: BT-125 attached document, embedded in the invoice.
          - `filename` string, required: BT-125-2 attached document filename. Must be unique across the invoice (BR-DE-22).
          - `mimeCode` string, required: BT-125-1 attached document MIME code. BR-CL-24 admits only application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet and application/vnd.oasis.opendocument.spreadsheet.
          - `content` string, required: BT-125 the document bytes, base64-encoded. Written as given, not re-encoded.
      - `deliveryDate` string, date: BT-72 actual delivery date, ISO 8601. Required with BT-80 by BR-IC-11 for category K. On XRechnung profiles, an invoice with no time of supply at all (no BT-72, no `invoicingPeriod`, no line `period`) raises BR-DE-TMP-32 at severity `information`.
      - `deliverTo` DeliverToAddress: BG-15 deliver-to address. Only the country code is required by the model; XRechnung also requires the city and post code once the group is present.
        - `line1` string: BT-75 deliver-to address line 1.
        - `line2` string: BT-76 deliver-to address line 2.
        - `city` string: BT-77 deliver-to city. Mandatory under XRechnung once BG-15 is present.
        - `postalCode` string: BT-78 deliver-to post code. Mandatory under XRechnung once BG-15 is present.
        - `countrySubdivision` string: BT-79 deliver-to country subdivision.
        - `countryCode` string, required: BT-80 deliver-to country code, ISO 3166-1 alpha-2.
      - `deliverToName` string: BT-70 deliver-to party name.
      - `deliverToLocationId` SchemedIdentifier: An identifier with its scheme. The field that holds it names the business term, and which code list the scheme comes from.
        - `value` string, required: The identifier.
        - `schemeId` string: Its scheme identifier: ISO 6523 ICD for party, location and item identifiers, UNTDID 1153 for the invoiced object and line object identifiers.
      - `vatAccountingCurrency` string: BT-6 VAT accounting currency, ISO 4217, when VAT is reported in a currency other than BT-5. Supplying it obliges you to supply `taxAmountInAccountingCurrency` (BR-53).
      - `taxAmountInAccountingCurrency` number: BT-111 invoice total VAT amount in the VAT accounting currency. It depends on the exchange rate the tax authority requires for the tax point, which is not on the invoice, so it cannot be derived: you supply it.
      - `paidAmount` number: BT-113 paid amount: a prepayment or deposit already received. It is subtracted from the amount due (BT-115).
      - `roundingAmount` number: BT-114 rounding amount, added to the total to produce a payable round figure.
      - `vatExemptionReasons` object: BT-120 VAT exemption reason text, keyed by VAT category, such as `{"E": "…"}`. Defaults are applied for AE, K, G and O; category E has no standard text, so BR-E-10 requires you to supply one.
      - `vatExemptionReasonCodes` object: BT-121 VAT exemption reason code from the CEF VATEX list, keyed by VAT category.
      - `declaredTotals` DeclaredTotals: Totals as someone else computed them, checked against the computed ones under BR-CO-10/11/12/13/14/15/16. Generation always writes the computed values: these exist so you can catch a mismatch in your own accounting system before a tax authority does, and omitting one is never an error. The readers (POST /v1/parse, and POST /v1/validate with a document) also record here what a document states, including the fields described as set by the readers, which a caller building the model leaves out. On that path a document must state its totals: one that omits BT-106, BT-109, BT-112 or BT-115 fails BR-12, BR-13, BR-14 or BR-15, and one that states a total that cannot be read as a number fails ATW-DECLARED-TOTAL-NOT-A-NUMBER.
        - `syntax` 'ubl' | 'cii': Set by the readers: the syntax the document was read from. It decides how BR-S-08 and its per-category siblings compare the stated taxable amount: exactly in CII, within ±1 in UBL.
        - `taxTotalsInInvoiceCurrency` number: Set by the readers: how many VAT totals carry the invoice currency (BT-5). BR-CO-15 requires exactly one.
        - `specificationIdentifier` string: BT-24 specification identifier as the document states it, trimmed; empty when absent. Set by the readers, so BR-01 can be judged.
        - `lineNetAmounts` number[]: BT-131 invoice line net amounts as each line states them, in document order; null where a line states none. Set by the readers.
        - `subtotals` DeclaredTaxSubtotal[]: BG-23 VAT breakdown as the document states it, in document order. Set by the readers.
          - `category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M': BT-118 VAT category code, as written.
          - `rate` number: BT-119 VAT category rate, as written.
          - `taxableAmount` number: BT-116 VAT category taxable amount, as written.
          - `taxAmount` number: BT-117 VAT category tax amount, as written.
        - `lineExtensionAmount` number: BT-106 sum of invoice line net amounts.
        - `allowanceTotalAmount` number: BT-107 sum of allowances on document level.
        - `chargeTotalAmount` number: BT-108 sum of charges on document level.
        - `taxExclusiveAmount` number: BT-109 invoice total amount without VAT.
        - `taxAmount` number: BT-110 invoice total VAT amount.
        - `taxInclusiveAmount` number: BT-112 invoice total amount with VAT.
        - `payableAmount` number: BT-115 amount due for payment.
        - `defects` DeclaredTotalDefect[]: Set by the readers: document totals the document was supposed to state and did not state readably, one entry per term. On the JSON model an omitted total means "compute it" and is never a defect.
          - `key` 'lineExtensionAmount' | 'allowanceTotalAmount' | 'chargeTotalAmount' | 'taxExclusiveAmount' | 'taxAmount' | 'taxInclusiveAmount' | 'payableAmount' | 'taxAmountInAccountingCurrency', required: Which total it is, as a key of DeclaredTotals. `taxAmountInAccountingCurrency` names BT-111, which the model carries on the invoice itself.
          - `field` string, required: The business term, such as BT-115.
          - `state` 'absent' | 'empty' | 'unreadable', required: Why it could not be read: `absent` fails a BR presence rule, while `empty` and `unreadable` fail XML Schema validation at the official validator before any business rule, and this API reports them as ATW-DECLARED-TOTAL-NOT-A-NUMBER.
          - `text` string: What the element held, verbatim, cut at 200 characters. Only for `unreadable`.
          - `xpath` string, required: Where the value is in the document, or where it should have been.
        - `overPrecise` OverPreciseAmount[]: Set by the readers: amounts the document wrote with more than two decimal places, in document order, which the BR-DEC rules report.
          - `field` string, required: The business term, which selects the BR-DEC rule.
          - `decimals` number, required: Digits after the decimal point, trailing zeros included.
          - `text` string, required: The amount exactly as the document writes it.
          - `xpath` string, required: Where it was found.
          - `line` number: 1-based invoice line, for a line-level term (BT-131).
          - `group` number: 1-based VAT breakdown group, for BT-116 and BT-117.
    - `pdf` PdfOptions: Options for the page of the Factur-X / ZUGFeRD PDF (`?format=pdf`). Every one is optional; an unknown name is refused with 400 rather than ignored.
      - `language` 'en' | 'de' | 'fr': The language of the page: its labels, and the way it formats numbers and dates. Default: the seller country's — DE and AT German, FR French, anything else English. The invoice's own text (names, descriptions, notes) and the embedded XML are the same in every language. Query parameter: `language`.
      - `logo` string: A PNG or baseline JPEG as a data URL (`data:image/png;base64,…` or `data:image/jpeg;base64,…`), at most 256 KB and 2000 pixels on either side, in RGB or greyscale. It is printed in the top-left corner of the first page, scaled to fit 150 × 50 points; a PNG keeps its transparency. About 625 × 210 pixels is already 300 dpi there, and a larger PNG only costs time to decode. Refused with 400: a CMYK or progressive JPEG, an interlaced PNG, or any other kind of file. Body only.
      - `paymentQr` boolean: The EPC payment QR code ("GiroCode"), printed beside the payment details so a banking app can fill in the transfer: payee, IBAN, amount due and reference. Default: printed whenever the invoice can carry one — currency EUR, payment means 30, 42 or 58 (credit transfer), a valid IBAN, an amount due from 0.01 EUR, and not a credit note — and left out otherwise. `false` leaves it out; `true` requires it, and an invoice that cannot carry it is then a 400 that says why. The reference in the code is the payment reference (BT-83), or else the invoice number. Query parameter: `payment_qr=true|false`.
      - `paymentLink` string, uri: An https:// address where the invoice can be paid online, such as a payment page from your payment provider. It is printed under the payment details and is clickable in the PDF (a link annotation, which PDF/A permits; no script). At most 500 characters, no user name or password. It is on the page only: EN 16931 has no field for it, so the embedded XML does not carry it. Query parameter: `payment_link` (URL-encoded).

## Response `200`

The generated document.

- object
  - `xml` string, required: The complete XML document.
  - `profile` 'en16931' | 'xrechnung-ubl' | 'peppol-bis-3' | 'xrechnung-cii' | 'facturx-en16931', required
  - `syntax` 'ubl' | 'cii', required: Which syntax the `xml` is in. Determined by `profile`: xrechnung-cii and facturx-en16931 are CII, everything else is UBL 2.1.
  - `note` string: Present on CII responses only. States that the document is the CII XML payload and not a Factur-X or ZUGFeRD PDF, because that is the mistake this response invites. Absent for UBL.
  - `warnings` TeachingError[], required
    - `rule` string, required: The rule id, as the KoSIT validator prints it: BR-*, BR-DE-*, PEPPOL-EN16931-R*. `ATW-*` is a check of this validator's own rather than the regulation's. `AW-*` is not a rule at all: see above.
    - `field` union, required: Business term(s) the rule constrains.
      - string
      - string[]
    - `severity` 'fatal' | 'warning' | 'information', required: The reference validators' own three levels. `fatal` rejects the document; `warning` does not; `information` is advisory — KoSIT raises it and then accepts the invoice.
    - `message` string, required
    - `fix` string, required
    - `xpath` string: Where the element is. For a JSON invoice, its place in the UBL this API would generate. For an XML document, its path in that document as written when it is there, otherwise where it belongs, in the document's own syntax.
    - `docsUrl` string, uri: Where the rule is explained. On every finding except an `AW-` one, which is not a rule and has no page.
    - `example` string
    - `location` SourceLocation: Only on findings for a document, and not on an `AW-` one, which is about the whole document. The line and column of the element in the document that was sent. When the element is missing, or several could be meant and nothing says which, `exact` is false and this is the nearest enclosing element that is there.
      - `line` integer, required
      - `column` integer, required: Of the start tag, in UTF-16 code units.
      - `path` string, required: The element's path, with the document's own prefixes.
      - `exact` boolean, required
      - `attachment` string: Only when a PDF was sent: the name of the attachment the XML was read from. `line` and `column` are then in that XML, not in the PDF.
  - `information` TeachingError[], required: Advisory findings from the validation that preceded generation. They did not block the document.
    - `rule` string, required: The rule id, as the KoSIT validator prints it: BR-*, BR-DE-*, PEPPOL-EN16931-R*. `ATW-*` is a check of this validator's own rather than the regulation's. `AW-*` is not a rule at all: see above.
    - `field` union, required: Business term(s) the rule constrains.
      - string
      - string[]
    - `severity` 'fatal' | 'warning' | 'information', required: The reference validators' own three levels. `fatal` rejects the document; `warning` does not; `information` is advisory — KoSIT raises it and then accepts the invoice.
    - `message` string, required
    - `fix` string, required
    - `xpath` string: Where the element is. For a JSON invoice, its place in the UBL this API would generate. For an XML document, its path in that document as written when it is there, otherwise where it belongs, in the document's own syntax.
    - `docsUrl` string, uri: Where the rule is explained. On every finding except an `AW-` one, which is not a rule and has no page.
    - `example` string
    - `location` SourceLocation: Only on findings for a document, and not on an `AW-` one, which is about the whole document. The line and column of the element in the document that was sent. When the element is missing, or several could be meant and nothing says which, `exact` is false and this is the nearest enclosing element that is there.
      - `line` integer, required
      - `column` integer, required: Of the start tag, in UTF-16 code units.
      - `path` string, required: The element's path, with the document's own prefixes.
      - `exact` boolean, required
      - `attachment` string: Only when a PDF was sent: the name of the attachment the XML was read from. `line` and `column` are then in that XML, not in the PDF.
  - `findings_truncated` FindingsTruncated: Present ONLY when a findings array was truncated, and absent — not null, not zeroed — otherwise. Each of `errors`, `warnings` and `information` is capped independently; past the cap the array is cut and this object states what was left out. `valid` still reflects the whole document: truncation changes what is printed, never the verdict. Reaching the cap takes a hundred-plus invoice lines on which every field is wrong, and at that scale the errors are systematic — every distinct problem in the document already appears in what you were given. Treat it as a hint to fix the pattern and re-validate, not as an error.
    - `total` integer, required: Findings the engine produced, across all three severities.
    - `returned` integer, required: Findings actually listed in this response.
    - `cap` integer, required: The per-severity cap this deployment applied.
    - `by_severity` object, required: Per-array totals, so you can see which one overflowed.
      - `errors` TruncationCount, required
        - `total` integer, required
        - `returned` integer, required
      - `warnings` TruncationCount, required
        - `total` integer, required
        - `returned` integer, required
      - `information` TruncationCount, required
        - `total` integer, required
        - `returned` integer, required
    - `note` string, required: Prose explanation, safe to show a user or an agent verbatim.
  - `profile_choice` ProfileChoice: Present only when the request said `"profile": "auto"`: the profile the API chose from the invoice's buyer, the rule that chose it, and why. Deterministic and made without any network call; POST /v1/recipient answers the same question from live registrations.
    - `requested` 'auto', required
    - `profile` 'en16931' | 'xrechnung-ubl' | 'peppol-bis-3' | 'xrechnung-cii' | 'facturx-en16931', required
    - `rule` 'leitweg-id' | 'belgium' | 'peppol-address' | 'france' | 'germany-austria-business' | 'default', required: `leitweg-id`: the buyer's electronic address has scheme 0204, or a German buyer reference is a Leitweg-ID. `belgium`: the buyer is in Belgium. `peppol-address`: the buyer's electronic address is a Peppol participant identifier. `france`: the buyer is in France. `germany-austria-business`: a business buyer in Germany or Austria. `default`: none of these.
    - `reason` string, required: The rule, as a sentence about this invoice.
  - `provenance` Provenance: What ran. Present on every metered response — POST /v1/validate and POST /v1/parse, JSON body or XML document, and the JSON envelope of POST /v1/generate including the `422` it returns for an invoice it will not emit. WHY IT EXISTS. Pin `@attestwire/en16931` and your CI gets the same answer for the same invoice forever; the hosted API always runs the current rule set, because a compliance service that froze its rules would be answering last quarter's regulation. Both are correct and the difference used to be invisible — a `valid: false` looked identical whether your invoice had changed or our rules had. This says which. The one metered response WITHOUT it is `/v1/generate?format=xml`, which returns the document alone: an XML file has nowhere to put this, and this API does not write its own metadata into a customer's tax document.
    - `engine` string, required: The npm package every compliance decision on this API comes from. Install this package at `engine_version` and you have the build that judged your document.
    - `engine_version` string, required
    - `ruleset` string, required: The standard and our build of it, as one identifier to quote.
    - `profile` string, nullable, required: The CIUS that ACTUALLY ran, read from the result rather than from your request: a body naming no profile is judged as `en16931`, and this is where you see that. `null` when there was no verdict to read it from.
    - `kosit_conformance` KositConformance, required: When the official KoSIT validator was last run against this engine's committed fixtures, and with what. **NOTHING IS SENT TO KoSIT WHEN YOU CALL US.** This is a dated record of a check we ran on release, not a per-call verification, and it says nothing about YOUR document.
      - `recorded` string, date, required: The date of the last recorded full fixture run.
      - `validator` string, required: Version of the KoSIT standalone validator used.
      - `configuration` string, required: Version of the XRechnung validator configuration used.
      - `configuration_published` string, date, required: The date that configuration was published by KoSIT.

## Other responses

- `400`: Two codes. `bad_request` — the invoice could not be read at all (see the same code on `/v1/validate`), or the request's shape or PDF options are wrong: a `pdf` object without an `invoice`, a wrapper with keys other than `invoice` and `pdf`, an unknown PDF option, a value an option does not take, or one option named differently in the body and the query. The message names the field. `unsupported_profile` — for JSON and XML, kept as a safety net that current input does not reach: this build has no generator for the requested profile. Generation currently covers: en16931, xrechnung-ubl, peppol-bis-3, xrechnung-cii, facturx-en16931, which is every value in the `profile` enum, and a `profile` outside the enum fails validation first (`ATW-PROFILE-UNKNOWN`, a 422). With `?format=pdf` it is also the answer to any profile other than `facturx-en16931`, which is the only profile this API's Factur-X / ZUGFeRD PDF carries; that check comes before validation, so a profile outside the enum gets this 400 rather than the 422. Neither code charges a document.
- `401`: Missing or unknown API key.
- `410`: The key presented was retired by an earlier rotation. Its replacement is the live credential; this one is permanently gone, so retrying with it cannot work. Every authenticated endpoint answers this, not just /v1/keys/rotate.
- `413`: The request body is over 1 MB. Nothing was read and nothing was charged.
- `422`: The invoice does not satisfy the profile; nothing was generated and no document was charged. The body is the ValidationResult /v1/validate would have returned, capped on the same terms, and the `X-RateLimit-*` set reports the UNCHANGED counter.
- `429`: Refused for pace or for allowance. `error: "quota_exceeded"` — the monthly document allowance is exhausted, and the counter resets at 00:00 UTC on the 1st. `error: "rate_limited"` — too many requests per second on this key; retry after the number of seconds in `Retry-After` and the same request will succeed. Nothing is charged in either case.
- `500`: Something threw. Nothing was charged either way — the meter moves only once there is XML to hand over. `generation_failed` comes from the generator itself and carries the quota headers; `uncaught` comes from the route-wide handler and carries no headers and no `docs` link.
- `501`: Generation is not available in this build. Checked before authentication, so it costs neither a key nor a document.

---

[API](https://skmtc.dev/attestwire/apis/attestwire-api.md) · [All operations](https://skmtc.dev/attestwire/apis/attestwire-api/llms.txt) · [OpenAPI document](https://skmtc.dev/attestwire/apis/attestwire-api/revisions/0036f8e043b2?raw)