edoobox API

Die edoobox API ermöglicht den direkten Zugriff auf edoobox Daten für eigene Websites, Buchhaltungssysteme, CRM, Reporting, Automationen oder weitere Integrationen. API-Projekte sollten immer mit einem klaren Ziel, passenden Rechten und sicherer Schlüsselverwaltung starten.

AAPI-ZugangsverwaltungBSicherheitshinweisCSchlüsselstatus und Rechte

Was die edoobox API ermöglicht

Über die API können Systeme edoobox Daten lesen oder, mit entsprechenden Rechten, schreiben. Typische Ressourcen sind Angebote, Kategorien, Buchungen, Teilnehmende, Rechnungen, Transaktionen oder weitere Stammdaten. API V2 arbeitet mit JSON Web Tokens und stellt je nach Ressource typische Operationen wie Lesen, Erstellen, Aktualisieren und Löschen bereit.

Verwenden Sie die API nicht direkt aus öffentlichem Browser-Code, wenn dafür Secret Keys oder Tokens nötig sind. Solche Anfragen gehören in ein serverseitiges Backend.

Rechte und Berechtigungsgruppen

Mit API V2 können Sie den Zugriff über Berechtigungsgruppen einschränken. Für ein Buchhaltungstool sollten zum Beispiel nur Rechnungs- und Zahlungsdaten freigegeben werden, nicht alle Admin- oder Angebotsfunktionen.

Die bekannten Hauptrollen wie Superadministrator, Administrator, Leiter oder begrenzter Leiter können grundsätzlich auch API-Zugriff ermöglichen, wenn sich ein Admin mit seinen Login-Daten authentifiziert. Für dauerhafte Integrationen ist das aber selten ideal.

Erstellen Sie für Integrationen nach Möglichkeit eigene Berechtigungsgruppen. Verwenden Sie nicht unüberlegt die Rechte eines realen Admins, weil dadurch entweder zu viele Rechte an die API gehen oder der Admin im normalen Betrieb Rechte verliert. Eine eigene Gruppe macht sichtbar, welche Daten die Integration wirklich braucht.

API-Schlüssel erstellen und sicher aufbewahren

API-Schlüssel erstellen Sie in den Kontoeinstellungen in der API-Zugangsverwaltung. Der Secret Key wird nur einmal angezeigt. Speichern Sie ihn sofort in einem Passwortmanager oder Secret-System.

Erstellen Sie pro Integration einen eigenen Schlüssel. So können Sie später Rechte, Verantwortliche, Rotation und Deaktivierung sauber zuordnen. Details stehen unter API-Schlüssel und Zugriffsrechte verwalten.

API V2, Base URL und Postman

Für erste Tests eignet sich Postman oder ein vergleichbares API-Werkzeug. Legen Sie eine Environment mit Base URL, API Key, Secret Key, EdID, Token und Ablaufzeit an. Die Base URL hängt von der verwendeten edoobox Umgebung ab; für die produktive V2-Umgebung wird typischerweise https://app2.edoobox.com/v2 verwendet.

Die aktuelle Endpunktreferenz finden Sie in der integrierten API-v2-Dokumentation. Dort stehen auch die OpenAPI-Datei zum Herunterladen und Markdown für LLMs bereit. Die mitgelieferte Serveradresse ist eine lokale Testumgebung; setzen Sie beim Import in Ihr API-Werkzeug den Host Ihrer tatsächlichen edoobox Umgebung ein.

Postman hilft, Authentifizierung, Header, Parameter und Fehlerantworten zu prüfen, bevor eine Integration programmiert wird. Geben Sie Postman-Collections niemals mit echten Secrets weiter. Wenn Sie Beispiele dokumentieren, ersetzen Sie API Key, Secret Key, Token, Kundendaten und Rechnungsdaten durch Platzhalter.

Authentifizierung und Tokens

Die API nutzt Zugangsdaten, um ein Zugriffstoken zu erhalten. Ein typischer Start ist der Authentifizierungs-Request an /auth mit API Key, Secret Key und gewünschter Ablaufzeit. Dieses Token verwenden Sie anschliessend für API-Aufrufe. Tokens und Secrets müssen wie Passwörter behandelt werden. Speichern Sie Ablaufzeit, Umgebung und zugewiesene Berechtigungsgruppe in Ihrer technischen Dokumentation, damit spätere Fehler schneller eingegrenzt werden können.

Die Spezifikation beschreibt für die meisten geschützten Operationen zwei Alternativen: Bearer-JWT zusammen mit edid oder die bestehende Browsersitzung über _edlogin zusammen mit edid. Der genaue Aufbau der Token-Antwort ist in der gelieferten OpenAPI-Datei teilweise offen. Verwenden Sie nur eine für Ihre Umgebung bestätigte Login-Implementierung. Für serverseitige Integrationen sind eigene API-Zugänge meist klarer kontrollierbar als persönliche Admin-Logins.

Wenn Authentifizierung fehlschlägt, prüfen Sie Umgebung, API Key, Secret Key, Rechte, Ablaufzeit, Header und ob der Schlüssel noch aktiv ist.

API-Fehler erkennen

API-Fehler enthalten Statuscode und Meldung. Häufige Ursachen sind fehlende Rechte, falsche Credentials, ungültige Parameter, falsche Umgebung, abgelaufene Tokens oder nicht vorhandene Ressourcen.

Protokollieren Sie Fehler ohne Secrets. Sinnvoll sind Zeitpunkt, Request-ID oder fachlicher Kontext. Secret Keys, Tokens oder personenbezogene Rohdaten gehören nicht in Logs.

API V1 und ältere Integrationen

Ältere Integrationen können noch auf API V1 oder alte App-Versionen verweisen. Die API V1 wird nicht mehr weiterentwickelt und sollte für neue Projekte nicht mehr verwendet werden. Bestehende Schnittstellen können weiterhin funktionieren; auch ältere WordPress-Anbindungen können noch auf V1-Mechanismen verweisen. Prüfen Sie bei neuen Projekten, ob API V2 verwendet werden kann. Dokumentieren Sie alte Integrationen, damit Abhängigkeiten sichtbar bleiben.

Wenn Sie eine bestehende Integration modernisieren, planen Sie Tests mit Demo-Daten, Rechteabgleich und eine klare Umschaltung. Prüfen Sie bei alten Scripts besonders, ob sie noch mit Admin-Login, alten Base URLs oder zu breiten Rechten arbeiten.

Anwendungsbeispiel: Angebotsdaten auf eigener Website

Eine Organisation möchte veröffentlichte Angebote auf einer eigenen Website darstellen. Das Backend verwendet einen API-Schlüssel mit Leserechten für Angebote und Kategorien, ruft die Daten serverseitig ab und liefert nur die benötigten Felder an die Website aus. Secret Key und Token bleiben auf dem Server.

Fehler einer Lese- oder Schreibanfrage einordnen

Prüfen Sie sowohl den HTTP-Status als auch das Feld error der JSON-Antwort. Eine technisch empfangene Antwort kann fachlich abgewiesen sein. Bei Authentifizierungsproblemen prüfen Sie den aktiven Schlüssel, sein Recht, das Token und die zum Token gehörende edid.

Bei einem unklaren Schreibresultat suchen Sie zuerst nach dem bereits erzeugten Objekt beziehungsweise seiner dokumentierten Fremdreferenz. Erstellen Sie eine Buchung, Rechnung oder Zahlung nach einem Timeout nicht blind nochmals. Für vollständige Listen beachten Sie die Startposition und Seitengrösse jeder Seite.

Eigene Angebotswebsite und Kursplaner aufbauen

Für eigene Seiten lesen Sie Angebotsdaten und Texte serverseitig, ordnen sie über die Angebots-ID zu und aktualisieren einen bewusst geführten Cache. Eigene redaktionelle Kurzfassungen können über die Text-Ressource aus einem vereinbarten Zusatztext gelesen werden. Die Anleitung API: Eigene Angebotswebsite und Kursplaner zeigt Datenfelder, Sprachbezug, aktuelle Buchungslinks und Bildgrenzen.

Die Buchung verbleibt im vorgesehenen edoobox-Prozess. Ein lokaler Cache reserviert keinen Platz. Für eine zeitnahe Aktualisierung können passende Webhooks einen gezielten Abruf anstossen; der regelmässige Abgleich bleibt Teil Ihrer Integration.

Kursleitungen eines Termins über die API ändern

Die Zuordnung gehört zur Ressource date, also zum konkreten Termin. Das Feld leader ist eine Liste öffentlicher admin-IDs. Mehrere Leitende werden gemeinsam in dieser Liste gespeichert.

Lesen Sie den Termin mit GET /v2/date/{id} und übernehmen Sie seine aktuelle leader-Liste.
Ermitteln Sie die vollständige gewünschte Liste: vorhandene weiterhin zuständige Personen behalten, eine neue Admin-ID ergänzen oder die zu entfernende ID weglassen.
Senden Sie die gesamte Liste mit PUT /v2/date/{id} im Feld data.leader.
Prüfen Sie HTTP- und fachlichen Status. Lesen Sie danach denselben Termin erneut und vergleichen Sie die tatsächlich gespeicherten IDs mit der gewünschten Liste.

// currentLeaderIds wurden aus dem Termin gelesen.
// additionalAdminId und removedAdminId sind geprüfte öffentliche Admin-IDs.
const desiredLeaderIds = [...new Set([...currentLeaderIds, additionalAdminId])]
  .filter(id => id !== removedAdminId);
const requestBody = { data: { leader: desiredLeaderIds } };
// requestBody als JSON mit PUT /v2/date/{id} senden und Ergebnis zurücklesen.

Die gesendete Liste ersetzt die bisherige Zuordnung. Senden Sie nur eine neue ID, bleiben die bisherigen Leitenden nicht automatisch erhalten. {"data":{"leader":[]}} entfernt alle Leitungszuordnungen dieses Termins. Eigene add- oder remove-Operatoren sind für dieses Feld nicht vorgesehen.

Stimmen Sie parallele Änderungen ab, damit ein inzwischen aktualisierter Leitungsstand nicht überschrieben wird. Kontrollieren Sie im Kalender zusätzlich die Terminzuordnung. Das Ändern dieses Termins ändert nicht automatisch alle weiteren Termine des Angebots.

Buchungen mit CRM und anderen Systemen abgleichen

Für eine aktuelle Buchungsübersicht im CRM kombinieren Sie einen vollständigen Erstimport, laufende Abrufe neuer Buchungen und regelmässige Aktualisierungen bereits bekannter Buchungen. Der Buchungszeitpunkt time ist kein Änderungszeitstempel: Ein Zeitfilter für neue Buchungen erfasst spätere Stornos älterer Buchungen nicht automatisch.

Die Anleitung API: Buchungen synchronisieren erklärt Feldfilter, URL-Kodierung, eindeutige Sortierung, alle Listenseiten, wiederholbare Verarbeitung und die Kombination mit Webhooks anhand eines CRM-Beispiels.

Vor einem API-Projekt vorhandene Funktionen prüfen

Für die Buchhaltungsanbindung steht die native Bexio-Integration zur Verfügung. Interne Regeln für Tags, Notizen, Datenfelder und Vorlagenauswahl können Sie mit Automationen konfigurieren. Beide Funktionen werden über den Plugin Manager freigeschaltet.

Für Abonnemente und Mehrfachkarten existieren eigene Ressourcen für Definition, Benutzerzuordnung, Perioden und Einlösungen. Prüfen Sie vor Schreibzugriffen Plugin-Verfügbarkeit, Berechtigungen und die fachlichen Abläufe. Eine normale Buchung oder Transaktion ersetzt keine Prüfung der Abo-Gültigkeit oder der verbleibenden Einlösungen.