Zapier
Die claritos-App für Zapier: Auslöser für jedes Ereignis, Aktionen für jeden Schreib-Endpunkt, Suchen für jede Liste — alles aus der Spec erzeugt.
Was die App ist
Ein dünner Adapter (Zapier Platform CLI) über der öffentlichen API. Nichts Fachliches steckt in der App: Auslöser sind Webhook-Abonnements, Aktionen und Suchen rufen die HTTP-Endpunkte auf. Der Code liegt im Hauptrepo unter integrations/zapier; die Domänen-Teile (generated/) werden aus der OpenAPI-Spec und dem Ereigniskatalog erzeugt und ändern sich mit jeder API-Version automatisch.
Verbinden
Beim ersten Zap fragt Zapier nach einem claritos-API-Schlüssel (capi_…, Organisations-Einstellungen → API) und der Umgebung (Production oder Staging). Zapier prüft den Schlüssel über GET /me und zeigt den Organisationsnamen als Verbindungsnamen. Die Scopes des Schlüssels entscheiden, welche Auslöser und Aktionen funktionieren — fehlende Scopes erscheinen im Zap-Verlauf als 403 insufficient-scope.
Auslöser (REST Hooks)
Je Ereignistyp ein Auslöser („New Lead“, „Invoice Paid“, „Signature Request Completed“ …). Beim Einschalten des Zaps legt Zapier über POST /webhooks ein Abonnement mit genau diesem Ereignistyp an (sichtbar im Org-Tab „API“ → Webhooks), beim Ausschalten wird es gelöscht. Jede Zustellung wird gegen das Endpunkt-Geheimnis geprüft (Standard-Webhooks-Signatur). „Load sample“ holt echte jüngste Ereignisse über /webhooks/events/{type}/recent und fällt auf das dokumentierte Beispiel zurück.
POST /api/v1/webhooks
{ "url": "https://hooks.zapier.com/hooks/standard/…", "eventTypes": ["leads.lead.created"], "description": "Zapier — New Lead" }
201 { "id": "wh_…", "secret": "whsec_…", … } ← Zapier merkt sich id + secret (performSubscribe)Aktionen und Suchen
Aktionen entsprechen den Schreib-Endpunkten (Kontakt anlegen, Rechnung stellen, SMS senden, Signatur anfordern …); Felder kommen aus dem Body-Schema, verschachtelte Felder (Positionen, Werte) werden als JSON eingegeben. Suchen entsprechen den Listen-Endpunkten mit Suchbegriff und Filtern und liefern die erste Seite. Klientendaten-Endpunkte (clients.*) und die Webhook-Verwaltung sind bewusst nicht als Aktionen enthalten. Fehler kommen als Problem-Details (RFC 9457) mit Titel, Detail und Feldfehlern; 429 wird als Zapier-Drossel gemeldet.
Erzeugung und Versionen
pnpm api:openapi im Hauptrepo schreibt die Spec, den Ereigniskatalog (docs/api/events.v1.json) und die generierten Plattform-Dateien; pnpm api:check verlangt, dass alles eingecheckt ist. Die App-Version ist die Spec-Version. Tests (npm test) prüfen Struktur und Signaturprüfung ohne Netz; zapier validate prüft das Schema.
pnpm api:openapi # Spec + Ereigniskatalog + generierte Plattform-Dateien
cd integrations/zapier && npm install && npm test
npx zapier validate && npx zapier push # oder Tag zapier-v<version>Für Betreiber: Veröffentlichen
Einmalig: Zapier-Developer-Konto, zapier login, zapier register „claritos“ (App-ID → Secret ZAPIER_APP_ID), Deploy-Key → Secret ZAPIER_DEPLOY_KEY. Danach veröffentlicht der Workflow publish-zapier bei jedem Tag zapier-v<version> (validate + push). Für die öffentliche Listung reicht Zapier eine Prüfung ein; bis dahin lässt sich die App per Einladungslink nutzen.