# API-Anfragen sicher testen

> Teste den App-Tool-Katalog und einzelne SynCore-Tools mit PowerShell, curl oder einer OpenAPI-Anwendung.

Quelle: https://support.unitedsynergy.com/api/anfragen-testen/

Teste Integrationen zuerst mit einem eigenen Testschlüssel und einem Actor-User mit begrenzten Rechten. Beginne immer mit einem lesenden Tool.

> **Kein API-Key im Hilfe-Center**
>
> Gib deinen echten API-Key niemals auf einer öffentlichen Webseite ein. Der Befehls-Generator unten verarbeitet nur URL, Tool-Name und JSON lokal im Browser. Er sendet nichts und verwendet im Ergebnis ausschließlich die Variable `SYNCORE_API_KEY`.

## 1. Schlüssel im Terminal setzen

PowerShell:

```powershell
$env:SYNCORE_API_KEY = 'syn_DEIN_SCHLUESSEL'
```

Bash:

```bash
export SYNCORE_API_KEY='syn_DEIN_SCHLUESSEL'
```

## 2. Katalog testen

PowerShell:

```powershell
$BaseUrl = 'https://syncore.example.com'
$Headers = @{ 'X-API-KEY' = $env:SYNCORE_API_KEY }
$Catalog = Invoke-RestMethod `
  -Method Get `
  -Uri "$BaseUrl/api/app-tools?includeStructure=1" `
  -Headers $Headers

$Catalog.tools | Select-Object name, module, sideEffect, confirmationRequired
```

Prüfe, ob nur die erwarteten Apps und Aktionen erscheinen. Ein zu großer Katalog deutet auf zu weit gefasste Rollen des Actor-Users hin.

## 3. Ausführbaren Befehl erzeugen

Übernimm einen Tool-Namen aus deinem aktuellen Katalog und baue die Eingabe nach dessen `inputSchema`.

*(Im Hilfe-Center steht hier ein Generator, der aus Basis-URL, Tool-Name und Eingabe einen PowerShell- und einen curl-Befehl baut: `POST /api/app-tools`, Header `X-API-KEY`, Body `{"name": "<tool>", "input": {…}}`.)*

## 4. Ergebnis bewerten

- HTTP `200` und `ok: true`: Transport, Schlüssel, Rechte und Tool-Ausführung waren erfolgreich.
- Leere Daten sind nicht automatisch ein Fehler; möglicherweise gibt es im Datenscope keine passenden Datensätze.
- `needsSelection: true`: Kandidaten anzeigen und eine Auswahl anfordern.
- Bei einer Mutation den Zielzustand anschließend mit einem Lese-Tool prüfen.
- HTTP `429`: die Sekunden aus `Retry-After` abwarten und die Anfrage dann einmal wiederholen.
- Fehler nach Statuscode behandeln und keine automatischen Endlosschleifen bauen. Die Meldungen und ihre Ursachen stehen unter [Wenn eine API-Anfrage scheitert](https://support.unitedsynergy.com/api/fehlerbehebung/).

## Mit OpenAPI-Tools testen

1. Lade die [SynCore App-Tools OpenAPI-Datei](https://support.unitedsynergy.com/openapi/syncore-app-tools.openapi.json) herunter.
2. Importiere sie in Postman, Bruno oder Insomnia.
3. Setze die Server-Variable `baseUrl` auf deine SynCore-Instanz.
4. Hinterlege `X-API-KEY` als geschütztes Secret der lokalen Umgebung.
5. Rufe zuerst `GET /api/app-tools?includeStructure=1` auf.
6. Kopiere einen sichtbaren Tool-Namen und dessen Eingabeschema in den `POST`-Request.

Die OpenAPI-Datei beschreibt den stabilen Transport. Welche fachlichen Tools verfügbar sind, bestimmt ausschließlich der aktuelle Katalog der Zielinstanz.

## Abnahmereihenfolge

Für einen nachvollziehbaren Integrationstest empfehlen wir:

1. Ungültiger Key ergibt `401`.
2. Gültiger Key liefert einen berechtigungsgefilterten Katalog.
3. Ein lesendes Tool liefert `ok: true`.
4. Ein absichtlich unzulässiges Eingabefeld beziehungsweise ein falscher Typ ergibt `400`.
5. Ein schreibendes Tool wird erst nach Bestätigung ausgeführt.
6. Der geänderte Zustand wird per Readback nachgewiesen.
7. Ein gesperrter Schlüssel wird unmittelbar mit `401` abgewiesen.

Dokumentiere dabei Instanz, Version, Zeitpunkt, Schlüsselpräfix, Tool-Name und Ergebnis, aber niemals den vollständigen API-Key oder personenbezogene Antwortdaten.