Daten-API: Buchungen anlegen, ändern und auslesen

Grundlagen zu Schlüsseln: siehe Daten-API: Schlüssel, Zugriff und Dokumentation. Alle Felder stehen unter https://rest.myxentra.com/docs.

Rechte: Ohne „Gastdaten in Buchungen“ kommen Name, E-Mail, Telefon, Adresse und verification als null, und E-Mail oder Telefon zu setzen gibt 403. Ohne Zugang sind key_code, checkin_link, guest_page_link, wifi_password und custom_fields null, die Link-Endpunkte und das Setzen von Türcode oder WLAN-Passwort antworten mit 403. Siehe API-Key: Rechte, Gültigkeit, Rotieren.

Direktbuchungen anlegen und ändern

Nimmst du Buchungen per Telefon, Mail oder WhatsApp an und trägst sie über die API ein (POST /api/v1/bookings/create oder POST /api/v1/bookings), legst du sie gleich vollständig an. Die Einheit gibst du mit ihrer Unit-ID an (accommodation). Das Feld ist Pflicht, für Buchungen wie für Blockierungen: ohne Einheit antwortet die API mit 400, weil eine Buchung ohne Einheit in keinem Kalender, keiner Reinigung und bei keinem Teammitglied auftauchen würde. Die IDs stehen unter API / MCP im Bereich „Deine Units“.

Der Bereich „Deine Units“ mit Name und Unit-ID jeder Einheit

Anzahl der Nächte, Buchungsdatum und den Übernachtungspreis ohne Reinigung berechnet Xentra selbst, genau wie bei einer Buchung aus dem Kalender. Mit PUT /api/v1/bookings/{id} änderst du dieselben Felder später; ändern sich die Daten, rechnet Xentra die Nächte neu. portal, cleaning_fee, payment_status, payment_method und guest_remark gehen nur bei Buchungen, die über die API oder in der App angelegt wurden; bei importierten Buchungen würde der nächste Abgleich sie überschreiben, deshalb antwortet die API dort mit 400. internal_note, cleaning_notes und language kannst du an jeder Buchung setzen.

Du kannst eine Buchung so zurückschicken, wie du sie per GET bekommen hast: unveränderte Felder ändern nichts. Das allgemeine Notizfeld der Buchung ist über die API weder les- noch schreibbar; für deine eigenen Notizen ist internal_note da.

Buchungen aus der API gehen auch an dein PMS

Hast du ein PMS verbunden und dort „Buchungen an PMS senden“ eingeschaltet, behandelt Xentra eine Buchung aus der API wie eine aus dem Kalender: Anlegen, Ändern und Stornieren gehen an dein PMS, Blockierungen eingeschlossen. Löschst du eine solche Buchung mit DELETE, storniert Xentra sie vorher im PMS. Klappt die Übertragung nicht, scheitert dein API-Aufruf trotzdem nicht; die Buchung steht dann nur in Xentra. Mehr dazu: Buchungen an dein PMS senden.

Überschreibungen und Gast-Angaben

Drei Felder liefern oft null, obwohl im Konto Werte sichtbar sind:

Die tatsächlich geltenden Zeiten liefern GET /api/v1/properties/get-user-properties und GET /api/v1/properties/get-property/{id} je Einheit als effective_checkin_time und effective_checkout_time. Woher die Zeit kommt, sagen checkin_time_source und checkout_time_source: unit (eigene Zeiten der Einheit), account (dein Standard für alle Einheiten) oder fallback (noch nichts eingestellt, Xentra rechnet mit 14:00 und 12:00; zeig das Gästen nicht als feste Zusage).

Das Türfenster einer Buchung liefern access_valid_from und access_valid_until in GET /api/v1/bookings und GET /api/v1/bookings/{id} als UTC-Zeitstempel, mit gekauftem Early Check-in oder Late Check-out und einer Änderung von Hand. Den „Puffer für Türcodes“ enthalten sie nicht.

Was der Gast selbst angegeben hat, steht im Check-in-Block von GET /api/v1/bookings/{id}: verification.arrival_time, verification.departure_time und verification.custom_fields[] (deine eigenen Check-in-Felder, Dateien mit file_url).

Zu key_code: Das Feld gibt einen Türcode zurück, den ein angebundenes PMS geliefert oder die API selbst gesetzt hat. Codes, die eine Smart-Lock-Integration (zum Beispiel Nuki) erzeugt, stehen hier nicht; das Feld ist dann null, obwohl gültige Codes an den Gast gehen. Den erzeugten Code siehst du an der Buchung in der App oder gibst ihn über {{key_code}} in einer Nachricht aus.

Weitere Felder

booked_at ist leer, wenn die Quelle keine Uhrzeit liefert, und bei Buchungen, die direkt in Xentra entstehen; dort ist created_at der Buchungszeitpunkt. Bei importierten Buchungen (zum Beispiel nach einem PMS-Wechsel) ist created_at der Importtag.

Buchungsnummer des Portals und Zahlung aus dem Check-in

Bei Buchungen, Rechnungen und Nachrichten bekommst du über die API die Buchungsnummer des Portals als platform_booking_number, also die Nummer, die der Gast bei Booking.com, Airbnb oder Expedia sieht. Es ist dieselbe Nummer wie im Webhook invoice_created. Bei anderen Buchungen, und wenn das Portal keine eigene Nummer mitgeliefert hat, ist sie null. Du kannst auch danach suchen: GET /api/v1/bookings?platform_booking_number=4012345678. Die Suche braucht die genaue Schreibweise und findet auch vergangene Buchungen.

Mit expand=checkin_payment (in der Liste und an der einzelnen Buchung) siehst du pro Buchung die Zahlung aus dem Online-Check-in: status, total, tourist_tax_amount (Kurtaxe), currency, paid_at (wann bezahlt wurde) und payment_method (stripe online oder invoice auf Rechnung). null heißt: zu dieser Buchung gibt es keine Zahlung aus dem Check-in. Jede Buchung trägt außerdem apartment (Name der Einheit) und booking_source (woher die Buchung kommt).

Check-in-Link und Gästemappe pro Buchung

Es sind dieselben Links wie in den Platzhaltern {{online_checkin_link}} und {{digital_guestbook_link}}, mit deiner eigenen Domain, falls eingerichtet. Beide Links sind Zugangsdaten, deshalb stehen sie nur an der einzelnen Buchung, nicht in der Liste. null heißt: gerade kein aktiver Link. Das Passwort der Gästemappe wird nie ausgegeben.