Getting started with HSP API

This guide will lead and help to implement the HSP API .

Integrating HSP API has few aspects that highly recommended to plan before starting the integration:

  • How to implement the API, which response you would like to receive - there are multi options to receive different results.
  • How to set default User settings.
  • How to build your Client hierarchy.

On-boarding Process

Step 1: Client to fill a Form

Client account card will be created with default settings under Cert environment.

Email with all relevant details will be sent by the support team with endpoints, credentials, Documentation and Postman API examples.

Step 2: Development and configuration

Before starting to implement the API, go to ‘Manage Client Settings’ article and review the settings options and markups.

HSP API allows to receive Hotels response with different details, go to ‘Hotels API’ article and review all API aspects, which parameters are available on each request and how it impact the response that API return results.

Once you clear how you prefer to display results on your side, you can configure the system accordingly.

Step 3: Certification test

Cert environment is a replica of the Production environment and will allow you to test your integration and see how it would work once you move to production.

Cert environment is available at any moment if you would like to implement a new feature or do any upgrade on your side and perform testing before launch in your production environment.

Will allow us to verify that HSP API integration was done correctly and avoid mistakes between the 3 systems.

Step 4: Access to Live

Once the certification been completed successfully :
Client account card will be created with default settings under the Prod (Live) environment .

Email with all Live details will be sent by support team with endpoints and credentials .

Admin user has to login and set the relevant settings, activate Accounts (suppliers) per user, set markups and more .


Going Live

Congratulations, HSP API integration completed and ready to Go Live and start perform Live bookings.

Make sure all settings have been set in Production environment.

Verify Accounts (suppliers) been activated under the relevant user.

Markup was set on each Account (supplier) HSP platform been set.

For Security reason set a strong password and replace the password once a while .


Understanding HSP API

HSP API provides methods for Authentication, Search & booking flow, Post Booking and Financial reports.

Authentication

The HSP API operates as a session-based service, so proper session creation and management are crucial.

There are two methods to generate a session ID :

  • Login request: Initiate a "Login" request using username and password. the response return the Session ID .
  • Search Hotels request: By starting a "Search Hotels" request with username and password, the response return a Session ID in addition to Hotels results.

More information - Click here.

The Session ID is essential for continuing the workflow and will be valid for approximately 40 minutes, after the session expires it will be required to generate a new session ID.

  • Session ID is used to identify a specific session flow in HSP GLogs system.
  • Session ID in essential when you need submit a ticket to support team to answer questions regarding a specific Search / booking flow

Clients that implementing cache or connecting to Meta-searches there is an option to avoid from storing the session and all relevant dumps.

  • Stateless – Allows to perform Search Hotels calls (only) without storing the session and all related dumps, mainly to display availability and minimum room rates in Meta-Searches or for other needs.

Using Stateless mode won't allow to call other API calls that requires sessions ID.

  • Stateful – Allow to perform full booking flow (from Search to Book), in addition the system will save and store the session and all related dumps for 7 days, after that it will be deleted
    (Sessions and dumps can be save for longer period – check the Offering pricing plan).

More information - Click here.

Search Hotels

Search Hotels response return all properties that been returned by the client's active accounts (suppliers).

Search Hotels return hotels details according the the 'detail Level' that been sent in the search hotels request.

Detail Level has 9 options - you can review and decide which option return the best results according to your needs.

Search Hotels supports searching by :

  • Hotel IDs (up to 3,000 IDs in a single request)

Search by Hotel IDs requires to download list of all properties and manage on the Client side list of IDs per destination (for more details go to Hotel Level content article) .

  • Geo Codes (Latitude & Longitude) with a radius (up to 75 Km)

Search by Geo Code requires to use a third party tool to get the Lat & Long of the destination that is interested to search and which radius to send.

👍

Note :

HSP is online and not using any kind of caching in order to store results, all rates, availability and cancellation policy is as returned by suppliers, online.

if a supplier is returning cache data HSP has no way to identify it.

More information - Click here.

Get Packages

Get Packages return detailed room data based on a single Hotel ID which is obtained in the Search Hotels response (Hotels that weren't returned in the session response won’t be allowed to call by Get Packages).

It also offers additional capabilities for room-related information, including details about profits, commissions, hotel taxes and fees, and for supported suppliers, the SRSP (Supplier Recommended Selling Price).

More information - Click here.

Get Cancellation Policy

Get Cancellation Policy returns detailed and updated information about the rooms cancellation deadlines, supplier remarks and cxl fees - based on a single/multiple PackageID’s for rooms that returned in the Get Packages step .

The cancellation policy request should be used before sending a booking request.

More information - Click here.

Get Payment Preferences

Get Payment Preferences returns the booking payment options based on the PackageID based on the PackageID for rooms that returned in the Get Packages step .

It also offers additional capabilities such as including the cxl-policy in the response .

More information - Click here.

Book Hotel

HSP supports booking by credit line (Cash / NET), Credit Card (Gross) and Virtual Credit Card (VCC).

It also offers additional capabilities such as custom booking reference, internal agent references and more .
Once a successful booking is made, HSP will assign OrderID & SegmentID as well as booking status and more information.

To understand more about Order/Segment Statuses - Click here.

Segment ID – a unique number that represent a Package (room) in HSP platform .
There are suppliers that for a multi rooms reservation, generate a unique identifier for each room – HSP generate a unique Segment ID for each room as well.
Suppliers that return a single identifier for multi rooms reservation – HSP generate a single Segment ID for all rooms.

Order ID – a unique number that represent a single room or multi rooms reservation.
Note - a OrderID can have multiple SegmentIDs . But a single SegmentID can only be assigned to a single OrderID.
Client can send an existing OrderID in order to relate (add) a new room to an exist reservation.

Check Status

Check Status returns the updated status of any existing booking .

More information - Click here.

Cancel Reservation

Cancel Reservation submits a request to cancel any existing booking .

More information - Click here.

GLogs

At HSP, we believe in technical transparency and empowering users through self-service platforms.

Session viewer
To embody these values, we've created the Session Viewer tool - this innovative tool enables users to observe, preserve, and scrutinize every action taken during a session. This includes monitoring requests and responses both to and from the HSP API, as well as interactions with supplier APIs.

Transactions
The transactions section (under Glogs) allows you to inspect any failed booking attempts on a specific date, and to review in depth any errors which may have occurred during the activity.

More information - Click here.

Errors Handling

HSP offers a comprehensive library of unified error codes that correspond to a range of error codes and messages from different suppliers.

Each error code comes along with the respective explanation and handling.

There are alerts / warning errors like check-in after check-out, credit card is incorrect and etc. - that you can display to end consumer to fill correct data.
There are type of errors that required additional investigation through GLogs.

More information - Click here.

Financial Reports

HSP offers order and financial services that allow retrieval of full information regarding orders and their financial details. These services are especially useful when dealing with synchronization to external accounting and billing systems on the Client side.

More information - Click here.


Understanding Client Hierarchy

The HSP platform is a hierarchical, multi-layered system that streamlines the management of various nodes, branches, users.

At the core of this system are its administrative and organizational controls, inherently hierarchical, which facilitate the creation, setup, and management of complex organizational structures and distribution networks. HSP functions on a hierarchical system, necessitating the definition of relevant Nodes and Users, including API users, agencies, and admin users.

In light of this, it is recommended to plan and design ahead the Nodes & Users hierarchy .

Understanding default user settings

Settings & Configurations
HSP offers various settings, features, and configurations that can be customized to meet your business/company's needs, such as yield management (static or dynamic markups), VCC, timeout settings, Hotel Rules, and much more.

These settings directly impact the results and require careful review and configuration in the Back-Office.

To explore basic and advanced settings and features learn more under the "MANAGE SETTINGS" section.