Yoplanning Agent API
Yoplanning bietet eine Agent-API, mit der Sie Yoplanning programmatisch oder über einen KI-Assistenten steuern können – genau wie über die Weboberfläche. Die vollständige technische Referenz (alle Endpunkte, alle Felder) finden Sie in der Swagger-Datei.
Dieser Artikel ersetzt nicht die technische Referenz: Er erklärt das allgemeine Prinzip, wofür diese API verwendet wird und vor allem die Vorsichtsmaßnahmen, die vor der Verbindung mit irgendetwas zu treffen sind.
Methodik
Die Agent-API folgt einigen einfachen Prinzipien, die jedoch vor ihrer Verwendung beachtet werden sollten:
Dies ist eine direkte Verbindung zum internen Code von Yoplanning – demselben Code, den die Weboberfläche aufruft. Das Schreiben über die API verhält sich exakt gleich, beinhaltet dieselben Validierungen und Nebenwirkungen wie eine manuelle Aktion in Yoplanning. Es gibt keine versteckte Logik: Was die Oberfläche zulässt, lässt auch die API zu; was die Oberfläche ablehnt, lehnt auch die API mit derselben Fehlermeldung ab.
Alles ist teambezogen. Fast jede Adresse beginnt mit Ihrer Team-ID (
/teams/{teamId}/…), und ein Token gewährt nur Zugriff auf das Team, für das es erstellt wurde.Die Regel für den „Roundtrip“ bei jeder Änderung: Das bestehende Objekt wird abgerufen, die gewünschten Felder werden geändert und anschließend wird das gesamte Objekt erneut übermittelt. Eine Aktualisierung ist keine Teilkorrektur: Fehlende Felder werden zurückgesetzt. Dies ist eine häufige Fehlerquelle, wenn sie nicht vorhergesehen wird.
Authentifizierung per Token, spezifisch für einen Benutzer und ein Team, wird in jeder Anfrage über den
Authorization-Header übermittelt.
Wozu dient es?
Mit der Agent API können Sie fast alles, was Yoplanning verwaltet – Kunden, Produkte, Sitzungen, Bestellungen, Zahlungen, Mitarbeiter, Aktionscodes, Buchungsmaschine, Wiederverkäufer usw. – erstellen, konfigurieren, ändern oder löschen. Dabei haben Sie die gleichen Rechte wie die Person, deren Token es ist.
In der Praxis wird es verwendet, um Yoplanning mit einem externen System (Website, internem Tool, anderer Unternehmenssoftware) oder mit einem KI-Assistenten zu verbinden, an den wir Konfigurations- oder Verwaltungsaufgaben in natürlicher Sprache delegieren möchten, anstatt alles manuell in der Benutzeroberfläche zu erledigen.
Risiken, die vor dem Verbinden eines Tools mit dieser API beachtet werden sollten
Dies ist keine reine Lese-API: Sie bietet denselben Funktionsumfang wie ein angemeldetes Yoplanning-Benutzerkonto. Bevor Sie sie mit einem Tool, Skript oder KI-Assistenten verbinden, beachten Sie bitte Folgendes:
Das Token ist streng vertraulich – genau wie ein Passwort. Jede Person oder jedes Programm, das im Besitz dieses Tokens ist, kann in Ihrem Team genauso agieren wie Sie: erstellen, ändern, löschen.
Fügen Sie diese Datei niemals in ein Code-Repository (auch nicht in ein privates), eine unverschlüsselte Nachricht, eine E-Mail, einen Screenshot oder ein Tool ein, dem Sie nicht vollständig vertrauen. Sollte die Datei dennoch offengelegt werden, betrachten Sie sie als kompromittiert: Generieren Sie umgehend eine neue Datei über Ihre erweiterten Einstellungen oder kontaktieren Sie support@yoplanning.com, falls Sie sich über das weitere Vorgehen unsicher sind.
Die Nebenwirkungen sind real. Ein Skript kann eine Bestätigungs-E-Mail versenden, eine Zahlung erfassen, eine Einladung verschicken oder Daten tatsächlich löschen – allerdings nur einmal, genau wie die Benutzeroberfläche. Ein schlecht konzipiertes Skript oder ein fehlerhafter Agent kann daher bei Ihren Kunden oder Ihrem Team ganz reale Aktionen auslösen und nicht nur intern Daten verändern.
Bei einer Aktualisierung wird das gesamte Objekt ersetzt. Wenn das verbundene Tool das Objekt nicht erneut einliest, bevor es die geänderte Version zurücksendet, kann es unbeabsichtigt Felder löschen, anstatt sie unverändert zu lassen.
Das Token trägt die Rechte des Erstellers. Wenn Sie einen KI-Assistenten mit dieser API verbinden, kann dieser alle Aktionen ausführen – und rückgängig machen –, die der Ersteller in diesem Team ausführen kann. Definieren Sie genau, was der Assistent tun soll, insbesondere bei irreversiblen Aktionen (Löschen, Versenden von E-Mails oder SMS, Zahlungsabwicklung), und verwenden Sie, sofern möglich, ein speziell für diesen Zweck erstelltes Token anstelle Ihres persönlichen Haupttokens.
Um weiterzukommen
Für eine schlankere, schreibgeschützte KI-Integration, die auf Ihre eigenen Berechtigungen beschränkt ist, siehe auch den Artikel Verbindung zu Yoplanning über MCP. Ausführliche Informationen zu den Ressourcen und Feldern der Agent-API finden Sie weiterhin in der Swagger.
Zuletzt aktualisiert