n8n

Der claritos-Community-Node für n8n: ein Trigger-Node für alle Ereignisse und ein Regular-Node für jeden Endpunkt — aus der Spec erzeugt.

Was das Paket ist

npm-Paket n8n-nodes-claritos (Repo: integrations/n8n) mit zwei Nodes und einem Credential-Typ. Der Regular-Node ist deklarativ: Resource = API-Domäne, Operation = Endpunkt, Felder aus dem Schema; Listen werden auf ihre data-Einträge entpackt. Der Trigger-Node abonniert Ereignisse über die Webhook-API. Beides wird aus der OpenAPI-Spec und dem Ereigniskatalog generiert und folgt jeder API-Version.

Installieren und verbinden

In n8n unter Settings → Community Nodes das Paket n8n-nodes-claritos installieren (selbst gehostet: npm install im Node-Verzeichnis). Credential „claritos API“: API-Schlüssel (capi_…) und Umgebung; n8n prüft die Verbindung über GET /me. Die Scopes des Schlüssels bestimmen, welche Operationen und Ereignisse funktionieren.

bash

# n8n → Settings → Community Nodes → Install
n8n-nodes-claritos

# oder selbst gehostet
cd ~/.n8n/nodes && npm install n8n-nodes-claritos

Trigger-Node

Beim Aktivieren des Workflows legt der Node über POST /webhooks ein Abonnement auf die n8n-Webhook-URL an (gewählte Ereignistypen, leer = alle), merkt sich id und secret in den Node-Daten und prüft jede Zustellung gegen die Standard-Webhooks-Signatur (webhook-id, webhook-timestamp, webhook-signature; 5 Minuten Toleranz). Beim Deaktivieren wird das Abonnement gelöscht. Nutzlast = Ereignis-Envelope {id, type, createdAt, data}. Zum Testen ohne echtes Ereignis: POST /webhooks/{id}/test aus der API oder „Testzustellung“ im Org-Tab.

Regular-Node

Resource wählen (Kontakte, Rechnungen, Signaturen, Briefe, Aufgaben …), Operation wählen — Pfad-Parameter sind Pflichtfelder, Query-/Body-Felder optional; verschachtelte Felder (Positionen, Werte) als JSON. Idempotency-Key setzen Sie bei Bedarf als eigenen Header über die Node-Optionen nicht; für Wiederholungen nutzen Sie die n8n-Retry-Einstellungen sparsam. Fehler kommen als Problem-Details (RFC 9457) und erscheinen mit Titel/Detail im Ausführungsprotokoll; 429 trägt Retry-After.

Alternative: MCP-Client-Node

n8n bringt einen MCP-Client-Node mit. Statt des Community-Nodes lässt sich auch der claritos-MCP (POST /api/mcp/v1) mit Authorization-Header einbinden — nützlich für KI-Agenten-Workflows, in denen das Modell die Werkzeuge selbst wählt (Leitfaden „MCP“).

json

// n8n „MCP Client“-Node: Server-URL + Header
{ "url": "https://www.claritos.io/api/mcp/v1", "headers": { "Authorization": "Bearer capi_…" } }

Für Betreiber: Veröffentlichen

npm-Konto/-Token als Secret NPM_TOKEN; Tag n8n-v<version> startet den Workflow publish-n8n (Tests, Build, npm publish mit Provenance). Für die Kennzeichnung „verified“ das Paket bei n8n einreichen (Community-Node-Richtlinien: keine Laufzeit-Abhängigkeiten außer n8n-workflow — erfüllt).