Zum Inhalt

Entwicklerhandbuch - Reservation API

Der verbundene OTA Partner verwendet die offizielle OTA Nachricht OTA_HotelResNotifRQ, um Reservierungen vom Kanal Kurzurlaub.de abzurufen. Kurzurlaub.de antwortet mit OTA_HotelResNotifRS als Bestätigung des Erfolgs oder Misserfolgs bei der Bearbeitung der Anfrage.

Wir unterstützen 2 Wege der Kommunikation: 1. Reservierungen können angefragt und abgerufen werden (PULL) 2. Reservierungen können gesendet werden (PUSH)

Allgemeine Informationen

Benötigte Information

Kurzurlaub.de folgt der offiziellen OTA-Reservierungsspezifikation und ermöglicht das Senden vieler Informationen zu Reservierungen. Nicht alle diese Informationen sind zwingend erforderlich, damit der OTA Partner die Reservierung bearbeiten kann.

Bitte beachten Sie die Reservierungsspezifikationen, um zu sehen, welche Informationen obligatorisch sind.

EchoToken

EchoTokens (meist eine GUID) sind für alle Anfragen (insbesondere OTA_HotelResNotifRQ) unerlässlich, um die Daten zu identifizieren. EchoTokens stellen sicher, dass jede Anfrage für Fehlerbehebungszwecke sowohl in Test- als auch in Produktionsumgebungen eindeutig identifiziert werden kann.

Alle Anfragen / Antworten, die Sie von Kurzurlaub.de senden, sollten ein EchoToken enthalten, und die Antwort (von Kurzurlaub.de) wird dasselbe EchoToken enthalten, das Sie in der Anfrage gesendet haben.

Sofern kein spezielles EchoToken gesendet wird, liefern wir als EchoToken eine GUID - Globally unique identifier (V4).

Lieferung von Reservierungen

Der Status der Reservierung wird durch das Attribut OTA_HotelResNotifRQ ResStatus bestimmt, für das die Werte Book, Modify und Cancel zulässig sind.

Kurzurlaub.de erlaubt nur einen Hotelcode pro Reservierung. Wenn ein Kanal mehrere Hotels pro Reservierung zulässt, muss eine Reservierung pro Hotel gesendet werden.

Mehrere Zimmer und Preise sind in einer Reservierungsanfrage zulässig.

Status von Buchungen

Buchungen werden mit aktuellem Status gesendet, Sofern der Status von Buchungen geändert wird durch Buchungsänderungen (Modify) oder Stornierungen (Cancel) senden wir eine erneute Push-Mitteilung an den Partner.

Status Beschreibung
Book Neue Buchungen, diese Status wird nur einmal beim ersten Senden verwendet, danach werden alle weitere Response zu einer Buchungs-ID immer mit Status Modify gesendet
Modify Buchungsänderungen oder erneuter Abruf einer schon gesendeten Buchung per ResID_Value oder Datumsbereich von/bis
Cancel Stornierungen

Die Reservierungsnummer (ResID_Value)

Der Wert der Reservierungs-Nummer setzt sich zusammen aus:

R{Buchungs-ID}-{Angebots-ID}-{Hotel-ID}

bspw. R12345678-1234567-12345

oder auch mit (A) R12345678-A1234567-12345 / (AP) R12345678-AP1234567-12345

Für eventuelle Anfragen benötigen Sie nur die Buchungsnummer (Buchungs-ID). Hilfreich ist natürlich auch die komplette Komposition.

Der Hotelier kennt den kompletten Wert aus seinem eigenen Verwaltungsbereich und den E-Mails. Eventuell benötigt er die Angebotsnummer (Angebots-ID), um die inkludierten Leistungen dem Angebot zuzuordnen.

Bei einer wichtigen Änderung eines Eintrags, z.B. die Änderung der Zimmeranzahl oder das Reisedatum, wird der Status der Reservierung Book auf Modify geändert.

Reservierungsbestätigung

Es ist wichtig zu beachten, dass Kurzurlaub.de als Autorität fungiert, wenn es darum geht, eine Reservierung zuzulassen oder abzulehnen.

Die OTA_HotelResNotifRS Antwort vom Partner (Success oder Error) zeigt uns, ob der Partner die Reservierungszustellungsnachricht / Benachrichtigungsanforderung empfangen hat oder nicht.

Vor diesem Hintergrund sollte das Paar OTA_HotelResNotifRQ ↔ OTA_HotelResNotifRS, das die Reservierungsnachricht/Benachrichtigung an den OTA-Partner sendet, nicht in einem Front-End-Kundenbuchungsprozess verknüpft werden.

Der Kunde/Agent, der eine Reservierung über Ihren Buchungskanal vornimmt, sollte in der Lage sein, eine Reservierung vorzunehmen, unabhängig von der Antwort (oder dem Fehlen einer solchen), die er von einem OTA-Partner zurückerhalten wird.

Bitte beachten:

  • Kurzurlaub.de erlaubt nur einen 1 Hotelcode pro Reservierung. Wenn ein Partner mehrere Hotels pro Reservierung zulässt, muss eine 1 Reservierung pro Hotel gesendet werden.
  • Kurzurlaub.de erlaubt mehrere Reservierungen pro gesendeter Anfrage.
  • Sofern Reservierungen per ResID_Value angefordert werden, sollte man nur 1 Reservierung angefragen.

Fehlerbehandlung

Wenn die Antwort vom Typ OTA_HotelResNotifRS eine Fehlermeldung enthält, kann die Reservierungsanfrage nicht verarbeitet werden, da einige Daten / Parameter ungültig sind.

Dies könnte beispielsweise der Fall sein, wenn erforderliche Daten fehlen oder wenn die Anmeldeinformationen oder der Hotelcode falsch sind und die Reservierung nicht verarbeitet wird, bis der Fehler behoben ist. Wenn der Fehler darin besteht, dass erforderliche Elemente oder Attribute fehlen, muss die Implementierung angepasst werden, um die erforderlichen Daten zu senden.

Wenn der Fehler mit den Anmeldeinformationen zusammenhängt, überprüfen Sie, ob der richtige Benutzername/das richtige Passwort gesendet wird. Wenn der Fehler ein ungültiger Hotelcode ist, wenden Sie sich an das Hotel, um sicherzustellen, dass die Schnittstelle für den Empfang von Reservierungen korrekt eingerichtet ist.

Beispiele gängiger Fehlerquellen:

  • Anmeldeinformationen des Partner (AgentDutyCode)
  • ungültiger HotelCode
  • Hotel nicht online / nicht mit dem Partner verbunden
  • ungültige Reservierungs-ID (ResID_Value)

Es wird auch bei Fehlermeldungen immer eine XML Antwort mit ErrorCode und ErrorMessage gesendet, mit einem Status 200 - OK .

Siehe unsere implementierten OTA ErrorCodes im Bereich Error Handling

Nur bei Fehlern in der Authentifizierung (Problem mit AgentDutyCode oder HotelCode) senden wird einen Status 401 - Forbidden

Wenn die Antwort ein HTTP-Fehlerantwortcode im Bereich Status 500 ist, wird erwartet, dass der verbindende OTA Partner das Anfragen der Reservierung wiederholt, bis sie erfolgreich zugestellt wird oder eine vordefinierte Timeout-Periode erreicht wird.

Falls eine Reservierung nicht abgerufen werden kann, sollte ein Problemfall beim Support Team von Kurzurlaub.de gemeldet werden.

Reservierungen abrufen (PULL)

Übersicht der verfügbaren Nachrichten

Diverse offizielle OTA Messages zum Abrufen (PULL) von Buchungen werden von Kurzurlaub.de unterstützt

Um das Ziel einern vollständigen 2-Wege-Integration zwischen dem Buchungskanal Kurzurlaub.de und einem Channelmanager zu erreichen, ist es von Vorteil die PUSH Methode zum Senden der Buchungsgdaten zu verwenden.

Reservierungen senden an OTA-Partner (PUSH)

Wir halten Sie auf dem neuesten Stand!

Wenn der Hotelier eine Buchung erhält, können wir Ihnen einen einfachen Push senden, mit dem Sie neue Buchungsdaten Per Reservierungs-ID anfordern können. Gleiches gilt für Änderungen und Stornierungen. Der Push kann beispielsweise so gebildet werden:

GET your.exampledomain.com/push.php?requestor_id=12345&resid_value=R12345678-1234567-123456&resstatus=new

3 gesendete Parameter: - requestor_id - resid_value - resstatus

Die genaue Zusammensetzung und Bezeichnung der Parameter ist Ihnen überlassen, mögliche Parameter sind z.B. die RequestorID, ResID_Value und ResStatus. Um uns für Ihren Dienst zu autorisieren, können zusätzliche notwendidge Parameter angehängt werden.

Es kann auch XML mit Buchungsdaten gesendet werden, wir bevorzugen es aber, wenn Sie die Buchungsdaten nach dem Push per ResID_Value und Message OTA_HotelResNotifRQ abrufen.

Für weitere Informationen und das Einrichten des PUSH wenden Sie sich direkt an das Connectivity Team.

Buchungen abfragen per GET - REST-API

Jede unterstützte OTA Message kann auch per REST-API mittels GET aufgerufen werden. Aber dies sollte bei Buchungen nur zu Entwicklungs- oder Testzwecken erfolgen

Verwendete allgemeine Parameter:

  • AgentDutyCode (optional, sofern IP WhiteList oder HTTP Basic Auth verwendet wird)
  • HotelCode (mandatory)

Lesen von Buchungen mit ReservationsId

Verwendete Parameter:

  • HotelReservationId (mandatory) eine ReservationsId oder kommagetrennte IDs
  • Id (alternativ zu HotelReservationId)

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&HotelReservationId=2129149

oder kommagetrennte ReservationsId's

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&HotelReservationId=2129149,2129150,2129151

alternativ auch mit Angabe der gesamten ResID_Value (R12345678-A123456-1234 bspw. R2129149-A20540-4) möglich.

Lesen von Buchungen mit Datumsbereich (Datum von/bis)

Verwendete Parameter:

  • DateFrom
  • DateTo

Erwartet wird ein DateFormat oder DateTimeFormat - DateFormat (YYYY-MM-DD) - DateTimeFormat (YYYY-MM-DD(T)HH:MM:SS)

Geliefert werden alle Buchungen in Datumsbereich von/bis (00:00:00 - 23:59:29) oder mit dem konkret angefragten Uhrzeitbereich per DateTimeFormat

Beispiel

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&DateFrom=2022-01-01&DateTo=2022-02-01

oder im DateTimeFormat

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&DateFrom=2022-02-01T15:30:00&DateTo=2022-02-01T16:45:00

Lesen von Buchungen mit Datum ab (PurgeDate)

Verwendeter Parameter:

  • PurgeDate Erwartet wird ein DateFormat (YYYY-MM-DD)

liefert alle Buchungen ab dem angefragten Datum

Beispiel

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&PurgeDate=2022-02-01

Buchungen abfragen per POST

Verwendete allgemeine Parameter:

  • @AgentDutyCode (Agent-ID): (optional)
  • RequestorID@ID (Hotel-ID): (mandatory)

Lesen von Buchungen mit ReservationsId

Verwendeter Parameter:

  • UniqueID@ID (mandatory) eine ReservationsId
<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="2.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
    <!-- send booking for this ReservationId -->
    <UniqueID Type="RES" ID="12345678" />
    <HotelReservations>
        <HotelReservation />
    </HotelReservations>
</OTA_ReadRQ>

Alternativ

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="2.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
    <UniqueID Type="RES" ID="1513695" />
</OTA_ReadRQ>

Lesen von Buchungen mit Datumsbereich (Datum von/bis)

Erwartet wird von den Parametern

  • eine gültige DatumsPeriode (@Start - @End)

  • ein gültiges DatumsFormat oder DateTimeFormat

  • DatumsFormat (YYYY-MM-DD)

  • DateTimeFormat (YYYY-MM-DD(T)HH:MM:SS)

Variante 1 - Verwendete Parameter:

  • SelectionCriteria@Start (mandatory)
  • SelectionCriteria@End (mandatory)

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="3.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
    <ReadRequests>
        <HotelReadRequest HotelCode="4">
            <SelectionCriteria Start="2022-01-01" End="2022-01-30"/>

            <!-- alternative DateTimeFormat
            <SelectionCriteria Start="2022-01-27T11:30:00" End="2022-01-27T11:37:00"/>
            -->
        </HotelReadRequest>
    </ReadRequests>
</OTA_ReadRQ>

Variante 2 - Verwendete Parameter:

  • GlobalReservationReadRequest@Start (mandatory)
  • GlobalReservationReadRequest@End (mandatory)

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="3.0">
<POS>
    <Source AgentDutyCode="1">
        <RequestorID ID="4" Type="4"/>
    </Source>
</POS>
<ReadRequests>
    <HotelReadRequest HotelCode="4"/>   
    <GlobalReservationReadRequest Start="2020-10-01" End="2020-11-30"/>

    <!-- alternative DateTimeFormat
    <GlobalReservationReadRequest Start="2022-01-27T11:30:00" End="2022-01-27T11:31:00"/>
    -->
</ReadRequests>
</OTA_ReadRQ>

Lesen von Buchungen mit Datum ab (PurgeDate)

wird in der Message OTA_ReadRQ für POST Requests nicht angeboten, da es laut OTA Spezifikation nicht vorgesehen ist.

Lesen von neuen Buchungen (PULL)

wenn keine Parameter angegeben werden, liefern wir alle neuen Buchungen, welche noch nie gesendet wurden. Achtung: dies passiert nur genau ein mal!

Verwendete Parameter:

  • keine
<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="2.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
</OTA_ReadRQ>

OTA_HotelResNotifRS - Versionen der Response

Die Ausgabe der Reservierungsdaten erfolgt identisch zum OTA Format und in Form der Standard Message

Hinweis:

Sollten keine Reservierungen für die abgefragten Parameter vorliegen, erhalten sie eine Antwort mit einem <Success/> (es sind also keine Fehler in den gesendet Parametern aufgetreten) und einem leeren <HotelReservations/> Block.

Beispiel: keine Reservierungen vorhanden

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelResNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" EchoToken="5915874940c61a0f496dd31928e85672" PrimaryLangID="de" TimeStamp="2022-02-04T15:48:17+01:00" Target="Production" Version="1.000">
  <Success/>
  <HotelReservations/>
</OTA_HotelResNotifRS>

Fehlermeldungen

Wenn schwere Fehler bspw. in der Authentifizierung auftreten, senden wird diese in einer OTA_ErrorRS Response mit @ErrorCode und @ErrorMessage

Eine Liste gängiger Fehler finden Sie in der Dokumentation der Standard Message OTA_HotelResNotifRQ

und in unseren implementierten OTA ErrorCodes im Bereich Error Handling

Besonderer Hinweis zu Formatfehlern:

Eine besondere Fehlermeldung bezieht sich auf das fehlerhafte Format bei den Parametern DateFrom, DateTo oder bei PurgeDate

Erwartet wird ein DateFormat (YYYY-MM-DD) oder DateTimeFormat (YYYY-MM-DD(T)HH:MM:SS)

Beispiel: ErrorMessage

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ErrorRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" EchoToken="f3de3733d5095b49a5c774b99f467e57" PrimaryLangID="de" TimeStamp="2022-02-04T12:15:46+01:00" Target="Production" Version="1.000" 
    ErrorCode="500" 
    ErrorMessage="InternalError - Internal OTA Error: wrong format for param DateFrom (2022-02-01T15:30:00) or param DateTo (2022-02-01T16:45:0) in GET method ErrorRS (allowed format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)"
/>