Skip to main content
Glama

finisma – ZUGFeRD e-invoices

ZUGFeRD-Rechnung erzeugen

create_zugferd
Idempotent

Erzeugt eine ZUGFeRD-PDF aus strukturierten EN-16931-Daten (kein LLM). Mit visueller PDF (pdf_base64/upload_id) wird das XML in diese PDF eingebettet; ohne PDF wird die Rechnung aus den Daten gesetzt, optional mit Logo (logo_base64: PNG, JPEG oder SVG, max. 500 KB) und Sprache (lang: de oder en). Verletzen die Daten EN-16931-Geschäftsregeln, liefert der Remote-Kanal (Chat-Connector) strukturierte Issues statt einer Datei zurück — invoice korrigieren (siehe extract_invoice) und mit denselben Quelldaten (upload_id/pdf_base64) erneut aufrufen. Ohne aktives Abo kostenlos mit Konto (API-Key): die PDF trägt dann das finisma-Prüfsiegel als Wasserzeichen, standardmäßig bis zu 5 Rechnungen pro Tag; mit Abo ohne Wasserzeichen und ohne Tageslimit. Rabatte und Zuschläge je Position (lines[].allowanceCharges) dürfen als Prozentsatz ohne Betrag kommen: amount = round2(Menge × unitPriceNet × percent / 100); ebenso auf die ganze Rechnung (allowanceCharges): Grundbetrag ohne Angabe ist die Summe der lineNetAmount mit ratePercent. lineNetAmount, vatBreakdown und die Summen muss der Aufrufer mit diesen Beträgen rechnen. Für öffentliche Auftraggeber erzeugt invoice.profile='xrechnung' eine XRechnung 3.0 (nur als reines XML über die REST-API mit format=xml; Pflichten: Leitweg-ID in buyerReference, Verkäufer-Kontakt mit Telefon und E-Mail, payment, electronicAddress beider Parteien).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "invoice": "<invoice>"
    },
    "name": "create_zugferd"
  }
}

Input Schema

NameRequiredDescriptionDefault
langNoSprache der aus den Daten gesetzten Rechnung (Beschriftungen, Zahlen- und Datumsformat). Standard: de.
invoiceYesStrukturierte Rechnungsdaten nach EN 16931 (wird gegen Schema und Geschäftsregeln geprüft).
filenameNoDateiname der erzeugten Rechnung (Standard: invoice.pdf).
logo_mimeNoOptional; der Typ wird sonst aus dem Inhalt erkannt.
upload_idNoReferenz auf eine zuvor über request_upload_link hochgeladene Datei, anstelle von pdf_base64. Höchstens eines von beiden angeben.
pdf_base64NoOptional: die visuelle Rechnungs-PDF, Base64-kodiert (max. 25 MB). In sie wird das CII-XML eingebettet. Alternativ 'upload_id' angeben. Ohne beides wird die Rechnung aus den Daten gesetzt. Chat-Clients, die eine angehängte Datei nicht zuverlässig als Base64 übergeben können, rufen zuerst request_upload_link auf.
attachmentsNoOptionale Anhänge (z. B. Stundennachweise). Erlaubt: PDF, PNG, JPEG, CSV, XLSX, ODS, XML; je max. 10 MB.
logo_base64NoOptionales Logo für die aus den Daten gesetzte Rechnung (nur ohne PDF): PNG, JPEG oder SVG, Base64-kodiert oder als data:-URI, max. 500 KB. Steht rechts oben im Kopf. SVG nur ohne Skripte und ohne Verweise auf andere Dateien.

Output Schema

NameRequiredDescriptionDefault
bytesNoGröße der erzeugten PDF in Bytes.
issuesNoNur gesetzt, wenn die übergebenen Rechnungsdaten EN-16931-Geschäftsregeln verletzen: es wurde keine Datei erzeugt (Korrekturschleife, T20). Felder anhand der Issues korrigieren und create_zugferd mit denselben Quelldaten (upload_id/pdf_base64) und dem korrigierten invoice erneut aufrufen.
noticeNoHinweis für den Nutzer zu rerendered (Ursache und ob das Layout geprüft werden sollte).
generatedNotrue, wenn die Rechnung ohne Eingabe-PDF aus den Daten gesetzt wurde.
expires_atNoISO-8601-Zeitpunkt, ab dem download_url verfällt (nur mit download_url gesetzt).
pdf_base64NoDie erzeugte ZUGFeRD-Rechnung (PDF/A-3 mit eingebettetem CII-XML). Gesetzt, wenn die Eingabe als 'pdf_base64' kam oder die Rechnung über WebMCP aus den Daten gesetzt wurde; sonst steht download_url im Ergebnis.
rerenderedNoNur gesetzt, wenn die Eingabe-PDF Schriften mit PDF/A-Fehlern enthielt (Regel 6.2.11). true: finisma hat das PDF neu aufgebaut, optisch verglichen und erneut geprüft. false: das Original wurde verwendet, die Datei erfüllt PDF/A-3 nicht in jedem Punkt. Den Text aus notice an den Nutzer weitergeben.
watermarkedNotrue, wenn die PDF aus dem kostenlosen Tageskontingent stammt und das finisma-Prüfsiegel als Wasserzeichen trägt (Aufruf ohne aktives Abo).
download_urlNoKurzlebiger Download-Link zur erzeugten PDF. Gesetzt, wenn die Eingabe als 'upload_id' kam (Chat-Client-Fallback) oder die Rechnung über den Remote-Kanal aus den Daten gesetzt wurde.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / attachments / items / properties / note
      Added value: +{
      +  "description": "Hinweis auf die Anlage im strukturierten Teil (Notiz BT-22, z. B. \"Eingebettete Anlage „stunden.pdf“: Stundennachweis März 2026.\"), wie ihn das BMF-Schreiben vom 15.10.2026 verlangt. Standard true; false lässt den Hinweis weg.",
      +  "type": "boolean"
      +}
  2. Changed2 schema fields changed
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Hinweis für den Nutzer zu rerendered (Ursache und ob das Layout geprüft werden sollte).",
      +  "type": "string"
      +}
    • addedOutput schema / properties / rerendered
      Added value: +{
      +  "description": "Nur gesetzt, wenn die Eingabe-PDF Schriften mit PDF/A-Fehlern enthielt (Regel 6.2.11). true: finisma hat das PDF neu aufgebaut, optisch verglichen und erneut geprüft. false: das Original wurde verwendet, die Datei erfüllt PDF/A-3 nicht in jedem Punkt. Den Text aus notice an den Nutzer weitergeben.",
      +  "type": "boolean"
      +}
  3. Changed8 schema fields changed
    • addedInput schema / properties / lang
      Added value: +{
      +  "description": "Sprache der aus den Daten gesetzten Rechnung (Beschriftungen, Zahlen- und Datumsformat). Standard: de.",
      +  "enum": [
      +    "de",
      +    "en"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / logo_base64
      Added value: +{
      +  "contentEncoding": "base64",
      +  "description": "Optionales Logo für die aus den Daten gesetzte Rechnung (nur ohne PDF): PNG, JPEG oder SVG, Base64-kodiert oder als data:-URI, max. 500 KB. Steht rechts oben im Kopf. SVG nur ohne Skripte und ohne Verweise auf andere Dateien.",
      +  "type": "string"
      +}
    • addedInput schema / properties / logo_mime
      Added value: +{
      +  "description": "Optional; der Typ wird sonst aus dem Inhalt erkannt.",
      +  "enum": [
      +    "image/png",
      +    "image/jpeg",
      +    "image/svg+xml"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / pdf_base64 / description
      Previous value: -"Die visuelle Rechnungs-PDF, Base64-kodiert (max. 25 MB). In sie wird das CII-XML eingebettet. Alternativ 'upload_id' angeben. Chat-Clients, die eine angehängte Datei nicht zuverlässig als Base64 übergeben können, rufen zuerst request_upload_link auf."New value: +"Optional: die visuelle Rechnungs-PDF, Base64-kodiert (max. 25 MB). In sie wird das CII-XML eingebettet. Alternativ 'upload_id' angeben. Ohne beides wird die Rechnung aus den Daten gesetzt. Chat-Clients, die eine angehängte Datei nicht zuverlässig als Base64 übergeben können, rufen zuerst request_upload_link auf."
    • changedInput schema / properties / upload_id / description
      Previous value: -"Referenz auf eine zuvor über request_upload_link hochgeladene Datei, anstelle von pdf_base64. Genau eines von beiden angeben."New value: +"Referenz auf eine zuvor über request_upload_link hochgeladene Datei, anstelle von pdf_base64. Höchstens eines von beiden angeben."
    • changedOutput schema / properties / download_url / description
      Previous value: -"Kurzlebiger Download-Link zur erzeugten PDF. Nur gesetzt, wenn die Eingabe als 'upload_id' kam (Chat-Client-Fallback)."New value: +"Kurzlebiger Download-Link zur erzeugten PDF. Gesetzt, wenn die Eingabe als 'upload_id' kam (Chat-Client-Fallback) oder die Rechnung über den Remote-Kanal aus den Daten gesetzt wurde."
    • addedOutput schema / properties / generated
      Added value: +{
      +  "description": "true, wenn die Rechnung ohne Eingabe-PDF aus den Daten gesetzt wurde.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / pdf_base64 / description
      Previous value: -"Die erzeugte ZUGFeRD-Rechnung (PDF/A-3 mit eingebettetem CII-XML). Nur gesetzt, wenn die Eingabe als 'pdf_base64' kam; wurde 'upload_id' verwendet, steht stattdessen download_url im Ergebnis."New value: +"Die erzeugte ZUGFeRD-Rechnung (PDF/A-3 mit eingebettetem CII-XML). Gesetzt, wenn die Eingabe als 'pdf_base64' kam oder die Rechnung über WebMCP aus den Daten gesetzt wurde; sonst steht download_url im Ergebnis."
  4. Changed1 schema field changed
    • addedInput schema / properties / invoice / properties / seller / properties / customerAssignedId
      Added value: +{
      +  "maxLength": 100,
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / invoice / properties / delivery / properties / gln
      Added value: +{
      +  "maxLength": 20,
      +  "type": "string"
      +}
  6. First observed

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true); the description goes well beyond by disclosing the free-tier watermark ('finisma-Prüfsiegel'), the 5-invoices-per-day quota, account/API-key requirements, and that EN-16931 business-rule violations return structured issues instead of a file. It also discloses where the logo is placed and the SVG restrictions, which no annotation covers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is correctly front-loaded, but everything after it is one dense run-on paragraph mixing pricing tiers, allowance formulas, error handling and the XRechnung special case, with no separation. Every clause carries information, yet the lack of structure makes it hard to scan and increases the chance of an agent missing the conditional XRechnung rule.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the deep nested schema, the output schema, and the annotations, the description covers the remaining gaps: business-rule validation behavior, quota/watermark consequences, and the caller's calculation duties. The one weak spot is the closing XRechnung sentence, which introduces a 'format=xml' REST-only path and mandatory fields that do not correspond to any parameter in this schema, leaving the agent unsure whether that mode is reachable through this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still earns credit by adding caller-side arithmetic semantics not derivable from the schema alone — the round2(quantity × unitPriceNet × percent / 100) formula and the explicit statement that lineNetAmount, vatBreakdown and the totals must be computed by the caller using those amounts. It also restates file constraints (500 KB logo, allowed formats) that the schema mostly carries already.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and artifact ('Erzeugt eine ZUGFeRD-PDF aus strukturierten EN-16931-Daten') and explicitly marks it as deterministic ('kein LLM'), which separates it cleanly from the LLM-driven extract siblings. It also distinguishes the two operating modes (embedding into a supplied PDF vs. rendering from data), so an agent knows exactly which artifact it produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Rich context: when to supply pdf_base64 vs upload_id, when logo/lang apply, and the retry path after rule violations ('invoice korrigieren ... mit denselben Quelldaten erneut aufrufen'). It names extract_invoice and request_upload_link as related steps, though it never explicitly states when to prefer verify_zugferd instead of creating a new invoice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources