• ron api

RON XML API Reference

Index

• Introduction

• API Overview

• Nulls and Empty Strings

• Date Formats

• YSN Fields

• Training Mode Mappings

Function Reference

• ping

• login

• readCurrentLogin

• readCreditStatus

• readPaymentOptions

• readHosts

• readHostDetails

• readPaxTypes

• readTours

• readTourDetails

• readTourWebDetails

• readTourTimes

• readTourBases

• readTourPickups

• readTourPrices

• readTourPricesRange

• readTourAvailability

• readTourAvailabilityRange

• checkReservation

• writeReservation

• writeCancellation

---

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

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 and the link you will be using to develop and interface between your system and RON.

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)

Note that 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.

---

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.

NOTE! Distributor mappings are only functional in the live environment.

Example

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

Results

 string(42) "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
 }

Current User Fields

Current Organisation Fields

---

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 Statuses

---

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
 }

Payment Option Fields

Example Payment Options

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.

---

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
}

Host List Fields

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 associative array of extended information for the host including contact information.

Example

 results = api.readHostDetails('BCGI')

Results

host details record

Host Details Fields

---

readPaxTypes

array readPaxTypes (string hostid)

Returns an indexed array of associative arrays containing the pax type information for the host.

Example

 results = api.readPaxTypes('FF')

Results

  array(
    [0] => pax type record,
    ...
    [n-1] => pax type record
  )

Pax Type Fields

Pax Types and Reservation Fields

An operator can customise the pax type labels to suit her products. This can include moving the label of one pax type to another field. For example, the operator could change the infant pax type to a new type called "Family Child" and then change the user defined pax type to infant. The pax types would still need to be booked in the original reservation field names. In the previous example, family children would be booked in the intNoPax_Infant field and infants would be booked in the intNoPax_UDef1 field.

Pax Type Associations

On any given trip, if a pax type's associated pax type (intWebPaxAssoc) has no price then that pax type cannot be booked. For example, the default association of pax type 1 is to itself, therefore to book an adult, there must be an adult price. That is the same for all pax types except pax type 2. Pax type 2 by default is associated to pax type 1 therefore to book an infant there must be an adult price and at least one adult travelling. The default pax type associations cover the need of many operators to allow infants to travel free with their parent or guardian.

---

readTours

array readTours (string hostid)

Returns an array of associative arrays each containing the tour code and tour name for all the publicly visible tours from the specified host.

Example

 results = api.readTours('OZEX')

Results

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

Tour List Fields

---

readTourDetails

array readTourDetails (string hostid, string tourcode)

Returns an associative array of extended tour information from the host for the specified tour code.

Example

 results = api.readTourDetails('OZEX', 'BRUCE')

Results

tour details record

Tour Details Fields

* The travel terms field is not yet supported by all operators.

Travel Terms Fields

---

readTourWebDetails

array readTourWebDetails (string hostid, string tourcode, boolean images)

Returns an associative array of promotional and descriptive information for the tour. Due to the size of base 64 encoded images, you can optionally request that image information not be returned by sending false as the third parameter.

Example

 results = api.readTourWebDetails('KIWIEX', 'FULLMONTY', True)

Results

tour web details record

Tour Web Details Fields

---

readTourTimes

array readTourTimes (string hostid, string tourcode)

Returns an array of associative arrays from the host each containing the details of a departure time for the specified tour.

Example

 results = api.readTourTimes('GA', 'GIECO')

Results

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

Tour Times Fields

---

readTourBases

array readTourBases (string hostid, string tourcode)

Returns an array of associative arrays from the host each containing the details of a fare basis and type for the specified tour.

NOTE! Any subsequent function that requires both a basis and subbasis id requires a pair of ids from a single record in the results. You cannot mix and match basis and subbasis ids from different records.

Example

 results = api.readTourBases('RT', 'ATR')

Results

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

Tour Bases Fields

---

readTourPickups

array readTourPickups (string hostid, string tourcode, integer tourtimeid, integer basisid)

Returns an array of associative arrays from the host each containing the details of a pickup location and time for the specified tour, time and basis combination.

To uniquely and correctly identify a pickup, you must specify the pickup route code, pickup time id and pickup id. The recommended method of doing this is to use the strPickupKey field when selecting a pickup and when writing a reservation.

Example

 results = api.readTourPickups('RT', 'BUNGY', 137, 744)

Results

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

Tour Pickups Fields

---

readTourPrices

array readTourPrices (string hostid, string tourcode, integer basisid, integer subbasisid, string tourdate, integer tourtimeid, integer pickupid, integer dropoffid)

Returns an associative array from the host containing price, levy and commission information for adult, child, infant, foc and udef pax types. If the tour sell value for a pax type is calculated as zero or the pax type assoc flag is false, that pax type should be disabled on the client. Pickup and dropoff ids are optional but should be provided if a pickup is selected in the booking.

Example

 results = api.readTourPrices('ATA', 'AR3', 423, 1542, '31-OCT-2009', 57)

Results

array(29) {
    ["curAdultTourSell"] => float(227)
    ["curAdultTourLevy"] => float(10)
    ["curChildTourSell"] => float(187)
    ["curChildTourLevy"] => float(10)
    ["curInfantTourSell"] => float(187)
    ["curInfantTourLevy"] => float(10)
    ["curFOCTourSell"] => float(0)
    ["curFOCTourLevy"] => float(0)
    ["curUDef1TourSell"] => float(0)
    ["curUDef1TourLevy"] => float(0)
    ["dblAdultCommission"] => float(18.75)
    ["dblChildCommission"] => float(12.75)
    ["dblInfantCommission"] => float(12.75)
    ["dblFOCCommission"]=> float(0)
    ["dblUDef1Commission"]=> float(0)
    ["curDeposit"] => float(0)
    ["curBookingFee"] => float(0)
    ["curCardFee"] => float(0)
    ["curPayOnBoard"] => float(0)
    ["curTourLevy"] => float(0)
    ["curTotal"] => float(0)
    ["strCurrencyType"] => string(3) "AUD"
    ["strCurrencySymbol"] => string(1) "$"
    ["strPaymentOption"] => string(6) "credit"
    ["boolAdultAssoc"] => bool(true)
    ["boolChildAssoc"] => bool(true)
    ["boolInfantAssoc"] => bool(true)
    ["boolFOCAssoc"] => bool(false)
    ["boolUDef1Assoc"] => bool(false)
}

Tour Prices Fields

---

readTourPricesRange

array readTourPricesRange (array productList)

This function allows the multiple price queries to be processed in one call. The product list arrays are returned with the price information appended. If any call produces a fault, the function continues running and returns the individual fault as part of the results. Note that price ranges cannot include bus route pricing. Each item in the product list must contain a host, tour code, basis id, subbasis id and time id.

Example

 query1 = array(
   'strHostID' => 'AS',
   'strTourCode' => 'WDWWMBWC',
   'intBasisID' => 317,
   'intSubBasisID' => 988,
   'dteTourDate' => '21-Dec-2012',
   'intTourTimeID' => 82
 )

 query2 = array(
   'strHostID' => 'EC',
   'strTourCode' => 'BYDTWD',
   'intBasisID' => 22342,
   'intSubBasisID' => 4122,
   'dteTourDate' => '21-Dec-2012',
   'intTourTimeID' => 711
 )

 results = api.readTourPricesRange(array(query1, query2))

Results

  array(
    array(
      "strHostID" => "AS",
      "strTourCode" => "WDWWMBWC",
      "intBasisID" => 317,
      "intSubBasisID" => 988,
      "dteTourDate" => "21-Dec-2012",
      "intTourTimeID" => 82,
      "curAdultTourSell" => 575.00,
      "curAdultTourLevy" => 25.00,
      "curInfantTourSell" => 0.00,
      "curInfantTourLevy" => 0.00,
      "curChildTourSell" => 460.00,
      "curChildTourLevy" => 25.00,
      "curFOCTourSell" => 0.00,
      "curFOCTourLevy" => 0.00,
      "curUDef1TourSell" => 0.00,
      "curUDef1TourLevy" => 0.00,
      "strCurrencyType" => "AUD",
      "strCurrencySymbol" => "$",
      "strPaymentOption" => "comm-agent/bal-pob",
      "dblAdultCommission" => 19.6667,
      "dblInfantCommission" => 0.00,
      "dblChildCommission" => 0.00,
      "dblFOCCommission" => 0.00,
      "dblUDef1Commission" => 0.00,
      "boolAdultAssoc" => true,
      "boolInfantAssoc" => false,
      "boolChildAssoc" => true,
      "boolFOCAssoc" => false,
      "boolUDef1Assoc" => false
    ),
    array(
      "strHostID" => "EC",
      "strTourCode" => "BYDTWD",
      "intBasisID" => 22342,
      "intSubBasisID" => 4122,
      "dteTourDate" => "21-Dec-2012",
      "intTourTimeID" => 711,
      "curAdultTourSell" => 0.00,
      "curAdultTourLevy" => 0.00,
      "curInfantTourSell" => 0.00,
      "curInfantTourLevy" => 0.00,
      "curChildTourSell" => 0.00,
      "curChildTourLevy" => 0.00,
      "curFOCTourSell" => 0.00,
      "curFOCTourLevy" => 0.00,
      "curUDef1TourSell" => 0.00,
      "curUDef1TourLevy" => 0.00,
      "strCurrencyType" => "AUD",
      "strCurrencySymbol" => "$",
      "strPaymentOption" => "comm-agent/bal-pob",
      "dblAdultCommission" => 0.00,
      "dblInfantCommission" => 0.00,
      "dblChildCommission" => 0.00,
      "dblFOCCommission" => 0.00,
      "dblUDef1Commission" => 0.00,
      "boolAdultAssoc" => false,
      "boolInfantAssoc" => false,
      "boolChildAssoc" => false,
      "boolFOCAssoc" => false,
      "boolUDef1Assoc" => false,
      "faultCode" => 201,
      "faultString" => "ERROR (server-ron) : ERROR (respax-external) : Specified basis does not exist."
    )
  )

---

readTourAvailability

integer readTourAvailability (string hostid, string tourcode, integer basisid, integer subbasisid, string tourdate, integer tourtimeid)

Returns an integer representing the number of places remaining on the specified trip.

Example

 results = api.readTourAvailability('KIWIEX', 'DOGLEG', 317, 988, '15-JUN-2010', 82)

Results

int(14)

---

readTourAvailabilityRange

array readTourAvailabilityRange (array productList)

This function allows the multiple availability queries to be processed in one call. The product list arrays are returned with the availability information appended. If any call produces a fault, the function continues running and returns the individual fault as part of the results. Note that availability ranges cannot include bus route availability. Each item in the product list must contain a host, tour code, basis id, subbasis id and time id.

Two additional fields are returned on top of the individual availability call: boolTrip and boolThreshold.

boolTrip

Indicates if the tour is actually running on the day in question. If the availability is zero and trip is true, the tour is running but full. If the availability is zero and trip is false, the tour is not running on that day.

boolThreshold

Indicates if the availability value has been capped by an operator threshold. If the availability is 10 and threshold is true, then there are greater than 10 seats but the operator only allows up to 10 to be visible. If the availability is 10 and threshold is false, then there really are only 10 seats remaining.

Example

 query1 = array(
   'strHostID' => 'AS',
   'strTourCode' => 'WDWWMBWC',
   'intBasisID' => 317,
   'intSubBasisID' => 988,
   'dteTourDate' => '01-Jan-2013',
   'intTourTimeID' => 82
 )

 query2 = array(
   'strHostID' => 'EC',
   'strTourCode' => 'BYDTWD',
   'intBasisID' => 22342,
   'intSubBasisID' => 2122,
   'dteTourDate' => '01-Jan-2013',
   'intTourTimeID' => 82
 )

 results = api.readTourAvailabilityRange(array(query1, query2))

Results

  array(
    array(
      "strHostID" => "AS",
      "strTourCode" => "WDWWMBWC",
      "intBasisID" => 317,
      "intSubBasisID" => 988,
      "dteTourDate" => "01-Jan-2013",
      "intTourTimeID" => 82,
      "intAvailability" => 10,
      "boolTrip" => true,
      "boolThreshold" => true
    ),
    array(
      "strHostID" => "EC",
      "strTourCode" => "BYDTWD",
      "intBasisID" => 22342,
      "intSubBasisID" => 2122,
      "dteTourDate" => "01-Jan-2013",
      "intTourTimeID" => 31,
      "intAvailability" => -1,
      "boolTrip" => false,
      "boolThreshold" => false,
      "faultCode" => 201,
      "faultString" => "ERROR (server-ron) : ERROR (respax-external) : Specified basis does not exist."
    )
  )

---

checkReservation

array checkReservation (string hostid, array reservation, array payment)

Runs a series of precommit checks on a reservation without attempting to commit. See writeReservation for the structure of the reservation and payment array parameters. Returns an array of errors in the reservation. An empty array means no errors were found in the precommit check.

Example

 reservation = array(
    'strTourCode' => 'COBBER',
    'intBasisID' => 338,
    'dteTourDate' => "31-OCT-2007",
    'intTourTimeID' => 144,
    'strPaxFirstName' => 'Wernher',
    'strPaxLastName' => 'von Braun',
    'strPaxEmail' => 'wernher@example.com',
    'intNoPax_Adults' => 1,
 )
 
 payment = array(
    'strPaymentOption' => 'full-agent'
 )

 results = api.checkReservation('OZEX', reservation, payment)

Results

 array(2) {
   [0]=> string(53) "No room type or subbasis id provided for reservation."
   [1]=> string(329) "The requested payment option was rejected by the operator. You requested (full-agent) which means: Full amount is collected by the agent at time of booking. Your credit status with the operator does not allow this payment option to be processed. Please contact the operator for more information or to review your credit status."
 }

---

writeReservation

integer writeReservation (string hostid, int confirmation, array reservation, array payment)

• Sends the details of the reservations array to the host and returns a confirmation number if the reservation is successfully committed. Provide a confirmation number of -1 to create a new reservation. Updating an existing reservation is not supported at this time.

The previous system of writing pickups by manually providing strPickupRouteCode, intPickupRouteTimeID and intPickupID has been replaced with a single field strPickupKey. To specify that the reservation has no pickup you can do one of 4 things:

1. Do not provide the strPickupKey field.
2. Set strPickupKey field to null.
3. Set strPickupKey field to an empty string.
4. Set strPickupKey field to the string value 0:0:0.

All these options assume you are no longer passing the individual pickup related fields.

Payment defines how much money you are collecting in the booking. Payment options available to you when booking is determined by your Credit status with each operator. See readPaymentOptions for information on determining a valid payment option.

Example

 reservation = array(
    'strTourCode' => 'COBBER',
    'intBasisID' => 338,
    'intSubBasisID' => 1477,
    'dteTourDate' => "31-OCT-2007",
    'intTourTimeID' => 144,
    'strPaxFirstName' => 'Wernher',
    'strPaxLastName' => 'von Braun',
    'strPaxEmail' => 'wernher@example.com',
    'intNoPax_Adults' => 2,
    'strGeneralComment' => 'Alergic to ginger toupees.'
 )
 
 payment = array(
    'strPaymentOption' => 'full-agent'
 )

 results = api.writeReservation('OZEX', -1, reservation, payment)

Results

int(69777)

Reservations Fields

Payment Options

See readPaymentOptions for information on determining a valid payment option.

---

writeCancellation

boolean writeCancellation (string hostid, integer confirmation, string reason)

Cancels a reservation at the host with the specified confirmation number and updates the reservation with the cancellation reason. It returns the cofirmation number if successful.

Example

 results = api.writeCancellation('OZEX', 69777, 'Pax suffered a spleen injury.')

Results

int(69777)