E-Rechnung-API: PDF-Rechnungen in XRechnung und ZUGFeRD umwandeln

Was die API liefert

Sie schicken eine PDF-Rechnung, die API liest die Angaben aus und rechnet die Summen nach. Ist alles vollständig, bekommen Sie bis zu vier Dateien zurück, jeweils Base64-kodiert:

Es sind dieselben Dateien wie im Konverter auf der Website, aus derselben Prüfung. Die XRechnung wird nur ausgeliefert, wenn sie die KoSIT-Prüfregeln erfüllt. Die ZUGFeRD-PDF kommt nur dazu, wenn sie außerdem die Prüfung mit dem Mustang-Validator besteht; sonst bekommen Sie die drei übrigen Dateien.

Zugang und Preis

• Den API-Schlüssel legen Sie in Ihrem Konto an. Er wird einmal angezeigt; pdfvera speichert davon nur einen Hashwert und die ersten zehn Zeichen.
• Die API gehört zu jedem Abo, ohne Aufpreis. Jede erzeugte Rechnung zählt einmal gegen Ihr Monatskontingent, wie auf der Website.
• Dieselbe PDF im selben Monat noch einmal umwandeln zählt nicht erneut.
• Eine Prüfung ohne Dateien (Formularfeld mode=preview, also -F mode=preview) zählt nicht. Damit können Sie Ihre Anbindung testen, ohne Kontingent zu verbrauchen.
• Bis zu fünf Schlüssel pro Konto, etwa einen je System. Einen Schlüssel sperren Sie im Konto mit einem Klick.

Die Preise der Abos stehen auf der Preisseite. Für Buchhaltungsbüros mit vielen Mandanten gibt es das „Büro-Paket“ auf Anfrage.

Erster Aufruf mit curl

Der Schlüssel steht im Header Authorization, die PDF geht als Formularfeld pdf mit:

curl https://pdfvera.com/api/v1/de/convert \
  -H "Authorization: Bearer pv_IHR_SCHLUESSEL" \
  -F pdf=@rechnung.pdf

Ist die Rechnung vollständig, steht in der Antwort "deliverable": true, und outputs enthält die Dateien. So speichern Sie die XRechnung mit jq; fehlt sie, bleibt die Datei leer:

curl -s https://pdfvera.com/api/v1/de/convert \
  -H "Authorization: Bearer pv_IHR_SCHLUESSEL" \
  -F pdf=@rechnung.pdf \
  | jq -r '.outputs["xrechnung-ubl.xml"] // empty' | base64 --decode > rechnung.xml

Fehlende Angaben nachreichen

Fehlt in der PDF eine Angabe, die eine XRechnung verlangt, zum Beispiel die Käuferreferenz (Leitweg-ID) oder die E-Mail-Adresse des Empfängers, steht "deliverable": false in der Antwort. questions listet die Angaben, die diese Rechnung braucht, mit Feldname, Beschreibung und Beispiel; was noch fehlt, trägt "missing": true. Sie senden die Werte im Formularfeld form als JSON-Objekt mit derselben PDF noch einmal:

curl https://pdfvera.com/api/v1/de/convert \
  -H "Authorization: Bearer pv_IHR_SCHLUESSEL" \
  -F pdf=@rechnung.pdf \
  -F 'form={"buyer_reference":"04011000-12345-06","buyer.email":"rechnung@kunde.de"}'

Falsch gelesene Angaben korrigieren Sie auf dieselbe Weise. Die Liste found zeigt, was aus der PDF gelesen wurde. Jeder korrigierbare Eintrag nennt in edit[].key den Schlüssel, etwa fix:number für die Rechnungsnummer. Wird eine Korrektur abgelehnt, nennt fix_errors den Grund:

-F 'form={"fix:number":"RE-2026-0042"}'

Nicht jede Rechnung lässt sich mit Angaben retten. Passen etwa die Summen in der PDF nicht zusammen, bleibt questions leer, und reasons nennt den Grund.

Die Antwort im Überblick

Den Stand Ihres Kontingents fragen Sie mit GET /api/v1/usage ab. Die vollständige Beschreibung aller Felder steht in der OpenAPI-Datei.

Fehlercodes

Grenzen

• Eine PDF bis 20 MB und 30 Seiten pro Aufruf, davon höchstens 10 gescannte Seiten.
• Pro Konto bis zu 20 Aufrufe je Minute, 120 je Stunde und 1.000 je Tag, Website und API zusammen.
• Pro Aufruf eine Rechnung. Für viele Rechnungen rufen Sie die API nacheinander auf.

MCP-Server für Claude, Cursor und andere KI-Assistenten

Mit dem MCP-Server von pdfvera wandelt ein KI-Assistent Rechnungen auf Ihrem Rechner um. Das kleine Programm liest die PDF von Ihrer Festplatte, ruft die API mit Ihrem Schlüssel auf und legt die Dateien neben die PDF. Fehlt eine Pflichtangabe, fragt der Assistent Sie danach und ruft die API noch einmal auf. Es gelten dasselbe Kontingent und dieselben Grenzen wie bei der API.

• Claude Desktop: Erweiterung pdfvera.mcpb herunterladen, mit Doppelklick öffnen und den API-Schlüssel eintragen.
• Claude Code (braucht Node.js 18 oder neuer) als Plugin; es fragt beim Installieren nach dem API-Schlüssel:

/plugin marketplace add pdfvera/pdfvera-mcp
/plugin install pdfvera@pdfvera

Oder ohne Plugin direkt als MCP-Server:

claude mcp add pdfvera -e PDFVERA_API_KEY=pv_IHR_SCHLUESSEL -- npx -y pdfvera-mcp@latest

Cursor und andere Programme mit MCP-Unterstützung tragen den Server in ihre MCP-Konfiguration ein, bei Cursor in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pdfvera": {
      "command": "npx",
      "args": ["-y", "pdfvera-mcp@latest"],
      "env": { "PDFVERA_API_KEY": "pv_IHR_SCHLUESSEL" }
    }
  }
}

Der Server bietet drei Werkzeuge: convert_invoice (PDF-Rechnung in XRechnung und ZUGFeRD), convert_bank_statement (brasilianische Kontoauszüge) und get_usage (Abo und Kontingent). Für ChatGPT, das nur MCP-Server im Netz anbindet, gibt es noch keine Version. Mit @latest holt sich der Server neue Versionen beim nächsten Start selbst. Der Quellcode steht auf GitHub (MIT-Lizenz), das Paket auf npm.

Datenschutz

Die PDF wird in der EU verarbeitet und nicht gespeichert. Gespeichert wird nur ein Hashwert der PDF, wenn Dateien erzeugt wurden, damit dieselbe Rechnung im Monat nicht doppelt zählt. Wie die Datei verarbeitet wird und welche Dienstleister beteiligt sind, steht unter Datenverarbeitung. Den Vertrag zur Auftragsverarbeitung finden Sie unter AVV.