{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/invowerk-dev/json-schema/invowerk-dev-generate-request-schema.json",
  "title": "GenerateRequest",
  "description": "The request body of POST /v1/generate: an EN 16931 invoice, keyed on\nBusiness Terms (BT-*).\n\nAll amounts are your own figures. invowerk writes them into the XML and\nchecks the result against EN 16931 (and XRechnung, if selected). It does not\ncompute or correct them. Input that breaks an EN 16931 or XRechnung rule is\nrefused (HTTP 422), each rule named. Dates are YYYY-MM-DD, amounts go up to\n999,999,999.99.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/invowerk-dev-openapi.yml#/components/schemas/GenerateRequest",
  "properties": {
    "syntax": {
      "$ref": "#/$defs/Syntax",
      "description": "XML syntax of the invoice: 'ubl' or 'cii'.",
      "default": "ubl"
    },
    "flavor": {
      "$ref": "#/$defs/Flavor",
      "description": "Rule set: 'en16931' (plain EN 16931) or 'xrechnung' (German rules).",
      "default": "en16931"
    },
    "invoice_number": {
      "type": "string",
      "title": "Invoice Number",
      "description": "Invoice number (BT-1)."
    },
    "issue_date": {
      "type": "string",
      "title": "Issue Date",
      "description": "Issue date, 'YYYY-MM-DD' (BT-2)."
    },
    "currency": {
      "type": "string",
      "maxLength": 3,
      "minLength": 3,
      "title": "Currency",
      "description": "Currency code, ISO 4217, e.g. 'EUR' (BT-5).",
      "default": "EUR"
    },
    "invoice_type_code": {
      "type": "string",
      "title": "Invoice Type Code",
      "description": "Invoice type code from UNTDID 1001 (BT-3): '380' commercial invoice, '326' partial invoice, '381' credit note (syntax 'cii' only), '384' corrected invoice, '389' self-billed invoice, '875'/'876'/'877' partial, partial final and final construction invoice.",
      "default": "380"
    },
    "buyer_reference": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Buyer Reference",
      "description": "Buyer reference, in Germany often the Leitweg-ID (BT-10). Required for flavor 'xrechnung' (BR-DE-15), optional for plain EN 16931."
    },
    "due_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Due Date",
      "description": "Payment due date, 'YYYY-MM-DD' (BT-9)."
    },
    "payment_iban": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Payment Iban",
      "description": "IBAN of the payee account for a bank transfer (BT-84). Without it the invoice carries no payment instructions (BG-16). Required for flavor 'xrechnung' (BR-DE-1)."
    },
    "payment_terms": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Payment Terms",
      "description": "Payment terms as free text (BT-20)."
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Notes",
      "description": "Free-text notes on the invoice as a whole, one entry per note (BT-22)."
    },
    "delivery_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Delivery Date",
      "description": "Actual delivery date, 'YYYY-MM-DD' (BT-72). Defaults to the issue date unless a delivery period is given."
    },
    "delivery_period_start": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Delivery Period Start",
      "description": "Start of the invoicing period, 'YYYY-MM-DD' (BT-73, BG-14), e.g. the period a service covers."
    },
    "delivery_period_end": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Delivery Period End",
      "description": "End of the invoicing period, 'YYYY-MM-DD' (BT-74, BG-14). Not before the start (BR-29)."
    },
    "deliver_to": {
      "anyOf": [
        {
          "$ref": "#/$defs/PostalAddress"
        },
        {
          "type": "null"
        }
      ],
      "description": "Deliver-to address (BG-15): where the goods go or the service is performed. Needed for VAT category 'K', intra-community supply (BT-80, BR-IC-12)."
    },
    "deliver_to_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Deliver To Name",
      "description": "Name of the party the goods or services are delivered to (BT-70)."
    },
    "deliver_to_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Deliver To Id",
      "description": "Identifier of the delivery location, e.g. a GLN (BT-71)."
    },
    "deliver_to_id_scheme": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Deliver To Id Scheme",
      "description": "Scheme of 'deliver_to_id', an ISO/IEC 6523 ICD code, e.g. '0088' for a GLN (BT-71-1). Without it the identifier is written without a scheme."
    },
    "order_reference": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Order Reference",
      "description": "Purchase order reference: the buyer's order number (BT-13)."
    },
    "preceding_invoices": {
      "items": {
        "$ref": "#/$defs/PrecedingInvoice"
      },
      "type": "array",
      "title": "Preceding Invoices",
      "description": "Earlier invoices this invoice refers to (BG-3), e.g. the invoice a corrected invoice (384) replaces. Syntax 'cii' carries at most one."
    },
    "seller": {
      "$ref": "#/$defs/Seller"
    },
    "buyer": {
      "$ref": "#/$defs/Buyer"
    },
    "lines": {
      "items": {
        "$ref": "#/$defs/InvoiceLine"
      },
      "type": "array",
      "minItems": 1,
      "title": "Lines",
      "description": "One or more invoice lines (BG-25)."
    },
    "tax_breakdown": {
      "items": {
        "$ref": "#/$defs/TaxBreakdown"
      },
      "type": "array",
      "minItems": 1,
      "title": "Tax Breakdown",
      "description": "One or more VAT breakdowns, one per VAT category and rate (BG-23)."
    },
    "totals": {
      "$ref": "#/$defs/DocumentTotals"
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "invoice_number",
    "issue_date",
    "seller",
    "buyer",
    "lines",
    "tax_breakdown",
    "totals"
  ],
  "$defs": {
    "Buyer": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Buyer name (BT-44)."
        },
        "address": {
          "$ref": "#/$defs/PostalAddress",
          "description": "Buyer postal address (BG-8)."
        },
        "vat_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Vat Id",
          "description": "Buyer VAT ID, e.g. 'ATU12345678' (BT-48). Needed on lines with VAT category 'AE' (BR-AE-02) or 'K' (BR-IC-02)."
        },
        "electronic_address": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Electronic Address",
          "description": "Buyer electronic address (BT-49)."
        }
      },
      "type": "object",
      "required": [
        "name",
        "address"
      ],
      "title": "Buyer",
      "description": "The buyer (BG-7)."
    },
    "DocumentTotals": {
      "properties": {
        "line_total": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Line Total",
          "description": "Sum of the line net amounts (BT-106)."
        },
        "tax_exclusive": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Tax Exclusive",
          "description": "Invoice total without VAT (BT-109). invowerk writes no document-level allowances or charges, so to generate, it must equal the line total (BR-CO-13)."
        },
        "tax_inclusive": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Tax Inclusive",
          "description": "Invoice total with VAT (BT-112): the total without VAT plus the sum of the VAT breakdown amounts (BR-CO-15)."
        },
        "prepaid": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prepaid",
          "description": "Amount already paid, e.g. the sum of earlier partial invoices on a final invoice (BT-113)."
        },
        "payable": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Payable",
          "description": "Amount due for payment (BT-115). Defaults to the total with VAT minus the paid amount (BT-112 − BT-113)."
        }
      },
      "type": "object",
      "required": [
        "line_total",
        "tax_exclusive",
        "tax_inclusive"
      ],
      "title": "DocumentTotals",
      "description": "The document totals (BG-22)."
    },
    "Flavor": {
      "type": "string",
      "enum": [
        "en16931",
        "xrechnung"
      ],
      "title": "Flavor",
      "description": "The rule set the invoice follows: plain EN 16931, or XRechnung (German rules)."
    },
    "InvoiceLine": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Item name (BT-153)."
        },
        "net_price": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Net Price",
          "description": "Net price per unit (BT-146)."
        },
        "quantity": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Quantity",
          "description": "Invoiced quantity (BT-129)."
        },
        "unit_code": {
          "type": "string",
          "title": "Unit Code",
          "description": "Unit code from UN/ECE Recommendation 20; 'C62' means 'one' (BT-130).",
          "default": "C62"
        },
        "line_net_amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Line Net Amount",
          "description": "Line net amount, quantity × net price, as you state it (BT-131)."
        },
        "tax_category": {
          "type": "string",
          "title": "Tax Category",
          "description": "VAT category code of the line, e.g. 'S' for standard rate (BT-151).",
          "default": "S"
        },
        "tax_rate": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Tax Rate",
          "description": "VAT rate of the line in percent, e.g. 19.00 (BT-152). Not written for category 'O', not subject to VAT (BR-O-05).",
          "default": "19.00"
        }
      },
      "type": "object",
      "required": [
        "name",
        "net_price",
        "quantity",
        "line_net_amount"
      ],
      "title": "InvoiceLine",
      "description": "One invoice line (BG-25)."
    },
    "PostalAddress": {
      "properties": {
        "line_one": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Line One",
          "description": "Address line 1, usually street and house number (BT-35 seller, BT-50 buyer, BT-75 deliver-to)."
        },
        "city": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "City",
          "description": "City (BT-37 seller, BT-52 buyer)."
        },
        "post_code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Post Code",
          "description": "Post code (BT-38 seller, BT-53 buyer)."
        },
        "country_code": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2,
          "title": "Country Code",
          "description": "Country code, ISO 3166-1 alpha-2, e.g. 'DE' (BT-40 seller, BT-55 buyer)."
        }
      },
      "type": "object",
      "required": [
        "country_code"
      ],
      "title": "PostalAddress",
      "description": "A postal address (BG-5 seller, BG-8 buyer, BG-15 deliver-to).\n\nEN 16931 requires only the country. XRechnung also requires city and post\ncode for the seller. invowerk does not check that the address exists."
    },
    "PrecedingInvoice": {
      "properties": {
        "number": {
          "type": "string",
          "title": "Number",
          "description": "Number of the earlier invoice (BT-25)."
        },
        "issue_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Issue Date",
          "description": "Issue date of the earlier invoice, 'YYYY-MM-DD' (BT-26)."
        }
      },
      "type": "object",
      "required": [
        "number"
      ],
      "title": "PrecedingInvoice",
      "description": "A reference to an earlier invoice (BG-3), e.g. the invoice a corrected invoice\n(384) replaces, or a partial invoice a final invoice (877) settles."
    },
    "Seller": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Seller name, the registered name (BT-27)."
        },
        "address": {
          "$ref": "#/$defs/PostalAddress",
          "description": "Seller postal address (BG-5)."
        },
        "vat_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Vat Id",
          "description": "Seller VAT ID, e.g. 'DE123456789' (BT-31). Needed when a line has VAT category 'S' (BR-S-02)."
        },
        "tax_number": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Tax Number",
          "description": "Seller tax registration identifier, e.g. a German Steuernummer '123/456/78901' (BT-32). Written with scheme 'FC'."
        },
        "identifier": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Identifier",
          "description": "Seller identifier, e.g. a GLN or an ID the buyer knows the seller by (BT-29). An invoice needs BT-29, BT-30 or BT-31 (BR-CO-26)."
        },
        "identifier_scheme": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Identifier Scheme",
          "description": "Scheme of the seller identifier, an ISO/IEC 6523 ICD code, e.g. '0088' for a GLN (BT-29-1). Leave empty for an identifier without a scheme."
        },
        "legal_registration_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Legal Registration Id",
          "description": "Seller legal registration identifier, e.g. a Handelsregisternummer 'HRB 12345' (BT-30). An invoice needs BT-29, BT-30 or BT-31 (BR-CO-26)."
        },
        "legal_registration_scheme": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Legal Registration Scheme",
          "description": "Scheme of the legal registration identifier, an ISO/IEC 6523 ICD code (BT-30-1). Leave empty for an identifier without a scheme."
        },
        "contact_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Contact Name",
          "description": "Seller contact name; required for XRechnung (BT-41)."
        },
        "contact_phone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Contact Phone",
          "description": "Seller contact phone; required for XRechnung (BT-42)."
        },
        "contact_email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Contact Email",
          "description": "Seller contact email; required for XRechnung (BT-43)."
        },
        "electronic_address": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Electronic Address",
          "description": "Seller electronic address, e.g. an email address (BT-34)."
        }
      },
      "type": "object",
      "required": [
        "name",
        "address"
      ],
      "title": "Seller",
      "description": "The seller (BG-4)."
    },
    "Syntax": {
      "type": "string",
      "enum": [
        "cii",
        "ubl"
      ],
      "title": "Syntax",
      "description": "The XML syntax of the invoice: UBL or CII."
    },
    "TaxBreakdown": {
      "properties": {
        "taxable_amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Taxable Amount",
          "description": "Taxable amount of the category (BT-116)."
        },
        "tax_amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Tax Amount",
          "description": "VAT amount of the category (BT-117)."
        },
        "category": {
          "type": "string",
          "title": "Category",
          "description": "VAT category code, e.g. 'S' for standard rate (BT-118).",
          "default": "S"
        },
        "rate": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            }
          ],
          "title": "Rate",
          "description": "VAT rate of the category in percent (BT-119).",
          "default": "19.00"
        },
        "exemption_reason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Exemption Reason",
          "description": "VAT exemption reason as text (BT-120). The rules require it or its code for categories such as 'E', 'AE', 'K', 'G' (e.g. BR-E-10)."
        },
        "exemption_reason_code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Exemption Reason Code",
          "description": "VAT exemption reason code from the VATEX code list, e.g. 'VATEX-EU-AE' (BT-121)."
        }
      },
      "type": "object",
      "required": [
        "taxable_amount",
        "tax_amount"
      ],
      "title": "TaxBreakdown",
      "description": "One VAT breakdown: the totals for one VAT category and rate (BG-23)."
    }
  }
}