Entwickler-Dokumentation

finisma lässt sich auf vier Wegen ansteuern: eine REST-API für Server-zu-Server-Aufrufe, ein MCP-Connector für KI-Agenten (mit WebMCP für Browser-Agenten direkt auf dieser Website), OAuth 2.1 für Integrationen, die ein fremdes finisma-Konto verbinden, und die n8n-Community-Node als fertiger Baustein für n8n-Workflows. Alle vier Kanäle rufen dieselbe Funktionsschicht auf, nur der Zugang unterscheidet sich.

Die vier Kanäle

REST-API
Rechnungen prüfen (/verify), Daten aus PDFs auslesen (/extractions) und als ZUGFeRD erzeugen (/invoices, auf Wunsch nur das XML), Konto- und Abo-Status abfragen (/me). Mit Zahlungsverkehr-Abo zusätzlich SEPA- und Auslandszahlungsdateien erzeugen (/payments/sepa, /payments/axz), BIC-Lookup und KI-gestützte Adress-Strukturierung. Auth per API-Key oder OAuth-Token.
MCP-Connector und WebMCP
Vier Tools für KI-Agenten wie Claude und ChatGPT über den Remote-MCP-Server, zwei davon zusätzlich als In-Page-Tools direkt im Browser (WebMCP, über die Login-Session).
OAuth 2.1
Für Integrationen, die ein fremdes finisma-Konto verbinden, statt einen API-Key abzutippen. Authorization Code mit PKCE, Dynamic Client Registration für Chat-Connectoren.
n8n-Community-Node
n8n-nodes-zugferd-finisma: vorgefertigte Nodes für Prüfen, Auslesen und Erzeugen samt Credential-Typen für API-Key und OAuth, als reiner Client der REST-API. Quellcode und Installation auf GitHub; wer keine Node installieren will, kommt mit dem eingebauten HTTP-Request-Node genauso ans Ziel (Anleitung unten).

Erste Schritte

Jeder Zugang außer der reinen In-Page-Nutzung von WebMCP braucht ein Credential:

  1. Konto anlegen und im Bereich „API und Anwendungen“ einen API-Key erstellen. Er wird genau einmal angezeigt; finisma speichert nur einen Hash.
  2. Den Key als Bearer-Token schicken. Das Prüfen ist kostenlos (Credential trotzdem nötig), das Erzeugen setzt ein aktives Abo voraus.

Erster Aufruf, eine Rechnung prüfen:

curl -X POST https://finisma.de/api/v1/verify \
  -H "Authorization: Bearer $FINISMA_KEY" \
  -F "pdf=@rechnung.pdf;type=application/pdf"

Vollständige Endpoint-Referenz mit allen Feldern, Beispielen und Fehlercodes: REST-API-Referenz. Wer statt eines statischen Keys ein fremdes Konto verbinden will (n8n-Workflow, eigene Anwendung, Chat-Connector), nutzt stattdessen OAuth 2.1.

Maschinenlesbare Spezifikation

Die vollständige REST-API als OpenAPI-3.1-Dokument, direkt aus den Laufzeit-Schemas erzeugt (immer aktuell, kein separat gepflegtes Duplikat): https://finisma.de/api/v1/openapi.json

n8n ohne Community-Node

Für n8n führen zwei Wege ans Ziel: die Community-Node oben, oder der eingebaute HTTP-Request-Node direkt gegen die REST-API, ganz ohne Installation. Den zweiten Weg erklärt Schritt für Schritt der Artikel E-Rechnungen automatisch mit n8n erzeugen.

Fragen zum Einsatz mit KI-Agenten

Hintergrund, Grenzen und ein vollständiges Aufruf-Beispiel für den MCP-Connector stehen im Artikel E-Rechnung per API und KI-Agent erstellen.