RON XML API Reference

Introduction

The Respax Operator Network (RON) XML API is the window into a real-time tour operator portal network connecting in real-time to major Australian and New Zealand tour operators. The Respax Operator Network enables development of interfaces to directly interact with each operator retrieving tour details with imagery, check availability, check prices and commit bookings directly into the remote operators system. For a more detailed overview of RON, please checkout the RON Introduction page to get started with your interface. You will need to register as a user on http://ron.respax.com.au. As part of the registration process, you will be sent an email with your user details.

While developing and testing your interface, please use the training server:

Training Database

https://ron.respax.com.au:30443/section/xmlrpc/server-ron.php?config=train

Once your interface is complete and you are certified live, change to the live server:

Live Database

https://ron.respax.com.au:30443/section/xmlrpc/server-ron.php?config=live

Contents

- 1.1 Training Database
- 1.2 Live Database
2 API Overview
3 Nulls and Empty Strings
4 Date Formats
5 YSN Fields
6 Training Mode Mappings
7 Function Reference
- 7.1 ping
- 7.2 login
- 7.3 readCurrentLogin
- 7.4 writeCurrentLogin
- 7.5 readCreditStatus
- 7.6 readPaymentOptions
- 7.7 readCreditCardTypes
- 7.8 readHosts
- 7.9 readHostDetails
- 7.10 readPaxTypes
- 7.11 readOrigins
- 7.12 readSources
- 7.13 readTours
- 7.14 readTourDetails
- 7.15 readTourWebDetails
- 7.16 readTourTimes
- 7.17 readTourBases
- 7.18 readTourPickups
- 7.19 readTourPrices
- 7.20 readTourPricesRange
- 7.21 readTourAvailability
- 7.22 readTourAvailabilityRange
- 7.23 checkReservation
- 7.24 checkReservationAndPrices
- 7.25 writeReservation
- 7.26 Payment Options
- 7.27 writeCancellation

API Overview

This XML-RPC (Extensible Markup Language - Remote Procedure Calling) API (Application Programming Interface) provides a simplified method to access a central database which in turn connects to multiple tour operator ResPax databases. The functions listed here allow a client application to view tour content as well as assemble the necessary information to commit a reservation into a host operator's database.

XML-RPC Home
http://www.xmlrpc.com/

Database records are returned as associative arrays where the field name maps on to the field value. Anywhere that an example result refers to a record (eg web details record) refer to the fields table for a list of all field names and a description of their values. When writing new reservations or updating existing reservations, assemble a record as an associative array using the reservations fields table as a guide.

With the exception of ping, searchHost and searchKeyWord, the client must have successfully logged in using the login function before calling other functions. In addition, the session id returned by login must be appended to the server address as an additional request variable for these functions. Examples are provided below.

Nulls and Empty Strings

Currently XML-RPC cannot represent null values. As a result, null values in the RON or operator databases are converted to empty strings. For the purposes of this API, any string field that contains an empty string should be considered an empty string. Any non string field that contains an empty string should be considered a null value.

Date Formats

Dates in the API can be passed as a string representation in the format dd-MMM-yyyy. For Example:

26-JAN-1788 (26th of January, 1788)  
21-DEC-2012 (21st of December, 2012)

The API has support for the ISO 8601 standard. For example:

1788-01-26 (26th of January, 1788)  
2012-12-21 (21st of December, 2012)

week number and ordinal date formats are not supported

http://www.w3.org/TR/NOTE-datetime

http://en.wikipedia.org/wiki/ISO_8601

Passing dates in any other format may produce unexpected results.

YSN Fields

Fields prefixed with ysn are legacy boolean variants. For such fields a value of 0 (zero) equates to False and a value of -1 (negative one) equates to True.

Training Mode Mappings

To speed up development and testing, a set of generic mappings for each host are automatically in place when accessing the API in training mode. If you are seeing variations in results between live and training, keep in mind that you are using the generic test mappings in training mode and not mappings specific to your account.

Function Reference

ping

string ping ()

This simple test function returns the string "pong" if your xmlrpc call has been successful.

Example

results = api.ping()

Results

string(4) "pong"

login

string login (string userid, string password, string distributor)

Validates the userid and password against the RON database. If the user is valid, associated globals in the server session are set and a string containing the session id variable name and value is returned. This string needs to be appended as an additional request variable to the server address for most subsequent function calls.

Optionally you can pass a distributor id with the login details. This will look up the equivalent agent in each operator's database and set that as the current agent instead of the agent associated with the login details.

Distributor mappings are only functional in the live environment.

Example

results = api.login('albert', 'secret')

Results

string(42) "PHPSESSID=1bea4b6a9491805f986ad14389a1a25e"

Usage

# Use the unmodified server address for authentication.   
server_address = 'https://ron.respax.com.au:30443/section/xmlrpc/server-ron.php?config=train'   
api.address = server_address   
results = api.login('albert', 'secret')     

# If authentication was successful, append the session id to the server address.   
if faultCode not in results:   
		api.address = server_address + '&' + results

Assuming authentication was successful, api.address should hold the following.

string(117) "https://ron.respax.com.au:30443/section/xmlrpc/server-ron.php?config=train&PHPSESSID=1bea4b6a9491805f986ad14389a1a25e"

readCurrentLogin

array readCurrentLogin ()

Returns an array of two elements. The first element containing the details of the currently logged in user and the second element the details of the current user's organisation.

Example

results = api.readCurrentLogin()

Results

array(2) {   
	["arrCurrentUser"] => current user record,   
	["arrCurrentOrganisation"] => current organisation record  
	["arrHost"] => deprecated - information available from readHostDetails   
}

Field Name	Description
Current User Fields
intID	Unique integer identifier for the user.
strUserID	User id used to login.
strFirstName	User's first name. (Maximum 50 Characters)
strLastName	User's last name.(Maximum 50 Characters)
strEmail	User's email address.
strPhone	User's contact phone number.

Field Name	Description
Current Organisation Fields
intID	Unique integer identifier for the organistion.
strOrgID	String identifier for the organisation.
strName	Name of the organisation.

Host Fields

Deprecated, use readHostDetails for additional host information.

writeCurrentLogin

boolean writeCurrentLogin (array user, array organisation)

Allows the currently authenticated user to update his user and organisation details. Returns the boolean value True if successful. It is not necessary to include all fields listed below in the parameter arrays. Only the fields requiring an update must be provided. Note that if you change the password, the new password will be required for subsequent calls to the login function.

Example

user = array('strEmail' => 'example@example.com')   
organisation = array('strReservationsEmail' => 'example@example.com')   
results = api.writeCurrentLogin(user, organisation)

Results

boolean True

Field Name	Description
User Update Fields
strFirstName	First or given name of the user.
strLastName	Last or family name of the user.
strEmail	Primary contact email address.
strPhone	Primary contact phone number.
strPassword	The password required to authenticate the user.

Field Name	Description
Organisation Update Fields
strReservations	Contact name for any reservations related communications.
strReservationsEmail	Email address for reservations.
strReservationsPhone	Phone number for reservations.
strTechnical	Contact name for any technical support related communications.
strTechnicalEmail	Email address for technical support.
strTechnicalPhone	Phone number for technical support.
strAccounts	Contact name for any accounts related communications.
strAccountsEmail	Email address for accounts.
strAccountsPhone	Phone number for accounts.

readCreditStatus

string readCreditStatus (string hostid)

Returns the credit status of the current user at the host specified.

Example

results = api.readCreditStatus('TEE')

Results

string(3) "dep"

Credit Status	Payment Options
Credit Statuses
full	See readPaymentOptions for information on determining a valid payment option.
fulllevy	See readPaymentOptions for information on determining a valid payment option.
dep	See readPaymentOptions for information on determining a valid payment option.
fullpob	See readPaymentOptions for information on determining a valid payment option.
stop	Stopped agents cannot process payments and must be blocked from making new bookings.

readPaymentOptions

array readPaymentOptions (string hostid)

Returns an array of zero or more associative arrays each representing a payment option that is valid for the currently logged in user at the host specified.

Example

results = api.readPaymentOptions('ATA');

Results

array(n) {   
	[0] => payment option record,   
	...   
	[n-1] => payment option record   }

Field Name	Description
Payment Option Fields
strCode	Unique identifier for the payment option.
strDescription	Description of the normal method of payment collection when using this payment option.
ysnDefault	Indicates the default payment option that is preferred by the operator.
strCode_Deprecated	Payment option codes have been migrated to a standard format. All operators should now accept the standard format. (strCode)

Payment Option	Description
Example Payment Options
full-agent	Full amount is collected by the agent at time of booking.
bal-agent/levy-pob	Full amount less the levy is collected by the agent at time of booking. Levy is collected by the tour operator on day of travel.
comm-agent/bal-pob	Deposit is collected by the agent at time of booking. Balance is collected by the tour operator on day of travel.
full-ccard	Full amount is collected on credit card at time of booking.
bal-ccard/levy-pob	Full amount less the levy is collected on credit card at time of booking. Levy is collected by the operator on day of travel.
full-pob	Full amount is collected by the tour operator on day of travel.
comm-ccard/bal-pob	Deposit is collected on credit card at time of booking. Balance is collected by the tour operator on day of travel.
comm-agent/bal-ccard	Deposit is collected by the agent at time of booking. Balance is collected on credit card at time of booking.

When checking or writing a reservation you must provide a payment option that is returned by this function. Any attempt to use a payment option that is not returned by this function will result in the booking being rejected. If the payment option you want to use is not returned by this function, contact the operator to review your credit status.

readCreditCardTypes

array readCreditCardTypes (string hostid)

Returns an array of zero or more associative arrays each representing a credit card type supported by the host for processing 'ccard' payments.

Example

results = api.readCreditCardTypes('TW');

Results

array(n) {   
	[0] => credit card type record,   
	...   
	[n-1] => credit card type record   
}

Field Name	Description	Type
Credit Card Type Fields
strCCTypeID	Unique identifier for the credit card type.	string(10)
strCCDesc	Description of the credit card type.	string(50)
dblWebCardFee	The processing fee charged by the host. This is a percentage applied to the amount being charged.	float

readHosts

array readHosts ()

Returns an array of associative arrays each containing the host id, name and a boolean value indicating the current state of the host.

Example

results = api.readHosts()

Results

array(n) {   
	[0] => host record   
	...   
	[n-1] => host record  
}

Field Name	Description
Host List Fields
strHostID	Unique identifier for the host.
strHostName	Host organisation's name.
boolServerUp	Flag to indicate if the host server is currently reachable.
boolOnline	Flag to indicate if the host configuration process is complete.
boolSecure	Flag to indicate if the RON connection to the operator is secure. Attempting to send credit card payments to an insecure host will generate an error.

About Host Status

There are two flags that must be enabled for tour content to be available. The flag boolServerUp indicates if the physical machine responded to the most recent attempt to contact it. The flag boolOnline is set by a RON administrator once the host has completed all the steps necessary to publish their tour content successfully. Function calls to any host with boolOnline disabled should be avoided as the results may not be valid.

readHostDetails

array readHostDetails (string hostid)

Returns an array containing a single associative array of extended information for the host including contact information.

Example

results = api.readHostDetails('BCGI')

Results

array(1) {   
	[0] => host details record  
}

Field Name	Description
Host Details Fields
strHostID	Unique identifier for the host.
strHostName	Host organisation's name.
boolServerUp	Flag to indicate if the host server is currently reachable.
boolOnline	Flag to indicate if the host configuration process is complete.
strConfigMode	Indicates if the host data was drawn from the live or train registrations.
strLocation	Approximate geographical location of the host.
strReservations	Name of reservations staff contact.
strReservationsEmail	Reservations email address.
strReservationsPhone	Reservations phone number.
strTechnical	Name of technical support contact.
strTechnicalEmail	Technical support email address.
strTechnicalPhone	Technical support phone number.
strAccounts	Name of accounts department contact.
strAccountsEmail	Accounts department email address.
strAccountsPhone	Accounts department phone number.
strHostType	Indicates whether the host takes live bookings or requests.
boolPOBCreditCard	deprecated
boolMandatoryOrigin	Host requires the pax origin field in reservations.
boolMandatorySource	Host requires the pax source field in reservations.
intCancellationOffset	Number of days prior to tour date that reservations for this host can be cancelled via this API. Note that other system rules may still prevent cancellations.
intMinimumTourDateOffset	Number of days prior to tour date that reservations for this host can be booked via this API. Note that resource expiries may still prevent new reservations.
strInterfaceVersion	Version of the API in use by the host.

readPaxTypes

array readPaxTypes (string hostid)