Technischer Leitfaden zur Regiondotour-API

Für Entwicklerinnen, Entwickler und technische Verantwortliche von Tourenanbietern, die Regiondotour an ihre internen Systeme anbinden möchten.

Überblick

Die Regiondotour-API ist eine REST-Schnittstelle, über die Ihre autorisierten Anwendungen lesend und schreibend auf Ihr Anbieter-Konto zugreifen: Buchungen, Verfügbarkeiten, Preise, Kundenprofile, Vertriebskanäle. Alle Anfragen müssen authentifiziert sein und laufen über HTTPS. Die Antworten werden als JSON in UTF-8 zurückgegeben.

Base-URL und Versionen

Produktions-URL: https://api.regiondotour.org/v1. Sandbox-URL: https://sandbox.regiondotour.org/v1. Die aktuelle Version ist v1. Abwärtskompatible Weiterentwicklungen bleiben auf v1. Größere Änderungen führen zu einer v2 mit einer Übergangszeit von mindestens 12 Monaten.

Schritte zur Einrichtung

API-Schlüssel erzeugen

Öffnen Sie in Ihrem Anbieter-Bereich Einstellungen → Integrationen → API-Zugang. Klicken Sie auf „Neuer Schlüssel", benennen Sie ihn nach der Zielintegration (z. B. „Internes CRM", „Power BI") und wählen Sie ausschließlich die minimal notwendigen Berechtigungen aus.

Schlüssel serverseitig speichern

Der Schlüssel wird bei der Erzeugung nur einmal angezeigt. Kopieren Sie ihn in Ihren Secret-Manager (Vault, AWS Secrets Manager, verschlüsselte Umgebungsvariablen). Legen Sie ihn niemals in einem Git-Repository ab.

In der Sandbox testen

Richten Sie Ihre Aufrufe zunächst gegen sandbox.regiondotour.org. Die Sandbox enthält Testdaten, die jede Nacht zurückgesetzt werden. Prüfen Sie das Antwortformat, das Fehlerverhalten und die Ratenlimits.

In Produktion gehen

Ersetzen Sie die URL durch die Produktionsadresse und beobachten Sie die ersten 48 Stunden über die Aufrufprotokolle unter Einstellungen → Integrationen → Protokolle.

Authentifizierung

Jede Anfrage muss den Header X-Api-Key enthalten. Beispiel: X-Api-Key: ep_live_a1b2c3d4e5f6.... Sandbox-Schlüssel beginnen mit ep_sandbox_. Produktionsschlüssel beginnen mit ep_live_. Ein kompromittierter Schlüssel muss über die Verwaltungsansicht sofort widerrufen werden.

Kategorien von Endpunkten

Buchungen: GET/POST/PATCH auf /reservations. Enthält Teilnehmende, Zeitfenster, Zahlungsstatus, Herkunftskanal, gekaufte Extras.
Verfügbarkeiten: GET/PATCH auf /availability. Abruf und Sperren von Zeitfenstern, Steuerung der Mindestteilnehmerzahl.
Preise: GET/POST auf /pricing. Preisraster nach Teilnehmerkategorie, Rabatte, Saisontarife.
Katalog: GET auf /activities und /categories. Katalogstruktur, Attribute, Bilder.
Kunden: GET/PATCH auf /customers. Kundenprofile, Teilnahmehistorie, Präferenzen.
Kanäle: GET auf /channels. Status der Anbindungen an GetYourGuide, Viator, Musement, Regiondo usw.
Webhooks: GET/POST/DELETE auf /webhooks. Registrieren von Ziel-URLs je Ereignistyp.
Berichte: GET auf /reports. Volumen, Umsätze, Margen nach Kanal oder Aktivität.

Ratenlimits

600 Anfragen pro Minute je API-Schlüssel. Ein Überschreiten liefert HTTP 429 mit einem Retry-After-Header. Setzen Sie einen exponentiellen Backoff ein: 1 s, 2 s, 4 s, 8 s. Bündeln Sie Ihre Anfragen (?from=&to=), statt jedes Element einzeln abzufragen.

Fehlerbehandlung

HTTP-Code	Bedeutung	Empfohlene Maßnahme
200 / 201	Erfolg	Antwort normal verarbeiten
400	Ungültige Anfrage — Payload fehlerhaft	JSON-Struktur des Aufrufs prüfen
401	Nicht authentifiziert — Schlüssel fehlt oder falsch	Header X-Api-Key prüfen
403	Verboten — unzureichende Berechtigungen	Berechtigungen des Schlüssels anpassen
404	Ressource nicht gefunden	ID der Ressource prüfen
409	Konflikt — inkompatibler Zustand	Ressource neu lesen und erneut versuchen
429	Zu viele Anfragen	Retry-After beachten, Backoff einsetzen
500 / 503	Serverfehler bei Regiondotour	Nach 60 s erneut versuchen, bei Anhalten Support kontaktieren

Webhooks: HMAC-Signatur

Jeder von Regiondotour versendete Webhook enthält den Header X-Regiondotour-Signature mit einer HMAC-SHA256-Signatur des Requestkörpers, berechnet mit dem gemeinsamen Geheimnis Ihres Endpunkts. Prüfen Sie diese Signatur konsequent vor jeder Verarbeitung — andernfalls könnte eine dritte Partei Ereignisse fälschen.