Zum Inhalt

OTA_HotelRateAmountNotifRQ

Methode zum Senden von Preisen auf Zimmer-/Angebotsebene (RoomType/RatePlan Kombination) an Kurzurlaub.de.

Wir beschreiben den OTA_HotelRateAmountNotifRQ Request (RQ) und Response (RS) am Beispiel des Testhotels. Das Senden der Daten erfolgt immer per POST Request.

OTA_HotelRateAmountNotifRQ - Anfrage per POST

Endpunkt für POST Request:

POST /ota/api/HotelRateAmountNotif

Verwendete Parameter

Parameter für Authentifizierung und Hotel:

  • @AgentDutyCode - Agent-ID: (optionale Angabe - Testagent = 1)
  • RequestorID@ID - Hotel-ID: (TestHotel = 4)
  • RateAmountMessages@HotelCode - Hotel-ID / HotelCode: (TestHotel 4)

Parameter für Zeitraum, Zimmer und Rate:

Erwartet wird eine Zimmer-ID + Angebot und ein Zeitraum (Datum von/bis) als RateAmountMessage

  • @Start - Datum (DateFormat YYYY-MM-DD)
  • @End - Datum (DateFormat YYYY-MM-DD)
  • @InvTypeCode - Zimmer-ID oder alternativ auch @InvCode möglich
  • @RatePlanCode - Angebots-ID / Code oder alternativ auch @RatePlanID möglich

Beispiele: 

<StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-12-24" End="2023-12-31"/>
<StatusApplicationControl InvTypeCode="9143" RatePlanCode="TEST-BAR" Start="2023-12-24" End="2023-12-31"/>
<StatusApplicationControl InvCode="9143" RatePlanID="20540" Start="2023-12-24" End="2023-12-31"/>

Parameter für Preise:

  • @AmountAfterTax - Preis (Wert >= 0)
  • @NumberOfGuests - Anzahl der Gäste im Zimmer (Wert > 0) bspw. 1 Person im Einzelzimmer, 2 Personen im Doppelzimmer
  • @AgeQualifyingCode - Preis für Erwachsene Personen oder Kinder
    • Preis für Erwachsene Personen im Zimmer AgeQualifyingCode="10"
    • Preis für Kinder AgeQualifyingCode="8" (wird momentan noch ignoriert)

Beispiel:

<BaseByGuestAmts>
    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="155.99" />
    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="125.99" />
    <BaseByGuestAmt AgeQualifyingCode="8" AmountAfterTax="15.99" />
</BaseByGuestAmts>

Hinweis: soweit die Anzahl der Personen im Zimmer nicht dem NumberOfGuests Attribut entspricht, wird der Preis ignoriert. Im Doppelzimmer (Belegung mit 2 Personen) wird also nur der Preise NumberOfGuests="2" beachtet, eine Einzelbelegung mit anderem Preis ist so nicht möglich.

Alternative Parameter:

  • @RatePlanCode - String für Angebots-Code (RatePlanCode="TEST-BAR" oder ID RatePlanCode="20540")
  • @RatePlanID - Integer für Angebots-ID (RatePlanID ="20540")

Durch Verwendung der Parameter @RatePlanCode oder @RatePlanID werden die Preise auf Zimmer- und Angebotsebene in Kombination verarbeitet.

Als @RatePlanCode kann entweder ein String (BEST-BAR) oder alternativ auch eine Angebots-ID (Integer Wert) gesendet werden. Der Raten-Code kann im Kurzurlaub.de Backend der Hoteliers je Angebot hinterlegt werden, um Angebote und Raten im OTA Backend oder Hotel Software besser und übersichtlicher zu mappen.

Hinweis:

  • wir ignorieren momentan diverse BookingRules (bspw. LengthOfStay, CloseToArrival CTA, CloseToDeparture CTD, Close)

Validierung eingehender Daten

Validierung der eingehenden Parameter für Datumsbereich (Datum von/bis):

  • eine gültige DatumsPeriode (@Start - @End)
  • ein gültiges DatumsFormat (YYYY-MM-DD)
  • nicht in der Vergangenheit
  • nicht mehr als 2 Jahre im Vorraus
  • nicht mehr als 3 Monate als zusammenhängender Zeitraum

Validierung sonstiger Parameter:

  • nicht mehr als 4000 Zeilen pro Anfrage
  • Preis - als float >= 0 (AmountAfterTax="125.90" oder AmountAfterTax="12590" DecimalPlaces="2")
  • Zimmer-ID gültig und Zimmer ist online / aktiv
  • Zimmer-ID und Angebots-ID in Kombination gültig und Angebot ist online / aktiv

Hinweis:

Die vom OTA-Partner gesendeten Daten werden nur für Zimmer akzeptiert, die *aktiv und online* sind, alternativ werden Warnungen als Antwort gesendet.

Generell werden Zeilen mit RateAmountMessage einzeln betrachtet, d.h. ein Fehler im InvTypeCode oder im Datumsformat, Datumsbreich wird nur für diese eine Zeile als Warnung gesendet. Alle weiteren Zeilen werden unabhängig davon bearbeitet.

Jede Nachricht enthält bspw. ein StatusApplicationControl-Element für ein Zimmer/Angebot eines Hotels (RequestorID@ID).

Beispiel für Anfrage

Beispiel OTA_HotelRateAmountNotifRQ Request zum Senden von Preise auf Zimmer- und Angebotsebene mit verwendeten Attributen @RatePlanID oder @RatePlanCode

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" TimeStamp="2022-12-01T09:30:47+08:00" Version="1.0" EchoToken="abc123">
<RateAmountMessages HotelCode="4">
    <!-- Invalid RatePlanCode (TEST-BAR) or InvTypeCode (2625) not allowed within this rate-->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="2625" RatePlanCode="TEST-BARS" Start="2022-12-26" End="2022-12-27"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="155.99" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="125.99" />
                    <BaseByGuestAmt AgeQualifyingCode="8" AmountAfterTax="15.99" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <!-- Error: Invalid start date (2022-12-18) is in past -->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-05-18" End="2023-05-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>   
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="3895" DecimalPlaces="2" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="4995" DecimalPlaces="2" />
                    <BaseByGuestAmt NumberOfGuests="3" AgeQualifyingCode="10" AmountAfterTax="5995" DecimalPlaces="2" />
                </BaseByGuestAmts>
                <AdditionalGuestAmounts>
                    <AdditionalGuestAmount Amount="1000" DecimalPlaces="2" />
                </AdditionalGuestAmounts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <!-- Doppelzimmer - NumberOfGuests="2" -->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="431721" Start="2023-05-18" End="2023-05-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="5996" DecimalPlaces="2" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <!-- Einzelzimmer - NumberOfGuests=1  -->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="5307" RatePlanCode="431721" Start="2023-05-16" End="2023-05-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="4450" DecimalPlaces="2" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>

    <!-- Invalid RatePlanCode (TEST-BAR) or InvTypeCode (2625) not allowed within this rate-->
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="2625" RatePlanCode="TEST-BAR" Start="2022-12-16" End="2022-12-17"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt AgeQualifyingCode="10" AmountAfterTax="125.50"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="TEST-BAR" Start="2022-12-28" End="2022-12-29"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt AgeQualifyingCode="10" AmountAfterTax="135.00"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvCode="9143" RatePlanID="20540" Start="2022-12-20" End="2022-12-21"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <!-- ohne Komma - mit Dezimalstellen -->
                    <BaseByGuestAmt AmountAfterTax="3800" DecimalPlaces="2" NumberOfGuests="3" CurrencyCode="EUR"/>
                    <BaseByGuestAmt AmountAfterTax="3800" DecimalPlaces="2" NumberOfGuests="1" CurrencyCode="EUR"/>
                    <BaseByGuestAmt AmountAfterTax="4500" DecimalPlaces="2" CurrencyCode="EUR"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-01-29" End="2023-01-31"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <!-- todo use DecimalPlaces 14995 -> 149.95 we save only the 149 -->
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="13698" DecimalPlaces="2" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="14698" DecimalPlaces="2" />
                </BaseByGuestAmts>
                <AdditionalGuestAmounts>
                    <AdditionalGuestAmount Amount="1000" DecimalPlaces="2" />
                </AdditionalGuestAmounts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-01-26" End="2023-01-28"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="139.95" />
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="149.95" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="9143" RatePlanCode="20540" Start="2023-10-10" End="2023-10-12"/>
        <Rates>
            <Rate>
                <BaseByGuestAmts>
                    <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="249.95" />
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>

OTA_HotelRateAmountNotifRS - Versionen der Response

Normalerweise wird ein <Success/> als Antwort gesendet oder entsprechende Fehlermeldungen und / oder Warnungen

Beispiel OTA_HotelRateAmountNotifRS Response

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       EchoToken="b1e1a4a5cf11520d81fc9edbe781ba12" PrimaryLangID="de"
                       TimeStamp="2022-03-08T16:34:10+01:00" Target="Production" Version="2.01">
    <Success/>
</OTA_HotelRateAmountNotifRS>

Warnungen

Jede gesendete Zeile mit Preisen wird einzeln betrachtet und verarbeitet, daher werden Fehler in der Validierung von Parametern nur für diese eine Zeile als Warnung gesendet. (Siehe auch Liste gängiger Fehlermeldungen)

Alle weiteren Zeilen werden unabhängig davon bearbeitet.

Für jede Warnung werden die benutzten Attribute zur Kontrolle mit ausgegeben.

Sofern Warnungen vorhanden sind, wird die Anzahl der erfolgreich verarbeiteten Zeilen am Ende als separater Hinweis mit gesendet. bspw.

1 of 3 incoming RateAmountMessage processed. See warnings before

Beispiel OTA_HotelAvailNotifRS Response mit Warnungen

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          EchoToken="fa9c12edfe5baba3b98deac1138ed5b2" PrimaryLangID="de"
                          TimeStamp="2022-03-08T15:48:27+01:00" Target="Production" Version="2.01">
    <Warnings>
        <Warning Code="448" Type="1">AmountAfterTax (155.99) ignored (NumberOfGuests 1 vs AdultsPerRoom 4)</Warning>
        <Warning Code="448" Type="1">AmountAfterTax (15.99) ignored (AgeQualifyingCode 8 is not 10)</Warning>
        <Warning Code="321" Type="1">RateAmountMessage cannot processed (amountAfterTax is null) - used attributes
            (AmountAfterTax: n/a, Start: 2022-12-26, End: 2022-12-27, InvTypeCode: 2625, RatePlanCode: TEST-BARS,
            RatePlanID: 0)
            </Warning>
        <Warning Code="404" Type="1">Invalid start date (2023-05-18) is in past</Warning>
    </Warnings>
</OTA_HotelAvailNotifRS>

Fehlermeldungen

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

Beispiel

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            EchoToken="283857aab0941e378f826b8eb96bbab1" PrimaryLangID="de"
                            TimeStamp="2023-06-08T14:39:03+02:00" Target="Production" Version="2.01">
    <Errors>
        <Error Code="448" Type="12">RateAmountMessages arttribute HotelCode (44) does not match request HotelCode (4)
        </Error>
    </Errors>
</OTA_HotelRateAmountNotifRS>

Sofern alle gesendeten Preise für das Hotel nicht verarbeitet werden können, bspw. aufgrund falscher Daten, erhalten Sie eine besondere Fehlermeldung:

No valid RateAmountMessage found (0 of 11 incoming)

Wenden Sie sich dann an das Service oder Connectivity Team.

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            EchoToken="4ce1635ec9ac0944aacb17d0ea86a9ea" PrimaryLangID="de"
                            TimeStamp="2023-06-08T14:40:31+02:00" Target="Production" Version="2.01">

    <Errors>
        <Error Code="450" Type="10">Error during processing RateAmountMessages. No valid RateAmountMessage found (0 of
            11 incoming)
        </Error>
    </Errors>
</OTA_HotelRateAmountNotifRS>

Liste der FehlerCodes

Hier eine Liste gängiger Fehlermeldungen beim Senden von Preisen

ErrorCode ErrorMessage
101 RateAmountMessages not found (empty or not well formed XML payload)
111 Method not allowed for hotel - hotel must support RateAmountMessages for dynamic prices
210 HotelNotLinked - Hotel linked to another channel manager
211 HotelNotActivated - Hotel not found
104 InternalError - Empty HotelCode (HotelId) in accepted params (agentdutycode, hotelcode, ...)
220 RoomMappingError - Hotel does not have rooms created or configured
221 RoomMappingError - Hotel does not have rates created or configured
230 RoomMappingError - Invalid room code
231 RoomMappingError - Invalid room quantity
232 RoomMappingError - Invalid rate code (bei Room/Rate Kombinationen)
240 DateRangeError - Invalid date range
500 AmountAfterTax ignored (NumberOfGuests 1 vs AdultsPerRoom 2)
500 Error during processing RateAmountMessages. Maybe some attribute is null
500 too many lines (max. 4.000 lines) of RateAmountMessages

Beispiel OTA_ErrorRS Response mit Fehler

<?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="968209e6b51ffeba7b2953801c4c8fce" PrimaryLangID="de" TimeStamp="2022-03-08T15:57:43+01:00"
             Target="Production" Version="1.000" 
             ErrorCode="211"
             ErrorMessage="HotelNotActivated - Hotel not found (HotelCode 1234 / AgentDutyCode 1)"/>

Beispiel ** OTA_HotelRateAmountNotifRS** Response mit Fehler

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" 
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                       EchoToken="08b99bdc46a0ee67b620ecf88a1f30ac" PrimaryLangID="de" 
                       TimeStamp="2022-03-09T10:46:12+01:00" Target="Production" Version="2.01">
    <Errors>
        <Error Code="500" Type="1">StatusApplicationControl (InvCode="5306" Start="2022-10-01" End="2022-10-03") cannot
            processed. some attribute is null
        </Error>
    </Errors>
</OTA_HotelRateAmountNotifRS>