API-Quickstart

SynCore stellt Integrationen über die App-Tools-API bereit. Der Katalog ist dynamisch: Du siehst ausschließlich die Apps und Aktionen, die für den Benutzer hinter deinem API-Key freigegeben sind.

1. Zugangsdaten als Umgebungsvariablen setzen

PowerShell:

$SynCoreBaseUrl = 'https://syncore.example.com'
$env:SYNCORE_API_KEY = 'syn_DEIN_SCHLUESSEL'

Bash, z. B. unter Linux oder macOS:

export SYNCORE_BASE_URL='https://syncore.example.com'
export SYNCORE_API_KEY='syn_DEIN_SCHLUESSEL'

Verwende die URL ohne abschließenden Schrägstrich. Schreibe den Schlüssel nicht in Quellcode, Git-Repositories, Tickets oder Screenshots.

2. Deinen verfügbaren Katalog abrufen

PowerShell:

$Headers = @{ 'X-API-KEY' = $env:SYNCORE_API_KEY }
Invoke-RestMethod `
  -Method Get `
  -Uri "$SynCoreBaseUrl/api/app-tools?includeStructure=1" `
  -Headers $Headers

curl:

curl --request GET \
  "$SYNCORE_BASE_URL/api/app-tools?includeStructure=1" \
  --header "X-API-KEY: $SYNCORE_API_KEY"

Die Antwort enthält:

• tools: alle für diesen Schlüssel erlaubten Aktionen mit Ein- und Ausgabeschema,
• structure: sichtbare Apps, Seiten, Navigation und effektive Berechtigungen,
• rules: verbindliche Laufzeitregeln für Auswahl, Bestätigung und Readback.

3. Ein lesendes Tool auswählen

Wähle für den ersten Test aus tools[] ein Tool mit sideEffect: "none". Übernimm den name exakt und bilde input nach dem gelieferten inputSchema.

{
  "name": "textbausteine.list_templates",
  "input": {
    "limit": 10
  }
}

Der Name ist nur ein Beispiel. Ist die App nicht aktiviert oder fehlen dem Actor-User die Rechte, erscheint dieses Tool gar nicht in deinem Katalog.

4. Tool ausführen

$Body = @'
{
  "name": "textbausteine.list_templates",
  "input": { "limit": 10 }
}
'@

Invoke-RestMethod `
  -Method Post `
  -Uri "$SynCoreBaseUrl/api/app-tools" `
  -Headers $Headers `
  -ContentType 'application/json' `
  -Body $Body

Eine erfolgreiche Antwort hat immer ok: true und nennt das ausgeführte Tool sowie das Modul. Die Fachdaten stehen je nach Tool in data oder in weiteren, im outputSchema beschriebenen Feldern.

Sicherheitsregeln

1. Lade vor einer Aktion immer zuerst den aktuellen Katalog mit includeStructure=1.
2. Rate keine IDs. Ermittle Datensätze zuerst über ein sichtbares Listen- oder Such-Tool.
3. Bei mehreren Treffern muss der Benutzer die Auswahl treffen.
4. Führe Aktionen mit confirmationRequired: true erst nach ausdrücklicher Bestätigung aus.
5. Prüfe Änderungen anschließend mit einem Lese- oder Listen-Tool.

Standardmäßig steht jeder ausgeführte Tool-Aufruf, auch ein fachlich gescheiterter, mit Mandant, Actor-User, Tool und Ergebnis im Audit-Log. Was sich abschalten lässt, steht unter Sicherheit der API. Abgewiesene Aufrufe (400, 403, 404) erreichen das Tool nicht. Die Aufbewahrung richtet sich nach der Audit-Einstellung des Mandanten.