Zapier, Make und n8n

Integrationsplattformen verbinden Sursa ohne Code mit Hunderten anderer Tools. Dafür ist keine eigene Sursa-App nötig: Die allgemeinen Schritte der Plattformen für HTTP-Anfragen und Webhooks arbeiten direkt mit der API. Diese Anleitung behandelt die drei häufigsten Rezepte:

Welche Plattform Sie auch verwenden: Bewahren Sie den Schlüssel in deren Speicher für Anmeldedaten oder Verbindungen auf, nicht im Schritt selbst, damit er nicht in jedes Szenario und jedes Ausführungsprotokoll kopiert wird.

Datensätze als Karten senden

Erstellen Sie in Sursa eine benutzerdefinierte Quelle (Sources → New source → Custom source) und dann auf der Seite der Quelle unter API keys einen Schlüssel dafür. Der Schlüssel beginnt mit kbsrc_ und kann nur Dokumente in diese Quelle schreiben. Damit ist er der richtige Schlüssel für die Plattform eines Drittanbieters.

Die übliche Einrichtung lautet „wenn in X ein Datensatz erstellt oder aktualisiert wird, an Sursa senden“:

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

• Ordnen Sie external_id eine stabile ID des Datensatzes zu, nie eine Uhrzeit oder eine Laufnummer. Wird derselbe Datensatz erneut gesendet, aktualisiert er dann dieselbe Karte, und ein wiederholter Schritt schadet nicht: Die Antwort lautet unchanged.
• Für einen Trigger „Datensatz gelöscht“ fügen Sie einen zweiten Workflow mit der Methode DELETE und der URL https://api.example.com/v1/push/sources/42/documents/{{record_id}} hinzu.
• Testen Sie die Verbindung mit GET https://api.example.com/v1/push/sources/42 und demselben Header Authorization. Die Antwort enthält den Namen der Quelle und die Anzahl ihrer Dokumente.

Die Felder des Dokuments sind dieselben wie im Code.

Zapier

Verwenden Sie Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: aus. Data: das JSON oben, mit Feldern aus dem Trigger.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Verwenden Sie das Modul HTTP → Make a request:

• Method POST, URL wie oben, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: das JSON oben mit zugeordneten Werten.
• Schalten Sie Parse response ein, um result (created, updated, unchanged) in späteren Modulen zu verwenden.
• Um eine Datei zu senden, wählen Sie Body type Multipart/form-data mit einem Feld file (die Datei aus einem früheren Modul) und einem Textfeld document, das die JSON-Felder ohne content enthält.

n8n

Verwenden Sie den Knoten HTTP Request:

• Method POST, URL wie oben.
• Authentication Generic Credential Type → Header Auth, mit dem Namen Authorization und dem Wert Bearer kbsrc_….
• Send Body an, Body Content Type JSON, Felder über Ausdrücke wie {{ $json.id }} zugeordnet.

Für einen geplanten vollständigen Export verketten Sie drei Knoten vom Typ HTTP Request: Synchronisierung öffnen (POST …/syncs mit {"type": "initial"} beim ersten Mal, danach {"type": "incremental"}), die Elemente senden und die Synchronisierung mit {"status": "complete"} schließen. n8n führt einen Knoten einmal pro Element aus; um weniger Anfragen zu senden, fassen Sie die Elemente mit einem Knoten Aggregate zusammen und senden Sie sie an …/documents/batch als {"sync_number": …, "documents": [...]}.

In einem Workflow eine Frage stellen

Ein Workflow kann Sursa fragen und die Antwort verwenden: eine Antwort auf ein Support-Ticket entwerfen, einen CRM-Datensatz anreichern, eine Antwort in einem Chat-Kanal posten. Verwenden Sie einen API-Schlüssel der Organisation mit dem Scope ask und einer Rolle, die die richtigen Sammlungen sieht.

Die Antwort enthält den Text der Antwort in answer (Markdown) und seine Quellen in sources, jeweils mit doc_name. Hat die Wissensbasis nichts zur Frage, ist empty gesetzt (zum Beispiel no_hits): Fügen Sie einen Filterschritt hinzu, damit der Workflow keine leere Antwort postet. Siehe Q&A-Bot bauen.

Antworten können mehrere Sekunden dauern. Hat der HTTP-Schritt der Plattform ein kurzes Standard-Timeout, erhöhen Sie es auf mindestens 60 Sekunden.

Einen Workflow aus einem Sursa-Ereignis starten

Jede Plattform kann Webhooks empfangen:

1. Erstellen Sie den Trigger und kopieren Sie die HTTPS-Adresse, die er Ihnen gibt.
2. Registrieren Sie in Sursa einen Webhook mit dieser Adresse und den gewünschten Ereignissen, unter Administration → Integrations → Webhooks and API oder mit POST /v1/webhooks.
3. Senden Sie auf der Seite des Webhooks ein Testereignis und ordnen Sie die Felder des Ereignisses (type, data.card.title, …) in den nächsten Schritten zu.

Prüfen Sie die Signatur. Die Adresse des Triggers ist öffentlich: Wer sie kennt, kann Anfragen daran senden. Prüfen Sie die Signatur jeder Zustellung, bevor Sie darauf reagieren, besonders wenn der Workflow Daten ändert:

• Fügen Sie in n8n nach dem Knoten Webhook einen Knoten Code mit der Node.js-Prüfung aus Webhooks empfangen hinzu und aktivieren Sie die Option für den rohen Body im Knoten Webhook, damit die exakten Bytes verfügbar sind.
• In Zapier und Make, wo der rohe Body schwerer zugänglich ist, halten Sie die Adresse zumindest geheim, filtern Sie nach type und lesen Sie das Objekt erneut über die API, bevor Sie darauf reagieren.

Wiederholungen und Duplikate betreffen Plattformen wie jeden anderen Empfänger: Filtern Sie nach der id des Ereignisses, wenn ein doppelter Lauf Schaden anrichten würde.

Tipps

• Lassen Sie bei 429 die automatische Wiederholung der Plattform die Sekunden aus Retry-After abwarten. Verwenden Sie für große Exporte bevorzugt Batches.
• Plattformen protokollieren jede Anfrage und jede Antwort. Setzen Sie einen Schlüssel nie in eine URL, und verwenden Sie bevorzugt den kbsrc_-Schlüssel, wo immer der Workflow nur Dokumente schreibt.
• Schlägt ein Schritt mit 401 sources.push_key_invalid fehl, prüfen Sie, ob die Quell-ID in der URL zum Schlüssel passt.