Ihr System mit einer benutzerdefinierten Quelle synchronisieren

Eine benutzerdefinierte Quelle bindet ein System an, für das es keinen eingebauten Connector gibt: Ihr Wiki, Ihr Ticketsystem, eine Datenbank, einen Export von irgendwoher. Ihr Code sendet Dokumente an Sursa, und Sursa macht daraus Karten in der Sammlung und den Ordnern, für die die Quelle eingerichtet ist – mit derselben Suche, denselben Antworten, derselben Prüfung und denselben Berechtigungen wie bei Karten aus jeder anderen Quelle.

Anders als beim direkten Schreiben von Karten merkt sich eine benutzerdefinierte Quelle, was Sie gesendet haben. Am Ende einer vollständigen Synchronisierung archiviert Sursa jedes Dokument, das Sie nicht gesendet haben. So kommen Löschungen in Ihrem System ohne Zusatzaufwand bei Sursa an.

Quelle einrichten

Die Quelle legen Administratorinnen und Administratoren in Sursa unter Sources → New source → Custom source an und wählen dabei:

• die Sammlung und optional einen Ordner für ihre Karten;
• den Ordnermodus: alle Karten im gewählten Ordner oder Unterordner, die den path jedes Dokuments abbilden;
• die Berechtigungen: die Berechtigungen der Sammlung oder „wie in der Quelle“, wobei jedes Dokument angibt, wer es sehen darf.

Die Seite der Quelle zeigt ihre ID; die Beispiele verwenden 42.

Schlüssel wählen

Der Quellschlüssel ist die sicherste Wahl für eine einzelne Integration, besonders für eine, die auf einer Plattform eines Drittanbieters läuft. Ein Schlüssel der Organisation mit import:write eignet sich für einen Dienst, der mehrere Quellen befüllt.

Beide Schlüssel werden auf dieselbe Weise gesendet, und jeder Push-Endpunkt liegt unter /v1/push/sources/{source_id}. Prüfen Sie den Schlüssel und den Zustand der Quelle mit GET /v1/push/sources/{source_id}:

curl https://api.sursa.com/v1/push/sources/42 \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

{"source_id": 42, "name": "Helpdesk articles", "documents": 1840, "open_sync": null}

Das Dokument

Statt content kann ein einzelnes Dokument in einer Anfrage mit multipart/form-data eine Datei von bis zu 100 MB mitbringen: die Datei im Teil file, die obigen Felder als JSON im Teil document. Uploads in Teilen für upload_id und attachments werden mit einem Schlüssel der Organisation erstellt, der den Scope import:write hat, und mit dem Zweck import_attachment; ein Quellschlüssel kann sie nicht erstellen.

Zwei Arten zu senden

Direkte Aktualisierungen eignen sich für Systeme, die Sie über jede Änderung informieren, etwa ein Webhook aus Ihrem Helpdesk oder ein Schritt in Zapier. Senden Sie ein Dokument, wenn es erstellt oder geändert wird, und löschen Sie es, wenn es entfernt wird:

Änderungen werden innerhalb von etwa einer Minute zu Karten; mehrere aufeinanderfolgende Änderungen werden gemeinsam verarbeitet.

Synchronisierungen eignen sich für regelmäßige Exporte: Sie senden alles oder alles Geänderte, und Sursa gleicht ab. Der Rest dieser Anleitung behandelt Synchronisierungen.

Vollständige Synchronisierung ausführen

Eine Synchronisierung hat drei Schritte: öffnen, senden, schließen.

1. Öffnen

POST /v1/push/sources/{source_id}/syncs öffnet eine Synchronisierung und gibt ihre Nummer zurück:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-2026-10-24" \
  -H "Content-Type: application/json" \
  -d '{"type": "initial", "max_minutes": 180}'

{"sync_number": 7, "type": "initial", "status": "open", "opened_at": "2026-10-24T02:00:00Z",
 "expires_at": "2026-10-24T05:00:00Z", "pushed": 0, "removed": 0}

• type ist initial für die erste Synchronisierung der Quelle und incremental, sobald eine Synchronisierung abgeschlossen ist. Eine incremental-Synchronisierung vor der ersten abgeschlossenen ergibt sources.push_initial_required.
• Es kann immer nur eine Synchronisierung offen sein: Eine zweite ergibt 409 sources.push_sync_open.
• Eine Synchronisierung bleibt max_minutes lang offen (standardmäßig 60, bis zu 1440). Danach läuft sie ab: Nichts wird archiviert, und ihre Nummer wird nicht mehr akzeptiert. Wählen Sie eine Zeit, die deutlich länger ist, als Ihr Export dauert.

2. Dokumente senden

Senden Sie die Dokumente in Batches von bis zu 500 zusammen mit der Synchronisierungsnummer. Der Body eines Batches umfasst bis zu 50 MiB; Dateien innerhalb eines Batches werden als upload_id übergeben.

curl -X POST https://api.sursa.com/v1/push/sources/42/documents/batch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-7-batch-1" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_number": 7,
    "documents": [
      {"external_id": "faq-shipping", "title": "Shipping", "content_type": "markdown",
       "content": "# Shipping\n\nWe ship worldwide within 5 days.", "path": ["Support"]},
      {"external_id": "faq-refunds", "title": "Refunds", "content_type": "html",
       "content": "<p>Refunds take 14 days.</p>", "path": ["Support", "Billing"],
       "permissions": {"groups": ["Support"]}, "metadata": {"article_id": "1042"}}
    ]
  }'

Die Antwort enthält für jedes Dokument ein Ergebnis, in der Reihenfolge, in der Sie sie gesendet haben:

{
  "results": [
    {"external_id": "faq-shipping", "result": "unchanged", "status": "indexed", "card_id": "8c1d…", "version": "5e0f…"},
    {"external_id": "faq-refunds", "result": "updated", "status": "pending", "card_id": "3f2c…", "version": "a91b…"}
  ]
}

Standardmäßig wird jedes Dokument eines Batches für sich angewendet: Ein fehlerhaftes Dokument hält die anderen nicht auf.

Dokumente, die sich seit der letzten Synchronisierung nicht geändert haben, müssen Sie nicht erneut senden. Bestätigen Sie sie über ihre ID mit POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, bis zu 1000 IDs pro Anfrage, damit der vollständige Abgleich sie behält:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/touch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ids": ["faq-contact", "faq-hours"]}'

3. Schließen

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close beendet die Synchronisierung:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/close \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "complete"}'

Schließen Sie mit failed, wann immer Ihr Export auf halbem Weg abbricht: Ein complete nach einem unvollständigen Export würde jedes Dokument archivieren, zu dem Sie nicht mehr gekommen sind. Dasselbe Schließen erneut auszuführen ergibt dasselbe Ergebnis.

Nach dem Schließen macht Sursa innerhalb von etwa einer Minute Karten aus den Dokumenten. Die Seite der Quelle zeigt jede Synchronisierung mit der Anzahl der gesendeten und archivierten Dokumente, und GET /v1/push/sources/{source_id}/syncs/{sync_number} gibt dieselben Zähler zurück.

Inkrementelle Synchronisierungen

Senden Sie zwischen vollständigen Synchronisierungen nur, was sich geändert hat:

1. Öffnen Sie mit "type": "incremental".
2. Senden Sie die geänderten Dokumente und tragen Sie die IDs entfernter Dokumente in deletes ein (siehe unten).
3. Schließen Sie mit complete_incremental.

Führen Sie von Zeit zu Zeit eine vollständige Synchronisierung aus, zum Beispiel wöchentlich, um alles zu erfassen, was ein inkrementeller Lauf verpasst hat.

Dokumente in einem Batch löschen

Ein Batch kann zusammen mit den Dokumenten, die er schreibt, auch Dokumente entfernen. Führen Sie deren IDs in deletes auf:

{
  "sync_number": 8,
  "documents": [{"external_id": "faq-shipping", "title": "Shipping", "content": "…"}],
  "deletes": ["faq-old-returns", "faq-fax"]
}

Jede gelöschte ID erhält einen eigenen Eintrag in results, mit result gleich deleted oder not_found, wenn die Quelle kein solches Dokument hat. Dieselbe ID erneut zu löschen schadet nicht.

Atomare Batches

Manche Änderungen ergeben nur zusammen einen Sinn, zum Beispiel ein Dokument und das Dokument, das es ersetzt. Senden Sie "atomic": true, dann wird der Batch ganz oder gar nicht angewendet: Besteht ein Dokument seine Prüfungen nicht, wird nichts aus dem Batch übernommen, und die Antwort ist 422 mit dem Code sources.push_batch_rejected und dem Ergebnis jedes Dokuments in error.details.results: Die fehlgeschlagenen Dokumente haben error, die anderen skipped.

{"sync_number": 8, "atomic": true, "documents": […], "deletes": ["faq-old-returns"]}

Ohne atomic wird ein Batch Dokument für Dokument angewendet. Verwenden Sie atomare Batches für zusammengehörige Änderungen und normale Batches für Massenladungen, bei denen ein fehlerhaftes Dokument den Rest nicht aufhalten soll.

Ergebnis jedes Dokuments prüfen

Die Antwort auf einen Batch sagt Ihnen, wie jedes Dokument geschrieben wurde. Die Umwandlung in eine Karte geschieht danach, daher kann status noch pending sein. So finden Sie die Dokumente einer Synchronisierung, die nicht zu Karten geworden sind:

curl "https://api.sursa.com/v1/push/sources/42/syncs/7/documents?status=failed" \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

Jeder Eintrag hat external_id, title, status, card_id, version und reason, und die Liste wird mit cursor paginiert. status akzeptiert auch pending, processing, indexed und removed.

Sie können sich auch benachrichtigen lassen, statt nachzufragen: Die Ereignisse import.sync_completed (eine Synchronisierung ist geschlossen und verarbeitet, mit ihren Summen) und import.document_failed (ein Dokument ist nicht zur Karte geworden, mit seinem reason) kommen per Webhook und im Ereignis-Feed an.

Wiederholungen

• Senden Sie bei jedem POST einen Idempotency-Key. Ein wiederholter Batch mit demselben Schlüssel gibt das erste Ergebnis zurück.
• Auch ohne den Schlüssel wird ein Dokument mit derselben external_id nie zu einer zweiten Karte: Es ist unchanged oder updated.
• Bricht der Prozess mitten in einer Synchronisierung ab, öffnen Sie eine neue, nachdem die alte abgelaufen ist, oder schließen Sie die alte mit failed, wenn Sie ihre Nummer noch haben, und führen Sie die Synchronisierung erneut aus.

Limits

Ein Dokument über dem Dokumentenlimit der Quelle schlägt in einem Batch mit dem Grund limit_reached fehl; eine Anfrage mit einem einzelnen Dokument ergibt 409 mit dem Code sources.push_too_many_documents. Ratenlimits gelten wie für jede andere Anfrage; siehe Ratenlimits und Kontingente.

Häufige Fehler