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

## Booking Handling (Pull)

**GET URL**: ```/v1/hotels/reservations/get```

**NOTIF URL**: ```/v1/hotels/reservations/notif``` (only applicable when querying for "Undelivered")

### Goals

To be able to pull new, modified, or canceled bookings in Despegar.

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

#### Pulling Strategies

There are two different methods for pulling reservations:

* Querying by date or status criteria.
  
  In this case, you indicate whether you wish to retrieve reservations based upon their dates or status. 
  You set `@SelectionType` to "All" and also set `@DateType` and/or `@ResStatus`.
   
  A common way to keep your system synchronized using this method is to periodically query by reservation 
  last-update date, e.g., Query every 1 hour for reservations with a last-update date within `now - 1 hour` and `now`.

* Querying by delivery status criterion.
   
  In this method you select to retrieve reservation the API knows your system does not know about.
  You set `@SelectionType` to "Undelivered" and omit `@DateType` and `@ResStatus`.
  
  For the API to be able to determine which reservations should be sent, the channel system must 
  acknowledge every reservation it gets using `OTA_NotifReportRQ`.
  
  The flow of information in this method can be expressed in these steps:
  
  * Hoteliers connect their hotels with your channel system. 
  * The API will start recording events for those hotels.
  * Your channel system will fire its first request for undelivered reservations.
  * The API will send those reservations that were, in one way or another, updated in our system 
    of records during the time the hotel was connected and the time the channel requested for 
    reservations. The channel may resend the same request and the API will respond with the same or a
    bigger set of reservations since those reservations were not acknowledged yet.
  * The channel system acknowledges all reservations using `OTA_NotifReportRQ`.
  * If an acknowledged reservation is modified later in our system or records, the acknowledgment 
    will be cleared and the reservation will be sent again in a subsequent request.

#### Pagination

This API mandates pagination. A response will include a `@MoreIndicator` attribute set to "true" to 
indicate there are more records for this result, also a `@MoreDataEchoToken` attribute will
contain an offset to be sent in a subsequent request to retrieve the next page of results.

The page size can be set via the `@MaxResponses` attribute, but it has a maximum value 
so you will have to always check the attributes above and retrieve reservation by pages.

**Don't forget to check these attributes when querying**. You may be missing reservations otherwise.

#### <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)

#### Reservation Payment Types

There are two types of reservation payments: _Pay at destination_ and _prepay_. The type is signalled by the presence of one of two, mutually exclusive elements: `Guarantee` and `DepositPayments`, respectively.

For _pay at destination_ reservations:
    
* The `Guarantee` / `@GuaranteeType` attribute will be set to:
  * `"CC/DC/Voucher"` for reservations including a guest credit card as guarantee. A `PaymentCard` element will contain the details.
  * `"None"` for cash reservations. No extra information will be provided.

For _prepay_ reservations:

* The `DepositPayments` / `GuaranteePayment` / `@GuaranteeType` attribute will be set to `"PrePay"`.
* The `DepositPayments` / `AcceptedPayments` / `AcceptedPayment` / `@GuaranteeTypeCode` attribute will indicate how the hotel collects their rate:
  * `"43"` for virtual credit card. A `PaymentCard` element will contain the details.
  * `"28"` for wire transfer. A `BankAcct` element will indicate the bank account type.

#### <a name="credit-cards"></a>Credit Cards

**Complete guest credit card details are only available via [reservation push](/portal/documentation/booking-handling-push)**.

For reservations queried with this API, guest credit card details are **masked** and for reference only.

Virtual credit cards are issued by Despegar.com for the hotel to collect their rates and
always appear in complete and plain form.

The `PaymentCard` element, regardless of the card type, can itself be absent for a number of reasons:

* The reservation could be cash, paid at destination, as mentioned in the previous section.
  * The credit card could have been invalidated due to fraud prevention.
  * The reservation is prepaid, but the hotel has selected wire transfer as hotel payment method, as mentioned in the previous section. 
  * The reservation is prepaid, but the virtual credit card has not been generated yet. In this case, as soon as the virtual credit card becomes available, the reservation will be updated to include the new details.

In addition, the following cases will include a `Warning` element indicating a missing card:

* Pay at destination reservation for which the guest credit card could not be retrieved.
  * Prepay reservation for which the virtual credit card could not be retrieved.
  
Despegar supports the following list of credit cards type:

| Code     | Name                 |
|:---------|:---------------------|
| AX       | American Express     |
| CA       | MasterCard           |
| CB       | Carte Blanche        |
| CD       | Codensa              |
| CL       | Cabal                |
| CM       | Argencard            |
| CS       | Cencosud             |
| CS       | Tarjeta Cencosud     |
| DC       | Diners Club          |
| DS       | Discover             |
| EC       | Elo                  |
| HC       | Hipercard            |
| MD       | MasterCard Débito    |
| MG       | Magna                |
| NT       | Nativa               |
| NV       | Tarjeta Nevada       |
| OC       | OCACard              |
| OH       | OH                   |
| PR       | Presto               |
| RI       | Ripley               |
| SHO      | Tarjeta shopping     |
| TN       | Tarjeta Naranja      |
| VD       | Visa Débito          |
| VI       | Visa                 |

#### Querying by ID

This API supports querying by reservation ID. This is primarily meant for debugging purposes. See "By id" in
[examples](/portal/examples/booking-handling-pull).

### Message Detail

#### Input: OTA_ReadRQ

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_ReadRQ									| 	1	 | Root element |
| @Version										| 	1	 | Service version |
| @MaxResponses                                 |  0..1  | Result page size. Defaults to 50, which is currently the maximum value allow. |
| @MoreDataEchoToken                            |  0..1  | Used to repeat a previous request to retrieve paginated results |               
| OTA_ReadRQ / ReadRequests						| 	1	 | |
| ReadRequests / HotelReadRequest				| 	1	 | |
| @HotelCode									| 	1	 | Hotel code. It's mandatory. |
| HotelReadRequest / SelectionCriteria 			| 	1 	 | |
| @DateType 									|  0..1  | Specifies the type of date expected in the attributes dates (start and end). Possible values: <ul><li> "ArrivalDate" (Booking check in) </li><li> "CreateDate" (Booking creation date) </li><li> "DepartureDate" (Booking check-out date) </li><li> "LastUpdateDate" (Booking last modified date) </li></ul>|
| @Start 										|  0..1  | DateOrTimeOrDateTimeType. The start value of the time interval. |
| @End 										    |  0..1  | DateOrTimeOrDateTimeType. The end value of the time interval. |
| @SelectionType 								|  0..1  | Indicates that the bookings must be selected according to the delivery status. Possible values: <ul><li> "All": All reservations</li><li> "Undelivered": Undelivered reservations</li> </ul>|
| @ResStatus									|  0..1  | Indicates the booking status. The values allowed are: <ul><li> "Book": booked. </li><li> "Modify" : modified. </li><li> "Cancel".: canceled.</li></ul>  If it is omitted all will be returned |

#### Output: OTA_ResRetrieveRS

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_ResRetrieveRS 							|	1	 | First element (root element) |
| ReservationsList / HotelReservation			|  1..n  | See [HotelReservationType] |
| OTA_ResRetrieveRS / Success 					|  0..1  | It is present if the request has been processed successfully. The error node is not present if this node appears. |
| OTA_ResRetrieveRS / Errors					|  0..1  | Contains an error list in case the request was not processed correctly. |
| Errors / Error 								|  1..n  | If there is an error node then there has to exist at least one error node. |
| @Version  			   						| 	1	 | Service version |
| @Type 										|	1	 | Error type |
| @Code 										|  0..1  | Error code |
| @MoreIndicator                                |  0..1  | Indicates if there are more records in this result |
| @MoreDataEchoToken                            |  0..1  | Indicates the offset is must be used in a subsequent request to retrieve the next page of results |

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