← Zurück

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, WebMCP für Browser-Agenten direkt auf dieser Website und OAuth 2.1 für Integrationen, die ein fremdes finisma-Konto verbinden. Alle vier Kanäle rufen dieselbe Funktionsschicht auf, nur der Zugang unterscheidet sich.

Die vier Kanäle

REST-API
Rechnungen prüfen (/verify) und als ZUGFeRD erzeugen (/invoices), Konto- und Abo-Status abfragen (/me). Mit Zahlungsverkehr-Abo zusätzlich 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.

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-Community-Node

Für n8n gibt es zwei Wege: den eingebauten HTTP-Request-Node gegen die REST-API (keine Installation nötig, Schritt für Schritt erklärt im Artikel E-Rechnungen automatisch mit n8n erzeugen), oder die Community-Node n8n-nodes-zugferd-finisma. Sie ist ein reiner Client der REST-API unter /api/v1 mit vorgefertigten Nodes und Credential-Typen für API-Key und OAuth. Quellcode und Installationshinweise stehen öffentlich im Repository:

https://github.com/paulibytes/n8n-nodes-zugferd-finisma

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.