Make

Die claritos-Custom-App für Make: Instant-Trigger für jedes Ereignis, Module für jeden Endpunkt — der ganze App-Baum wird aus der Spec erzeugt.

Was die App ist

Eine Make-Custom-App als Datei-Baum (Repo: integrations/make/app): Basis (URL aus der Verbindung, Bearer-Header, Fehlerabbildung), Verbindung, Webhook, ein Instant-Trigger je Ereignistyp und Action-/Search-/Get-/Delete-Module je Endpunkt. Alles wird von scripts/integrations-generate.mjs aus der OpenAPI-Spec und dem Ereigniskatalog geschrieben und folgt jeder API-Version; hochgeladen wird per Skript über die Make-Apps-SDK-API.

Verbinden

Verbindung „claritos (API key)“: API-Schlüssel (capi_…) und Umgebung (Production/Staging). Make prüft über GET /me und benennt die Verbindung nach der Organisation. Die Scopes des Schlüssels entscheiden, welche Module funktionieren; 403 insufficient-scope erscheint als Modulfehler mit Titel und Detail.

Instant-Trigger

Je Ereignistyp ein Modul („New Lead“, „Invoice Paid“ …). Beim Speichern des Szenarios legt Make über POST /webhooks ein Abonnement für genau diesen Typ auf die Make-Webhook-URL an (sichtbar im Org-Tab „API“ → Webhooks), beim Löschen wird es entfernt. Die Ausgabe ist der Ereignis-Envelope {id, type, createdAt, data} mit Interface und Beispiel aus dem Katalog. Make prüft Signaturen nicht selbst — die Webhook-URL ist geheim; wer sie zusätzlich absichern will, ergänzt ein Filter-Modul auf den Header webhook-signature.

Module

Actions entsprechen den Schreib-Endpunkten (POST-Aufrufe senden automatisch einen Idempotency-Key aus {{uuid}}, damit Wiederholungen des Szenarios nichts doppelt anlegen), Searches den Listen (Cursor-Pagination über nextCursor, Limit als Parameter), Get-/Delete-Module den Einzel-Endpunkten. Pfad-Parameter sind Pflichtfelder, Query-/Body-Felder mappbar; verschachtelte Felder (Positionen, Werte) als Collection/Array. Klientendaten-Endpunkte (clients.*) und die Webhook-Verwaltung sind nicht enthalten.

json

// Modul contacts_create (Ausschnitt, generiert)
{ "type": "action",
  "api": { "url": "/contacts", "method": "POST",
           "body": { "type": "{{parameters.type}}", "displayName": "{{parameters.displayName}}", "email": "{{parameters.email}}", … },
           "headers": { "idempotency-key": "{{uuid}}" },
           "response": { "output": "{{body}}" } } }

Erzeugen und hochladen

pnpm api:openapi im Hauptrepo schreibt den App-Baum; pnpm api:check verlangt, dass er eingecheckt ist. npm test prüft die Struktur ohne Netz. scripts/upload.mjs legt Verbindung, Webhook und Module über die Apps-SDK-API an bzw. aktualisiert sie (MAKE_API_TOKEN, MAKE_ZONE, MAKE_APP_NAME). Die Endpunkt-Formen der SDK-API sind beim ersten Lauf gegen die aktuelle Make-Doku zu prüfen — das Skript meldet jede Antwort ≠ 2xx.

bash

cd integrations/make && npm test
MAKE_API_TOKEN=… MAKE_ZONE=eu1.make.com MAKE_APP_NAME=claritos node scripts/upload.mjs   # oder Tag make-v<version>

Für Betreiber: Veröffentlichen

Einmalig in Make: Custom App „claritos“ anlegen, API-Token mit sdk-apps-Scopes erzeugen → GitHub-Secret MAKE_API_TOKEN (+ Variablen MAKE_ZONE, MAKE_APP_NAME). Tag make-v<version> startet den Workflow publish-make (Tests + Upload). Für die öffentliche Listung reicht Make eine Prüfung ein; bis dahin ist die App in der eigenen Make-Organisation nutzbar (Einladungslink möglich).