Skip to content
HALOWERK

Formatwerk

zugferd generate

Builds the structured invoice as XRechnung 3.0 in UN/CEFACT CII syntax, validates it with the KoSIT validator 1.6.3 (XRechnung configuration 3.0.2) and only then creates the hybrid PDF: PDF/A-3b with embedded fonts (Liberation Sans, OFL) and sRGB output intent, XMP metadata with the Factur-X extension schema (conformance level XRECHNUNG), and the XML attached as xrechnung.xml with AFRelationship Alternative, as required for the ZUGFeRD 2.3 profile XRECHNUNG. The visible invoice (German or.

POST https://format.halowerk.com/v1/zugferd-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
languagestringNo
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
          }
        }
      }
    },
    "language": {
      "type": "string",
      "enum": [
        "de",
        "en"
      ],
      "default": "de"
    }
  },
  "$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
    }
  ],
  "language": "de"
}

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 →