Home
Developer Guide
Introduction
About the API
Integrating with the API
FAQ
Get Hotel Information
Information
Examples
List RoomRates (Room + RatePlan)
Information
Examples
Get Availability and Restrictions
Information
Examples
Get Inventory
Information
Examples
Update Availability and Restrictions
Information
Examples
List Rate Plans
Information
Examples
Get Rates
Information
Examples
Update Rates
Information
Examples
Booking Handling (Pull)
Information
Examples
Booking Handling (Push)
Information
Examples
Reference Tables
Warning Validation Codes
Error Validation Codes
Booking Data Structures
## Integrating with the API ### Sending Data There are [several messages][api-services] at your disposal to query and update the data at Despegar.com. Each message has its own documentation page plus examples, and for some messages, there's also a warning/error codes page. ← You can access all documentation pages through the links at the left. #### The First Test Message Let's try the API by sending a test message. We'll use the [Get Hotel Information] API to discover general information like name and rooms about hotel
${hotel-id}
. First, you need to make note of the development credentials that have been generated for you at the [home page] and create your [authorization expression][access-control]. You should get something like this: ```http Channel-User api-key="${api-key}", username="${username}", password="${password}", hotel="${hotel-id}" ``` Then, you can send your first message using [curl] or any other HTTP test tool you prefer. ```bash curl -iX POST ${environment-dev}hotel-info/get \ -H 'Content-Type: application/xml' \ -H 'Authorization: Channel-User api-key="${api-key}", username="${username}", password="${password}", hotel="${hotel-id}"' \ -d '
' ``` Notice the URL. This is the sandbox environment where you can play freely. Below you will find more details about this environment. Remember that each service has its own examples page. All examples can be run from the browser directly, except reservation pushes. #### Hotel Outlook For an overview of the hotel, you need the [Get Hotel Information] API. From this message you will get: * The hotel name. * Hotel room names and IDs. * Occupancy bounds. * Whether hotel rates include taxes or not. > **This one is particularly important**. The [Get Rates] and [Update Rates] APIs use different attributes to emphasize the selection between the two models. * The hotel commission policy. * The default maximum length-of-stay policy. * Supported meal-plans. ####
PAR
Discovery This is a quick rundown of which messages to use to gather PAR information about a hotel: 1. Use [List Rate Plans] to retrieve all rate plans created for a hotel, including: * Rate plan names and IDs. * Currency. * Charge type. > **This one is important**. The [Get Rates] and [Update Rates] APIs expect you to state the exact same charge type code you get here. * If the rate plan is a **child** rate plan: * The rate adjustment. * Linked restrictions (restrictions inherited from the parent rate plan). > This is the only place so far where the Despegar.com API deviates from OTA since there is no concept of inherited restrictions in the OTA specification. 1. Use [List RoomRates (Room + RatePlan)] to get room and rate plan assignments. 1. Use [Get Availability and Restrictions] to retrieve: * Flexible allotment. > See the [meaning][booking-limit-meaning] of the `@BookingLimit` attribute. * Restrictions. > See the [interpretation][cta-ctd-stop-sell-interpretation] of
CTA
/
CTD
/ Stop-Sell. 1. Use [Get Inventory] to retrieve: * Flexible allotment. * Contract allotment (also known as guaranteed allotment). * Booking count. > You need the flexible allotment and the booking count to calculate `@BookingLimit` when updating allotment. 1. Use [Get Rates] to retrieve the current rates for a hotel. After following all these steps, you should have all the information you need to show the user the current state of the hotel in Despegar.com. The next step after this is to [Update Availability and Restrictions] or [Update Rates]. #### Getting Reservations Despegar.com supports two reservation transfer methods: [Pull][Booking Handling (Pull)] and [Push][Booking Handling (Push)]. The Pull API allows you to query for reservation by several criteria, being "last update date" the most common. This API is the easiest to integrate with albeit it has its [limitations][booking-pull-credit-cards]. The Push API works in the opposite direction, as it will reach out to an endpoint provided by you to send you updates about relevant reservations. See the [notes][booking-push-notes] about integrating with this API. ### Processing Results After any call, the response will include either a `Success` or an `Errors` element. The presence of `Errors` means the message was rejected entirely and may not be retried until the cause is determined and corrected. The `Success` element may also include `Warnings`, which indicate the message was partially processed. The warnings should be analyzed since, in most cases, reflect situations that may not be retried like an invalid room or rate plan code. The only exception to this rule is the response of a reservation push. In this case, the API will simply expect your endpoint to return a 200 HTTP status code. Any payload content is ignored, and any other status code will mark the event to be retried later. ### Sandbox As mentioned before, your development credentials were created to give you access to the sandbox environment where you can test your integration as needed. The stub environment (at
${environment-dev}
) has the same validations we enforce in production, and we offer a variety of examples trying to show all the different situations you may face while coding. What is not currently possible is to alter the information, so even if you receive a `Success` response you will not see any changes in the hotel. We have set up two hotels that you can use with two rooms in order to explore and test against all the possible scenarios we support. The stub environment will behave differently depending upon the hotel / room / date being accessed. The behavior is summarized in the following table: | Service | January | Febrary | March | July | |:--------------------------|:---------------:|:-----------:|:-----------:|:-----------:| | **Get restrictions** | -- | Empty data | stop-sell | Timeout | | **Get stop-sell** | -- | Empty data | -- | Timeout | | **Get allotment** | No availability | Empty data | -- | Timeout | | **Update allotment** | -- | -- | -- | Timeout | | **Get rates per room** | -- | Empty data | -- | Timeout | | **Get rates per person** | -- | Empty data | -- | Timeout | | **Update rates** | -- | -- | -- | Timeout | 1. For other months the response contains information. 1. If you want a response for a missing room, try with room ID `1`. Regarding reservations, the stub environment has two reservations: * Hotel `638049` → Reservation ID `1`. * Hotel `282445` → Reservation ID `2`. ### Preventing `HTTP 429` Errors Even though the sandbox environment is unrestricted, the certification and production environments restrict the number of requests / operations that you can perform. These restrictions are tolerant enough to allow for all the operations you would normally need for a hotel, but if you don't follow certain steps, your may see your traffic being limited. Shaping the traffic within API limits is your responsibility. To avoid getting `HTTP 429` errors, please follow these guidelines: 1. Send as much information as possible in a single message. The limits affect primarily the number of HTTP requests you can send. 1. Avoid unnecessary updates. Blindly re-syncing data will get your quota exhausted. 1. Don't ignore errors or warnings. Only `HTTP 500` responses and `HTTP 429` responses can be retried, eventually. Any other `HTTP 200` or `HTTP 400` response, including an `Errors` or `Warnings` element may not be retried. If you just keep on retrying these cases, you will get your quota exhausted. 1. Pay attention if your system re-syncs information too often, or too much at a time. If you re-sync an entire year every time a user makes a minor change, you will get your quota exhausted. **This is particularly important for PMS or other revenue management tools, or if any of those piggyback on your channel manager**. 1. Come up with an initial load strategy. In some cases, the channel manager doesn't care about allotment or rates loaded in Despegar.com since the channel manager always pushes this information from its own database. If this is your case, you will want to send all the data you have for a hotel at the moment the user enables the connection between your channel and Despegar.com. We expect you to shape the traffic so that you can completely sync the information to us without affecting normal operations. ___ ### Further Reading Take a look at the [FAQ]. [home page]: [api-services]: [access-control]: [booking-limit-meaning]: [cta-ctd-stop-sell-interpretation]: [booking-pull-credit-cards]: [booking-push-notes]: [FAQ]: [Get Hotel Information]: [Get Rates]: [Update Rates]: [List Rate Plans]: [List RoomRates (Room + RatePlan)]: [Get Availability and Restrictions]: [Get Inventory]: [Update Availability and Restrictions]: [Booking Handling (Pull)]: [Booking Handling (Push)]: [curl]: