API: Eigene Angebotswebsite und Kursplaner

Sie können Angebote auf einer eigenen Website oder in einem externen Kursplaner darstellen und die eigentliche Buchung weiterhin in edoobox durchführen lassen. Diese Anleitung beschreibt einen serverseitigen Abgleich mit eigenen Detailseiten, gezielt übernommenen Texten und einem lokalen Zwischenspeicher.

Darstellung, Abgleich und Buchung aufteilen

Das Website-Backend liest die freigegebenen Angebotsdaten über die API und speichert die benötigten Felder in seiner eigenen Datenbank. Die öffentliche Website liest diesen vorbereiteten Bestand. Der Anmeldebutton öffnet den von edoobox gelieferten Buchungsweg. Die verbindliche Prüfung von Buchbarkeit, Preis, Kapazität und Voraussetzungen erfolgt weiterhin im edoobox-Buchungsprozess.

Für ein fertiges eingebettetes Angebot verwenden Sie das WordPress-Plugin oder Vorschau/Share und iFrame. Eine selbst gestaltete API-Website benötigt eigene Entwicklung für Datenhaltung, Aktualisierung, Navigation und SEO. Fertig gerenderte Templates liefern HTML; sie sind eine andere Ausgabeform als die hier verwendeten Rohdaten.

Zugang und Veröffentlichungsumfang vorbereiten

Erstellen Sie einen eigenen API-Schlüssel und begrenzen Sie ihn auf die benötigten Leserechte, beispielsweise für Angebote, Texte und bei Bedarf Termine, Orte oder Preise.
Richten Sie die serverseitige Authentifizierung mit dem richtigen Host, Token und edid ein.
Bestimmen Sie, welche Angebote und Sprachen auf der Website erscheinen dürfen. Ein administratives API-Leserecht ist keine automatische öffentliche Freigabe aller gelesenen Inhalte.
Speichern Sie die edoobox-Angebots-ID als unveränderte Zuordnung zu Ihrer eigenen Website-Seite.
Definieren Sie eine Aktualisierungsfrequenz sowie ein Verhalten für fehlende oder veraltete Daten.

Interne Angebote und deren Zugangscodes gehören nicht ungeprüft in einen öffentlichen Datenbestand. Übernehmen Sie nur die ausdrücklich freigegebenen Felder; geben Sie API-Zugangsdaten nicht an den Website-Browser weiter.

Angebotsdaten vollständig und sprachbezogen lesen

Verwenden Sie GET /v2/offer/list und wählen Sie die benötigten Felder. Ein Ausgangspunkt ist id, number, name, status, date_start, date_end, archive, trash, shortdescription und image. Setzen Sie language ausdrücklich auf eine verwendete Sprache, zum Beispiel de. Die API-v2-Referenz beschreibt die einzelnen Ressourcen.

Lesen Sie alle Seiten über limit.start, limit.reply und die Antwortdaten. Die Anleitung Listen vollständig abrufen erklärt den Aufbau. Verwenden Sie über einen vollständigen Lauf dieselben Filter und eine eindeutige Sortierung.

shortdescription ist eine abgeleitete Kurzbeschreibung. Sie ist kein frei benannter zusätzlicher Text und kein Ersatz für die vollständige HTML-Beschreibung. Für eine eigene redaktionelle Kurzfassung verwenden Sie einen vereinbarten Zusatztext.

Beschreibung und eigene Zusatztexte über die Text-Ressource lesen

Die Texte sind eigene Datensätze. GET /v2/text/list unterstützt die Felder id, resource, resource_id, language und value. Filtern Sie die Textart, die Angebots-ID und die Sprache gemeinsam:

Gewünschter Inhalt	Wert für `resource`
Vollständige Beschreibung	`description`
Zusatztext 1	`additionaltext1`
Zusatztext 2	`additionaltext2`
Zusatztext 3	`additionaltext3`

// offerId stammt unverändert aus der Angebotsantwort.
const url = new URL('https://app2.edoobox.com/v2/text/list');
url.searchParams.set('fields', JSON.stringify([
  'id', 'resource', 'resource_id', 'language', 'value'
]));
url.searchParams.set('filter', JSON.stringify([
  { property: 'resource', expression: '=', value: 'additionaltext1' },
  { property: 'resource_id', expression: '=', value: offerId },
  { property: 'language', expression: '=', value: 'de' }
]));
url.searchParams.set('response_type', 'array');
// Serverseitig mit denselben edid- und Authorization-Headern abrufen.

Der passende Eintrag enthält seinen Text in value. Ein leeres Ergebnis muss als fehlende Textfassung behandelt werden; die Integration entscheidet bewusst über einen Ersatztext oder das Ausblenden. Ein Kategorietext ist über die Kategorie-ID ein eigener Eintrag. Er wird durch diesen Angebotsfilter nicht automatisch mitgeladen.

Vereinbaren Sie zum Beispiel: Zusatztext 1 enthält die redaktionelle Kurzfassung des externen Kursplaners, die Beschreibung bleibt die ausführliche Kursinformation. Prüfen Sie vorher die anderen Verwendungen der Zusatztexte in E-Mails und PDFs. Eine Änderung wirkt dort ebenfalls, wenn derselbe Text ausgegeben wird. HTML-Inhalte müssen im Zielsystem passend und sicher verarbeitet werden; ein HTML-Text ist nicht automatisch Klartext.

Aktuelle Buchungslinks übernehmen

Lesen Sie für das Angebot GET /v2/offer/{id}/shareurl. Die Antwort enthält unter data.shareurl.url.booknow den vorgesehenen direkten Buchungslink und unter data.shareurl.url.segment die sprachbezogenen Angebotspfade. Verwenden Sie die tatsächlich gelieferten Werte. Die Auswahl im Vorschau-/Share-Dialog ist zusätzlich hilfreich, wenn Sie einen vollständigen öffentlichen Sprach-, Kategorie- oder Einbettungslink benötigen.

Verknüpfen Sie Ihre eigene Detailseite dauerhaft über die Angebots-ID und aktualisieren Sie die von edoobox gelieferten URLs beim Abgleich. Namen, Kategoriepfade und Sprache können sich ändern; ein aus dem sichtbaren Angebotsnamen selbst zusammengesetzter edoobox-Link ist dafür kein verlässlicher Ersatz. Kopieren Sie auch keine persönliche Buchungssitzung oder einen Teilnehmenden-Zugangslink als allgemeinen Anmeldebutton.

Bei einem Unterangebot eines Multiangebots liefert der Share-Ablauf den Buchungsweg des übergeordneten Multiangebots. Prüfen Sie deshalb die tatsächliche Auswahl im Zielprozess. Interne Codes aus einer Share-Antwort dürfen nur in den vorgesehenen geschützten Verteiler gelangen.

Bild-URLs, Varianten und Originalproportionen prüfen

Das Angebotsfeld image kann false sein. Bei einem zugewiesenen Bild enthält es unter anderem name, type, url und url300. Verwenden Sie die zurückgegebenen URLs unverändert. image.url besitzt keine allgemeine Zusage für eine feste Pixelgrösse oder für die unveränderte Originaldatei.

edoobox verarbeitet Bilder je nach Uploadweg und gespeichertem Bildtyp unterschiedlich. Bestehende Vorschaubilder können auf feste Seitenverhältnisse zugeschnitten sein; andere Bildwege verwenden die öffentliche Ausgangsdatei oder eigene Grössenvarianten. Eine hochgeladene Hochformatdatei bedeutet deshalb nicht, dass jede Angebotsansicht oder API-URL das Hochformat ausliefert.

Ausgabe	Was Sie verwenden können
REST-Angebotsantwort	Die tatsächlich gelieferten `image.url` und `image.url300`. Ein allgemeines Feld `image.original`, `url600` oder `url900` wird hier nicht ausgegeben.
WordPress-Kopfdaten	Das Plugin verwendet die vom Template gelieferten Bildvarianten für seine OpenGraph-Ausgabe. Diese Kopfdaten sind ein eigener Ausgabekontext.
Social-Media-Vorschaubild	Eigene generierte Ausschnitte für die Linkvorschau. Sie sind keine Originalbild-Schnittstelle für Ihr Frontend.

Ein manuell ergänztes Suffix wie _900 funktioniert nicht für jeden Bildtyp und jede Ablage. Bauen Sie darauf keinen allgemeinen Bildvertrag auf. Prüfen Sie die tatsächlich ausgelieferte Datei, Auflösung und Proportion mit mehreren Angeboten und nach einem Bildwechsel.

Benötigt Ihr eigener Kursplaner garantiert ein unbeschnittenes Original oder eine bestimmte grosse Auflösung, verwalten Sie dieses Webbild mit einer festen Zuordnung zur Angebots-ID in Ihrem CMS oder klären Sie den passenden Dateiabruf für Ihre konkrete Anbindung. Durch das Hochskalieren einer kleinen Vorschau entstehen keine zusätzlichen Bilddetails.

Eigenen Cache aktualisieren und Ausfälle behandeln

Laden Sie die vorgesehenen Angebote, Texte und Buchungslinks in einen neuen vorbereiteten Stand. Prüfen Sie jede API-Antwort auf HTTP- und fachliche Fehler.
Übernehmen Sie den neuen vollständigen Stand erst, wenn alle benötigten Seiten und Pflichtdaten erfolgreich gelesen wurden.
Speichern Sie den Zeitpunkt des letzten erfolgreichen Abgleichs und die Zuordnung je Angebots-ID.
Bei einem Fehler behalten Sie den letzten geprüften Stand, kennzeichnen die Störung intern und wiederholen den Abruf kontrolliert. Ein Fehler darf den Bestand nicht als vermeintlich leeres Ergebnis ersetzen.
Legen Sie fest, ab welchem Datenalter Preise, freie Plätze oder Anmeldebuttons nicht mehr ungeprüft angezeigt werden. Der edoobox-Buchungsprozess bleibt für den tatsächlichen Abschluss massgebend.

Ein Intervall wie 15 Minuten ist eine Entscheidung Ihrer Integration. Es erzeugt keine Reservierung in edoobox und garantiert keine unveränderten Plätze bis zum nächsten Lauf. Stellen Sie abgeschlossene, archivierte oder nicht mehr freigegebene Angebote im eigenen Bestand passend um. Entfernen Sie einen Datensatz erst nach einem vollständig geprüften Abgleich und nicht wegen einer fehlgeschlagenen Seite.

Mit Webhooks können Sie passende Änderungen zum Anlass eines gezielten Nachladens nehmen. Behalten Sie den regelmässigen Abgleich bei. Für übernommene Buchungen erläutert API: Buchungen synchronisieren den eigenen Verarbeitungsstand und spätere Stornos.

Beispiel: Externer Kursplaner mit eigener Kurzfassung

Eine Organisation pflegt vollständige Kursinformationen in edoobox und eine kurze redaktionelle Einleitung im Zusatztext 1. Ihr Website-Backend liest Angebote und die deutsche Textfassung, speichert sie nach Angebots-ID und stellt eigene Seiten unter https://example.org/kurse/… dar. Der Anmeldebutton verwendet den zuletzt erfolgreich geladenen edoobox-Buchungslink.

Bei einer Textänderung übernimmt der nächste vollständige Lauf die neue Kurzfassung. Bei einem API-Ausfall bleibt der letzte geprüfte Inhalt erhalten; veraltete Verfügbarkeitsangaben werden gemäss der vereinbarten Website-Regel behandelt. Nach einer Verschiebung in eine andere Kategorie wird der aktuelle Link erneut aus edoobox gelesen. Die Website errechnet keine eigene verbindliche Buchungsbestätigung aus dem Cache.

Vor der Veröffentlichung und bei Fehlern kontrollieren

Ein Angebot mit vollständigem Text, eines ohne Zusatztext und ein mehrsprachiges Angebot vergleichen.
Mehr als eine Listenseite, ein gelöschtes beziehungsweise archiviertes Angebot und eine fehlgeschlagene API-Seite berücksichtigen.
Hochformat-, Querformat- und ersetzte Bilder in der tatsächlich verwendeten Auflösung prüfen.
Öffentlichen Buchungslink, Multiangebot und einen geschützten Bereich getrennt prüfen.
Titel, Beschreibung und kanonische URL der eigenen Website im eigenen CMS pflegen; OpenGraph und Canonical unterscheiden.
Für den Betrieb Zeitpunkt, Angebots-ID und Fehlerkategorie protokollieren; Zugangsdaten und unnötige Personendaten weglassen.