TripAuthority Web Services APITripAuthority is Alliance Reservations Network XML API for hotel availability, rate details, bookings, and cancellations. This guide provides the information a competent developer will need in order to integrate our services with your website. XML integration is for serious businesses only; it will require major development and is not suitable for a part time developer or first time developer attempting to learn on the job. We charge a $2000 integration fee before you're allowed access to the API to begin development. If you're ready to begin, first register as an affiliate, once you have your account, email our accounting department and inform them you'd like to pay the fee and begin development. You will be given seperate credentials for the API in addition to the credentials you received for being an affiliate. After you receive your credentials, the information found below will enable your developer to code to our API. The TripAuthority web services are located here. Click "Service Description" to see the WSDL. The XSD's for a request and response are also available. In .Net, simply add a web reference to your project and point it to http://tripauthority.com/hotel.asmx and code directly to the generated classes. The required work-flow to use TripAuthority as the back end for you own booking engine requires the following steps. This is just an overview, details about the actual requests and valid values can be found in the XSD and the charts below. Static Content and SearchingDownload our property data and setup your own local database of all static content. You will be doing your own searching in your own database locally. You should automate this process as our data dumps are updated weekly. It is important that you do this so you have fresh content and access to the latest hotels, and know which hotels are no longer active so you can disable them in your database. Once you've searched and decided what hotels you'd like to pull rate information for, you're ready for the next step. Availability RequestGiven a list of hotels that you're interested in, you must now query TripAuthority for availability information for those hotels. Here's a sample request: Make this request for the total number of rooms and the total number of guests. Request is limited to 50 hotels per request; make multiple requests if you need more than 50. You will get back a response that contains available rate plans and room types from various suppliers that we call gateways. Rate Results -- Nightly or First Night OnlyThe response might contain full nightly rates and tax information, or possibly only first night rates with or without tax information. Display what you can to the guest. Full rate information are not always available and there is nothing you can do about this; this is how the industry works and you must accept this if you want to build a successful application. To not show rates that don't include the full price of the stay you'd have to not sell well over half of the inventory available on the market today. You application requirements do not matter, you must work with what is available on the Global Distribution System (GDS). There is no creative way around this restriction that cause excessive traffic and exceed our bandwidth restrictions or we'd have already done it. The response should be essentially self documenting, however, DisplayCurrency requires a bit of explanation. Rates are always returned in the hotels native currency. If you request another DisplayCurrency, the correct conversion rate from the hotels native currency to the desired DisplayCurrency will be returned as DisplayCurrencyMultiplier. You may use this value to convert the hotel currency to the desired currency for display in your UI. This allows you to show both the original currency and display currency side by side without us duplicating the values in the XML. Make sure your code can handle all cases and don't switch on the gateways doing different things for different gateways. Any gateway could potentially return any valid response with varying amounts of information. When an availability calls fails you just don't display rates for that hotel, nothing else needs to be done. Details RequestOnce the guest has selected a particular rate to view, you'll then be ready to use the information from the availability response to build and submit a detail request. Given the hotel, gateway, rate code, and room code, you can request all the details for a particular rate. Also make this request for the total number of rooms and the total number of guests. The detail response contains the full information for that particular rate including full nightly rates, all taxes and fees associated with the room, and all hotel, payment, and cancellation policies that apply to the rate. This is a much more expensive request, do not attempt to do a full details request for every rate that comes back in the availability response to try and get the full nightly rate and tax information up front. There's a reason this information isn't included in the availability response, it would be too much load on the suppliers systems. When a detail request fails it means the rate is no longer available, this is a common case and the user should be informed that this rate is sold out or other not available. Subsequent availability calls should no longer return this rate, the failed call should flush the availability cache to ensure the next call receives a fresh copy of current rates at the hotel. Detail responses may contain information about extra adult fees, this is informational only, do not rely on this field for pricing as it is not always available and may simply come back with $0 amount. This doesn't mean there isn't a charge for additional guests, it just means we don't have the information. All room prices are based on the number of adults you request per room. Do not assume that you can request 1 adult and then book extra people into the room because the extra person fees are 0. If you do so you will be liable for the difference when the guest complains about having to pay extra when they arrive at the hotel. Reservation RequestOnce the guest has decided to book a particular rate, and they've viewed all the relevant details, policies, and charges for that rate, you can use the information contained within the details response, combined with the information you collect from the user, to build a reservation request. For collections and accounting reasons, and unlike the previous requests, this request must be made for a single room, with the number of guests that will be in this room. If you give us an incorrect number of adults and pricing is affected, you are liable for any refund due to the guest. This will require that you do a little math with the values from the detail request to determine the one room totals to submit a correct reservation request; alternatively you could do a details request for a single room which will return all the correct values necessary to build a successful booking request. Make one reservation request for each room you want to book, the system will reject any attempt to book more than one room in a single request. The reservation response will contain three values you'll need: the reservation and itinerary id's which will be needed to cancel a reservation, and the confirmation number which you'll give to the guest. You must store all of these for later use in the cancellation request. Reservation requests can fail for many reasons, most often because a rate is no longer available because of selling out, or because some hotel restriction on those particular dates has been violated such as no-checkin or no-checkout. Refer to the errors.csv for a list of failure codes and error messages we display to our users. You may use this or display errors of your own choosing. Cancellation RequestShould a guest need to cancel a reservation, you can submit a cancellation request. If the request succeeds you'll receive a CancellationID indicating success. Should a cancellation be in conflict with the hotels cancellation policy, it will fail. If the request fails, you'll need to present the guest with whatever options for customer service you have to allow the issue to be resolved manually. Common IssuesXML is not just a stringXML documents are not just concatenated strings. Do not build requests by just sticking a bunch of strings together or you'll often end up with an invalid document that isn't properly xml encoded. Whatever language or library you're using, there is a proper XML Document object you should be using to build XML Documents which will properly handle the necessary XML encoding. There are three methods you may use to submit requests to us: SubmitRequestDoc, SubmitRequestRpc, and SubmitRequest. This is also the order of preferred use. If you're using .Net or Java, you'll probably want to use SubmitRequestDoc. If you're using PHP, Python, or Ruby, you'll probably have less trouble with SubmitRequestRpc. As a last resort, if you're going to use SubmitRequest, you'll need to xml encode your xmlFormattedString to get SubmitRequest working since it takes the document as a formatted string. That means a request such as this...
<ArnRequest>
<Availability DisplayCurrency="USD" SearchTimeout="15">
<HotelAvailability InDate="2007-04-26" OutDate="2007-04-29" Rooms="1" Adults="2" Children="0">
<Hotel HotelID="8800" />
</HotelAvailability>
</Availability>
</ArnRequest>
Will actually get passed to the webservice as a string that looks like this...
<ArnRequest>
<Availability DisplayCurrency="USD" SearchTimeout="15">
<HotelAvailability InDate="2007-04-26" OutDate="2007-04-29" Rooms="1" Adults="2" Children="0">
<Hotel HotelID="8800" />
</HotelAvailability>
</Availability>
</ArnRequest>
Multiple CurrenciesWhen dealing with multiple currencies leave all currencies in their native rate. The rate that came down in the rate details call is the native rate. For booking fees, that's always USD. For the hotels rates, that's whatever rate is native to that hotel. For your user, that is the display currency. You cannot change the currency to another currency and submit a reservation. If you're showing the guest USD, and you get a rate from a Canadian hotel, then you use the DisplayCurrencyMultiplier that comes back on the room to convert the Canadian rate to USD *for display* to the user only. Behind the scenes, you're working with a Canadian rate and you need to submit a booking request using the Canadian rate for the room. Even with this Canadian rate, you'd have gotten a USD booking fee. You can't add different currencies, so you must convert them all to a single currency before doing the addition for the user. Since the users DisplayCurrency is USD, then multiply everything by its DisplayCurrencyMultiplier and then you'll have all USD prices so you can correctly summarize the total charges to the user. When submitting a reservations, you're pretty much just echoing back what comes down in the detail response. Booking fees will always be in USD, regardless of what currency the native hotel rate is, because we charge the booking fee. Developer ExperienceMake sure to choose a developer who has experience with cross platform SOAP web services. Be very careful before choosing a PHP developer who has never worked with a .Net SOAP web service before, they often fail to be able to complete an integration. They should have past experience calling .Net SOAP web services from the language the client is using. They should understand some basic things like document encoding, be it literal, RPC, or soap encoded, and should be good enough to shake out the kinks and get it working on their own. The should also know how to trace their requests and collect samples of both the request and the response before seeking advice from us. Do not send us your source code asking us to fix it for you (typical of PHP developers), it is your responsibility to know how to use your language of choice and to understand the proper way to use web services. Sample CodeWe do not provide sample code, these are simple web services and a competent developer should be able to reference and use this service successfully in under an hour without requiring that we write the code for him. If you require sample code to understand how to reference and use a simple web service, you are not experienced enough for this integration. GatewaysAfter you've integrated you will find you're authorized to see all Gateways (individual suppliers) except Gateway 30 and Gateway 2. Gateway 30 has specific UI requirements you must implement to be able to sell their rates. Gateway 2 is for the delivery of negotiated and preferred rates from hoteliers to your account; until you've negotiated preferred rates, you won't see any. To learn more about Gateway 2, email support@allresnet.com and request Gateway 2 information. To receive Gateway 30 content, go to the supplier here and make sure you conform before you go live. Once you have completed the requirements you can request a site review to activate the service by emailing support@allresnet.com and provide a staging URL, a login if required, requesting activation of gateway 30 for your testing and our site review. We must be able to do a test booking. Include an email address for critical updates. TestingTest all requests in the live environment. Availability and details calls are read only and can be tested without consequence. Reservation and cancellation calls are real live reservations. When testing reservations in the live environment, make sure to book a few months out and select a cancelable reservation that doesn't charge a cancellation fee. Make sure to cancel all test reservations booked. You are responsible for any charges you incur with the hotel for accidental booking of non-cancelable reservations or for test reservations that were left uncanceled. You can use two fake card numbers to force credit card failures to ensure you handle them properly. 4321432143214327 will cause an authorization declined error and 5454545454545454 will cause an amount that must be charged is different from amount authorized error. Any other card numbers will be sent to the live credit card processor. Upon request we will refund any booking fees that may have been charged during testing. For service fee credits, if any, email the cancellation acknowledgment to customerservice@allresnet.com with the subject line "Credit for Service Fee of TEST Reservation" SupportWe have setup support groups to help you quickly get in contact with the correct people to help you with your problem. We encourage you to only use these email addresses when requesting support, and to not send emails to individuals.
|