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

## About the API

Despegar.com offers an connectivity interface for partners to streamline the process of
sending availability and rates to Despegar.com, and receiving reservations from Despegar.com.

### <a name="api-services"></a>API services
 
The services use [OTA 2013B](http://www.opentravel.org/Specifications/SchemaIndex.aspx?FolderName=2013B) messages. 
Since OTA is a very flexible protocol, we use a subset of the elements proposed 
in order to simplify the integration. The subset comprises those elements Despegar.com supports.

| API Service | OTA Message |
|:-------------------------------------|:-------------|
| [Get Hotel Information](/portal/documentation/get-hotel-info) | [OTA_HotelDescriptiveInfoRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelDescriptiveInfoRQ) |
| [List RoomRates (Room + RatePlan)](/portal/documentation/list-room-rates) | [OTA_HotelAvailGetRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelAvailGetRQ) |
| [Get Availability and Restrictions](/portal/documentation/get-avail-restr) | [OTA_HotelAvailGetRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelAvailGetRQ) |
| [Get Inventory](/portal/documentation/get-inventory) | [OTA_HotelInvCountRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelInvCountRQ) |
| [Update Availability and Restrictions](/portal/documentation/update-avail-restr) | [OTA_HotelAvailNotifRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelAvailNotifRQ) |
| [List Rate Plans](/portal/documentation/list-rate-plans) | [OTA_HotelRatePlanRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelRatePlanRQ) |
| [Get Rates](/portal/documentation/get-rates) | [OTA_HotelRatePlanRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelRatePlanRQ) |
| [Update Rates](/portal/documentation/update-rates) | [OTA_HotelRatePlanNotifRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelRatePlanNotifRQ) |
| [Booking Handling (Pull)](/portal/documentation/booking-handling-pull) | [OTA_ReadRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_ReadRQ) [OTA_NotifReportRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_NotifReportRQ) |
| [Booking Handling (Push)](/portal/documentation/booking-handling-push) | [OTA_HotelResNotifRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelResNotifRQ) [OTA_HotelResModifyNotifRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_HotelResModifyNotifRQ) [OTA_CancelRQ](http://adriatic.pilotfish-net.com/ota-modelviewer/model/index/usages?term=OTA_CancelRQ)|

Another aspect of this simplification is that any one message exchanged will contain information
for one hotel only. For example, when querying for hotel information, you can query one hotel 
per request, i.e., per `OTA_HotelDescriptiveInfoRQ` message. When updating rates, you can 
update rates for one hotel per request, or `OTA_HotelRatePlanNotifRQ` message, and so on.

You must be authorized to access any hotel. See "Access Control" below.

### Technical Details

#### XML

Since the API follows the OTA specification, all messages are XML-formatted.

#### SSL

Due to the sensitivity of the data exposed and manipulated with this API, it will 
be mandatory to have a safe connection. Whether it is Channel Manager or PMS the 
communication with Despegar.com will always be established using a secure 
connection (HTTPS).

#### Synchronous

For the time being, the API is 100% synchronous.

Concurrent updates to allotment/restrictions or rates for the same hotel are not allowed.

#### <a name="access-control"></a>Access Control

To perform authentication and authorization, clients are required to send an 
`Authorization` header with their credentials expressed in the following format.

```http
Authorization: Channel-User api-key="1iclHfzD", username="concierge", password="NcNk3m5i", hotel=482000
```

Where:

`api-key` is the channel manager ID.
> As a channel manager, you will receive your own API-Key after we certify your 
integration.

`username` is the same username used by the hotel in the Despegar.com extranet.

> This is used to identify on behalf of which extranet user your channel manager is
accessing a hotel.

`password` is a password that the hotel created for this connection.

> This password was generated when the user connected their hotel to your 
channel manager.

> Each time a user creates a connection to a channel manager, a unique password is 
generated and given so that the user can transfer it to the channel manager.

> The password is given to the user only once at the time of generation. If the user 
loses this password, they will need to regenerate it.

`hotel` is the ID of the hotel you wish to access.

> Along with a username and a password, the user will also give to the channel 
manager the ID of the hotel those credentials are for.

The extranet offers manuals and video tutorials on how to connect their 
hotels to your channel manager. If a hotel you're already working with asks you 
about integrating with Despegar.com, please instruct them to go to the 
"Channel Connections" module in our extranet and create a connection.
 
* English: Hotel profile → Channel Connections.
* Spanish: Perfil del hotel → Conexiones Channels.
* Portuguese: Perfil do hotel → Conexões Channels.

#### <a name="request-limits"></a>Request Limits

The API currently enforces these limits by default1:

| | Per Second | Per Minute | Per Day |
|------------------------|------------|------------|---------|
| Requests | 5 | 60 | 4000 |
| Operations2 | 500 | 6000 | 400000 |

1. These limits are **per client, per hotel**.
2. A request contains one or more operations.

This is how message cost is calculated:

| Message                      | Requests | Operations                           |
|:-----------------------------|:---------|:-------------------------------------|
| `OTA_HotelDescriptiveInfoRQ` | 1        | 1                                    |
| `OTA_HotelAvailGetRQ`        | 1        | # of `AvailStatusMessage` elements   |
| `OTA_HotelAvailNotifRQ`      | 1        | # of `AvailStatusMessage` elements   |
| `OTA_HotelInvCountRQ`        | 1        | # of `HotelInvCountRequest` elements |
| `OTA_HotelRatePlanRQ`        | 1        | # of `RatePlan` elements             |
| `OTA_HotelRatePlanNotifRQ`   | 1        | # of `RatePlan` elements             |
| `OTA_ReadRQ`                 | 1        | 1                                    |

The following message has a cost of 1 request and 2 operations:

```xml
<OTA_HotelAvailNotifRQ xmlns="http://www.despegar.com/hotels/ota/v1/" Version="1.0">
 <AvailStatusMessages HotelCode="282445">
 <AvailStatusMessage BookingLimit="10" BookingLimitMessageType="SetLimit">
 <StatusApplicationControl Start="2020-01-01" End="2020-01-02" InvCode="74959" />
 </AvailStatusMessage>
 <AvailStatusMessage>
 <StatusApplicationControl Start="2020-01-01" End="2020-01-02" RatePlanCode="27" InvCode="74959" />
 <LengthsOfStay>
 <LengthOfStay Time="3" TimeUnit="Day" MinMaxMessageType="MinLOS" />
 <LengthOfStay Time="60" TimeUnit="Day" MinMaxMessageType="MaxLOS" />
 </LengthsOfStay>
 <RestrictionStatus Restriction="Arrival" Status="Close" />
 </AvailStatusMessage>
 </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>
```

A typical `HTTP 429` response looks like this:

```xml
<OTA_HotelRatePlanRS xmlns="http://www.despegar.com/hotels/ota/v1/" Version="v1" CorrelationID="123">
 <Errors>
 <Error Type="7" Code="E40003" NodeList="">Request exceeds limits: 5 request/s per 1 second. This means the channel manager is using the API OF DESPEGAR.COM in a bad way. Please contact them to improve their connection and let you update the information in our System.</Error>
 </Errors>
</OTA_HotelRatePlanRS>
```

We monitor API traffic to detect when a client starts getting `HTTP 429` responses. 
When that happens, we reach out to the channel manager to let them know and 
investigate the issue.

Most frequently, these errors signal a bad use of the API.

___

### Ready to Start Integrating?

Begin [Integrating with the API](/portal/documentation/integrating).