Skip to main content
Glama

finisma – ZUGFeRD e-invoices

by de.finisma
OverviewDiscussionsAdmin

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).

Input Schema

TableJSON 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

TableJSON 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.
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.
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. 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."
  2. Changed2 schema fields changed
    • addedInput schema / properties / invoice / properties / delivery / properties / gln
      Added value: +{
+  "maxLength": 20,
+  "type": "string"
+}
    • addedInput schema / properties / invoice / properties / seller / properties / customerAssignedId
      Added value: +{
+  "maxLength": 100,
+  "type": "string"
+}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Goes well past the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it discloses that rule violations return structured issues instead of a file, the free-tier watermark and 5-per-day cap versus the subscription tier, caller responsibility for computing lineNetAmount/vatBreakdown/totals, and the extra obligations for xrechnung. No contradiction with the annotations.

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

Conciseness4/5

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

Front-loaded with purpose, then PDF embedding, error handling, billing tier, calculation formula and xrechnung profile — a sensible order. It is a single dense block with no formatting, which makes it harder to scan, but almost every sentence carries information an agent needs.

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

Completeness5/5

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

For a complex 8-parameter, deeply nested tool, the description covers generation paths, validation-failure behavior, licensing limits and the public-sector profile variant. With an output schema present it need not describe return values, and nothing an agent needs to invoke it correctly is missing.

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, but the description adds genuine semantics the schema does not: the rounding formula for percentage allowances (round2(quantity × unitPriceNet × percent / 100)) and the explicit warning that the caller must compute lineNetAmount, vatBreakdown and the totals themselves. It also reinforces the 500 KB / PNG-JPEG-SVG logo constraint.

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?

"Erzeugt eine ZUGFeRD-PDF aus strukturierten EN-16931-Daten (kein LLM)" gives a specific verb, resource, input format and a hard constraint in one clause. It is immediately distinguishable from verify_zugferd (checks) and extract_invoice (reads data out of invoices).

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

Usage Guidelines5/5

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

It states the three mutually exclusive paths (pdf_base64 vs upload_id vs no PDF, documented as "Höchstens eines von beiden") and when each applies. It also names the recovery branch explicitly: on business-rule violations, correct the invoice (referencing extract_invoice) and re-call with the same source data.

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

All finisma – ZUGFeRD e-invoices toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources