API-Dokumentation
Diese Seite besteht aus zwei Teilen: öffentlich lesbare Adressen (kein Schlüssel erforderlich, Suchmaschinen und KI-Retriever lesen direkt) und dem Skill-Kanal zur Anbindung von KI-Agenten (erfordert ein Site-Token, damit Agenten wie WorkBuddy diese Site lesen und schreiben können).
1. Öffentliche Adressen: kein Schlüssel erforderlich
| Adresse | Zweck | Parameter | Getesteter Status |
|---|---|---|---|
| /sitemap.xml | Index aller öffentlichen Seiten der Site | keine | 200 |
| /robots.txt | Erläuterung der Crawling-Regeln | keine | 200 |
| /llms.txt | Site-Beschreibung und Verzeichnis öffentlicher Adressen für KI-Retriever | keine | 200 |
| /api/geo/v1/capabilities | Deklariert die lesbaren Felder und die Liste öffentlicher Adressen dieser Site | keine | 200 |
| /capi/geo/list | Listet öffentliche Inhalte auf (Produkte / Kategorien / Seiten / Artikel) | type, page, pageSize, updated_since | 200 |
| /capi/geo/product/info | Öffentliche Wissensansicht eines einzelnen Produkts | handle | 200 |
| /capi/geo/entity/info | Öffentliche Ansicht von Entitätswissen wie Seiten | entity_type, entity_id | 200 |
Einheitliche Rückgabe { code, message, data }, code 200 bedeutet Erfolg. Es werden nur bereits veröffentlichte Inhalte zurückgegeben: freigeschaltete Produkte, veröffentlichte Seiten und Artikel.
2. Anbindung von KI-Agenten (Skill-Kanal)
Kurz gesagt: Schnittstellenadresse + Site-Token, beide Werte im Agenten eintragen und er ist einsatzbereit. Das Token entspricht den Backend-Berechtigungen dieser Site; es gehört ausschließlich in den Request-Header, nicht in die URL und nicht ins Code-Repository.
1. Beide Werte abrufen
- Im Backend anmelden und in der linken Navigation die Seite „KI-Verbindung“ öffnen.
- Auf der Seite stehen zwei Zeilen: Schnittstellenadresse (diese Site fest auf /api/skill, vollständige Adresse https://deine-domain/api/skill) und Zugriffstoken (beginnt mit sk_).
- Rechts auf die Kopierschaltfläche klicken; alternativ „Anbindungsanleitung kopieren“ anklicken, um Adresse, Authentifizierung und Schnittstellenerkennung in einem Block an den Agenten zu übergeben.
Ein Zurücksetzen des Tokens macht das alte Token sofort ungültig; bereits verwendende Agenten müssen synchron aktualisiert werden, sonst geben alle Aufrufe 401 zurück.
2. Authentifizierung
Alle Skill-Schnittstellen akzeptieren nur einen Request-Header: X-Site-Token: dein Token. Das Token kann nicht als URL-Parameter übergeben werden – URLs landen in Zugriffsprotokollen, Referern und Browserverläufen und würden die Backend-Berechtigungen offenlegen.
Ein minimaler Aufruf (Domain und Token durch eigene ersetzen):
curl -s https://deine-domain/api/skill/capabilities \
-H "X-Site-Token: sk_dein_token"
3. Erst fragen „Was kannst du?“, dann konkrete Schnittstellen aufrufen
Nicht zu Beginn Schnittstellennamen raten. Zwei Self-Service-Schnittstellen sind immer verfügbar; der Agent entdeckt seine Fähigkeiten selbst darüber:
- GET /api/skill/capabilities —— vollständige Fähigkeitsliste: Schnittstellenpfade, Methoden, Lese-/Schreibtyp, Parameterbeschreibungen sowie Authentifizierungsart und Versionsnummer dieser Site.
- GET /api/skill/base/init —— Basisinformationen der Site: Site-Typ (B2B / B2C), aktuelles Theme, verfügbare Themes, Sprachen und Währungen.
Die übrigen Schnittstellen sind nach Modulen gegliedert, häufig genutzt: /api/skill/product/list (Produkte), /api/skill/plugin/list (Plugins), /api/skill/i18n/list (mehrsprachige Einträge), /api/skill/analytics/traffic-get (Traffic), /api/skill/b2c-order/list (Bestellungen, B2C-Site).
4. Berechtigungsmatrix: standardmäßig alles offen, pro Modul einschränkbar
Im Backend unter „Schnittstellenberechtigungen“ gibt es zwei Stufen: alles erlauben (Standard, entspricht dem Verhalten bei Freischaltung) und nach Modul einschränken (Lese- / Schreib- / riskante Operationen pro Modul einzeln schaltbar).
| Kategorie | Bedeutung | Empfehlung |
|---|---|---|
| Nur Lesen | Produkte, Inhalte, Traffic, Plugin-Status abfragen | standardmäßig aktiviert |
| Schreiben | Produkte, Inhalte, Layouts anlegen oder ändern | aktivieren, wenn der Agent stellvertretend operiert |
| Riskant | Löschen, siteweites Überschreiben, Veröffentlichungsvorgänge | nur bei eindeutigem Bedarf aktivieren |
Die beiden Nur-Lese-Schnittstellen „Schnittstellenliste (capabilities)“ und „Site-Initialisierung (base/init)“ sind immer freigegeben und von der Berechtigungstabelle unabhängig – sonst könnte der Agent nicht einmal nachvollziehen, „warum keine Verbindung möglich ist“. Änderungen gelten sofort nach dem Speichern; auf Agentenseite ist keine Konfigurationsänderung nötig. Gesperrte Schnittstellen geben 403 zurück und nennen den Grund.
5. Testprotokoll (2026-10-19, je einmal auf zwei Kundensites getestet)
Mit dem jeweiligen echten Token jeder Site einzeln aufgerufen, Ergebnisse wie folgt (unbearbeitet, exakt die damaligen Rückgaben):
| Schnittstelle | B2B-Site | B2C-Site |
|---|---|---|
| GET /api/skill/capabilities | 200 / 46.063 B | 200 / 45.842 B |
| GET /api/skill/base/init | 200 / 644 B | 200 / 664 B |
| GET /api/skill/product/list?limit=2 | 200 / 25.534 B | 200 / 5.417 B |
| GET /api/skill/analytics/traffic-get | 200 / 3.424 B | 200 / 2.913 B |
| GET /api/skill/plugin/list | 200 / 15.673 B | 200 / 14.681 B |
| GET /api/skill/i18n/list | 200 / 5.275 B | 200 / 5.275 B |
| wie oben, jedoch ohne Token | 401 / 68 B | 401 / 68 B |
Fazit: Der Zugang beider Sites funktioniert, die Authentifizierung greift, ohne Token wird beides abgelehnt (Rückgabe „Nicht autorisiert: X-Site-Token fehlt oder stimmt nicht überein“). Unterschiedliche Größen sind Datenmengenunterschiede, keine Störung.
6. Fehlercodes und Behandlung
| Status | Bedeutung | Vorgehen |
|---|---|---|
| 401 | Token fehlt oder stimmt nicht überein | Prüfen, ob der Header-Name X-Site-Token lautet; ob das Token zurückgesetzt wurde |
| 403 | Von der Berechtigungsmatrix blockiert | reason in der Rückgabe prüfen; im Backend unter „Schnittstellenberechtigungen“ das entsprechende Modul freigeben |
| 404 | Pfad existiert nicht | Zunächst mit capabilities den Schnittstellennamen abgleichen, nicht aus dem Gedächtnis zusammensetzen |
| 503 | Serverseitig kein Site-Token konfiguriert | Die Seite „KI-Verbindung“ im Backend einmal normal öffnen, das System generiert es automatisch |
7. Drei Sicherheitsgrundregeln
- Token nicht in die URL, auch nicht in Chatfenster einfügen oder ins Code-Repository committen – es entspricht dem Backend-Login-Status.
- Nur notwendige Berechtigungen vergeben: für den täglichen Betrieb reichen Nur-Lesen + Schreiben, riskante Kategorien nur bei Bedarf temporär aktivieren.
- Bei Personenwechsel oder Übergabe das Token zurücksetzen, das alte Token wird sofort ungültig – zuverlässiger als einzelnes Widerrufen.
3. Minimale Schritte zur Anbindung von WorkBuddy
- Backend „KI-Verbindung“ → Schnittstellenadresse und Zugriffstoken kopieren (oder direkt die gesamte Anbindungsanleitung kopieren).
- In der Konnektor- / Skill-Konfiguration von WorkBuddy die Site-Adresse eintragen, Authentifizierung über X-Site-Token.
- Den Agenten zuerst capabilities zur Selbstbeschreibung aufrufen lassen, dann gemäß Liste die konkreten Schnittstellen aufrufen.