Download the PHP package xmlworld/api-client without Composer

api-client

Simple connection to the xml.world API

Instalation

You can add this library as a local, per-project dependency to your project using Composer:

composer require xml-world/api-client

Description

This library provides a quick way to integrate your booking system with the XML.world API.

You will be able to search for hotel accommodation scoped by several criteria, to book rooms, to check bookings, to update the reference as a trade, and to cancel it if needed.

The API will return and exhaustive summary of your booking.

Use

You first need to apply for trading credentials from XML World.

Once you have them, you can start the API like this:

The XMLClient exposes object exposes 5 methods from the API at XML World.

Search request

With this request, we send the criteria of our search in order to retrieve the list of stock that fulfills them.

We make use of the SearchDetails class which accepts params like arrivalDate, duration, regionID, roomRequests properties, propertyID, mealBasisID, minStarRating, minimumPrice, and maximumPrice.

The params roomRequests and properties are lists of room requested and properties. We express those lists with the objects RoomRequests and Properties.

RoomRequests accepts a list or RoomRequest objects where we specify the number of adults and the ages of non-adult visitors.
Each RoomRequest instance is a different room we request for.

Properties accepts a list of property IDs. It is used when we request for several hotels. If we are only interested in one hotel we can leave this param null and use propertyID. Both parameters are mutually exclusive.

The example is searching for rooms from the properties whose IDs are 19 and 21 two rooms, one for two adults and another run for an adult with 3 underage. The system will deduce that the 2-year-old child is actually an infant.

Finally, we post the request:

In $result we get the outcome of the request. It is a SearchResponse object. If the ReturnStatus is true, it will bring a list of rooms that match our searches in a PropertyResults object or an error message otherwise.

Book request

With the roomIDs we obtain from the previous request now we can book the rooms.

In order to do that, we construct a BookDetails object. This object accepts some of the same params of the SearchDetails object like arribalDate and duration and further params like tradeReference, totalPrice, leadGuest, roomBookings.

The names tell what those params are for.

It is important to mention that totalPrice is optional but advisable to use. It makes sure that we book at exactly the specified price if it's still available, otherwise it will book at whatever the curren price is.
This is to avoid the scenario where we do a search and get rooms and prices, but the book later and the price has changed, and it could be both lower and higher.

The leadGuest param admits a LeadGuest object which has to have firstName, lastName and title at minimum but it can have more details. This is the first guest, and it's assumed that goes in the first room of the book.

The roomBookings param admits a RoomBookings object, which is a list of rooms and accepts one or more RoomBooking objects.

Each RoomBooking object has the roomID, mealBasisID, which are the room and meal plan codes from the previous search request.

Then the adults, children and infants, which are the number of each for this room.

Finally, guests which accepts a Guests object that represents the lists of guests for this room.

If the room only has the lead guest, we can set null and if there are more guests along, we don't need to include it here.

Each Guest object has type whether adult, child or infant. The firstName and lastName. The age which is null if it's an adult and specified if a child. And the nationality.

Now we can post the book:

The var $result will be a BookResponse object which again, if ReturnStatus is true, bookingDetails will be a BookingDetails object with the list of rooms we just booked, their special offers, supplements, taxes, cancellation policies if any and hotel details as well as the booking reference at XML World. An error message otherwise.

Booking request

Booking request is for retrieving the current status of our booking at XML World.

We provide the XML World booking reference we got from the book request, and we get a BookingResponse object that is identical to the BookResponse object from the book request.

Booking update request

Booking update request is for setting the trade reference.

The method accepts the booking reference given in the BookRequest or BookingRequest requests and the trade reference. It returns a BookingUpdateRequestResponse object that holds the same data as BookResponse.

Cancel request

With the Cancel request, we do that, cancel the booking.

The method accepts the booking reference given in the BookRequest or BookingRequest requests and the trade reference. It returns a CancelResponse that in principle is like an BookResponse but informing about the cancellation success.

Once we cancel a booking, BookingRequest returns a BookingResponse object that holds the same details as this CancelResponse.

Development environment

XMLClient supports two environments, live (by default), and devel.

Live attacks the API in production, and the calls produce real results and bookings.

Devel attacks our staging environment and the data might mirror production, but bookings don't have a real effect.

To activate the devel environment, do this:

You just need to specify the dev environment by passing the constant XMLClient::ENV_DEV as third parameter.

If you ever need to request a different server in your development environment for tests purposes, you can do so this way:

Logging

XMLClient also provides a way to log calls and responses.

In order to do that, you need to implement the Interface Logger:

For example, we build this anonymous class that implements Logger and injects whatever logging object we use as a forth parameter.

Examples

you can find examples of use in the folder examples/

1. For searching, in search_example.php.
2. For booking, in book_example.php.
3. For retrieving a booking, in booking_example.php.
4. For updating a booking, in booking_update_example.php.
5. For canceling a booking, in cancel_example.php.
6. for logging injection, in logging_injection_example.php.