Syncler API

Sync per API starten

Mit der Syncler-API können Syncs direkt angestoßen werden. Typische Anwendungsfälle sind Ad-hoc-Ausführungen, z. B. um einen einzelnen Datensatz initial zu übertragen.
Je nach Szenario gibt es asynchrone (Warteschlange/Daemon) und synchrone (API führt aus) Varianten.

Grundlagen

Authentifizierung:
Authorization: Bearer <ACCESS_TOKEN> (siehe Abschnitt Anmeldung an der API).
Asynchrone Ausführung (empfohlen):
API legt Warteschlangen-Eintrag an → Daemon führt aus → Status wird über Queue-API abgefragt.
Synchrone Ausführung (nur Ausnahmen):
API führt selbst aus und wartet – Risiko von Request-Timeouts bei langen Läufen.
Routen & Schemas:
Die konkreten Pfade/Parameter können je Installation abweichen. Prüfen Sie die Swagger-Dokumentation Ihrer Instanz.

Endpunkte (Überblick)

Zweck	Modus	Beispiel-Route (schematisch)	Beschreibung
Ad-hoc-Start eines Sync (1 Datensatz)	Asynchron (Daemon)	`POST /StartProcessAdHoc/{syncId}/{sourceId}`	Legt Queue-Item an, Rückgabe enthält Warteschlangen-Datensatz
Beliebige Aktion zur Warteschlange hinzufügen	Asynchron (Daemon)	`POST /AddAction`	Erzeugt Queue-Item (z. B. adhoc, manual, repeat, …)
Ad-hoc-Start (sofort ausführen)	Synchron (API)	`POST /StartProcessDirect/{syncId}/{sourceID}`	API führt Sync direkt aus, Antwort wartet auf Abschluss
Ausführung in gewünschter Variante (sofort)	Synchron (API)	`POST /ExecuteProcess/{syncID}`	Beliebige Ausführungsart (z. B. manual, repeat) direkt ausführen
Status eines Queue-Items abfragen	–	`GET /GetAction/{queueId}`	Status/Statistiken/Fehler einsehen

Empfehlung: Bevorzugen Sie asynchrone Endpunkte (Warteschlange + Daemon).
Synchrone Endpunkte sind für Spezialfälle gedacht (z. B. kurzfristige, kurzlaufende Aufgaben).

StartProcessAdhoc (asynchron, bevorzugt)

Startet einen Sync für einen konkreten Datensatz. Der Sync und der Datensatz werden über die URL spezifiziert.
Die API legt einen Warteschlangen-Eintrag an; die Ausführung übernimmt der Daemon.

Beispiel (cURL)

curl -X POST "https://<BASE_URL>/StartProcessAdHoc/<syncId>/<sourceId>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/json"

Antwort (Beispiel, gekürzt):

{
  "ID": "1234",
  "StartType": "AdHoc",
  "ProcessId": "123",
  "CreatedDate": "2025-09-19T11:25:00Z",
  "Status": "Pending"
}

Status pollen

curl -X GET "https://<BASE_URL>/GetAction/1234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/json"

Mögliche Stati: Pending → InProgress → Complete/Failed.

Wichtig: Wenn der Daemon nicht aktiv ist, wird der Eintrag nicht ausgeführt.

AddAction (asynchron, flexibel)

Erstellt beliebige Warteschlangen-Einträge (nicht nur Ad-hoc) – Ausführung wieder durch den Daemon.

Antwort: Wie bei StartProcessAdhoc ein Queue-Item mit id, das Sie für das Status-Polling verwenden.

StartProcessDirect (synchron, nur Ausnahmen)

Startet denselben Ad-hoc-Fall wie StartProcessAdhoc, führt aber sofort aus und wartet auf das Ergebnis.
Risiko: Timeout bei langen Läufen, Ressourcenbelastung der API, Berechtigungsunterschiede in On-Prem-Setups.

Antwort (Beispiel, gekürzt):

{
  "ID": "1234",
  "StartType": "AdHoc",
  "ProcessId": "123",
  "CreatedDate": "2025-09-19T11:25:00Z",
  "Status": "Complete"
}

ExecuteProcess (synchron, allgemeiner Start)

Führt einen Sync in der angegebenen Ausführungsart (z. B. manual, repeat, planned) direkt aus.

Beispiel (cURL)

curl -X POST "https://<BASE_URL>/ExecuteProcess/{syncID}" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "WhereClause": "(optional) wird als Filter im Sync verwendet)",
        "StartType": "Single",
        "ActionParams": []
          {"Name": "Account", "Value": "123"}
        ]
      }'

Hinweis: Verwenden Sie synchrone Endpunkte sparsam. Für robuste und skalierbare Abläufe ist die Warteschlange mit Daemon vorzuziehen.