invowerk · Schema

GenerateRequest

The request body of POST /v1/generate: an EN 16931 invoice, keyed on Business Terms (BT-*). All amounts are your own figures. invowerk writes them into the XML and checks the result against EN 16931 (and XRechnung, if selected). It does not compute or correct them. Input that breaks an EN 16931 or XRechnung rule is refused (HTTP 422), each rule named. Dates are YYYY-MM-DD, amounts go up to 999,999,999.99.

Invoicinge-invoicePDFGermany

Properties

Name	Type	Description
syntax	object	XML syntax of the invoice: 'ubl' or 'cii'.
flavor	object	Rule set: 'en16931' (plain EN 16931) or 'xrechnung' (German rules).
invoice_number	string	Invoice number (BT-1).
issue_date	string	Issue date, 'YYYY-MM-DD' (BT-2).
currency	string	Currency code, ISO 4217, e.g. 'EUR' (BT-5).
invoice_type_code	string	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'
buyer_reference	object	Buyer reference, in Germany often the Leitweg-ID (BT-10). Required for flavor 'xrechnung' (BR-DE-15), optional for plain EN 16931.
due_date	object	Payment due date, 'YYYY-MM-DD' (BT-9).
payment_iban	object	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	object	Payment terms as free text (BT-20).
notes	array	Free-text notes on the invoice as a whole, one entry per note (BT-22).
delivery_date	object	Actual delivery date, 'YYYY-MM-DD' (BT-72). Defaults to the issue date unless a delivery period is given.
delivery_period_start	object	Start of the invoicing period, 'YYYY-MM-DD' (BT-73, BG-14), e.g. the period a service covers.
delivery_period_end	object	End of the invoicing period, 'YYYY-MM-DD' (BT-74, BG-14). Not before the start (BR-29).
deliver_to	object	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	object	Name of the party the goods or services are delivered to (BT-70).
deliver_to_id	object	Identifier of the delivery location, e.g. a GLN (BT-71).
deliver_to_id_scheme	object	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	object	Purchase order reference: the buyer's order number (BT-13).
preceding_invoices	array	Earlier invoices this invoice refers to (BG-3), e.g. the invoice a corrected invoice (384) replaces. Syntax 'cii' carries at most one.
seller	object
buyer	object
lines	array	One or more invoice lines (BG-25).
tax_breakdown	array	One or more VAT breakdowns, one per VAT category and rate (BG-23).
totals	object

View JSON Schema on GitHub

JSON Schema

{
  "$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)."
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this

find_json_schemasBrowse and filter every JSON Schema in the catalog.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This JSON Schema

curl "https://apis.io/api/v1/json-schemas/invowerk-dev-generate-request"

All schemas

curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.