Despegar.com - Hotels, flights, packages, cars, and more!

## Booking Handling (Push)

### Goals

To be able to receive reservation events as they happen in Despegar.com.

### <a name="notes"></a>Notes

#### Endpoint

This API requires your channel system to be registered with a reservation push URL. The API 
will send new, modified, or canceled reservations as they happen in our system or records.

The API needs to know which reservations to send, and retry. These are the steps for working with this API:

* Hoteliers connect their hotels with your channel system.
  * The API will notify your channel system of any reservation events for those hotels.
  * Your channel system acknowledges each event by responding with a `HTTP 200` status code. No 
    `OTA_NotifReportRQ` should be sent when working with this API.
  * If an acknowledged reservation is modified or canceled later in our system or records, it will be sent to your
    channel system again immediately.

#### Recovering missed reservations

Notice that if **for any reason**, the endpoint we are pushing the reservations to:
 - is down 
 - is temporarilly unreachable
 - is responding `HTTP 5XX` due to some unexpected system malfunction
 
 then the pushes will be retried later and you'll get the reservations anyway.

This way you don't have to worry for spurious network failures or if your system experiences downtime (previously scheduled or not) or is failing and responding `HTTP 5XX` for any reason.
If we receive any http status code in the response different than `HTTP 2XX`, then our system will eventually retry. 
Retries will fire within the minute at first. Later, if several failures occur, the time elapsed between retries will reach about 30 minutes.

Take into account that if we get a `HTTP 2XX` then there will be no further retries or re-sends from our system. 
If for any reason whatsoever you sent a `HTTP 2XX` and later you need to get the reservation again you will have to fetch it with the other resource in our API: 
[BookingHandling (Pull)](/portal/documentation/booking-handling-pull#pulling-strategies), always using the `SelectionType=All` and setting the desired filters accordingly. 
You'll probably want to filter by `DateType="LastUpdateDate"`

**The BookingHandling (Push) method and the BookingHandling (Pull) method with SelectionType=Undelivered are NOT compatible.**

#### <a name="AvailabilityAdjust"></a>Availability adjustments upon perceiving reservations

When you detect a new reservation in despegar.com either by the [pull](/portal/documentation/booking-handling-pull) or [push](/portal/documentation/booking-handling-push) method, you'll want to adjust the availability in the hotel inventory in other OTAs. In order to do this correctly and preserve the consistency of the inventory there are certain things you'll have to consider.

In this context an important factor is that despegar.com sometimes makes private contracts with some hotels arranging for a fraction of the inventory to be sold by despegar.com exclusively. 
This part of the inventory which is private is handled in our extranet only and is not exposed in our [GetInventory](/portal/documentation/get-inventory) service. 
You don't have to take into account this availability when you update the inventory using the [UpdateAvailability](/portal/documentation/update-avail-restr) service either. However, when you receive a reservation you'll have to check which part of the inventory it has impacted on.
After perceiving a reservation from despegar.com (either by [pull](/portal/documentation/booking-handling-pull) or [push](/portal/documentation/booking-handling-push)) you'll have to check which part of the inventory that reservation belongs to so you can decide if:
 
a) you need to subtract availability from that hotel's public inventory, and probably impact that in other OTAs
 
b) the reservation belongs to despegar.com's private inventory, and no action is called for regarding the public inventory shared with other OTAs

An important consideration over this form of integration is that in order to present a better service to our clients, the hotels, we think that we should always report all the reservations whether they belong to the public or private inventory. That's why we need to make a subtle distinction between the possible need for inventory re-adjustment and the plain fact of a new reservation being booked for the hotel. Because of this we do not consider an option to stop sending reservations belonging to despegar.com's private inventory.

In despegar.com some Reservations may be sold comprising different RoomRates for each of the nights in the stay, each of which may belong to different kinds of inventory. This results on the flag indicating the kind of inventory used for the Reservation being placed at a RoomRate level instead of on a higher level.

This indicator can take the values **PRIVATE** or **PUBLIC**. 
The value **PRIVATE** indicates that the corresponding RoomRate (along with its reservation nights) belongs to despegar.com's exclusive inventory.
The value **PUBLIC** indicates that the corresponding RoomRate (along with its reservation nights) belongs to the public inventory shared with other OTAs.
You'll find this in the inventory block code (InvBlockCode) attribute of the RoomRate:

HotelReservation / RoomStays / RoomStay / RoomRates / RoomRate / InvBlockCode

see further detail [here](/portal/documentation/booking-data-structures##RoomRateType)

#### SSL

Your reservation push URL must be HTTPS, and the certificate be issued by a known Certificate 
Authority. The API will validate the organization name (`O=` attribute) in each push, so 
the SSL certificate must be OV or EV (DV is not valid). More information [here](https://www.ssl.com/article/dv-ov-and-ev-certificates).

#### Messages

Depending on the event, you will receive a different message.

| Your endpoint will receive an...               | When...          |
|:----------------------------------------------|:-----------------|
| [OTA_HotelResNotifRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelResNotifRQ) | A new reservation is booked. |
| [OTA_HotelResModifyNotifRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelResModifyNotifRQ) | A reservation is updated. |
| [OTA_CancelRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_CancelRQ) | A reservation is canceled. |

Please see the [examples](/portal/example/push).

#### Source IP Addresses

You will need to add the following Despegar.com IP address pools to your whitelist:

* `192.169.5.251/32`
* `64.76.243.251/32`
* `38.88.164.82/32`
* `4.71.210.146/32`
* `34.202.179.220/32`

#### Credit Cards

The same definition of credit card as in the [Pull API](/portal/documentation/booking-handling-pull#credit-cards)
applies here, except **complete guest credit cards details** will be sent by this API.  
 
### Message Detail

#### Output: OTA_HotelResNotifRQ

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_HotelResNotifRQ                           |    1   | Root element |
| @Version										| 	 1	 | Service version |
| HotelReservations / HotelReservation          |    1   | See [HotelReservationType] |

#### Output: OTA_HotelResModifyNotifRQ

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_HotelResModifyNotifRQ                     |    1   | Root element |
| @Version										| 	 1	 | Service version |
| HotelResModifies / HotelResModify             |    1   | See [HotelResModifyType] |

#### Output: OTA_CancelRQ

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_CancelRQ                                  |    1   | Root element |
| @Version										| 	 1	 | Service version |
| UniqueID                                      |    2   | Hotel and reservation IDs |
| UniqueID / @Type                              |    1   | The type of ID. Refer to OpenTravel [Unique Id Type (UIT)](http://adriatic.pilotfish-net.com/ota-modelviewer/model/codelists/ota?term=UIT) code table. The API will issue two IDs with the following two types:<ul><li>"10": Hotel</li><li>"14": Reservation</li></ul> |
| UniqueID / @ID                                |    1   | The actual ID value |

[HotelReservationType]: </portal/documentation/booking-data-structures#HotelReservationType>
  [HotelResModifyType]: </portal/documentation/booking-data-structures#HotelResModifyType>