Skip to content
HALOWERK

Formatwerk

xrechnung generate

Builds an EN 16931 / XRechnung 3.0 invoice in UBL 2.1 or UN/CEFACT CII syntax with seller and buyer electronic addresses, contact, payment means (SEPA credit transfer with IBAN), VAT breakdown per category and rate, and totals rounded per EN 16931 rules (line net = quantity × price, VAT per category = base × rate). Every invoice is checked with the KoSIT validator 1.6.3 and the XRechnung configuration 3.0.2; invoices that are not accepted are not charged and the validator messages are returned.

POST https://format.halowerk.com/v1/xrechnung-generate

Inputs

Fields of the published input schema
FieldTypeRequiredDescription
numberstringYes
type_codestringNo
issue_datestringYes
due_datestringNo
currencystringNo
buyer_referencestringYesBT-10, for public buyers the Leitweg-ID.
order_referencestringNo
preceding_invoicestringNoBT-25, required for credit notes and corrections.
notestringNo
delivery_datestringNo
sellerReferenceYes
buyerReferenceYes
paymentobjectYes
linesarrayYes
syntaxstringNo
Show full input schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "number",
    "issue_date",
    "buyer_reference",
    "seller",
    "buyer",
    "lines",
    "payment"
  ],
  "properties": {
    "number": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "type_code": {
      "type": "string",
      "enum": [
        "380",
        "381",
        "384",
        "389",
        "326",
        "875",
        "876",
        "877"
      ],
      "default": "380"
    },
    "issue_date": {
      "type": "string",
      "format": "date"
    },
    "due_date": {
      "type": "string",
      "format": "date"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "default": "EUR"
    },
    "buyer_reference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "BT-10, for public buyers the Leitweg-ID."
    },
    "order_reference": {
      "type": "string",
      "maxLength": 100
    },
    "preceding_invoice": {
      "type": "string",
      "maxLength": 100,
      "description": "BT-25, required for credit notes and corrections."
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    },
    "delivery_date": {
      "type": "string",
      "format": "date"
    },
    "seller": {
      "$ref": "#/$defs/partei"
    },
    "buyer": {
      "$ref": "#/$defs/partei"
    },
    "payment": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "means_code"
      ],
      "properties": {
        "means_code": {
          "type": "string",
          "enum": [
            "58",
            "59",
            "30",
            "31",
            "42",
            "48",
            "49",
            "57",
            "1",
            "10",
            "97",
            "ZZZ"
          ]
        },
        "iban": {
          "type": "string",
          "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$"
        },
        "bic": {
          "type": "string",
          "pattern": "^[A-Z0-9]{8}([A-Z0-9]{3})?$"
        },
        "account_name": {
          "type": "string",
          "maxLength": 140
        },
        "terms": {
          "type": "string",
          "maxLength": 500
        },
        "remittance": {
          "type": "string",
          "maxLength": 140
        }
      }
    },
    "lines": {
      "type": "array",
      "minItems": 1,
      "maxItems": 1000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "quantity",
          "unit_code",
          "unit_price",
          "vat_rate"
        ],
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 50
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "description": {
            "type": "string",
            "maxLength": 2000
          },
          "quantity": {
            "type": "number"
          },
          "unit_code": {
            "type": "string",
            "pattern": "^[A-Z0-9]{2,3}$",
            "description": "UN/ECE Rec 20, e.g. C62 (piece), HUR (hour), DAY, KGM, MTR, LS (lump sum)."
          },
          "unit_price": {
            "type": "number",
            "minimum": 0
          },
          "vat_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "vat_category": {
            "type": "string",
            "enum": [
              "S",
              "Z",
              "E",
              "AE",
              "K",
              "G",
              "O"
            ],
            "description": "Default S for rate > 0, else E (requires exemption reason)."
          },
          "vat_exemption_reason": {
            "type": "string",
            "maxLength": 300
          }
        }
      }
    },
    "syntax": {
      "type": "string",
      "enum": [
        "ubl",
        "cii"
      ],
      "default": "ubl"
    }
  },
  "$defs": {
    "partei": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "street",
        "postcode",
        "city",
        "country",
        "electronic_address"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "street": {
          "type": "string",
          "maxLength": 200
        },
        "postcode": {
          "type": "string",
          "maxLength": 20
        },
        "city": {
          "type": "string",
          "maxLength": 100
        },
        "country": {
          "type": "string",
          "pattern": "^[A-Z]{2}$"
        },
        "vat_id": {
          "type": "string",
          "pattern": "^[A-Z]{2}[A-Za-z0-9]{2,13}$"
        },
        "tax_number": {
          "type": "string",
          "maxLength": 30
        },
        "electronic_address": {
          "type": "string",
          "minLength": 3,
          "maxLength": 200,
          "description": "BT-34/BT-49, e-mail address (scheme EM) or Leitweg-ID (scheme 0204)."
        },
        "electronic_scheme": {
          "type": "string",
          "enum": [
            "EM",
            "0204",
            "9930",
            "0088",
            "0060"
          ],
          "default": "EM"
        },
        "contact_name": {
          "type": "string",
          "maxLength": 100
        },
        "contact_phone": {
          "type": "string",
          "maxLength": 50
        },
        "contact_email": {
          "type": "string",
          "maxLength": 200
        }
      }
    }
  }
}

Open original schema

Published input example

{
  "number": "RE-2026-0042",
  "issue_date": "2026-10-30",
  "due_date": "2026-11-13",
  "delivery_date": "2026-10-28",
  "buyer_reference": "991-33333TEST-33",
  "seller": {
    "name": "Beispiel Manufaktur GmbH",
    "street": "Hallenweg 1",
    "postcode": "48599",
    "city": "Gronau",
    "country": "DE",
    "vat_id": "DE123456788",
    "electronic_address": "api@halowerk.com",
    "contact_name": "Buchhaltung",
    "contact_phone": "+49 2562 0000",
    "contact_email": "api@halowerk.com"
  },
  "buyer": {
    "name": "Beispielbehörde",
    "street": "Amtsweg 2",
    "postcode": "48143",
    "city": "Münster",
    "country": "DE",
    "electronic_address": "991-33333TEST-33",
    "electronic_scheme": "0204"
  },
  "payment": {
    "means_code": "58",
    "iban": "DE79000000001234567890",
    "terms": "Payable within 14 days without deduction."
  },
  "lines": [
    {
      "name": "Sensor maintenance",
      "quantity": 3,
      "unit_code": "HUR",
      "unit_price": 95,
      "vat_rate": 19
    },
    {
      "name": "Technical handbook",
      "quantity": 1,
      "unit_code": "C62",
      "unit_price": 20,
      "vat_rate": 7
    }
  ],
  "syntax": "ubl"
}

Result & documentation

Machine-readable documentation of this hub

Source of this page: the published HALOWERK catalog. Updated: 2026-11-17 UTC.

More endpoints in this hub

All endpoints in this hub →