Access Keys:
Skip to content (Access Key - 0)

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Data itemTypeDescription
AgentIDStringAgent internet usercode
PasswordStringAgent internet password
BookingIdIntegerUnique identifier for a Tourplan booking
RefString (10)Tourplan booking reference. From iCom 4.0.0 on bookings Bookings can be identified in all requests by their reference or their id. It is better to use the booking reference to identify bookings. In the request specifications that follow, the term booking identifier will be used to mean that either BookingId/Id or Ref can be supplied.

...

Data itemTypeDescription
VersionStringThe version number of hostConnect.
BackendStringSpecifies whether the underlying Tourplan system is iS or V5 (from iCom 72.0.0004, iS is the only value that will be returned).

...

The option type makes a difference in a number of situations, including:

  • It determines the form in which rate information is returned (see below).
  • MPFCU is only returned if SType is N or A.
  • When AddService is called for a room-based option the type of room being booked must be specified.
  • When a room-based or group-based option is booked using AddService, one unit of inventory is consumed (1 per room booked for room-based). When a pax-based option is booked using AddService the number of units of inventory consumed is the number of adults plus the number of children.
  • Limits on the number of adults and children that can be booked in a single call to AddService depend on the option type (see the AddService section for details).
Enquiry notes group

There can be multiple notes fields per option (though prior to iCom 6. 0.00 only one was accessible via hostConnect). If  N  is specified in  Info  then  OptEnquiryNotes  is included in the reply. Its value is all available notes are concatenated together. If  T  is specified in  Info  then the available notes are returned individually, with the note category and note text returned for each. If a value is supplied for the  NoteCategory  input field (and  T  is not included in  Info ) then only notes of the specified category are returned.

Data itemTypeDescription
OptEnquiryNotesStringOption enquiry notes.
NoteCategoryStringThe note category code (the type of note this is).
NoteTextStringThe contents of the note.
LastUpdateTimestampWhen the note was last changed.
The stay pricing group

If S is specified in the Info data item, then stay pricing and availability are returned for each option. The parameters of the stay are supplied in the input parameters DateFromRoomConfig, and SCUqty or DateTo. An option that does not have a valid rate for a booking made today, for the specified start date, room configuration and length of stay is omitted from the reply. Also, only options with the specified MinimumAvailability are returned.

Rates are returned in the currency associated with the agent identified by the AgentID data item unless the RateConvert data item has a value of N (in which case they are returned in the currency they are stored in). The conversion rate for DateFrom is the one used to do the conversion.

Data itemTypeDescription
AvailabilityStringThe availability of this option for the specified stay. One of NORQOK. The remaining fields only appear if Availability is not NO.
CurrencyStringThe currency that TotalPrice is in.
TotalPriceIntegerThe total price of the stay (totalled across all rooms and all second charge units) for this option.
CommissionPercentDecimal (2dp)Percentage of commission applicable to TotalPrice
AgentPriceIntegerTotalPrice less commission.
RateIdStringAn internal Tourplan identifier for this rate. Must be supplied to AddService if this rate is booked.
RateNameString (20)The name of the rate that applies on the first day of the stay.
RateTextString (60)Rate description for the rate that applies on the first day of the stay. Omitted if blank.
MinSCUIntegerIf there is a minimum number of days or nights required to qualify for the rate returned then MinSCU specifies this minimum. Omitted if no minimum.
Stay
Pay
IntegerIf a stay/pay deal has been applied in the price calculation then this pair of fields appears and gives details of the stay/pay deal applied.
CancelHoursIntegerCancellations within this number of hours of service date incur a cancellation penalty of some sort.
LastBookableDateDateSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the last date on which these rates are available for booking. Otherwise, this field is not present.
SaleFromDateRates in this date range cannot be sold before this date. Optional (does not appear if the sale from date in Tourplan is before January 1st, 2000).
SaleToDateRates in this date range cannot be sold after this date. Optional (does not appear if the sale to date in Tourplan is more than 5 years in the future).
PeriodValueAddsElementIf present, PeriodValueAdds contains additional information about the rate returned, and contains one or PeriodValueAdd elements. Each PeriodValueAdd has a start date, an end date, the rate name for the period, the rate text for the period (if not blank) and a collection of zero or more value adds for the period
PeriodValueAddElementContains DateFromDateToRateNameRateText (optional) and a collection of zero or more value adds that apply during the period. Each value add has a Type and a Description
TypeStringThe type of value add. The types are IncludedExtra and Descriptive. For IncludedExtra the value in Description is the name of a compulsory extra that has been charged for in the stay price. The other types are various pieces of descriptive text about the rate. The Type element can have a Number attribute that contains an integer. For type IncludedExtra the number is the extra number. For type Descriptive the number is the rate voucher text field number.
NumberIntegerThe Type element can have a Number attribute. For type IncludedExtra the number is the extra number. For type Descriptive the number is the rate voucher text field number.
DescriptionStringThe descriptive text for a value add.

If a rate has been retrieved from an external system, then  OptStayResults  contains a  ExternalRateDetails  element with additional information about the external rate. The fields present within  ExternalRateDetails  are listed below.

Data itemTypeDescription
ExtSupplierIdStringThe identifier for the supplier used in the external system.
ExtOptionIdStringThe identifier for the option used in the external system.
ExtOptionDescrStringOption description used in the external system.
ExtRatePlanCodeStringThe external system's rate plan code for the rate returned.
ExtRatePlanDescrStringDescription of the rate plan code.
ExtGuaranteeStringThe type of guarantee that must be supplied to the external system in order to book this rate. One of N (none), C (credit card), P (pre-pay using credit card) or A (agency). For an agency guarantee the details passed through are configured into Tourplan. Where a credit card is involved, credit card details can be supplied to AddService.
DetailNameDetailDescriptionStringsMiscellaneous data returned by an external system that does not fit into any other field is returned as DetailNameDetailDescription pairs, in an AdditionalDetail element.
CancelPoliciesXML elementAny cancel policies returned by the external system are reported under this element, in one or more CancelPenalty elements. Each of these elements contains an optional PenaltyDescription, and an optional deadline. The deadline is absolute (in which case the time component is always returned, and the date component can be returned) or relative (which is returned as units and multiplier).
OffsetTimeUnitStringOne of Second, Hour, Day, Week, Month or Year.
OffsetUnitMultiplierIntegerThe number of OffsetTimeUnit in this relative deadline.
DeadlineDateDateDate component of absolute deadline.
DeadlineTimeTimeTime component of absolute deadline.
DepotDetailXML elementOptional data that is relevant for rental car services which will describe the depot information that the rate pertains to.

Services that are connected to external rental car systems will return additional information describing the depot configuration that the rate pertains to.  The Point_ID values must be used when adding a service of this type.

PickupDetailXML elementData describing the pickup information relevant to the rate.
DropoffDetailXML elementData describing the drop off information relevant to the rate.
LocationCodeStringThe location code that the car is being picked up/drop off from
Point_IDIntegerThe internal identifier of the Tourplan pickup/dropoff point
ExternalDepotIDIntegerThe external suppliers depot identifier for the pickup/dropoff point
PointDescriptionStringThe description/name of the pickup/dropoff point
GroupNumberIntegerInternal grouping number for the pickup/dropoff point
The rate group

If R is specified in the Info data item, then rate information is returned for each option. The main difference between the information returned in the rate group and the stay pricing is that the rate group presents information on all rates associated with an option (all room types, all apartment sizes, all extras, and so on), whereas stay pricing is focused on a particular number of pax staying in a particular room configuration.

The rates returned are on the basis of a stay starting on DateFrom, of the length given by SCUqty or DateTo. An option that does not have a valid rate for a booking made today, for the specified start date and length of stay is omitted from the reply. In other words, an option that cannot be booked today for the specified start date and length of stay is not returned.

Rates are returned in the currency associated with the agent identified by the AgentID data item unless the RateConvert data item has a value of N (in which case they are returned in the currency they are stored in). The conversion rate for the DateFrom is the one used to do the conversion.

Rates are returned within an OptRates element. Rates for each day are returned in an OptRate element. Note that for options for which the SCU quantity does not apply (such as transfers) rates are returned for one day ( DateFrom ).

If a RoomConfigs element is provided in the input then then Availability is returned for each day, and for the period as a whole (in this case it is the weakest availability across all of the daily availabilities). Also, if RoomConfigs and MinimumAvailability elements are provided then only those options whose overall availability is at least the specified minimum availability are returned. See the stay group section for a description of the Availability item.

Data itemTypeDescription
CurrencyStringThe currency of the rates returned.
PaxBreaksInteger listSome type N (non-accommodation) and type P (package) options have rates that depend on the number of people travelling. If an option has pax-break pricing, then PaxRates reports the pax break ranges (PaxBreak elements nested within a PaxBreaks element). The integers given show the start of each pax range. So, if we have the list 1, 3, 4, 8, the ranges are 1-2, 3, 4-7, 8-MPFCU. The number of adults plus (if CountChildrenInPaxBreak is true) the number of children plus (CountInfantsInPaxBreak is true) the number of infants is what determines which pax break range is applied.
MinSCUIntegerIf this value appears, then the rates returned are on the basis of a minimum night stay (or days hire) of MinSCU. If MinSCU is not reported then there is no minimum that applies during the period (effectively the minimum is 1). This feature is often used to enforce minimum night stay rules of hotels during special events.
DateDateThe date that this set of rates applies to.
RateNameString (20)The name of the rate that applies on this day of the stay.
RateTextString (60)Rate description for the rate that applies on this day of the stay. Omitted if blank.
ValueAddsElementContains a collection of value adds that apply on that date. Each value add has a Type and a Description (see the stay pricing section for more information).
FreeOfChargeBooleanIf this field is present, and is Y, then this particular day of the stay is free of charge due to a stay / pay deal. The rates returned for this day show what the day would have cost had it not been free. Note that one or more extras can be chargeable on a free day. Each such extra will contain a FreeOfCharge element (as a child of the ExtrasRate element) with a value of N.
Availability
(within OptRates)
StringOverall availability for the whole period (the weakest availability over all days of the period covered). Possible values are described in the stay pricing section.
CancelHours
(within OptRates)
IntegerOverall cancel hours for the whole period (calculated from the cancel hours of the days in the period covered). See the stay pricing section for more details in this field.
LastBookableDate
(within OptRates)
DateSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the last date on which these rates are available for booking. Otherwise, this field is not present.
SaleFrom
(within OptRates)
DateRates in this date range cannot be sold before this date. Optional (does not appear if the sale from date in Tourplan is before January 1st, 2000).
SaleTo
(within OptRates)
DateRates in this date range cannot be sold after this date. Optional (does not appear if the sale to date in Tourplan is more than 5 years in the future).
CommissionPercentDecimal (2dp)Percentage of commission applicable to the rates returned.
AdultRateChildRate,
InfantRateOptionRate
IntegerThese data items appear in the reply if and only if the option has a service type of  A  or  N.If the service type is  A then there are MPFCU values and child and infant rates (the child rate is omitted if it is 0, and likewise for the infant rate). The MPFCU different values give the rates if 1 adult stays in the apartment, 2 adults, and so on up to MPFCU adults.If the service type is  N  and the MPFCU of the option is one, then pricing is per person. One adult rate is returned (one adult rate per pax range if the option has pax breaks). Child and infant rates handling is as described above unless the service has pax breaks and PaxBrakChildRates is supplied and set to Y. In that case a child and an infant rate will be returned for each pax break defined. In this case, zero rate values are returned.If the service type is  N  and the MPFCU of the option is greater than one then pricing is per group (of up to MPFCU adults plus children). One group rate is returned (one group rate range per pax range if the option has pax breaks). The group rate(s) appear as  OptionRate  elements within a  OptionRates  element.
SingleRateDoubleRate,
TwinRateTripeRate,
QuadRateExtraAdultRate,
ExtraChildRateInfantRate,
AdultRate
IntegerThese data items appear in the reply if and only if the option has a service type of  Y  or  P  (in other words, if and only if rates are room based). The five room rates and three extra pax rates appear as separate elements within a  RoomRates  element. Any zero rates are omitted. Some packages have room and pax break pricing. For these packages, the  PaxBreaks  element contains details of where the pax break boundaries are, and the  AdultRate  elements here give the rates for those various pax breaks ( AdultRate elements appear only for packages that have room and pax break rates).By default, ExtraChildRate and InfantRate are single values and are omitted if zero. However, if the Package has pax breaks defined and the PaxBreakChildRatesis set to Y then a child and an infant rate for each pax break is returned, including zero values.The  ExtraAdultRate  is relatively rare. It only applies for properties like apartments that can accommodate more than four adults (up to the maximum given by  MaxAdult ). So, for 6 adults, for example the rate that applies is the Quad room rate plus twice  ExtraAdultRate. The  ExtraChildRate  is the per child cost of any children over and above the room capacity (if this rate is 0 then any such children are free of charge). For example, with two adults and two children in a triple room then one child is charged at  ExtraChildRate. All infants are charged at the  InfantRate.
Availability
(within OptRate)
StringAvailability for a particular day. Possible values are described in the stay pricing section.
CancelHours
(within OptRate)
IntegerCancel hours for a particular day. See the stay pricing section for more details in this field.
SellBeforeTravelIntegerSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the number of days or months in advance that the rate must be purchased. For example, if there is a 7 day sell before period, then a booking for 2012-09-27 must be made no later than 2012-09-20. This field is not present if there is no sell before requirement.
SellBeforeTypeString (1)Present if and only if SellBeforeTravel is present, and specifies the units of SellBeforeTravel. D means days and M means months.

If there are rates for 1 or more extras, then an  ExtrasRates  element appears, that contains one  ExtrasRate  element for each extra for which rate information exists.

Data itemTypeDescription
SequenceNumberIntegerThe number of the extra that this rate applies to.
FreeOfChargeBooleanOnly relevant if the main rates for the day are free of charge. If this extra is charged for on a free of charge day, then this element is present and is N.
AdultRateIntegerAppears for extras charged per person.
ChildRateIntegerAppears for extras charged per person (if non-zero).
InfantRateIntegerAppears for extras charged per person (if non-zero).
ExRateIntegerAppears for extras charged per group.
The date range group

If  D  is specified in the  Info  data item, then date range rate information is returned for each option. The two forms of rate information described above (stay pricing, rate group) are based on rates that apply for a stay that starts on a particular date and has a particular length. Date range rates show rates that apply for the various rate seasons present within a specified period.

The date ranges returned are those found within a period whose start date is  DateFrom  and whose end date is determined by  SCUqty  or  DateTo  (as per the other rate requests). Options that do not have valid rates within the specified period are not omitted from the reply.

Rates are returned in the currency associated with the agent identified by the  AgentID  data item unless the  RateConvert  data item has a value of  N  (in which case they are returned in the currency they are stored in). The conversion rate for the  DateFrom  is the one used to do the conversion.

If the option has pax breaks, then these are returned as a child element of the  OptDateRange  element (the format is the same as that used for pax break information in the rate group).

Zero or more  OptDateRange  elements are returned. The date ranges are in increasing date order, and do not overlap. There can be gaps between one date range and the next. The  DateFrom  of the first date range is never before the  DateFrom  supplied to the  OptionInfo  request (even if the date range in Tourplan starts before  DateFrom ). Likewise the  DateTo  of the final date range never goes past the end of the period enquired on.

Each  OptDateRange  contains one or more  RateSet  elements. Usually there is a single  RateSet  element, but there are multiple if there are different rates for different lengths of stay/hire period, and/or different rates on different days of the week (weekend/weekday rates for hotels, for example). If there are multiple  RateSet  elements, then each combination of day of the week and length of stay will be covered by at most one  RateSet.

The data items in the  OptDateRange  and  RateSet  elements are listed below. The main rates are returned in the  OptRate  structure already discussed in the rate group section. Note that the non-rates elements of  OptRate  are omitted in this context (most of them can be found in the  RateSet  element). In some cases rates are expressed as a being a certain amount per night for the first N nights, and a different amount per night thereafter. Where details of one of these "special" rates are returned, the  MinSCU  element specifies the number N (the rate is only available for a stay of N or more nights), the  OptRate  element contains the rates for each of the first N nights, and the  ExtraNightRates  element contains the rates for extra nights (note that rates for all optional extras are stored against the  OptRates  rates, which is why there is no  ExtrasRates element in  ExtraNightRates.

Data itemTypeDescription
PriceCodeString (2)Price code of rate. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).
DateFromDateThe start date of the date range.
DateToDateThe end date of the date range.
SaleFromDateRates in this date range cannot be sold before this date. Optional (does not appear if the sale from date in Tourplan is before January 1st, 2000).
SaleToDateRates in this date range cannot be sold after this date. Optional (does not appear if the sale to date in Tourplan is more than 5 years in the future).
CurrencyStringThe currency of the rates returned.
SellBeforeTravelIntegerSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the number of days or months in advance that the rate must be purchased. For example, if there is a 7 day sell before period, then a booking for 2012-09-27 must be made no later than 2012-09-20. This field is not present if there is no sell before requirement.
SellBeforeTypeString (1)Present if and only if SellBeforeTravel is present, and specifies the units of SellBeforeTravel. D means days and M means months.
RateNameString (20)The name of the rate.
RateTextString (60)Rate description. Omitted if blank.
ValueAddsElementContains a collection of value adds that apply for the rate set. Each value add has a Type and a Description. Value adds of type IncludedExtra do not appear (they are not relevant for this type of rate request). See the stay pricing section for more information on the ValueAdds element.
MinSCU
MaxSCU
IntegersThe rate set applies where the SCU quantity (number of nights, days, whatever) falls on or between these two numbers.
AppliesDaysOfWeekBoolean attributesIf this element is omitted then the rates in this rate set apply on every day of the week. If this element is present then the rates in this rate set apply on the days whose attributes have a value of true (attribute names are Mon, Tue, Weds, Thur, Fri, Sat, Sun).
IsClosedBooleanIf true then this a closed rate set, and no rates are available. In this case none of the following XML elements are present.
ScuCheckOverlapOnlyBooleanControls what is checked where a stay includes parts of two or more rate sets, and one of the rate sets has a MinSCU greater than 0. If this value is true then the number of nights by which the stay overlaps the rate set period is validated against MinSCU. Otherwise the full length of the stay is validated against MinSCU.
CancelHoursIntegerCancel hours for booking made using this rate set. See the stay pricing section for more details in this field.
StayPayIntegersZero or more (stay, pay) pairs give the details of stay/pay deals that apply for rates in this rate set. For each stay/pay deal, if you stay for "stay" nights then you only pay for "pay" nights (in other words, "stay" - "pay" nights are free of charge). Where multiple stay/pay deals apply, they are in increasing order of stay length. Also, for any particular booking only one stay/pay deal applies; the one with the biggest "stay" value that is less than or equal to the length of the stay of the booking. Each Stay / Pay pair is within a StayPay element, and all of these elements are under a StayPays element.
SequenceNumberIntegerBy default, extras are free on days that are free of charge due to a stay / pay deal. If one or more extras is charged for on such days, then the StayPays element contains a ChargedExtras element, which has one or more SequenceNumber child elements. These child elements contain the sequence numbers of extras that are charged for on days where the main rates are free due to a stay / pay deal.
The availability group

Note that for it to be possible to book a service line there must be a valid rate. The availability returned only shows availability based on product inventory and/or whether the product is available on a request or free sell basis. It does NOT check or guarantee that there is also a valid rate for the dates searched for.

Data itemTypeDescription
OptAvailInteger listEach integer in the list gives the availability for one of the days in the range requested, from the start date through to the end date. The integer values are to be interpreted as follows:
  • Greater than 0 means that inventory is available, with the integer specifying the number of units available. For options with a service type of Y, the inventory is in units of rooms. For other service types, the inventory is in units of pax.
  • -1 Not available.
  • -2 Available on free sell.
  • -3 Available on request.

Note: A return value of 0 or something less than -3 is impossible.

The detailed availability group

In Tourplan, it is possible for one option to have inventory of several unit types. For example, an accommodation option may have (on a particular night) 2 single rooms and 1 double room available.

The availability group of return values is able to accurately return inventory details for an older generation Tourplan that did not support unit types, but is not powerful enough to handle some situations that can occur in Tourplan. If an option has inventory of two or more types, then the values are combined together to arrive at the information returned in the availability group. In the example before (2 single rooms and 1 double room available), a value of 3 (rooms) would be returned in the availability group.

It may be the case that a company using hostConnect to interface with a Tourplan system decides that the inventory information provided by the availability group is accurate enough (especially if the are few, if any, options that have inventories of more than one unit type). If, however, availability information is needed for each unit type, then the detailed availability group is available.

Detailed availability information is returned within a  DetailedAvails  element. Inventory information is returned as UnitType, OptAvail element pairs, with each pair within a  DetailedAvail  element.

Note that for it to be possible to book a service line there must be a valid rate. The availability returned specifies what the availability is if and only if there is a valid rate. It is possible for the returned availability on some particular day to be on request, for example, but for an attempt to book a service on that day to be rejected because there is no valid rate.

Data itemTypeDescription
UnitTypeUnit type listThe unit type(s) that apply (a single space follows each unit type). For accommodation options, the following unit types apply: sg (single), db (double), tw (twin), tr (triple), qd (quad), ot (other). At present Tourplan allows for one of these, or all of these. For apartments all room types are listed.For non-accommodation options, the following unit types apply: ad (adult), ch (child). A list of ad by itself means that only adults consume inventory. A list of ad and ch means that adults and children consume inventory. No other combinations are currently supported.
OptAvailInteger listAs for the availability group.
Replicated locations encountered in search

If  V  is specified in the  Info  data item, then for each option returned that has replicated locations, the list of one or more replicated locations the option is found by in this search is returned. The locations the option is found under are returned within a  ValidLocations  element (the  LocationCode  values returned within  ValidLocations  are a subset of the supplier's replicated locations). If the search is restricted to a single location or destination then generally there is a single  LocationCode  returned. Note that when booking an option whose supplier has replicated locations, a  LocationCode  should be supplied to  AddService  to specify which location is required.

Data itemTypeDescription
LocationCodeStringA replicated location code the option has been found under in this particular OptionInfo request.
Replicated locations and pickup points

If  L  or  P  is specified in the  Info  data item, then for each option returned that has replicated locations then the full list of replicated locations for the supplier is returned (and if  P  is specified details of any pickup points are also returned). The  SupplierLocations  element contains one or more  SupplierLocation  elements, each of which contains a location code, and zero or more pickup points.

Note that a pickup point can be specified in an  AddService  call by supplying the  PointDescription  as  puRemark  (for a pickup) or  doRemark  (for a dropoff).

Data itemTypeDescription
CodeStringA replicated location code.
Point_IDIntegerUnique pickup point identifier.
PointDescriptionStringPoint description (Sydney airport, for example).
CanPickupBooleanAre pickups allowed at this pickup point.
CanDropoffBooleanAre dropoffs allowed at this pickup point.
Package details

If  B  is specified in the  Info  data item, then for each option returned that is a package then details of the services options that make up the package are returned. Details of each service option included in a package are returned in a  PackageServiceLine  element. The  PackageDetails  element contains the  PackageServiceLine  elements.

Data itemTypeDescription
DayNumberIntegerWhich day this service option is booked relative to the date the package is booked (which is day 1).
SequenceNumberIntegerUsed to order service options with the same day number.
SCUqtyIntegerNumber of second charge units.
OptStringThe option identifier.
OptionNumberIntegerTourplan option number.
AvailabilityStringReturned if RoomConfigs has been supplied. The availability calculation is based on DateFrom as the booking date of the package, and the room configuration provided. One of NORQOK.

Anchor
AddService

2.4 AddService

A booking is built up service by service. Each  AddService  request adds one service to a (new or existing) booking. Note that for a service to be added to an existing booking the agent adding the service must be the same as the agent who made the original booking.

Input data items

The input data items can be divided into three groups:

  1. Data items that are specified only for the first service added to a new booking.
  2. Data items that are specified only for a service added to an existing booking.
  3. Data items that apply to services added to new and existing bookings. This group includes  AgentID  and  Password.

The data items provided in an  AddService  request are either groups 1 and 3 (for the first service in a new booking) or groups 2 and 3 (for a service added to an existing booking). In the discussion below, each group has its own section (except group 3 which has two sections).

New booking group

The new booking group of data items appear within a  NewBookingInfo  element.

Data itemTypeDescription
NameString (60)Name of the party for whom the booking is being made (required). Note that in some systems Name is forced to upper case.
QBString (1)The QB data item can take one of two values: Q if the service is being added to a new quote; B if the service is being added to a new booking.
BranchDepartmentString (2)One or more of these optional (up to 2 character) data items can be specified for the first service added to a new booking. In each case, if the data item is specified (and the value is non-empty) it is copied into the corresponding field in the booking header. If the data item is not specified, Tourplan will determine the value to use.
SalesAnalysis1 to
SalesAnalysis6
String (2)Same comment applies as for Branch and Department
Existing booking group

The existing booking group of data items appear within an  ExistingBookingInfo  element. This group contains the booking identifier of the existing booking.

Common group (room configuration)

The room configuration (adults, children, room type(s) and pax names) are the data items that make up the room configuration data. In early versions of hostConnect, room configuration consisted of three data items: Adults, Children and RoomType. This interface is still available (with the recent addition of Infants). It does have some limitations, as it is not possible to book more than one room on a service line. Also it is not possible to supply details of the pax in each room.

From iCom 4.0.00 it It is possible to specify multiple rooms on a service line, and to specify pax names.

There are one or more  RoomConfig  elements within a single  RoomConfigs  element. If the option being booked is not room-based, then there is a single  RoomConfig  element containing details of all pax being booked. If the option is room-based then there are one or  RoomConfig  elements. Specifying pax details are optional. Where there are pax whose details are not specified (either because no pax details are specified or because the number of pax details records is less than the number of pax in the room) hostConnect will assign pax records itself (by using other pax associated with the booking that aren't included on this service and/or generating pax records).

For each set of pax details specified hostConnect checks to see whether the pax is one that is already in the booking or is a new pax. If a  PersonId  is specified then an existing set of pax details for the current booking is being used, and there must be a pax record for the current booking with the specified  BookingId. Otherwise, the supplied title, forename, surname, date of birth and pax type are checked against all pax in the booking. If there is an existing pax in the booking that matches on all of these fields then that existing pax is used. Otherwise a new pax for the booking is created. Note that at present hostConnect is not able to update details of a pax already in a booking.

Data itemTypeDescription
AdultsInteger (0..99)Number of adults this booking is for. Required.For room-based options, this parameter is used to specify the number of adults that will occupy the specified  RoomType (see below). The number of adults cannot exceed the room's capacity. For example, no more than two adults can be booked in a double room.For options of all types, if a pax limit has been defined for this option (via  MaxAdults for example), a validation check is made to ensure the specified numbers of adults and children do not exceed the pax limits.Normally a quad room can take no more than four adults. However, if the pax limits for an accommodation option allow for more than four adults then a quad room booked for such an option can have up to the pax limit. An example of this is a large suite that can take up to 6 adults. Note that if the extra adult rate is non-zero, then the fifth and subsequent adults are charged at the extra adult rate.For group-based options, the number of adults plus children must not exceed the option's MPFCU, and the rate charged is the option rate. For apartment options the number of adults must not exceed MPFCU. Where two or more apartment units are required, each unit must be added to the booking by a separate AddService request.
ChildrenInteger (0..99)Number of children this booking is for. Optional (defaults to 0).Each option can be configured to define rates for children belonging to some age range. This data item is used to specify the number of attending children who are within this age range.For room-based options, any children over and above the room type's capacity will be charged at the extra child rate. For example, where there is an additional child rate and there are 2 adults and 2 children in a triple room then 1 child is charged at the extra child rate.For pax-based options, each child is charged at the child rate (and each adult at the adult rate).
InfantsInteger (0..99)Number of infants this booking is for. Optional (defaults to 0).
RoomTypeString (2)Room type being booked. This data item appears if and only if the option is room based. Legal values: SG (single), TW (twin), DB (double), TR (triple), QD (quad). The room type specified must be valid for the option being booked.
PersonIdIntegerThe id of a person already in the booking (optional). If specified, then none of the other pax-related fields (Title through to PaxType) should be specified.
TitleString (10)A person's title (optional).
ForenameString (60)A person's first name(s) (required for each set of pax details given in which PersonId is not specified).
SurnameString (60)A person's surname (required for each set of pax details given in which PersonId is not specified).
DateOfBirthDateA person's date of birth (optional).
PaxTypeString (1)A person's age category: A (Adult), C (Child) or I (Infant). Required for each set of pax details given in which PersonId is not specified.
Common group (except room configuration)
Data itemTypeDescription
OptString (17)Tourplan option identifier (Location + Service + Supplier + Option code). Either Opt or OptionNumber must be supplied.
OptionNumberIntegerTourplan option number. Either Opt or OptionNumber must be supplied.
RateIdStringAn internal Tourplan identifier for this rate, as returned by OptionInfo for a stay pricing request for the option being booked, where the DateFrom and SCUqty are the same as those in the AddService request. Some existing hostConnect users might not do a stay pricing OptionInfo call before AddService. In this case a a value of Default can be supplied for RateId, which means book the normal rate for the service line.
DateFromDateStart date for the booking of this service. Required.
SCUqtyIntegerThe number of second charge units required (second charge units are discussed in the OptionInfo section). Should only be specified for options that have SCUs. Defaults to the minimum SCU for option Opt if not specified. Legal range is option-dependent, and is given by the MinSCU and MaxSCU values returned by OptionInfo.
OnRequestBooleanIf true then the service is to be booked "on request" even if inventory is available; if false then the standard logic is used to determine whether the service line is confirmed or placed on request. Not relevant for quotes as all service lines for quotes are added on request. Defaults to false if not supplied.
SequenceNumberIntegerIf any "extras" are required, an ExtraQuantities element appears, which contains one or more ExtraQuantityItem elements. Each of these elements in turn contains a SequenceNumber that specifies which extra is required, as well as the quantity of that extra required.
ExtraQuantityInteger (0..20)Specifies the quantity of each extra that is required. These fields are optional (0 is the default). The extra required is identified by the associated SequenceNumber. Extra N should only appear if OptionInfo indicated that extra N exists.
ConsultString (30)Name of the consultant making the booking. Optional. Ignored if the AgentID supplied is a sub-login. Note that in some systems Consult is forced to upper case.
AgentRefString (60)Reference used by the agent to identify the booking. Optional. From iCom 7.0.00 this value is stored in a dedicated field in the booking header. Prior to this the agent reference was stored in one of the 5 user text fields associated with the booking.
EmailString (60)An email contact address for the booking. In fact, this field can be used to store any booking-related notes that will fit into 60 characters. Optional. This value is stored in one of the 5 user text fields associated with the booking.
puTimeTimePick-up time. Optional (see note 1 below).
puRemarkString (240)Pick-up remarks. Optional (see note 1 below).
doTimeTimeDrop-off time. Optional (see note 1 below).
doRemarkString (240)Drop-off remarks. Optional (see note 1 below).
RemarksString (240 or 60000)General remarks field. Optional (see note 1 below). This value is stored in the remarks field of the service line.
LocationCodeStringFor options with replicated locations, specifies which location the service line requires (if not specified defaults to the location the option is defined for).
PriceCodeString (2)Price code to book the service line under. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).

Note 1: each service option is associated with an iCom service type. Each iCom service type has associated with it 5 boolean values that determine whether each of the various "remarks" fields ( puTime,  puRemark,  doTime   doRemark  and  Remarks ) is recorded for bookings of options of that iCom service type. For each of the five fields, it is ignored if the relevant boolean value is false.

Various validation checks are made. These include that  DateFrom  is not in the past, that it is possible to confirm the booking or put the service on request (whichever is relevant), that for room-based services the room will hold the number of adults and children specified and that  SCUqty  (if specified) is in the required range.

Note that the way in which a service line is costed depends on the service type of the option.

Output data items

For the reply message, there are several valid combinations of data items.  Status  is always returned. If hostConnect itself determines the service cannot be added (even on request) on the specified date then it will simply return a  Status  of  NO, with no other values returned. Otherwise, the service line is added to the booking. In this case,  ServiceLineId,  Status  and  SeqNum  are always returned, and  Id  and  Ref  are returned if this is the first service added to a new booking (in other words, if  Id  was not specified as an input data item).

Data itemTypeDescription
BookingIdIntegerThe booking id. Note that this identifier is unique amongst all bookings that currently exist. If a booking is deleted, then its booking id might be re-used subsequently.
RefStringThe booking reference. Booking references are never re-used, even after the booking is deleted.
ServiceLineIdIntegerA unique identifier for the new service line. ServiceLineId is a better service line identifier than the combination of service date and sequence number as in some circumstances the sequence number can change. If a service line is deleted, then its service line identifier might be re-used subsequently.
SequenceNumberIntegerSequence number (within date). The main use of the sequence number in Tourplan is in ordering service details in booking messages.
StatusStringThe inventory status of the service line just added. Status can take one of four values:  OK  (inventory has been reserved---not possible for a service added to a quote),  RQ  (the service is on request),  NO  (this service has been declined) or  XX(the service line is marked as cancelled).Note that even if hostConnect has very recently indicated that inventory exists for a particular service option on a particular day, an attempt to book that inventory can put the service on request or even fail as it is possible that in the meantime all remaining inventory units have been allocated. For this reason, the  Status  value should always be checked to see whether inventory was successfully allocated or not.
SubServiceLineIdIntegerIf the service line just added has caused other service lines to be added to the booking the there is a SubServiceLineIds element returned, that contains one or more SubServiceLineId elements, each of which is the service line id of an additional service line. At present this happens in the following situations. First, where a service line is added as two or more service lines due to splitting on rate boundaries (note that very few Tourplan sites enable this). The main details returned by AddService are for the first service line. The service line ids of the other service lines are returned in SubServiceLineIds. Second, if optional package service lines are added at the same time as a package then their service line ids are returned in SubServiceLineIds (in this case the details of the package are the main return values of AddService).

Anchor
DeleteService

2.5 DeleteService

Request that a service be deleted from the booking. A status code is returned that shows whether the request was successful or not. There are two forms of "deletion". If the service is deleted, it is completely removed from the booking. If the service is cancelled, then the service remains in the booking, but its status is set to indicate that a cancellation has been requested.

hostConnect deletes the specified service if possible. Otherwise, cancellation is requested (though the service may have a status that does not permit the status to be changed to cancellation requested).

Note that the service line to be deleted is identified either by  ServiceLineId  or by  Date  and  SequenceNumber. It is expected that  ServiceLineId  will be the preferred identification method, with  Date  /  SequenceNumber  provided for backwards compatibility.

Input data items

AgentID,  Passwordbooking identifier. Also:

Data itemTypeDescription
ServiceLineIdIntegerService line identifier.
DateDateDate of the service line to be deleted.
SequenceNumberIntegerSequence number of the service line to be deleted.

Output data items

Data itemTypeDescription
BookingIdIntegerThe booking id. Returned for audit purposes.
RefStringTourplan booking reference. Returned for audit purposes.
ServiceLineIdIntegerService line identifier. Returned for audit purposes.
StatusStringThe new inventory status of the service line. If the service line has been deleted the status is deleted. Otherwise, the value will be one of those listed in the description of the Status return value for the AddService request.

2.6 CancelServices

Request that all services be cancelled in the specified booking. The new status of each service line is returned.

Input data items

AgentID,  Passwordbooking identifier.

Output data items

The new service line statuses are returned in the same format as that used by QuoteToBook to return statuses. As with DeleteService, it may not be possible to cancel some or all services, so it is important to check the status values returned. Also,  BookingId  and  Ref  are returned for audit purposes.

Anchor
QuoteToBook

2.7 QuoteToBook

Convert a quote to a confirmed booking. Note that the agent requesting the quote to book operation must be the same as the agent who made the booking.

Input data items

AgentID,  Passwordbooking identifier.

Output data items

The status of each of the services within the booking is returned. When a service is added to a quote, no inventory is allocated. When a quote is converted to a confirmed booking, inventory is allocated for each service line in the booking. The statuses returned by  QuoteToBook  indicate whether inventory was successfully allocated or not.

A booking contains 0 or more service lines. A  ServiceStatuses  element contains details of all service statuses. It contains zero or more  ServiceStatus  elements, each of which contains details of one service status.

Data itemTypeDescription
RefStringThe complete Tourplan booking reference.
ServiceLindIdIntegerService line identifier.
DateDateStart date for the this service line.
SequenceNumberIntegerSequence number (within date) of this service line.
StatusStringThe inventory status of the service line. See the description of the Status return data item for the AddService request for more information.

Anchor
GetBooking

2.8 GetBooking

This request retrieves a booking. Note that for a booking to be retrieved successfully the agent requesting the booking must be the same as the agent who made the booking.

Input data items

AgentID,  Passwordbooking identifier. Also:

Data itemTypeDescription
ForceReloadBooleanOptional (defaults to false). To improve performance, once retrieved from the database details of a booking are cached within hostConnect (until the completion of the next cache refresh, at which time hostConnect discards all cached bookings). When a  GetBooking occurs, if details of the required booking are in the booking cache then the values returned are from the cache rather than from the database.If a booking is changed by something other than the hostConnect (by a Tourplan user, or via webConnect for example) while the booking is held in hostConnect's cache, then these changes will not show up (via GetBooking) until the booking cache is discarded (which may be several hours later). Note that this situation is unusual; usually a booking is built up via hostConnect and, once complete, is taken over by the back office.The  ForceReload  data item is provided for situations in which the application using hostConnect wants to force hostConnect to get the booking afresh from the database (into the booking cache) before returning information on the booking. If  ForceReload  is true then the booking is always fetched from the database. Otherwise ( ForceReload  is false or not specified) the booking is fetched only if it is not already in the cache. Note that loading the booking from the database is significantly slower then retrieving it from the cache.
ReturnRoomConfigsBooleanOptional (defaults to false). If false returns the room configuration using the old-style room configuration of just reporting Adults, Children, Infants and RoomType. If true then the new format for room configuration is used, giving the room configuration, and the pax records for each room configuration.
ReturnAccountInfoBooleanOptional (defaults to false). If true then accounting information is returned in an  AccountingDetails  element.

Output data items

We can separate return values into two groups: those that are related to the booking as a whole, and those that repeat zero or more times to give details of the service lines that the booking is made up of. Note that fuller descriptions of many of these data items can be found in the AddService section. The data items that apply to the overall booking are:

Data itemTypeDescription
BookingIdIntegerThe booking id.
RefStringTourplan booking reference.
NameStringName of the party for whom the booking was made.
QBStringOne character indicating whether this is a quote (Q) or a booking (B).
ConsultStringName of the consultant making the booking.
AgentRefStringReference used by the agent to identify the booking.
EmailStringAn email contact address for the booking.
TravelDateDateDate on which travel commences.
EnteredDateDateDate on which the booking was created.
RemarksStringThe long remarks field associated with the booking.
DialogueStringA dialogue of log entries entered externally via iCom (see AddDialogueEntry for how to add a new dialogue entry) and internally from within Tourplan.
BookingStatusStringThe status of the booking. Note that this is the iCom booking status (as configured in the iCom configuration settings) and not the two character Tourplan booking status.
CurrencyStringThe booking currency.
TotalPriceIntegerThe total price of the booking. Sum of all service line LinePrice values for service lines where CostedInBooking is Y
AgentPriceIntegerThe total price of the booking less commission. Optional (only returned if hostConnect is configured to return agent pricing).
ReadOnlyBooleanIf true, then this booking is read-only, and cannot be modified via iCom.
CanAddServicesBooleanIf true, then service lines can be added to this booking using AddService, and if false they cannot. It is not possible to add services to bookings that are read-only, nor is it possible to add services to some some non-internet bookings.
BookingTypeStringF for a fast book (FIT) booking, G for a group book booking. Currently GetBooking cannot return data for a group book booking (ListBookings can, however).
IsInternetBookingBooleanIf true, then this booking is an internet booking. If false then this is a booking created in Tourplan.

If accounting details are returned then the following fields are returned in an  AccountingDetails  element.

Data itemTypeDescription
InvoicedTotalIntegerTotal of all of the invoice (INV) transactions.
ReceivedTotalIntegerTotal of all of the receipt (REC) and cheque (CHQ) transactions.
CreditsTotalIntegerTotal of all of the credit note (CRD) transactions.
AmountDueIntegerAmount of what has been invoiced that has not yet been paid.
FutureBillingIntegerAmount that has not yet been invoiced.
TransactionsElementDetails of the individual account transactions. If there are one or more transactions, then a Transactions element is present and contains one or more Transaction elements. The fields listed below appear in a Transaction element.
TransactionIdIntegerDatabase id of the transaction.
DateDateDate transaction occurred on.
TransactionRefStringTransaction reference printed on documentation.
RelatedRefStringThe TransactionRef of a related transaction. For receipts and credit notes this is the transaction reference of the invoice that the receipt or credit note is related to.
TransactionTypeStringOne of INV (invoice), CHQ (cheque), REC (receipt) or CRD (credit note).
AmountIntegerTax inclusive transaction amount, in booking currency.

A booking contains zero or more service lines. A  Services  element contains zero or more  Service  elements, each of which contains complete details of one service line.

Each service line can have non-zero quantities for between 0 and 5 extras. Only extras with non-zero quantities are reported. If there are one or more non-zero extra quantities, then each is reported as a  ServiceExtra  element, all of which are within a  ServiceExtras  element. Within the  ServiceExtra  element are two elements:  SequenceNumber  (the extra number), and  Quantity  (the quantity of that particular extra included in the service line).

The data items relating to room configuration are structured in the same way as they are for AddService. Whether the old or new style room configuration format is used is controlled by the input value of  ReturnRoomConfigs.

If a service line is booked in an external system, then additional details are returned in the ExternalServiceDetails element.

Service lines appear in date/sequence number order.

 

Data itemTypeDescription
ServiceLineIdIntegerService line identifier.
OptStringTourplan option identifier (Location + Service + Supplier + Option code). If necessary, spaces are added to make the option identifier 17 characters long.
OptionNumberIntegerTourplan option number.
DateDateStart date for the booking of this service.
SequenceNumberIntegerSequence number (within date).
AdultsIntegerThe number of adults booked for this service.
ChildrenIntegerThe number of children booked for this service.
InfantsIntegerThe number of infants booked for this service.
RoomTypeStringThe room type booked (appears only if the option service type is accommodation or package).
PersonIdIntegerDatabase id of this person record.
TitleStringPax title (only present if one was entered).
ForenameStringPax forename.
SurnameStringPax surname.
AgeIntegerPax age (only present if one was entered).
PaxTypeStringA (adult), C (child) or I (infant).
CostedInBookingBooleanSpecifies whether LinePrice is added in to the booking's TotalPrice. Usually this field is Y, and LinePrice is included in booking TotalPrice. One reason for a service line having a value of N here is that on some systems cancelled services do not contributed to the booking total. Another is that in some systems optional extra services are added into the booking, and do not contribute to the booking total (unless the agent decides to include the optional service). If this field is N then LinePrice shows the original price of the cancelled service, or how much the option service will cost if accepted.
LinePriceIntegerThe total price of this service line. Note that it is not always the case that the service line prices sum to the booking total price. This depends on the setup of the underlying Tourplan system (sometimes taxes or rebates are applied at the booking level).
SellCurrency
SellPrice
String
Integer
A few hostConnect systems are configured to return LinePrice converted to SellCurrency (the currency that the Tourplan user is transacting with the supplier). In such systems, this pair of fields is returned, giving the sell currency, and the SellPrice (LinePrice converted to SellCurrency). Often sell currency is the same as booking currency, in which case SellPrice and LinePrice are the same).
AgentPriceIntegerThe total price of the booking less commission. Optional (only returned if hostConnect is configured to return agent pricing).
SCUStringThe second charge unit (commonly night or day). Blank if the option does not have an SCU.
SCUqtyIntegerThe number of second charge units required.
puTimeTimePick-up time (see note 1 for AddService).
puRemarkStringPick-up remarks (see note 1 for AddService).
doTimeTimeDrop-off time (see note 1 for AddService).
doRemarkStringDrop-off remarks (see note 1 for AddService).
SupplierNameStringSupplier name this service is booked for.
DescriptionStringOption description of the option this service is booked for.
CommentStringOption comment of the option this service is booked for. Each hostConnect implementation is configured either to always return this field or never to return it.
CancelDeleteStatusStringD if the service line can be deleted, C if it can be cancelled, blank if neither is possible.
CanUpdateBooleanTrue if an AmendRemarks request can be made on this service line.
CanAcceptBooleanTrue if an AcceptService request can be made on this service line.
PriceCodeString (2)Price code of rates used on this service line. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).
RemarksStringGeneral remarks field (see note 1 for AddService).
LinkedServiceLineIdIntegerNon-zero if this service is related to another service in the booking, and neither are involved in a package. Currently only use is for the return of services booked via a third-party provider or a fixed service. In product like externally sourced air the field is used to identify each sector of the flight
StatusStringThe inventory status of the service line. See the description of the Status return value for the AddService request for more information. Status is only returned for services lines within confirmed bookings (not those within quotes).
HeaderServiceLineIdIntegerIf this service line is a part of a package, then this field gives the service line id of the package header.
SubServiceLineIdIntegerIf this service line is a package header service line that has additional service lines associated with it then there is a SubServiceLineIds element returned, that contains one or more SubServiceLineId elements, each of which is the service line id of a service line associated with the package.
LocationCodeStringLocation code the service line was booked under.
SequenceNumberInteger (1..5)Number identifying a particular extra
QuantityIntegerThe quantity of one extra included in the service line.
ExtSupplierIdStringThe identifier for the supplier used in the external system.
ExtOptionIdStringThe identifier for the option used in the external system.
ExtOptionDescrStringOption description used in the external system.
ExtRatePlanCodeStringThe external system's rate plan code for the rate returned.
ExtRatePlanDescrStringDescription of the rate plan code.
CancelPoliciesAdditionalDetailsXML elementsSee the OptionInfo section for details of these elements.

2.9  PriceBooking (deprecated)

This request returns price information for the specified booking. The currency used is the currency associated with the specified agent. The units of the prices returned is "dollars".

Note that this request is now deprecated. The total price of a booking is now available via GetBooking.

Anchor
SetBookingRemarks

2.10  SetBookingRemarks

Associated with each booking is a general-purpose remarks field. Unlike most other booking-related fields, this field cannot be set in the AddService request (though its value is returned by GetBooking). Instead, it must be set using the SetBookingRemarks request. The existing value in the remarks field is overwritten.

Input data items

AgentID,  Passwordbooking identifier. Also:

Data itemTypeDescription
RemarksString (60000)The remarks being recorded. Required.

Output data items

On success, an empty response message is returned.

2.11 GetBookingMessage

This request retrieves the specified Tourplan message generated for the specified booking. The message types available, and the format of each message type are site-specific.

Input data items

AgentID,  Passwordbooking identifier. Also:

Data itemTypeDescription
MessageLabelStringA message label returned by GetSystemSettings (must be a quote label if the booking specified is a quote, otherwise must be a booking label).
OutputFormatStringFormat that the message is returned in. One of txt (plain text), rtf (rich text format) or pdf. Optional (defaults to rtf). Note that for container messages, if a format is specified in the message then the format specified in the message takes precedence.

Output data items

Data itemTypeDescription
OutputFormatStringFormat that the message is returned in. One of txt (plain text), rtf (rich text format) or pdf. Optional (defaults to rtf). Note that for container messages, if a format is specified in the message then the format specified in the message takes precedence.
MessageStringThe message generated from the specified booking using the specified message template. Note that if the output format is PDF then the contents of this field are encoded in base64 format.

2.12 Resequence

The sequence numbers assigned to the various service lines play a part in determining the order of service lines in Tourplan messages. Service lines appear in increasing date order. The order of service lines on the same date is determined by the sequence numbers of those service lines. The  Resequence  request provides a way to change the sequence number order of the service lines in a booking. A list of two or more service line ids is given. The sequence numbers of the service lines listed are changed so as to make the order of the service lines in the booking match the order specified. Note that it is an error for the order given to not match the date order of the service lines. The request might list all service lines in the booking, although this is not required. Note that any service line not listed in the input may or may not have its sequence number changed, and may appear in any order with respect to any other service lines on the same day.

The request returns the sequence numbers of all service lines in the booking.

Input data items

AgentID,  Passwordbooking identifier. Also:

Data itemTypeDescription
ServiceLineIdIntegerService line identifier. In fact multiple service line identifiers can be specified (at least two are required) by having a series of ServiceLineId elements within a NewSequence element.

Output data items

Details are returned of the current sequence numbers of all service lines in the booking (not just the ones specified in the request). A  LineSequenceNumbers  element contains details of all service line identifiers and sequence numbers, each pair of which is within a  LineSequenceNumber  element.

Data itemTypeDescription
ServiceLineIdIntegerService line identifier.
SequenceNumberIntegerThe sequence number of the service line (which may or may not have been changed by the request).

Anchor
AddDialogueEntry

2.13 AddDialogueEntry

Associated with each booking is a dialogue containing entries submitted externally via iCom from agents, and entries submitted internally via Tourplan for viewing by agents. This request adds a new entry to the dialogue.

Input data items

AgentID,  Passwordbooking identifier. Also:

Data itemTypeDescription
DialogueEntryString (1500)The new dialogue entry. Required.

Output data items

Data itemTypeDescription
DialogueStringThe contents of the dialogue after the new entry has been added.

2.14 GetLocations

The  GetLocation  request returns a list of all location codes and names used in the system. Note that each  Opt  option identifier contains a location code.

Input data items

AgentID,  Password.

Output data items

A  Locations  element contains details of all locations, each pair of which is within a  Location  element.

Data itemTypeDescription
CodeString (3)The location code.
NameStringThe location name.

2.15 GetServices

The  GetServices  request returns a list of all service codes and names used in the system. Note that each  Opt  option identifier contains a service code.

Input data items

AgentID,  Password.

Output data items

A  TPLServices  element contains details of all service codes and names, each pair of which is within a  TPLService  element.

Data itemTypeDescription
CodeString (2)The service code.
NameStringThe service name.

2.16 SupplierInfo

The  SupplierInfo  request returns details of one or more suppliers.

Each supplier has two unique identifiers: its supplier code and its supplier number. Of the two, the supplier number is much less likely to change over time, and so is the best choice as the primary form of supplier identification in a system using hostConnect to interact with a Tourplan system. The supplier code will very likely change if the supplier name changes, and supplier name changes are not uncommon.

Suppliers are specified to the  SupplierInfo  request as zero or more supplier codes and zero or more supplier numbers (at least one supplier code or supplier number must be specified).

Input data items

AgentID,  Password. Also:

Data itemTypeDescription
SupplierCodeString (6)Tourplan supplier code. Zero or more supplier codes are to be specified.A pattern is a supplier code that contains one or more  ?  characters. When a pattern is specified it is checked against all supplier codes, and details about those that match the pattern are returned.
SupplierIdIntegerTourplan supplier number. Zero or more supplier numbers are to be specified.
NoteCategoryString (3)If specified then only notes with this category are returned (otherwise all note categories are returned).
NotesInRtfStringFormat to return notes in. One of N (plain text returned), Y (RTF returned) or H (HTML returned). HTML is supported in version 3.00.272 and above. Optional (defaults to plain text).
InfoString (1)L for replicated location information, location codes only
P for replicated location information with location codes and pickup points.
LocationCodeString (3)Specifies that only SupplierLocations matching this code should be returned (if a LocationCode is supplied then Info is treated as containing P, but restricted to the location specified).

Output data items

A  Suppliers  element contains details of all suppliers, with details for each supplier within a  Supplier  element.

A supplier has zero or more notes, each of which has a category and the actual text of the note.

A supplier has zero or more FYI messages, each of which applies over a certain period. An FYI can be used for recording when renovations will be done at a hotel, for example. Details of each FYI stored in a  FYI  element.

A supplier has zero or more amenities (for a hotel amenities might include swimming pool and broadband internet). For each amenity there is a category, an optional code, a description and a level indicator. Details of each amenity are stored in an  Amenity  element.

A supplier has zero or more  SupplierLocation  elements (depending on what is set in the  Info  input string). A  SupplierLocation  is made of up a location code and zero or more  PickupPoints  elements (whether pickup points are returned is determined by the  Info  input string). More detail on the SupplierLocation element is provided in the  OptionInfo  section.

Data itemTypeDescription
SupplierIdIntegerSupplier number.
CodeString (6)The supplier code.
NameStringThe supplier name.
LastUpdateTimestampThe time of the most recent change to information on this supplier.
Address1
Address2
Address3
Address4
Address5
PostCode
StringThe supplier's address.
SupplierAnalysis1 to
SupplierAnalysis6
StringThe supplier analysis codes.
PhoneStringSupplier phone number (XML element is omitted if blank). Phone numbers are available if returning of supplier contact details is enabled.
FaxStringSupplier fax number (XML element is omitted if blank). Fax numbers are available if returning of supplier contact details is enabled.
EmailStringSupplier email address (XML element is omitted if blank). Email addresses are available if returning of supplier contact details is enabled.
WebStringSupplier web page URL (XML element is omitted if blank). Web page URLs are available if returning of supplier contact details is enabled.
NoteCategoryStringThe note category code (the type of note this is).
NoteTextStringThe contents of the note.
LastUpdateTimestampWhen the note was last changed.
DateFromDateThe start of the period of an FYI.
DateToDateThe end of the period of an FYI.
FYITextStringThe FYI message.
AmenityLevelStringS for a supplier amenity and O for an option amenity (SupplierInfo always returns supplier level amenities; OptionInfo can return supplier and option level amenities).
AmenityCodeStringAmenity code (for standard amenities). Amenities codes differ from Tourplan system to Tourplan system.
AmenityCategoryStringAmenity category. Amenities categories differ from Tourplan system to Tourplan system.
AmenityDescriptionStringTextual description of the amenity.
SupplierLocation Code and List of PickupPoints

2.17 ListBookings

The  ListBookings  request returns header-level details of zero or more bookings made by the specified agent, and that meet all of the criteria specified. If a sub-login is supplied then only details of bookings associated with that sub-login are returned.

Input data items

AgentID,  Password. Also:

Data itemTypeDescription
TravelDateFromDateOnly details for bookings that travel on or after this date are returned. Optional.
RefStringOnly details for the booking with this booking reference are returned. Optional.
BookingIdIntegerOnly details for the booking with this booking id are returned. Optional.
TravelDateToDateOnly details for bookings that travel on or before this date are returned. Optional.
EnteredDateFromDateOnly details for bookings created on or after this date are returned. Optional.
EnteredDateToDateOnly details for bookings created on or before this date are returned. Optional.
NameContainsStringOnly details for bookings whose booking name contains this string are returned. Optional.
AgentRefStringOnly details for bookings whose agent reference equals this string are returned. Optional.
CurrencyStringOnly details for bookings in this currency are returned. Optional.
BookingTypesStringIf A then details of all bookings are returned, including group book bookings. Access to group book bookings has been provided to give access to accounting information on group book bookings. It is not possible to call GetBooking for a group book booking. Also, it is not possible to change a group book booking in any way. Optional.

Output data items

A  BookingHeaders  element contains details of bookings, with details for each booking within a  BookingHeader  element.

The fields returned are a subset of those returned in  GetBooking :  BookingId,  Ref,  Name,  QB,  Consult,  AgentRef,  TravelDate,  EnteredDate,  BookingStatus,  BookingType,  
IsInternetBooking
,  Currency,   TotalPriceAgentPrice  and  AccountingDetails.

Note that use of  TotalPrice and AgentPrice  is deprecated, as occasionally it can return 0 instead of the actual price (use  GetBooking  to get this information).

2.18 GetAgentSublogins

The  GetAgentSublogins  request returns a list of all sub-logins associated with the specified agent login. If the login is the main agent login then details of all sub-logins for that agent are returned. If the login is a sub-login then only details for that sub-login are returned.

Input data items

AgentID,  Password.

Output data items

A  Sublogins  element contains details of all sub-logins, with details for each sub-login within a  Sublogin  element.

Data itemTypeDescription
AgentIDStringThe sub-login code.
NameStringThe name associated with this sub-login.
TitleString (10)A title associated with this sub-login (optional).
ForenameString (60)The forename name associated with this sub-login (optional).
SurnameString (60)The surname name associated with this sub-login (optional).
Address1String (60)The first of up to 5 address lines that can be associated with this sub-login (optional).
Address2String (60)The second of up to 5 address lines that can be associated with this sub-login (optional).
Address3String (60)The third of up to 5 address lines that can be associated with this sub-login (optional).
Address4String (60)The forth of up to 5 address lines that can be associated with this sub-login (optional).
Address5String (60)The fifth of up to 5 address lines that can be associated with this sub-login (optional).
PostCodeString (20)The post code for the address that can be associated with this sub-login (optional).
ContactPhoneString (40)The contact phone number that can be associated with this sub-login (optional).
MobilePhoneString (40)The mobile phone number that can be associated with this sub-login (optional).
FaxString (40)The fax number that can be associated with this sub-login (optional).
EmailString (60)The email address that can be associated with this sub-login (optional).
Indicator1BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator2BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator3BooleanA user-defined boolean field that can be associated with this sub-login (optional).

2.19 AddAgentSublogin

The  AddAgentSublogin  request adds a new sub-login for the specified agent (note that the AgentID supplied must be that of the main agent login).

Input data items

AgentID,  Password. Also:

Data itemTypeDescription
AgentSubloginStringThe new sub-login code (whose prefix must match the AgentID in this request). No more than 30 characters are allowed after the prefix. Required.
AgentSubPasswordString (20)The password for the new sub-login (required).
NameString (40)The name associated with the new sub-login (required).
TitleString (10)A title associated with the new sub-login (optional).
ForenameString (60)The forename name associated with the new sub-login (optional).
SurnameString (60)The surname name associated with the new sub-login (optional).
Address1String (60)The first of up to 5 address lines that can be associated with the new sub-login (optional).
Address2String (60)The second of up to 5 address lines that can be associated with the new sub-login (optional).
Address3String (60)The third of up to 5 address lines that can be associated with the new sub-login (optional).
Address4String (60)The forth of up to 5 address lines that can be associated with the new sub-login (optional).
Address5String (60)The fifth of up to 5 address lines that can be associated with the new sub-login (optional).
PostCodeString (20)The post code for the address that can be associated with the new sub-login (optional).
ContactPhoneString (40)The contact phone number that can be associated with the new sub-login (optional).
MobilePhoneString (40)The mobile phone number that can be associated with the new sub-login (optional).
FaxString (40)The fax number that can be associated with the new sub-login (optional).
EmailString (60)The email address that can be associated with the new sub-login (optional).
Indicator1BooleanA user-defined boolean field that can be associated with the new sub-login (optional).
Indicator2BooleanA user-defined boolean field that can be associated with the new sub-login (optional).
Indicator3BooleanA user-defined boolean field that can be associated with the new sub-login (optional).

Output data items

On success, an empty response message is returned.

2.20 UpdateAgentSublogin

The  UpdateAgentSublogin  request modifies the password of the main login or the password and associated details of an existing sub-login. Modification of the details of the main agent is not permitted. If the AgentID supplied is the main login then the main login or any of that agent's sub-logins can be modified. If the the AgentID supplied is a sub-login then only that sub-login can be modified.

Input data items

AgentID,  Password. Also:

Data itemTypeDescription
AgentSubloginStringThe sub-login to be modified.
AgentSubPasswordString (20)The new password (optional).
NameString (40)The new name for the sub-login (optional).
TitleString (10)A title associated with this sub-login (optional).
ForenameString (60)The forename name associated with this sub-login (optional).
SurnameString (60)The surname name associated with this sub-login (optional).
Address1String (60)The first of up to 5 address lines that can be associated with this sub-login (optional).
Address2String (60)The second of up to 5 address lines that can be associated with this sub-login (optional).
Address3String (60)The third of up to 5 address lines that can be associated with this sub-login (optional).
Address4String (60)The forth of up to 5 address lines that can be associated with this sub-login (optional).
Address5String (60)The fifth of up to 5 address lines that can be associated with this sub-login (optional).
PostCodeString (20)The post code for the address that can be associated with this sub-login (optional).
ContactPhoneString (40)The contact phone number that can be associated with this sub-login (optional).
MobilePhoneString (40)The mobile phone number that can be associated with this sub-login (optional).
FaxString (40)The fax number that can be associated with this sub-login (optional).
EmailString (60)The email address that can be associated with this sub-login (optional).
Indicator1BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator2BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator3BooleanA user-defined boolean field that can be associated with this sub-login (optional).

Output data items

On success, an empty response message is returned.

2.21 DeleteAgentSublogin

The  DeleteAgentSublogin  request removes a sub-login for the specified agent (note that the AgentID supplied must be that of the main agent login for the agent whose sub-login is being deleted).

Input data items

AgentID,  Password. Also:

Data itemTypeDescription
AgentSubloginStringThe sub-login code for the sub-login being deleted (required).

Output data items

On success, an empty response message is returned.

2.22 AmendServiceRemarks

Request that a one of more of the remarks fields of a service line be updated.

Input data items

AgentID,  Passwordbooking identifier. Service lines are identified as per DeleteService (using  ServiceLineId, or  Date  and  SequenceNumber ). The following data items are permitted (all are optional; see AddService for field details):  puTime,  puRemark,  doTime,  doRemark,  Remarks.

Output data items

None.

2.23 GetSystemSettings

The  GetSystemSettings  request returns information about the overall system settings.

Input data items

AgentID,  Password.

Output data items

The information returned consists of a number of simple fields, a  Countries  element that contains details of each country (its name, and a list of destinations within the country), an  AvailableMessages  element containing a list of the names of the standard iCom messages available, and a  BookingStatuses  element that lists the valid non-blank  BookingStatus values (blank is often a possible value, but is not returned in this list of booking statuses).

Data itemTypeDescription
QuotesEnabledBooleanSpecifies whether it is possible to create quotes using AddService. If true both quotes and bookings can be created; if false only bookings can be created.
QuotesAreDefaultBooleanSpecifies whether webConnect should default to creating quotes or creating bookings. Only relevant if quotes are enabled.
QuoteMessageLabelStringLabel of one of the standard messages that can be retrieved for a quote (by passing the label as MessageLabel in a GetBookingMessage request).
BookingMessageLabelStringLabel of one of the standard messages that can be retrieved for a booking (by passing the label as MessageLabel in a GetBookingMessage request).
IsAgentDialogueEnabledBooleanTrue if AddDialogueEntry requests are permitted; false if they are not.
CountryNameStringName of a country. Often multiple countries are not defined, in which case all destination names are returned within the country (Unspecified).
DestinationNameStringName of an iCom destination. One technique for searching for options with the OptionInfo request is based on specifying a (DestinationNameButtonName) pair.
BookingStatusStringA booking status that can be returned by GetBooking or ListBookings.

2.24 GetServiceButtons

The  GetServiceButtons  request returns a list of all service buttons names.

Input data items

AgentID,  Password.

Output data items

A  ButtonNames  element is returned that contains  ButtonName elements.

Data itemTypeDescription
ButtonNameStringName of an iCom service button. One technique for searching for options with the OptionInfo request is based on specifying a (DestinationName, ButtonName) pair.

2.25 GetServiceButtonDetails

The  GetServiceButtonDetails request  returns information on the specified service button. Service buttons are primarily a way of grouping options for searching purposes (using  OptionInfo), but also have some influence on how service options are booked (the various remarks fields that are accepted, for example).

This request was added to support Tourplan webConnect, and many of the fields returned are likely to be of little interest to other hostConnect users.

Input data items

AgentID,  Password. Also:

Data itemTypeDescription
ButtonNameStringThe name of the iCom service button whose details are required. Required.
DestinationNameStringThe name of the iCom service button whose details are required. If this field is specified then additional information is returned about the specified destination in the specified service button.

Output data items

Two groups of data items are returned. One group is always returned. The second group is returned only if  DestinationName  is specified in the input.

Data items always returned

The information returned consists of a number of simple fields, a  Countries  element (whose structure is the same as for the  GetSystemSettings  request) and a  RemarksDetails  element that contains details of which remarks fields can be entered for service options associated the service buttons, and screen labels to use.

Data itemTypeDescription
ScuPromptStringIf it is recommended that OptionInfo requests for this service button include SCUqty (or DateTo) the ScuPrompt is returned and is the screen label to use for the quantity field (such as Night(s) for an Accommodation service button. Optional.
RoomBasedBooleanTrue if service options for this service button are predominantly room-based.
ClassLabelStringScreen label to use when displaying classes for this service button. It might be Star rating for an accommodation service button, or Vehicle type for a car rental service button.
DisplayOptionsWithZeroRatesBooleanIf true then it is recommended that options with no rates should still be displayed (intended for use by Tourplan webConnect).
PickupLabelStringScreen label to use for AddService fields puTime and puRemark for this service button.
PickupTimeAllowedBooleanIs entry of AddService field puTime allowed for this service button.
PickupRemarksAllowedBooleanIs entry of AddService field puRemark allowed for this service button.
DropoffLabelStringScreen label to use for AddService fields doTime and doRemark for this service button.
DropoffTimeAllowedBooleanIs entry of AddService field doTime allowed for this service button.
DropoffRemarksAllowedBooleanIs entry of AddService field doRemark allowed for this service button.
RemarksLabelStringScreen label to use for AddService field doRemarks for this service button.
RemarksAllowedBooleanIs entry of AddService field Remarks allowed for this service button.
CountryName
DestinationName
String
String
Countries elements (containing these fields) is returned. Names of destinations with no options linked to the service button are not returned. Likewise, the names of countries with no options linked to the service button are not returned.
Data items returned when DestinationName is supplied

If there are no options found with the  ButtonName,  DestinationName  specified in the input, then the  LocalityDescriptionsClassDescriptions and CodeTables  elements are not returned.

Data itemTypeDescription
DestinationNameStringThe DestinationName supplied in the request.
LocalityDescriptionStringLocality descriptions are returned in a LocalityDescriptions element. These are the localities used by the options associated with the service button and destination combination specified in the input.
ClassDescriptionStringZero or more class descriptions are returned in a ClassDescriptions element. These are the classes used by the options associated with the service button and destination combination specified in the input.
CodeTableTypeStringIf there are one or more options for the specified service button / destination combination, and hostConnect is configured to return one or more of the database analysis codes, then a CodeTables element is returned containing one or more code tables (each code table is returned in a CodeTable element). Each code table has a CodeTableType that specifies which code table the entries are from. Valid values range from DB1 (database analysis code 1) to DB6.
CodeDescriptionStringsFor each code table returned there is a CodeTableEntries element containing one or more CodeTableEntry elements. Each CodeTableEntry element contains a Code value and its Description.

2.26 AcceptService

Accept an optional service line. An optional service line is one that does not cost into the booking ( CostedInBooking  is returned as  Y ). If  CanAccept  is returned as  Y  then hostConnect can be told (via this request) that the service line is accepted. This has the effect of changing the status of the service to confirm the user's interest, and to add the service line total in to the booking total. This can be used for optional package components, or where a hotel stay has been added to a booking in an optional way because the originally requested hotel was not available.

Input data items

AgentID,  Passwordbooking identifier. Service lines are identified using  ServiceLineId.

Output data items

None.

2.27 UpdateBooking

This request allows the booking-level fields (below) to be updated WITHOUT extensions being enabled.  These fields are optional, and only those specified are changed.

Input data items

booking identifierAgentID,  Password.  Booking-Level fields: Consult,  AgentRef,  Email.

2.28 GetSupplierServiceLines

This request gives a supplier access to service lines booked with that supplier. Only service lines that meet all of the specified filters are returned.

Input data items

Password. Also:

Data itemTypeDescription
SupplierLoginStringThis request requires a supplier login, rather than an AgentId
GetForChainBooleanIf false (the default), the service lines returned are those for the supplier whose login is SupplierLogin. If true, the service lines returned are those for the suppliers whose Master Supplier is the supplier whose login is SupplierLogin.
Opt
OptionNumber
String
Integer
It is possible to restrict service lines to just those for a particular option (identified by option code or option number). If an option code is supplied then the location code can be either the actual location code, or a replicated location. If the former, then all service lines for the option are returned. If the latter, then only service lines with a matching replicated location are returned.
TravelDateFromDateOnly return details of service lines whose Date is on or after TravelDateFrom. Optional.
TravelDateToDateOnly return details of service lines whose Date is on or before TravelDateTo. Optional.
EnteredDateFromDateOnly return details of service lines created on or after EnteredDateFrom. Optional.
EnteredDateToDateOnly return details of service lines created on or before EnteredDateTo. Optional.
TourplanServiceStatusStringOne or more TourplanServiceStatus elements can be supplied in a TourplanServiceStatuses element. If one or more TourplanServiceStatus values are given then only service lines whose status is one the the states supplied are returned. Optional.
ServiceLineIdIntegerIf ServiceLineId is supplied then only service lines with the specified id are returned. This means either one service line is returned (if it exists, and meets any other filter criteria specified) or no service lines are returned.  Optional.

Output data items

One or more  SupplierServiceLine  elements are returned in a  SupplierServiceLines  element (if there are no service lines then no  SupplierServiceLines  element is returned). Most of the elements returned in a  SupplierServiceLine  are also returned in by  GetBooking. Refer to the GetBooking documentation for information on these fields. The remaining fields are documented below.

Data itemTypeDescription
BranchNameStringName of the branch making the booking.
DepartmentNameStringName of the department making the booking
AgentCodeStringCode of the agent making the booking.
AgentNameStringName of the agent making the booking.
UDText1 to UDText5StringBooking user defined text fields, numbered 1 through to 5
TourplanConsultantNameStringName of the consultant managing the booking
TourplanConsultantEmailStringEmail address of the consultant managing the booking.
SupplierCodeStringTourplan supplier code.
SupplierIdIntegerTourplan supplier number.
EnteredDateDateData service line was created.
Adults
Children
Infants
IntegerThe numbers of adults, children and infants booked on the service line, totalled across all rooms.
SingleCountTwinCount,
DoubleCountTripleCount,
QuadCountOtherCount
IntegerThe numbers of each room type booked on the service line.
TourplanServiceStatusStringTourplan status if the service line.
PriceCodeStringPrice code used in the service line.
CostCurrencyStringCurrency code of cost amount.
CostExclusiveIntegerCost of the service line (in cents) exclusive of tax. To get the inclusive amount add CostExclusive and CostTax.
CostTaxIntegerTax component of cost.

2.29 SupplierUpdateServiceLines

This request allows a supplier limited edit access to service lines booked against their product.

Input data items

Password. Also:

Data itemTypeDescription
SupplierLoginStringThis request requires a supplier login, rather than an AgentId
SupplierUpdateServiceLinesXML elementThis is a collection of the SupplierUpdateServiceLine elements that describe the service lines to manipulate and the changes required.
The SupplierUpdateServiceLines group

This group contains the list of manipulations to perform where each SupplierUpdateServiceLine element identifies a service line and the related changes.

Password. Also:

Data itemTypeDescription
ServiceLineIdIntegerThe ID of the service line to be manipulated.
SupplierConfirmationStringThe new supplier confirmation code that should be applied to the service line, not changed if not supplied.
TourplanServiceStatusStringThe new service status that should be applied to the service line, not changed if not supplied.

Output data items

One or more ServiceLineId elements are returned in a SupplierUpdatedServices element, one ID per line that was updated. The SupplierUpdatedServices element will not be present if no updates were made.

One or more SupplierFailedServiceUpdate elements are returned in a SupplierFailedServiceUpdates element, one entry per line that failed to updated.

Data itemTypeDescription
SupplierUpdatedServicesXML elementA list of service lines that were updated.
SupplierFailedServiceUpdatesXML elementA list of service lines that failed to update.
The SupplierFailedServiceUpdates group

This group contains the list of service line updates that failed along with the reason for the failures. Each entry detailing one line that failed to update.

Data itemTypeDescription
ServiceLineIdIntegerThe ID of the service line that failed to update.
UpdateFailureCodeStringThe code that identifies the reason for failure.
UpdateFailurereasonStringThe error message that describes the reason for the failure.

 

Tourplan Pacific Ltd reserves the right to change, modify, add or remove portions of this interface at any time.