Softrip's JSON API allows third parties to get user information, shop pricing and availability, and create bookings using a standard set of requests and responses.

Getting Started

Softrip's JSON API uses a standard request and response format.

Requests

Requests should be built as HTTP POST or GET messages. All requests must have a "TransType" parameter. All input parameters should be passed as simple key-value pairs (except in the case of BookCommands in the "BOOK" request, see below).
For example, a login request will look like this:

Response

Responses are returned as JSON objects. All response have the following members, in addition to process-specific members (in the "content" placeholder below):

Members:

• statuscode (int) - Should always return 200. This is a successful process. In cases of communication or HTTP errors, the response will most likely be blank.

• iserror (boolean) - Indicates that at least one error occurred during processing. For details on the errors that occurred, check the "errormessage" field and "errors" array

• errormessage (string) - The first error that occurred during processing. Same as the first member of the "errors" array.

• errors (array of strings) - The array of errors that occurred during processing.

• warnings (array of strings) - The array of warning that were raised during processing. These are similar to the errors, but did not cause the process to fail altogether. If your requests are causing warnings, make sure to carefully review the warnings to make sure the result set you're receiving is what you expect. Normal operation should not return any warnings.

• stacktrace (string) - Execution stack of the process. Only used for debugging purposes.

• processingtime (numeric) - The number of seconds it took for the server to process the request

• friendlyerror (string) - A user-friendly error message in case the request failed

• friendlyerrortype (string) - Can be either "SYSTEM" for system-related errors (timeouts, database unavailable etc.), or "BUSINESSLOGIC" for logic-related errors (missing/invalid inputs, services unavailable, etc.). In general, a SYSTEM error indicates a problem on the Softrip side, and a BUSINESSLOGIC error indicates a problem on the API consumer side.

• content (object) - The payload for the response. This is where the response object will be stored.

When consuming the API, always make sure to check the "iserror" boolean field. This will indicate if there was an error processing your request. If it is set to True, the "errors" array will contain an array of error messages that occurred during processing. The "errormessage" field contains the description of the first error that occurred (usually the most important one).
The "warnings" field contains an array of warning that occurred during processing. These are warning that didn't cause the process to fail, but may contain important messages about the process, indicating that the result set may not be what was expected.

Terminology and Formats

Dates

All dates should be formatted as strings in yyyy-MM-dd format.

Examples:

• 23 Sep 2014 will be represented by the string "2014-09-23"

• 1 Jan 2008 will be represented by the string "2008-01-01"

Masks

Masks are strings representing rooms and occupancies in a request (SHOP or BOOK). In a mask, each "A" represents an adult, each "C" represents a child (must be followed by the child's age), and each "/" (forward slash) represents a new room.

Examples:

• AA - Two adults in one room

• AA/A - One room with two adults + one room with one adult

• AAC5 - One room with two adults and one 5-year old child

Shares

If the product is configured to allow shared rooms, shared rooms can be booked using a special mask value to indicate the number of guests in a room, and their gender.

• S - Shared Room

• F - Female guest

• M - Male guest

• X - Gender irrelevant (males and females sharing room)

• [Room Mask] - The occupancy of the room to share

Examples:

• SFAA - One female guest in a double room

• SMAAA - One male guest in a triple room

• SXAA - One guest (male or female) in a double room

Suppliers & Services

Suppliers are companies providing services. For example, a hotel is a supplier, which provides room categories as services. Each supplier has a unique ID "SupplierID". Supplier IDs are strings representing this Supplier.

Examples:

• MX-CUNMP is the supplier ID for the hotel "Moon Palace" in Cancun, Mexico.

Services are provided by suppliers. Each service will be represented by a supplier-unique service ID "ServiceID". Note that a same service ID can be reused for different suppliers.
To uniquely identify a specific service, use both a supplierid and serviceid.

Examples:

• The "Standard Room" service provided by the Moon Palace hotel will have a service ID of "STD", and a supplier ID of "MX-CUNMP".

Service Types are strings indicating what type of service a supplierID and serviceID combination represents. The Standard Room provided by Moon Palace hotel will have a service type of "HTL".
Valid service types:

• AIR - Air

• CAR - Car Rental

• CNV - Conveyance (Multi-day shared bus/transport - For escorted tours)

• CRU - Cruise

• DRK - Drink

• ENF - Entrance Fee

• EXP - Expense

• FEE - Fee

• FOR - Foreign Operator

• GDE - Guide

• HTL - Hotel

• INS - Insurance

• INV - Inventory Management

• MIS - Miscellaneous

• PKG - Package

• PRO - Promotions and discounts

• RST - Meal (Restaurant)

• SHP - Shipping

• SST - Sightseeing Tour

• TIP - Tip

• TRA - Rail (Train - Per seat)

• TRF - Transfer

• TRS - Rail (Sleeper Train - Per cabin)

Products

Products are collections of related services. In order to sell a service, it must be part of a product. The product contains a list of related services, and markup rules determining the selling price and other pricing/costing/commission rules for those services.
Products are identified by a unique ProductCode (string).
There are two types of products in Softrip:

• Package

  • Packages are products with fixed itinerary, duration, and departure dates. For example, a package may be "8 Day Tour of Italy and Sicily". It will have a fixed duration, only depart on certain dates, and the itinerary will be pre-built (e.g. "Day 1 - Visit Rome, Day 2 - Tuscan winery your etc.").

• List

  • Used for FIT/build-your-own bookings. List are collections of related services that can be booked for any date, any duration. For example, the product "List of services in Cancun, Mexico" will have all the hotel services the provder wants to sell, and may also include some optional transfers or sightseeing tours.

Contacts

Softrip Contacts represent people. For example, each passenger on a reservation is a contact in the system.
In addition, travel agents are also stored as Contacts.
Contacts are represented by a unique integer as their ContactID.

Customers

Softrip Customers represent organizations or companies that purchase from the provider. For example, a travel agency will have a Customer record in the system.
Customer are represented by a unique CustomerID string. Usually, the CustomerID will be the travel agency's IATA or CLIA number.

Price vs. DisplayPrice

If you are familiar with Price and DisplayPrice, note that the API always returns DisplayPrice in its "price" field.
If you are not familiar with Price vs. DisplayPrice:

Price and DisplayPrice are values that help control the display of the price of individual services on a reservation or shopping result. Price is the actual, calculated price of the service in question. DisplayPrice is the price we will show on invoices etc. Note that a given's reservation total Price and total DisplayPrice must ALWAYS match.

Examples:

• One reservation with two services: A hotel at $250 and a transfer at $50. To hide the price of the individual services, we can add a package service that serves as a wrapper. In that case, the Prices and DisplayPrices of the services will be as follows:

• One reservation with two services: A hotel at $250 and a transfer at $50. To hide the price of the individual services, and create a discounted package price ("Book hotel and transfer together and SAVE!"), we can add a package service that serves as a wrapper, and changes the total Price and DisplayPrice on the reservation:

Sessioned Calls

Sessioned calls are always tied to a Softrip Reservation System or CMS session. If your company has its own homepage and static pages on a third-party platform (e.g. Joomla, Drupal), these calls can be used to change the content of the page based on the web user's status. For example, a logged-in user would see "My Account" in the header instead of "Log In" if they were not authenticated.

SessionLess Calls

SessionLess calls are not tied to a Softrip Reservation System or CMS session. These are used by third-party custom front-ends that use Softrip's API as a booking back-end, or to pull content into a third-party web platform (e.g. Joomla, Drupal).