edoobox API: Erste Schritte

Die edoobox API ermöglicht automatisierte Abfragen und Integrationen, zum Beispiel für Webseiten, Reporting, Buchhaltung, CRM, WordPress, Zapier oder eigene interne Systeme. Beginnen Sie immer mit einem klaren Anwendungsfall und einem API-Schlüssel mit möglichst eingeschränkten Rechten.

Echte edoobox API-Zugangsverwaltung mit bestehenden Schlüsseln, Status und Aktion Schlüssel hinzufügen in einem Demo-Konto.

AAPI-ZugangsverwaltungBSicherheitshinweisCSchlüsselstatus und Rechte

Vorbereitung

Klären Sie, welche Daten gelesen oder geschrieben werden sollen.
Erstellen Sie für jede Integration einen eigenen API-Schlüssel.
Vergeben Sie nur die Rechte, die wirklich benötigt werden.
Planen Sie sichere Ablage von Secret Key, Access Token und Postman-Environment.
Testen Sie zuerst mit Demo-Daten oder in einer ungefährlichen Umgebung.

API-Schlüssel generieren

Die API V2 verwendet API-Schlüssel aus dem V2-Konto. Öffnen Sie Einstellungen > API-Zugangsverwaltung und wählen Sie Schlüssel hinzufügen. Wählen Sie, ob der Schlüssel direkt aktiv sein soll, und bestimmen Sie danach das passende Recht.

Nach dem Speichern zeigt edoobox Public Key und Secret Key in einem Popup. Der Secret Key wird nur in diesem Moment vollständig angezeigt. Kopieren Sie beide Werte sofort in einen Passwortmanager oder Secret-Speicher. Senden Sie Secret Keys nicht per E-Mail, Chat oder Screenshot.

API-Schlüssel in der Zugangsverwaltung verwalten

In der API-Zugangsverwaltung sehen Sie vorhandene Schlüssel mit Status, Public Key und zugewiesenem Recht. Der Public Key kann in der Tabelle kopiert werden. Der Status kann zwischen aktiv und inaktiv umgeschaltet werden. Inaktive Schlüssel bleiben gespeichert, sollen aber nicht mehr eingesetzt werden.

Ein API-Schlüssel besitzt dieselben Berechtigungen wie das gewählte Recht. Die Auswahl kann vorhandene Rechte und vordefinierte Rechte wie WordPress Recht, Zapier Recht oder Leserecht enthalten. Wenn ein vordefiniertes Recht noch nicht vorhanden ist, kann edoobox es beim Erstellen des Schlüssels anlegen.

Wenn ein zugewiesenes Recht später gelöscht oder nicht mehr gefunden wird, ist der Schlüssel fachlich nicht mehr sauber nachvollziehbar. Erstellen Sie in diesem Fall ein neues passendes Recht oder deaktivieren Sie den Schlüssel, bis die Berechtigung geklärt ist.

Element	Bedeutung
Public Key	Sichtbarer API-Schlüssel, wird in der Übersicht angezeigt und für Authentifizierung verwendet.
Secret Key	Geheimes Gegenstück zum Public Key, wird nach dem Erstellen nur einmal vollständig angezeigt.
Status	Nur aktive Schlüssel können für Authentifizierung genutzt werden.
Recht	Begrenzt den Zugriff des Schlüssels auf die API.

Anwendungsbeispiel: API-Schlüssel für Reporting erstellen

Für eine externe Auswertung öffnen Sie die API-Zugangsverwaltung, klicken auf Schlüssel hinzufügen, lassen den Status aktiv und wählen ein Leserecht. Nach dem Speichern kopieren Sie Public Key und Secret Key sofort in den Secret-Speicher der Reporting-Anwendung.

Authentifizierung und Access Token

Die Authentifizierung erfolgt über https://app2.edoobox.com/v2/auth. Dafür senden Sie Public Key, Secret Key und optional ein Ablaufdatum. In der Antwort erhalten Sie eine edid und einen gültigen access_token.

Alle geschützten API-V2-Endpunkte benötigen danach den access_token und die edid. Die edid definiert, welches Konto aktuell authentifiziert wurde. In der Authentifizierungsantwort finden Sie ausserdem Informationen zu eingeloggten Konten, Konto-ID und Rechten, typischerweise unter data.login.data[edid]. Wenn ein Zugang mehrere Konten zurückliefert, verwenden Sie für jede Anfrage bewusst die passende edid; sonst lesen oder schreiben Sie Daten im falschen Konto oder erhalten scheinbar unerklärliche Rechtefehler.

Antwortstruktur nach der Authentifizierung

Die Authentifizierungsantwort enthält neben dem access_token auch die edid. Diese edid definiert, welches Konto innerhalb der Antwort aktuell authentifiziert wurde. Bei Multi-Session- oder Mehrkonten-Zugriffen können in data.login.data mehrere Konten erscheinen.

data.login.data[edid]

Dort finden Sie unter anderem Konto-ID und die Rechte, die mit diesem API-Schlüssel wirksam sind. Verwenden Sie für weitere API-Aufrufe immer den Token und die edid aus derselben erfolgreichen Authentifizierung.

Authentifizierung mit Node.js

const response = await fetch('https://app2.edoobox.com/v2/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'grant-type': 'password',
    key: process.env.EDOOBOX_PUBLIC_KEY,
    secret: process.env.EDOOBOX_SECRET_KEY
  })
});
const result = await response.json();
if (!response.ok || result.error || !result.data?.access_token || !result.data?.edid) {
  throw new Error('edoobox-Authentifizierung fehlgeschlagen');
}
const edid = result.data.edid;
const accessToken = result.data.access_token;
// Token nur serverseitig im Arbeitsspeicher oder Secret-Speicher verwenden.

Authentifizierung mit PHP

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app2.edoobox.com/v2/auth',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_CONNECTTIMEOUT => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_POSTFIELDS => json_encode(array(
    'grant-type' => 'password',
    'key' => getenv('EDOOBOX_PUBLIC_KEY'),
    'secret' => getenv('EDOOBOX_SECRET_KEY')
  )),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
$failed = $response === false;
curl_close($curl);
if ($failed || $status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP-Authentifizierung fehlgeschlagen');
}
$result = json_decode($response, true);
if (!is_array($result) || !empty($result['error']) || empty($result['data']['access_token']) || empty($result['data']['edid'])) {
    throw new RuntimeException('edoobox-Authentifizierung fehlgeschlagen');
}
$edid = $result['data']['edid'];
$accessToken = $result['data']['access_token'];

Erste Abfrage: eine Seite der Angebotsliste abrufen

Nach erfolgreicher Authentifizierung können Sie geschützte Endpunkte abfragen. Das Beispiel https://app2.edoobox.com/v2/offer/list liest die erste Seite der Angebotsliste, sofern das gewählte Recht diese Abfrage erlaubt. Ohne eigenen Listenparameter werden höchstens 100 Einträge geliefert. Für den vollständigen Bestand lesen Sie anschliessend die weiteren Seiten gemäss dem Abschnitt zur Paginierung.

Die aktuelle OpenAPI-Datei verlangt bei den üblichen geschützten Ressourcen Authorization: Bearer <JWT> zusammen mit edid. Ein zusätzlicher grant-type-Header ist dort nicht deklariert. Beim Authentifizierungsaufruf steht grant-type hingegen im JSON-Body. Prüfen Sie abweichende Anforderungen auf der jeweiligen Endpunktseite.

const offerResponse = await fetch('https://app2.edoobox.com/v2/offer/list', {
  method: 'GET',
  headers: {
    edid,
    Authorization: `Bearer ${accessToken}`
  }
});
if (!offerResponse.ok) {
  throw new Error('Angebote konnten nicht geladen werden');
}
const offers = await offerResponse.json();
if (offers.error) {
  throw new Error('edoobox hat die Angebotsabfrage abgewiesen');
}

Abfragen mit Postman testen

Mit Postman oder einem vergleichbaren Werkzeug können Sie API-Endpunkte prüfen, bevor Sie Code schreiben. Laden Sie die OpenAPI-Datei über die integrierte API-v2-Referenz herunter und importieren Sie sie als OpenAPI-Definition. Die Unterstützung des Formats OpenAPI 3.2.1 hängt von der verwendeten Werkzeugversion ab.

Legen Sie selbst ein Environment mit dem Host Ihrer Umgebung, Ihren Zugangsdaten sowie Variablen für JWT und edid an. Wählen Sie den importierten Endpunkt POST /v2/auth und übernehmen Sie das passende Body-Beispiel aus der Referenz. Eine zusätzliche Environment-Datei oder automatische Token-Übernahme wird mit der OpenAPI-Datei nicht mitgeliefert. Ordnen Sie die tatsächlichen Antwortfelder nach erfolgreicher Prüfung manuell zu oder verwenden Sie ein für Ihre Umgebung geprüftes Skript.

Wenn eine nachfolgende Anfrage fehlschlägt, prüfen Sie zuerst, ob das richtige Environment aktiv ist, ob der Auth-Request erfolgreich war und ob die Header edid und Authorization tatsächlich aus den gespeicherten Variablen befüllt werden.

API-Zugang: Verwenden Sie das Body-Beispiel apiLogin bei POST /v2/auth.
Admin-Login: Das Body-Beispiel administrator beschreibt E-Mail und Passwort, wenn dieser Weg für Ihren Testfall vorgesehen ist.
Weitere Abfragen: erst nach erfolgreicher Authentifizierung ausführen.

Sicherheit und Betrieb

Erstellen Sie getrennte Schlüssel pro Integration, rotieren Sie Schlüssel bei Personalwechsel oder Dienstleisterwechsel und deaktivieren Sie nicht mehr genutzte Zugänge. Speichern Sie Secrets nur in dafür vorgesehenen Systemen und nie direkt in öffentlich zugänglichem Frontend-Code.

Dokumentieren Sie zu jedem Schlüssel Zweck, verantwortliche Person, System, Rechteumfang und geplantes Rotationsdatum. So bleibt auch nach einem Dienstleisterwechsel klar, welche Integration welchen Zugriff besitzt.

Wenn eine Integration produktiv Buchungen, Rechnungen oder Teilnehmendendaten schreibt, planen Sie Logging, Fehlerbehandlung, Testdaten, Rate-Limits, Datenschutz und klare Zuständigkeiten. Details zur Verwaltung finden Sie unter API-Schlüssel und Zugriffsrechte verwalten.

Die nächste Listenseite gezielt anfordern

Der gemeinsame V2-Listenparameter ist ein JSON-Objekt mit start als Startposition und reply als Seitengrösse. Für die zweite Seite mit 100 Einträgen setzen Sie beispielsweise limit={"start":100,"reply":100}. Kodieren Sie das JSON als URL-Parameter; setzen Sie die nächste Startposition anschliessend um die angeforderte Seitengrösse weiter.

const url = new URL('https://app2.edoobox.com/v2/offer/list');
url.searchParams.set('limit', JSON.stringify({ start: 100, reply: 100 }));
// url mit denselben edid- und Authorization-Headern abrufen.

Prüfen Sie bei jeder Antwort HTTP-Status, error und den Datenbereich der konkreten Ressource. Verwenden Sie vorhandene Gesamt- oder Seitendaten dieser Ressource zum Abbruch. Eine fehlgeschlagene Seite darf nicht als leere Abschlussseite behandelt werden.

Für einen dauerhaften Buchungsabgleich behalten Sie Filter und Sortierung über alle Seiten bei und speichern den abgeschlossenen Verarbeitungsstand erst nach erfolgreicher Übernahme aller Seiten. Die Unterseite API: Buchungen synchronisieren zeigt den Ablauf mit Zeitfenstern, limit.total, doppelten Meldungen, Webhooks und dem zusätzlichen Abgleich älterer Buchungen. Dort wird auch erklärt, warum time kein Filter für sämtliche späteren Änderungen ist.

Nach der ersten Abfrage: Webhooks oder eigene Angebotsseiten

Für eine Ereignisverbindung genügt die Authentifizierung allein noch nicht. Die Anleitung Webhooks einrichten und betreiben führt über das passende Webhook-Recht, POST /v2/webhook, Topic-Auswahl, Signaturprüfung und Aktivierung bis zum geprüften Empfang. Die Einrichtung erfolgt mit den beschriebenen API-Anfragen.

Wenn Sie Angebote in einer eigenen Website darstellen möchten, lesen Sie Eigene Angebotswebsite und Kursplaner. Dort wird eine eigene redaktionelle Kurzfassung über GET /v2/text/list vom abgeleiteten Angebotsfeld shortdescription unterschieden.

Tokenlaufzeit und Listen vollständig verarbeiten

Die Beispiele laufen auf einem Server und lesen die Zugangsdaten aus vorbereiteten Umgebungsvariablen. Ohne eigenes expire stellt die API das Token standardmässig für 30 Minuten aus. Erneuern Sie es nach Ablauf über die Authentifizierung; veröffentlichen oder protokollieren Sie es nicht.

Eine Listenabfrage liefert standardmässig 100 Einträge. Die maximale Seitengrösse beträgt 2000. Verarbeiten Sie bei grösseren Datenbeständen die Seiten über die dokumentierten limit-Parameter, bis alle benötigten Datensätze abgeholt sind. Eine erfolgreiche erste Seite beweist nicht, dass alle Angebote geladen wurden.

Für neue Funktionen wie Abonnemente, Plugins oder Automationen prüfen Sie die jeweilige Ressource und das eigene Zugriffsrecht. Das vorbereitete Zapier-Recht ist kein allgemeines Schreibrecht für alle edoobox-Funktionen.