BookingService 3 – Booking Overview
The BookingService 3 service is a booking web-service, containing support for packaged and dynamically combined assortment. Together with the TravelSearch you can use these services to make a full search & book site, for packaged and dynamically combined assortment.
Contents
Functional steps
A typical book process would do these calls in sequence:
- GetBookableUnits
List all possible units (e.g. rooms) - GetBookableTransports
List all possible transports (e.g. flights) - GetBookableServiceTypes*
List the available extra service types - GetBookableExtras
List the available extra services - GetPriceInfo
Calculate the online price for the chosen units, transports and extras - PrepareBooking
Prepare all segments of the trip for final booking; check the final price - CompleteBooking
Confirm the previously prepared booking.
* GetBookableServiceTypes returns an empty list currently.
A BookRequest object is required in all calls, which describes the trip that was previously found using the TravelSearch. See Advancing to the Booking service.
Session management
The BookingService 3.0 uses a sessionId, that should be used on consecutive requests. The first call uses an empty sessionId. Use the returned sessionId in subsequent requests.
Changing trip details including departure date, duration or travelers requires you to retake the steps from the start with an empty sessionId. Also, after a successful CompleteBooking request the sessionId can no longer be used.
The sessionId has the format DID_3_somehexadecimalcode. Please always provide this ‘DID’ you received if you send us questions about specific calls.
Test-flag
Use the HTTP-header X-Test: true to force calls to test status. You may safely call PrepareBooking and CompleteBooking with this flag set to true, to test the complete flow. A valid booking response will be returned, with a status TestBooked.
Package price indication
Most responses of the BookingService contain an element packagePriceIndication. This is the best estimate of the total booking price given the current selection of the user. It will be updated as soon as more online calls to providers (using getBookableUnits, getBookableTransports and getBookableExtras) are made.
Messages
All responses of the BookingService can contain messages. These can be of several types:
- info: providing extra information
- erratum: information about the items you’re booking that is of importance to the consumer
- warning: alerts you to a possibly problematic situation
- error: a problem that prevents you from continuing the booking without making changes.
A message always contains a description, and sometimes a consumerDescription. Only the consumerDescription should be displayed to end-users. If none is available, the message is not intended to be displayed to the end-user.
Using the providerId and messageOn attributes of the message, the part of the booking the message relates to can be determined. This is certainly for errata of interest to be able to display this message at the most logical location in the user interface.
The code field can contain a standardized code which can be used to have standard processing response in the client. A list of codes can be found here: Message codes
BookingDescription
All responses of the BookingService contain a bookingDescription, which lists everything that is known about the booking up to this point.
The bookingStatus in the bookingDescription denotes the overall status of the booking.
Displaying prices
Prices returned by the BookingService for units, transports and extras are sales prices. The price of individual units and transports (such as rooms and flights) should not be displayed to the user. Only the difference between these prices should be displayed. The prices of extras may be displayed as returned.
For example, if three possible rooms are returned, with prices of €55, €65 and €73, the user interface should display:
- Room 1: description
- Room 2: description – + €10,-
- Room 3: description – + €18,-
The same applies to transport prices.
From the GetPriceInfo call and onward priceSegments are returned, describing the price composition for each segment. The netPrice and calculatedMargin should only be displayed in a professional (targeted at the travel agent) environment, and never to consumers (not even hidden in the html).
Booking flow
To start the Booking flow, create a BookRequest object based on information from the TravelSearch. A BookRequest looks like this:
"bookRequest" : {
"startDate" : "20190804",
"nightCount" : 7,
"countAdults" : 2,
"countChildren" : 0,
"countBabies" : 0,
"boardType" : "LO",
"accommodationId" : 40978504,
"transportType" : "Flight",
"departureAirport" : "AMS",
"arrivalAirport" : "LHR",
"preferredTransportCode" : "KC286289",
"preferredPackageCode" : null,
"actionCodes" : null,
"birthdates" : ["19900218", "19921204"]
}
The BookRequest is used in every call to the BookingService.
GetBookableUnits
The getBookableUnits call is used to retrieve all units (e.g. rooms) that can be booked for the selected trip (based on the BookRequest). A required parameter is the number of rooms and assignment of people to each of those rooms (number of adults, children and babies) (unitOccupations).
If you don’t know the arrangement of people among the room(s) yet, make sure you recall this function when you have the final arrangement – a different set of rooms might be applicable.
As a general rule to get the best availability, divide people amongst rooms in a way that at least one adult occupies each room, and children are divided between rooms.
Display the results of this call as a list of options to the user. Don’t display the individual unit prices – see Displaying prices for an explanation.
The bookableUnit objects returned from this function (nested inside the bookableUnitOccupations and bookableAccommodation) can be used as-is in the unitAssignment in following calls.
GetBookableTransports
The getBookableTransports call is used to retrieve all transports (e.g. flights) that can be booked for the selected trip (based on the BookRequest). A getBookableUnits call must have been done before. The getBookableTransports call is not required if no transport will be booked.
The response contains bookableTransports with for each toTransport (outbound flight) a list of possible fromTransports (inbound flights).
Display the results of this call as a list of possible to-transports to the user, and when one has been selected, a list of related from-transports. Don’t display the individual transport prices – see Displaying prices for an explanation.
Every Transport can also contain a list of PickupDropoff points, (mostly for bus and train transports), allow for a selection of a pickup (on to transport) and drop-off (on from transport).
A related toTransport and fromTransport can be used as-is in the transportAsignment in following calls. When available in the original Transport option a toPickupPoint and fromDropoffPoint must also be selected in the transportAssignment.
GetBookableServiceTypes
The getBookableServiceTypes call returns the possible (external) services that can be requested using the getBookableExtras call. Required parameters are the chosen units (from getBookableUnits), transports (from getBookableTransports), a list of traveler birthdates, and the assignment of those travelers to the units and transports.
The returned list of services can contain:
- insurance
- transfer
- parking
- airportHotel
Note that these services are not enabled by default because they require additional setup and/or agreements with third party services. Please contact us to learn more about the available services.
GetBookableExtras
The getBookableExtras call returns the possible extra’s that can or must be requested in following calls. Required parameters are the chosen units (from getBookableUnits), transports (from getBookableTransports), a list of traveler birthdates, and the assignment of those travelers to the units and transports.
This call always returns extras from the providers of the chosen unit and transports; e.g. an optional ‘All inclusive surcharge’ for a room, and luggage options for a flight. The extras configured in your account (like Calamiteitenfonds or Boekingkosten) are always returned as well. Extras from external services (like transfers, carrental, etc.) are only returned when they are requested in the services parameter. Which types of external services are available can be checked using the getBookableServiceTypes call.
The extras returned from this call are divided per type. The external services each have their own list of results, and a list of luggageOptions is provided. All other extras are grouped in the general extras list.
Luggage options
The luggageOptions contain a list of choices for the user. The options should be divided on type, giving a separate choice to the user for hand (cabin) and hold (checkin) luggage. Not every provider provides options for one or both types, but a No luggage options will always be present.
Each option contains a toLuggageOption for the toTransport, and a list of combinable luggage options for the fromTransport in the fromLuggageOptions, much like the bookableTransport structure returned by getBookableTransports. In some cases only one fromLuggageOption is provided per toLuggageOption, in which case the same amount of luggage must be booked for both directions.
Display the results of this call as a list of possible outbound luggage options to the user, and when one has been selected, a list of related inbound luggage options. You may display the price for each option to the end user. The total luggage price will be the sum from a valid combinable toLuggageOption and fromLuggageOption.
The toLuggageOption and fromLuggageOption objects can be used as-is in the luggageAssignment in following calls, but the type should be respected (only use luggageOptions of type hand for toHandLuggageOption and fromHandLuggageOption and only use luggageOptions of type hold fo toHoldLuggageOption and fromHoldLuggageOption).
Other extras
Extras that do not fall in any of the external service categories or luggage options, are listed in this element. Each extra contains a lot of details, including description, category, price, group, and valid date periods and quantities. The status of the extra determines how to present the extra to the consumer. Possible statuses are:
- optional / available: the user has a choice whether to book this extra
- required: this extra must be booked, and if not selected, will automatically be added
- onRequest: this extra is optional, but must be confirmed by its provider
- facultative: a choice must be made from a number of different extras, all within the same group
GetPriceInfo
The getPriceInfo call returns the online, total price calculation for the booking based on the selections by the user. Required parameters are the chosen units (from getBookableUnits), transports (from getBookableTransports), and extras of the different types (from getBookableExtras), and a list of traveler birthdates and the assignment of those travelers to the units, transports and extras.
Calculating the price can take a while, depending on the used providers. While waiting for its result, this is the best moment in the booking process to ask the user to enter all personal information required by the next calls.
GetPriceInfo no longer returns a packagePriceIndication but a totalPrice, along with a totalPriceAtLocation. The price composition for each segment is returned in priceSegments. The netPrice and calculatedMargin returned here should only be displayed in a professional (targeted at the travel agent) environment, and never to consumers (not even hidden in the html).
The sum of the prices of the priceSegments should be the totalPrice. Each priceSegment optionally contains priceDetails, which can list some specific items or selected options. Not all priceSegments will have priceDetails (the list may be empty), and the sum of priceDetails is not by definition equal to the total of the priceSegment.
GetPriceInfo also returns cancellationDetails and paymentSchedule, both of which should be displayed if available. Continuing the booking will compel the user to be bound by those terms.
PrepareBooking
The prepareBooking call starts the booking process at all providers. Required parameters are: chosen units (from getBookableUnits), transports (from getBookableTransports), and extras of the different types (from getBookableExtras). Other required parameters are the details for all travelers, the assignment of those travelers to the units, transports and extras, and the mainBooker and homeContact information.
It is required to have called getPriceInfo at least once for this session before you can call prepareBooking.
The results of prepareBooking are the same as those from getPriceInfo (see above), with the addition of a bookingToken, which is needed for the next call to confirm the booking.
The price returned by prepareBooking is the final price for which the booking will be made. It is possible the price is different from the one returned by getPriceInfo, due to availability changes or price fluctuations. If this is the case, the price difference must be displayed to the user, and the user must agree to the new price before continuing.
If there is no price difference, and the user does not have to arrange (pre)payment before confirming the booking, it is allowed to immediately follow this call with the completeBooking call. Make sure the Booking button which starts the prepareBooking call communicates this to the user in that case.
CompleteBooking
The completeBooking call confirms the booking that was prepared using the prepareBooking call. Besides the standard bookRequest and sessionId only the bookingToken as returned by the prepareBooking calls is a required parameter.
The results of completeBooking are the same as those from prepareBooking and getPriceInfo (see above), but the bookingToken now has been replaced by a bookingNumber. The bookingStatus in the bookingDescription will booked or testBooked if the booking succeeded.
The bookingNumber is a number assigned to the booking by DynpaX. All underlying booking references from separate providers can be found in the bookingDescription within each specific assignment object, in the element providerBookingReference.