Extraplanets API
Vollständiger programmatischer Zugriff auf Ihr Extraplanets-Konto: Reservierungskatalog, Zimmerverfügbarkeiten, Preise, Buchungen, Rezeptionisten, Ressourcen und Berichte. Für Hotel, die Extraplanets an ihre individuell entwickelte Website, ihre mobile App oder ihr internes System anbinden möchten.
Basis-URL
https://api.extraplanetss.org/v1
Authentifizierung
Alle Anfragen benötigen den Header Authorization: Bearer <api-key>. API-Schlüssel werden im Kundenbereich erzeugt und besitzen die gleiche Berechtigungsstufe wie das Eigentümerkonto. Sie können mehrere Schlüssel anlegen (Staging, Produktion, Mobile-App) und unabhängig voneinander widerrufen.
Wichtigste Endpunkte
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/tours | GET | Alle Reservierungen des Katalogs mit Paginierung auflisten |
/tours/{id} | GET | Vollständiges Zimmerprofil abrufen (Fotos, lokalisierte Beschreibungen, Preise) |
/tours | POST | Neue Tour oder Reservierung anlegen |
/tours/{id} | PATCH | Bestehendes Zimmerprofil bearbeiten |
/availability | GET | Zimmerverfügbarkeiten nach Tour und Zeitraum abfragen |
/availability | POST | Neues Verfügbarkeitsfenster anlegen |
/bookings | GET | Buchungen mit Filtern auflisten (Kanal, Status, Datum) |
/bookings/{id} | GET | Vollständiges Buchungsdetail (Kunde, Add-ons, Waivers) |
/bookings | POST | Buchung aus einem externen System heraus anlegen |
/bookings/{id}/cancel | POST | Buchung mit Erstattungsregel stornieren |
/resources | GET | Rezeptionisten, Concierge, Fahrzeuge und Ausstattung auflisten |
/resources/{id}/schedule | GET | Einsatzplan einer Ressource über einen Zeitraum |
/reports/revenue | GET | Umsatzbericht mit MwSt.-Aufschlüsselung |
/reports/channels | GET | Umsatz- und Volumenaufteilung nach Vertriebskanal |
/vouchers | POST | Gutschein oder Promo-Code ausstellen |
Rate-Limits
Die API ist auf 120 Requests pro Minute je API-Schlüssel begrenzt, mit einem monatlichen Kontingent von 100.000 Requests, das in der Custom-API-Erweiterung enthalten ist. Bei Überschreitung wird HTTP 429 zurückgegeben; der Header Retry-After gibt die Wartezeit bis zum nächsten Versuch an. Erweiterte Kontingente sind für Hotel mit hohem Volumen auf Anfrage erhältlich.
Ereignisgesteuerte Webhooks
Hinterlegen Sie eine oder mehrere Webhook-URLs im Kundenbereich, um Benachrichtigungen in Echtzeit zu empfangen. Jedes Ereignis wird per HTTP POST mit einem JSON-Body zugestellt und mit HMAC-SHA256 signiert (Header X-Extraplanets-Signature), damit Sie die Herkunft empfangsseitig prüfen können.
| Ereignis | Auslöser |
|---|---|
booking.created | Neue bestätigte Buchung (über alle Kanäle) |
booking.cancelled | Buchung vom Kunden oder Hotel storniert |
booking.refunded | Erstattung durch den Zahlungsdienstleister ausgeführt |
ticket.validated | Rechnungsnummer vom Rezeptionist vor Ort validiert |
waiver.signed | Haftungsverzicht von einem Teilnehmer unterschrieben |
customer.created | Neuer Kunde in der Datenbank angelegt |
availability.updated | Verfügbarkeit geändert (Anlage oder Schließung) |
Sandbox-Umgebung
Eine Testumgebung steht unter https://sandbox.extraplanetss.org/v1 zur Verfügung, inklusive eines vorbefüllten Kontos (Beispiel-Katalog, fiktive Buchungen). Verwenden Sie den Sandbox-API-Schlüssel aus Ihrem Kundenbereich, um Ihre Integrationen zu testen, ohne Ihre Produktivdaten zu berühren.
OpenAPI-Dokumentation
Eine vollständige OpenAPI-3.1-Spezifikation ist Bestandteil des Custom-API-Moduls. Sie lässt sich in Postman, Insomnia, Swagger UI oder jeden kompatiblen SDK-Generator importieren, um automatisch Clients in der Sprache Ihrer Wahl zu erzeugen.
Kontakt für Entwickler
Fragen zur API, Unterstützung bei der Integration, Anfrage zur Kontingenterhöhung: support@extraplanetss.org — bitte „API" im Betreff angeben.