Introduction

      The purpose of this document is to provide technical details about the API's. This document outlines the business processes supported by the API and details about specifications of API’s. It assumes that reader has a technical background and is familiar with JSON, API's.

Connection properties

RequestvalueDescription
Request MethodPOSTThe requested method.
Content-Typeapplication/jsonThe content type.


Request/Response

It is recommended that at least all booking and cancellation transactions sent through the Test / Live environment should be logged and maintained by the hotel agent for at least 6 months.

Go-Test/Live Process

In order to start testing, please notify our support team via e-mail at animesh@technoheaven.com

      When you have completed your development, contact your Account Manager for the activation of the access IP address of Test/Live Server is essential for whitelisting

Client Requirements

  • Client requests must be issued from a public, static IP address registered with System.
  • Client requests must be made via an HTTPS POST request.
  • SSL.
  • All data sent and received via the interface will be encoded in UTF-8.
  • we use deflate compression for response.

Development Phase

      Once you receive your Access token, you can start the development of your application/framework. The whole process of communication consists of simple JSON messages exchange (request /response) between your application/framework and system. Each request needs to be posted (through POST method) using https protocols. For details regarding requests and answers formats please consult the dedicated area of each request. For further assistance in development process do not hesitate to contact our support team.

Process Flow Diagram

img

Implementation Approach

  1. Client review of the API specifications
    1. Review of API specifications
  2. Test Environment Integration
    1. API Integration.
    2. Test Execution by your Tech Team.
  3. Integration Testing
    1. Determining the necessary test cases based on the API's by Our Tech Team
    2. Test Execution
    3. Certification by Our Tech Team
    4. Before you go live you need to share pdf sample voucher after booking.

  4. Production Environment
    1. API Integration
    2. Schedule Go Live Date
    3. Transaction Monitoring and issue Resolution

Important note

  • Follow these guidelines when searching for properties for your test bookings, even for static tests. Being diligent in your property selection will help you avoid incurring any accidental charges during your booking tests.
  • Please use city id : 20097 = kuala lumpur. for testing purpose.
  • To use different nationality of different countries use same name in countries api response.
  • Verify the booking will be outside of the hotel's cancellation policy.
  • Never pick next-day or same-day availabilities, even to test promos.
  • Shop a few months ahead whenever possible.
  • Use first name as Apitest.
  • Never automate static booking tests -we may flag or temporarily disable your account.
  • Shopping at least a few months ahead and paying attention to Policy will help you avoid the most common problems with test bookings. Remember, client is not responsible for any unintentional live or nonrefundable bookings you place during testing.
  • Make sure you cancel each test booking using api, if face any issue in cancellation contact us immediately.
  • Always do refundable feature booking and cancel booking after done.
  • No duplication allowed for internalreference, it must be unique for each time you hit that api.

Documentation and Download

Status & Error Code

NoStatus CodeDescription
1200OK
2400Bad Request
3401Unauthorized
4403Forbidden
5404Not Found
6500Internal Server Error
7503Service Unavailable

JSON Request Format:-


JSON Response Format:-


Date Format

  • Date format send to Payload MM-DD-YYYY

Error and Description

ErrorCode ErrorType ErrorDescription
INTERNAL_ERRORAPI_ERROR The server was unable to process the request due to an internal error
NOTPERMITTED_ERRORPermission1.Bookings within cancellation deadline are not permitted for this User.

2.Bookings are not permitted for this User.
CacheNotAvailableCacheNotAvailableAccess to one of the cache failed. The cache for this search key is no longer available
DUPLICATION_ERRORDuplicate1.Bookings within cancellation deadline are not permitted for this User

2.Booking token already exist for this criteria
MISMATCH_ERRORMismatch1.Pricing could not complete - rate missing.

2.Data mismatch from previous response.
CacheNotAvailableCacheNotAvailableAccess to one of the cache failed. The cache for this search key is no longer available
INVALID_REQUESTRequestErrorRequest is not well formed please check and try again.
NOCOUNT_ERRORGENERAL1.No record found for given criteria

2.No availability found for given criteria try search with other criteria

Countries

The Countries API has been designed to provide All Countries data. The following sections describe the Countries API Request and Response Format.

JSON Request format:

TagDescription Optionality
TokenYou have to put unique token which is provided by the systemMandatory

JSON Response format:


TagDescription
CountryIdRepresent unique CountryId.
NameRepresent Name

Cities

The Hotel List Search API has been designed to provide list of all Hotels with display Minimum price for particular city. The following sections describe the Hotel List Search request and response format

Request URL


JSON Request Format:


Parent TagTag DescriptionOptionality
RequestCountryIdRepresents unique CountryId Mandatory
TokenTokenYou have to put unique token which is provided by the systemMandatory

JSON Response Format:

TagDescription
CityIdRepresents unique CityId.
NameRepresents unique city name.

All Cities with Country

AllCitieswithCountry API has been designed to provide list of all cities with country .The following sections describe the AllCitieswithCountry in one API call request and response format.


JSON Request Format:



Parent TagTag DescriptionOptionality
TokenTokenYou have to put unique token which is provided by the system. Mandatory
RequestonlyhotelRepresents onlyhotelonlyhotel: 1 you will get all cities
onlyhotel: 0 you will get active cities

JSON Response Format:

Tag Description
cityidRepresents cityid
citynameRepresents cityname
CountryidRepresents Country id
countrynameRepresents country name.

All Hotels By City

AllHotelsByCity API has been designed to provide list of all Hotel details for that particular City.
  The following sections describe the AllHotelsByCity API request and response format.


JSON Request Format:



Parent TagTag DescriptionOptionality
RequestCityIdRepresents unique CityIdMandatory
TokenTokenYou have to put unique token which is provided by the system.Mandatory

JSON Response Format:

Tag DescriptionOptionality
HotelIdRepresents HotelIdMandatory
HotelNameRepresents HotelName Mandatory
LatitudeRepresents LatitudeMandatory
longitudeRepresents longitudeMandatory
AddressRepresents AddressMandatory
RatingRepresents RatingMandatory
IsRecomondedHotel-Mandatory

Availability

      The Availability API has been designed to provide list of all Hotels The following sections describe the hotellistsearch API request and response format. Currency set up done only once account is created and you have to use that Currency for transaction with api.


JSON Request Format:



Parent TagTag DescriptionOptionality
RoomAn array represents Room Mandatory
RoomNoRepresents RoomNo Mandatory
NoofAdultsRepresents total number of AdultsMandatory
NoOfChildRepresents total number of child. Mandatory
ChildAgeArray represents child Age.Mandatory
CityIDRepresents unique CityID.Mandatory
NationalityRepresents unique Nationality.Mandatory
CheckInDateRepresents CheckInDate. Date should be in the format: MM-DD-YYYY Example: 08-12-2018Mandatory
CheckOutDateRepresents CheckOutDate. Date should be in the format: MM-DD-YYYY Example: 08-12-2018Mandatory
NoofNightsRepresents number of NightsMandatory
currencyRepresents currency Mandatory
IsShowRooms1 Show Rooms 0 HotelOnly Mandatory
IsRecommendedOnly1 Only Preferred Hotels 0 All Hotels Mandatory
IsOnlyAvailable1 Available only 0 Include OnrequestMandatory
StarRatingSelection of star rating between two categories.
Minmin=min star rating0 star rating for unspecified or apartment
maxmax=max star ratingMandatory
HotelIDsRepresents list of comma seperated HotelIDs by cityOptional
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory
currencyRepresents currency Mandatory

JSON Response Format:

Tag Description
CountRepresents Count.
SearchKeySearchKey will use in next steps ,expires after 25 minutes. You have to do booking within that time limits.
Start priceRepresents unique Price
HotelIDRepresents unique Hotel id
HotelCodeRepresents unique hotel code
CurrencyRepresents Currency.
HoteloptionArray display detail.
HoteloptionIdRepresents unique hoteloptionid
MinPriceRepresent Min Price
IsCombinedTrue = Multiple rooms are combined in one
False = recieve list of rooms
HotelRoomsArray display details
RoomNoRepresents room number. You will get some combine rooms for multiple rooms search.
RoomTypeNameRepresents room type
MealNameRepresents MealName
PriceRepresents Price
BookingStatusRepresents BookingStatus.
RoomTokenIt display unique AvailToken which is provided by the system

Note:

As we have both direct inventories and dynamic rates also so for some cases you will receive combined room in multiple room search ,
so for easy to identify these rates we have now added new parameter in availability response IsCombined (true,false) if its true then rooms are combined to one room .
for example : if search is for
rooms :2
room 1 : 1 adult
room 2 : 2 adult
then id IsCombined =true that means both rooms are combined in one (roomNo: "1") ;
if False : then you recieve list of rooms(RoomNo:1,RoomNo:2).
and when you try to book such combined room you have to pass pax details separately for both the rooms.

Cancellation Policy

The CancellationPolicy for Hotel API has been designed to provide Price of cancellation for particular Room. The following section describes API request and response format.


JSON Request Format:



Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
RequestSearch key
HotelOptionIdRepresents unique HotelOptionID. Mandatory
RoomTokenUnique RoomToken which is provided by the system.Mandatory
currencyRepresents currency Mandatory
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory

JSON Response Format:

Parent TagTag Description
CancellationPolicyFromDateRepresents FromDate
ToDateRepresents ToDate.
CancellationPriceRepresents cancellation price.
CurrencyRepresents Currency.

Cancellation Policy Multi

The CancellationPolicyMulti for Hotel API has been designed to provide Price of cancellation for multiple Room in single request. The following section describes API request and response format.


JSON Request Format:



Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
RequestSearch key
HotelOptionIdRepresents unique HotelOptionID. Mandatory
HotelRoomsRepresents HotelRoomsMandatory
RoomTokenRepresents RoomNoMandatory
RoomTokenUnique RoomToken which is provided by the system.Mandatory
AdvancedOptions
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory
currencyRepresents currency Mandatory

JSON Response Format:

Parent TagTag Description
Error
ToDateRepresents ToDate.
CurrencyRepresents Currency
CancellationRS
RoomNoRepresents RoomNo
RoomTypeNameRepresents RoomTypeName
MealNameRepresents MealName
EssentialInformationRepresents EssentialInformation
CancellationPolicyFromDateRepresents FromDate
ToDateRepresents ToDate
CancellationPriceRepresents cancellation price.

PreBook

The PreBook API has been designed to check availability status of booking before book.This APImust hit once for one booking or you will get duplication error.The following section describesAPI request and response format.in case of isCombineRoom= true we are going to do one change inprevious response we sending price = 0 in other rooms and in roomNo=1 we giving you total price , butin new response we divide price in each room Total price will not change.only price is divided insideroom.

JSON Request Format:


Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
RequestSearch key
HotelOptionIdRepresents unique HotelID.Mandatory
HotelRoomsAn array represents room details Mandatory
RoomNoRepresents room numberMandatory
RoomTokenUnique RoomToken which is provided by the system. Mandatory
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory
currencyRepresents currency Mandatory

JSON Response Format:


JSON Response (Example ) IsCombineRoom=true


Parent TagTag Description
PreBookRS
HotelOption
HotelNameRepresents HotelName
Nationality Represents Nationality
BookingTokenUnique BookingToken which is provided by the system. And used for final booking request
Status If status is bookable than only proceed for booking.
IsPriceChange0 Represents Not Change in IsPriceChange
1 you have to notify price to customer before booking
CheckInDate Represents CheckInDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
CheckOutDateRepresents CheckOutDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
TotalPriceRepresents TotalPrice
HotelRoomsArrary represents Hotelrooms
UniqueIdRepresents UniqueId
RoomNoRepresents RoomNo
RoomTypeNameRepresents RoomTypeName
MealNameRepresents MealName
PriceRepresents Price
PriceChange Represents PriceChange
OldPrice Represents OldPrice
NewPrice Represents NewPrice
Currency Represents Currency.

Book

The Book API has been designed to give booking details .The following section describes API request and response format. After getting response or error in book response. you have to mandatory perform booking detail api to get the actual status of booking using your internal reference or reference number from Bookresponse.

JSON Request Format:


Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
RequestSearch key
BookBookingTokenUnique BookingToken which is provided by the system.Mandatory
TotalPriceRepresents Price Mandatory
InternalReferenceyour internal reference. should be 10 max character (No duplication allowed)Mandatory
HotelRoomsAn array represent HotelRoom Details. Mandatory
UniqueIdRepresents UniqeIdMandatory
RoomNoRepresents RoomNoMandatory
IsLead0 Represents No IsLead
For 1 booking you have to set ISLead = 1 and IsLead passeger must adult.
Mandatory
PaxTypeRepresents Adult / Child.Mandatory
PrefixRepresents Mr. / Mrs. /Ms.Mandatory
FirstNameRepresents FirstNameMandatory
LastNameRepresents LastNameMandatory
ChildAgeRepresents ChildAgeMandatory
UniqueIdRepresents UniqeIdMandatory
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory
currencyRepresents currency Mandatory

JSON Response Format:


Parent Tag TagDescription
BookRS
BookingId Represents BookingId
ReferenceNoYou need to show reference number on your voucher.
BookingStatusRepresents booking status with details
vouchered : confirmed
confirmed : confirmed
completed : Travel done.
cancelled : booking cancelled
on request : on request
not confirm : not confirmed
cancel charges: cancel charges if any for booking
InternalReferenceRepresents InternalReference
CurrencyRepresents Currency.
ErrorArray Represents Error

Booking Detail

API has been designed to Generate bookingDetails .The following section describes API request and response format. Only one ID can be passed. You can get booking details using either BookigID or your internalReference

JSON Request Format:


Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
Request
BookingDetailRQ
BookingIdRepresents BookingId Optional
InternalReferenceRepresents InternalReference optional
ReferenceNoRepresents ReferenceNooptional
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory
currencyRepresents currency Mandatory

JSON Response Format:


Parent TagTag Description
BookingDetailRS
HotelOption
HotelNameRepresent HotelName
HotelId Represent HotelId
Nationality Represent Nationality
BookingId Represent BookingId
InternalReferenceRepresents InternalReference
CheckInDate Represents CheckOutDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
CheckOutDateRepresents CheckOutDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
BookingDateRepresents BookingDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
LeadPaxNameRepresents LeadPaxName
TotalPriceRepresents TotalPrice
HotelRooms Array Represents HotelRooms
RoomNoRepresents RoomNo
RoomTypeNameRepresents RoomTypeName
MealName Represents MealName
Price Represents Price
CancellationPolicy Array represents CancellationPolicy
FromDate Represents FromDate. Date should be in the format: MM-DD-YYYY Example: 08-12-2018
ToDate Represents ToDate. Date should be in the format: MM-DD-YYYY Example: 08-12-2018
CancellationPriceRepresents CancellationPrice
PassengerNo special character allowed max length 20 character. Douplication passenger not allowed.
IsLeadRepresents lead pax
PaxTypeRepresents Adult / Child
PrefixRepresents Mr./Ms./Miss
NameRepresents Name
ChildAgeRepresents ChildAge
CurrencyRepresents Currency.
ErrorArray Represents Error

Check HotelCancellation Charges

JSON Request Format:


Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
Request
CheckHotelCancellationChargesRQ
BookingIdRepresents BookingId Mandatory
InternalReferenceyour internal reference.Mandatory
ReferenceNoMandatory
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory
currencyRepresents currency Mandatory
Note : To cancel whole booking you must have to pass cancelAll with value 1 and BookingDetailId=0

JSON Response Format:


Parent Tag TagDescription
CheckHotelCancellationChargesRS
HotelOptionRepresents HotelOption
BookingIdRepresents BookingId
TotalPriceRepresents TotalPrice
TotalChargeRepresents TotalCharge
TotalRefundRepresents TotalRefund
CancelCodeRepresents CancelCode
HotelRoomsAn Array Represents HotelRooms
BookingDetailIdRepresents BookingDetailId
RoomTypeNameRepresents RoomTypeName
PriceRepresent Price
RefundAmountRepresents RefundAmount
CurrencyRepresents Currency.
ErrorAn Array Represent Error

Cancel Booking

API has been designed to cancle booking .The following section describes API request and response format.

JSON Request Format:


Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
Request
CancelRQBookingIDRepresent BookingIDMandatory
BookingDetailIdBookingDetailIdValue = 0 to cancel whole booking.
CancelCodeCancelCodeMandatory
ReasonRepresents ReasonMandatory
CancelAllCancelAllValue = 1 to cancel whole booking.
CustomerIpAddressRepresents CustomerIpAddress Ip address of final end user Mandatory
currencyRepresents currency Mandatory
Note : To cancel whole booking you must have to pass cancelAll with value 1 and BookingDetailId=0

JSON Response Format:


Parent TagTag Description
CancelRS
HotelOption
BookingId Represents BookingId
HotelRoomsArray Represents HotelRooms
RoomTypeName Represents RoomTypeName
MessageRepresents Message
CancelStatus1 Represents booking cancel
Currency Represents Currency.
ErrorArray Represents Error

Booking Search

API has been designed to Generate bookingDetails .Date range allowed 31 days. The following section describes API request and response format.

JSON Request Format:


Parent TagTag DescriptionOptionality
TokenTokenToken Mandatory
RequestMandatory
BookingSearchRQMandatory
SearchBySearch By BookingDate or CheckingDate Mandatory
OnlyAPI0 Represents All booking
1 Represents only apibookings
Mandatory
SearchCriteria
Dates
FromDateRepresents FromDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
Mandatory
ToDate Represents ToDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
Mandatory
AdvancedOptionsCurrency Represents CurrencyMandatory
Note : OnlyAPI = 0 Represents All booking OnlyAPI = 1 Represents Api booking

JSON Response Format:


Parent TagTag Description
Error
BookingSearchRS
BookingList
HotelName
HotelIdRepresents HotelId
InternalReference Represent InternalReference
ReferenceNo Represent ReferenceNo
CheckinDate Represents CheckinDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
CheckOutDate Represents CheckOutDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
BookingDate Represents BookingDate.
Date should be in the format:
MM-DD-YYYY
Example: 08-12-2018
TotalPrice Represents TotalPrice
BookingStatus Represents BookingStatus
IsAPI IsAPI = True Represents booking made via api IsAPI = False Represents booking made direct on client portal
Currency Represents Currency.

Certification process

Please go through certification process in order to get live access.

Step 1 : Work Flow.

To ensure what API methods you are using, flow of method calls for these methods. This will help us to verify the integration.

Step 2 : Test Cases Execution by client.

Here we are providing a list of test cases needs to be executed .
Request / response for these cases will be required for verification .

[Test 1] :
Room 1 – Adult 1 (1 night)
[Test 2] :
Room 1 – Adult 2, Child 2 (3 night)
[Test 3] :
Room 1 – Adult 1 | Room 2 – Adult 1 both (2 night)
[Test 4] :
Room 1 – Adult 1, Child 1 | Room 2 – Adult 1 (1 night)
Provide Logs As below
[Test 1] : Availability→CancellationPolicy→PreBook→Book
BookingDetail→CheckHotelCancellationCharges→CancelBooking.

Step 3: Test Verification

Technical team will verify the test cases using Request / Response and suggest if there is any change required.

Step 4: Client Portal verification

After completion of step 3, you have to provide test link of your integration website to verify the integration flow.

Step 5: Sign off and Live access

On successful completion of all the above steps, we will give sign off and provide Live access details.

Since 2007 We have been offering travel services
to our agents of the highest quality, combining our energy and enthusiasm.
ADDRESS

Within Earth Holidays Sdn Bhd (854439 -T)

B-09-4 Megan Avenue 2 Jalan Yap Kwang Seng Kuala Lumpur -Malaysia

NEED HELP?
+0060321663969
support@withinearth.com
FOLLOW US
© 2019 WithinEarth All right reserved.
Design and Deavloped by Technoheaven Consultancy
General Terms and conditions
Privacy Policy
Cookie Policy
SEARCH NOW

Notification

×

SEARCH NOW

×