SOAP

Agency service is a SOAP 1.1 service that gives access to a subset of functions of the PonoRez Reservation system. Namely, it allows to create, modify and cancel reservations and to get information on the Reservation system objects that are necessary for said operations.

The service is intended for use by agencies registered within the Reservation system; it requires a valid agency user login information (username and password).

Sections

Terms and Concepts

The following terms and concepts are used in this specification:

Agency– a travel agency. Agencies is the target audience of this specification. An agency typically has access to many supplier companies and their activities.

Supplier– an activity provider company.

Activity– an activity provided by a supplier. A primary product sold via the Reservation system. Each supplier typically has several activities.

Reservation– a package sold to customers that gives them right to participate in activities. Primary properties of a reservation are: activity date, participating guests, added upgrades, price.

Guest– a part of a reservation. Represents a person (or, in some cases, a group of people) that are going to attend an activity. Each guest is assigned a guest type.

GuestType– a type of guests used in reservations. Determines what kind of attendant(s) a guest represents, how many personal seats a guest comprises, what is the price, and so on.Each supplier sets up its own guesttypes, for example it could be Adult (a regular attendant, full price),Child (a child, half-price), Tandem (two attendants, uses two personal seats, special price), Infant (a small child, free). For each activity there is a list of allowed guest types. Each guest type has its own price for each activity it’s used in; a guest type can (and usually will) have different prices for different activities. A reservation can contain up to five different guest types, with one or several guests for each guest type; for example, one Tandem guest, one Adult guest, two Child guests.

Personal Seat– space for one person in an activity, in a reservation, etc. A reservation’s guest comprises one or several personal seats. Personal seats are used to determine the number of per-seat surcharges applied to a reservation, to calculate the per-seat transportation price, to compose activity’s checklist; so a two-seat guest will yield two per-seat surcharges, will require doubled per-seat transportation price, will add two lines to reservation’s checklist. Each activity has a certain availability for a given date – it’s a number of personal seats it can accommodate; each reservation draws the number of its personal seats from this availability, reservations can’t be made if there is not enough availability for them to occupy. Transportation routes and upgrade types can have their own availability as well.

Upgrade– an addition to a reservation that doesn’t represent people and thus doesn’t occupy activity availability. Each activity has its own set of upgrade types, for example, Lunch, Digital Camera or T-Shirt. Each upgrade type has its own price, and customers are free to add or not add upgrades when they book reservations. A reservation can have multiple upgrades of different upgrade types (for example, two Lunch upgrades and one Digital Camera upgrade), or no upgrades at all.

Surcharge– a charge applied to a reservation, accounted separately from guests and upgrades. A surcharge can be paid on per-trip (once for a reservation) or per-seat (for each personal seat of reservation’s non-free guests) basis. Each activity has its own set of surcharge types, for example, Fuel (per-trip), Parking Fee (per-trip), State Tax (per-seat). A reservation with one Tandem guest and one Adult guest would have one Fuel surcharge, one Parking Fee surcharge and three State Tax surcharges (for two personal seats of the Tandem guest and one personal seat of the Adult guest).

Transportation– refers to a part of reservation information that describes transportation to and from the place where the activity happens. Some suppliers provide free or paid transportation options for their guests, usually from hotels to the place where the activity starts.

“Staying at” Hotel– a hotel where activity attendants of a reservation live during their trip.

type CategoryIslandInfo
{
         string island;
         string links;
         string description;
}

Contains island-specific information on a Reservation system’s category. Used in methods’ output.

ChecklistItemInfo

type ChecklistItemInfo
{
         int id;
         string name;
         ChecklistItemType type;
         bool isPerSeat;
         bool isMandatory;
         string[] values;
         string defaultValue;
         int fieldSize;
}

Contains information on a Reservation system’s checklist item. Used in methods’ output.

id is used to identify the checklist item.

type determines the range of expected checklist values and the recommended representation of user interface controls to use for this checklist item. See description of the ChecklistItemType enum for a list of possible values.

isPerSeat specifies whether checklist values of this type are assigned to each of reservation’s personal seats, as opposed to the reservation as a whole.

isMandatory specifies whether a non-empty checklist value must be specified when creating reservations for the trip or for each guest; the service doesn’t currently control whether values are provided for the required checklist items, but it may do so in the future.

values lists allowed values for selection-type checklist items (RadioButtons and SelectBox types).

defaultValue specifies the default value for selection-type checklist items to be used when initializing user interface controls.

fieldSize specifies the recommended size (in characters) of input fields for field-type user interface controls; it isn’t meant as a limit of an allowed value length.

The service doesn’t currently control if the checklist values passed in reservation orders conform to the limitations set by type and values, but it may do so in the future.

ChecklistItemType

enum ChecklistItemType
{
         TextField,
         NumberField,
         TextArea,
         RadioButtons,
         CheckBox,
         SelectBox
}

Determines the type of a checklist item. Used in methods’ output.

TextField value is a single-line text string of arbitrary characters.

NumberField value is a single-line text string representing an integer non-negative number.

TextArea value is a multi-line text string of arbitrary characters.

RadioButtons or SelectBox value is a single-line text string chosen from a given set of values. It’s recommended to use a set of radio buttons for user interface of RadioButtons checklist items and a drop-down (“select”) box for SelectBox controls.

CheckBox value is either yes or no.

ChecklistValue

type ChecklistValue
{
         [null] int guestNumber;
         int checklistItemId;
         string value;
}

Contains checklist value for the given checklist item (if it’s a per-trip checklist item), or for the given personal seat number (guest number) and the given checklist item (if it’s a per-seat checklist item). Used in reservation orders passed to the service.

For per-seat checklist items reservation’s checklist values are specified for each of reservation’s personal seats. This is done using ChecklistValue objects with guestNumber ranging from zero to the number of reservation’s personal seats minus one. For per-trip checklist items guestNumber must be null.

CreditCardInfo

type CreditCardInfo
{
         string firstName;
         string lastName;
         string number;
         string securityCode;
         string expMonth;
         string expYear;
}

Contains credit card information. Used in methods’ input.

The only field that can be empty is securityCode.

GuestTypeInfo

type GuestTypeInfo
{
         int id;
         string name;
         string description;
         int availabilityPerGuest;
         bool noChargesApplied;
         double price;
}

Contains information on an activity’s guest type as of a specific date. (Returned by methods that are given the date as a parameter.) Used in methods’ output.

id is used to identify the guest type.

availabilityPerGuest specifies the amount of availability consumed by one guest of this type, or putting it in a different way, the number of personal seats that one guest of the guest type comprises.

noChargesApplied specifies whether guests of this type aren’t charged for per-seat surcharges and per-seat transportation.

price is the guest type price effective at the date for which the GuestTypeInfo object was generated.

HotelInfo

type HotelInfo
{
         int id;
         string name;
         string island;
         Address address;
         string localPhone;
         string tollFreePhone;
}

Contains information on a hotel. Used in methods’ output.

id is used to identify the hotel.

island is the name of the island the hotel is situated on. Island names in Reservation system are uniform: the same string (for example, Kauai) is used as the name of the given island (no variations like kauai or KAUAI).

IdCount

type IdCount
{
         int id;
         int count;
}

Contains a numeric identifier of some object and the number assigned to this object. Used in arrays to specify counts for multiple entities, for example, counts for several guest types in a reservation order; in this case, id is a guest type identifier and count is the number of ordered guests for this guest type.

ModificationInfo

type ModificationInfo
{
         int reservationId;
         int modificationId;
         string reason;
         string description;
         double amountPaidToSupplier;
}

Contains information on a reservation modification. Used in methods’ output.

reservationId is an identifier of the modified reservation in Reservation system.

modificationId is an identifier of the reservation modification in Reservation system.

reason is a reason provided by whoever made the modification.

description is generated by the Reservation system and contains information on what was changed in the reservation.

amountPaidToSupplier is a sum of amounts of payments made from the customer to the supplier, credits issued by the supplier to the customer (counted as negative amounts), voids of supplier payments (counted as negative amounts), and voids of supplier credits. In general, it’s a difference between the total amount of non-voided supplier payments/credits after the modification and the same total amount before the modification.

ReservationChecklistValue

type ReservationChecklistValue
{
         [null] int guestNumber;
         int checklistItemId;
         string checklistItemName;
         string value;
}

Contains checklist value for the given checklist item (if it’s a per-trip checklist item), or for the given personal seat number (guest number) and the given checklist item (if it’s a per-seat checklist item). Also contains the checklist item name. Used in reservation information returned by the service.

For per-seat checklist items reservation’s checklist values can be specified for each of reservation’s personal seats. This is done using ReservationChecklistValue objects with guestNumber ranging from zero to the number of reservation’s personal seats minus one. For per-trip checklist items guestNumber must be null.

ReservationGuestInfo_v2

ReservationGuestInfo_v2
{
         int guestTypeId;
         string guestTypeName;
         int count;
         bool noChargesApplied;
         double price;
}

Contains the number of guests for the given guest type, the guest type name and information on the price that was used for this guest type. Used in reservation information returned by the service.

noChargesApplied specifies whether guests of this type weren’t charged for per-seat surcharges and per-seat transportation charges.

ReservationInfo_v3

type ReservationInfo_v3
{
         int id;
         SupplierInfo supplier;
         ActivityInfo activity;
         double totalPrice;
         double commission;
         date date;
         string firstName;
         string lastName;
         Address address;
         string contactPhone;
         string email;
         ReservationGuestInfo_v2[] guestInfos;
         double guestsPrice;
         ReservationUpgradeInfo_v2[] upgradeInfos;
         double upgradesPrice;
         ReservationSurchargeInfo_v2[] surchargeInfos;
         double surchargesPrice;
         HotelInfo stayingAtHotel;
         string room;
         [null] TransportationRouteInfo transportationRoute;
         [null] double transportationRoutePrice;
         [null] bool transportationRoutePriceIsPerAvailability;
         [null] HotelInfo pickupHotel;
         [null] int pickupTimeMinutes;
         string transportationComments;
         double transportationPrice;
         date arrivalDate;
         string voucherId;
         ReservationChecklistValue[] checklistValues;
         string comments;
         bool cancelled;
         [null] int cancellationModificationId;
}

Contains information on a Reservation system’s reservation. Used in methods’ output.

id is used to identify the reservation.

date is the activity date of the reservation.

totalPrice is the total reservation price, including the commission.

commission is the agency’s commission for the reservation.

guestInfos is an array of ReservationGuestInfo_v2 objects, one for each guest type used in the reservation.

upgradeInfos is an array of ReservationUpgradeInfo_v2 objects, one for each upgrade used in the reservation.

surchargeInfos is an array of ReservationSurchargeInfo_v2 objects, one for each surcharge applied to the reservation.

stayingAtHotel describes reservation’s “staying at” hotel; it can be a special hotel like “not listed” or “local residence”.

transportationRoute describes reservation’s transportation route, if any. If it’s specified then transportationRoutePrice, transportationRoutePriceIsPerAvailability, pickupHotel and pickupTimeMinutes are specified as well; if it’s null then those four fields are null as well.

transportationRoutePrice is the transportation route price that was used for the reservation, if any.

transportationRoutePriceIsPerAvailability specifies whether the transportation route price was applied on per-seat or per-trip basis; defined if the reservation has a transportation route.

pickupHotel describes reservation’s pickup hotel; defined if the reservation has a transportation route.

pickupTimeMinutes specifies the time of day when attendants are picked up for transportation at the pickup hotel, presented as number of minutes from midnight (from 0, which means 00:00, to 1439, which means 23:59); defined if the reservation has a transportation route.

transportationPrice is the transportation price that was applied for the entire reservation.

checklistValues is an array of ReservationChecklistValue objects, one for each per-trip checklist item value filled in the reservation and one for each combination of per-seat checklist item and reservation’s personal seat that have a value filled in the reservation.

cancelled specifies whether the reservation is currently cancelled. (Reservations that were cancelled but then restored are not considered cancelled.)

cancellationModificationId is an identifier of the Reservation system’s reservation modification that cancelled this reservation, if it’s currently cancelled. In exceptional cases cancellationModificationId may be null even for a cancelled reservation.

ReservationOrder_v2

type ReservationOrder_v2
{
         date date;
         string firstName;
         string lastName;
         Address address;
         string contactPhone;
         string email;
         IdCount[] guestCounts;
         IdCount[] upgradeCounts;
         int stayingAtHotelId;
         string room;
         [null] int transportationRouteId;
         string transportationComments;
         date arrivalDate;
         string voucherId;
         ChecklistValue[] checklistValues;
         string comments;
}

Contains desired parameters of a reservation to be created, updated or evaluated. Used in methods’ input.

guestCounts is an array of IdCount objects, one for each ordered guest type. id fields of those IdCount objects are guest types’ identifiers, count fields determine the number of ordered guests. count fields must be greater than zero.

upgradeCounts is an array of IdCount objects, one for each ordered upgrade. id fields of those IdCount objects are upgrades’ identifiers, count fields determine the number of ordered upgrades. count fields must be greater than zero.

stayingAtHotelId is the identifier of the “staying at” hotel to be assigned to the reservation.

transportationRouteId is the identifier of the transportation route to be assigned to the reservation.

checklistValues is an array of ChecklistValue objects; each of them specifies a value for a per-trip checklist item or for a combination of per-seat checklist item and reservation’s personal seat.

firstName, lastName and contactPhone must be non-empty. guestCounts must contain at least one item.

ReservationSurchargeInfo_v2

type ReservationSurchargeInfo_v2
{
         int surchargeId;
         string surchargeName;
         int count;
         double price;
         bool priceIsPerAvailability;
}

Contains the number of the given surcharges applied to the reservation, the surcharge name and information on the price that was used for this surcharge. Used in reservation information returned by the service.

priceIsPerAvailability specifies whether the surcharge was applied on per-trip or per-seat basis. For per-trip surcharges (priceIsPerAvailability is false) one surcharge was applied to an entire reservation, unless the reservation had no non-free guests. For per-seat surcharges one surcharge was applied for each personal seat of reservation’s non-free guests.

ReservationUpgradeInfo_v2

type ReservationUpgradeInfo_v2
{
         int upgradeId;
         string upgradeName;
         int count;
         double price;
}

Contains the number of the given upgrades added to the reservation, the upgrade name and information on the price that was used for this upgrade. Used in reservation information returned by the service.

ServiceLogin

type ServiceLogin
{
         string username;
         string password;
}

Contains the user name and the password to log into the service. Passed to all service methods.

The service accepts the logins (user names and passwords) that the Reservation system accepts for its agency interface. A valid login must be passed for every method except for testLogin to work.

SupplierInfo

type SupplierInfo
{
         int id;
         string name;
         int[] categoryIds;
         Address address;
         string rsvpPhone;
         string adminPhone;
         string tollFreePhone;
         string fax;
         string url;
         string cancellationPolicy;
}

Contains information on a Reservation system’s supplier. Used in methods’ output.

id is used to identify the supplier.

SurchargeInfo

type SurchargeInfo
{
         int id;
         string name;
         double price;
         bool priceIsPerAvailability;
}

Contains information on an activity’s surcharge as of a specific date. (Returned by methods that are given the date as a parameter.) Used in methods’ output.

id is used to identify the surcharge.

price is the surcharge price effective at the date for which the SurchargeInfo object was generated.

priceIsPerAvailability specifies whether the surcharge is applied on per-trip or per-seat basis. For per-trip surcharges (priceIsPerAvailability is false), one surcharge is applied to an entire reservation, unless the reservation contains no non-free guests. For per-seat surcharges, one surcharge is applied for each of reservation’s non-free guests.

TransportationMappingItem

type TransportationMappingItem
{
         int stayingAtHotelId;
         int transportationRouteId;
         string transportationOptionIdCode;
}

Specifies which transportation option (see type TransportationOption) will be used for a given combination of the “staying at” hotel and transportation route. Used in methods’ output.

TransportationOption

type TransportationOption
{
         string idCode;
         [null] int pickupHotelId;
         int pickupTimeMinutes;
         string description;
         double price;
         bool priceIsPerAvailability;
}

Contains information on an activity’s “transportation option” (which is a set of transportation-related parameters that can change depending on which transportation route and “staying at” hotel is selected) as of a specific date. (Returned by methods that are given the date as a parameter.) Used in methods’ output.

idCode is used to identify the transportation option. Those identifiers are used in TransportationMappingItem objects to reference a specific transportation option.

pickupHotelId specifies a different pickup hotel to be used in this transportation option. If this field is null then the pickup hotel is the same as the “staying at” hotel.

pickupTimeMinutes specifies the time of day when attendants are picked up for transportation at the pickup hotel, presented as number of minutes from midnight (from 0, which means 00:00, to 1439, which means 23:59).

price is the transportation price effective at the date for which the TransportationOption object was generated.

priceIsPerAvailability specifies whether the transportation price is calculated on per-trip or per-seat basis. For per-trip transportation options (priceIsPerAvailability is false), the transportation price is charged as is. (Currently the per-trip transportation price is charged for reservations that have no non-free guests, but this is subject to change.) For per-seat transportation options, the transportation price is multiplied by the number of reservation’s non-free guests.

TransportationRouteInfo

type TransportationRouteInfo
{
         int id;
         string name;
}

Contains information on a Reservation system’s transportation route. Used in methods’ output.

id is used to identify the transportation route.

UpgradeInfo

type UpgradeInfo
{
         int id;
         string name;
         double price;
}

Contains information on an activity’s upgrade as of a specific date. (Returned by methods that are given the date as a parameter.) Used in methods’ output.

id is used to identify the upgrade.

price is the upgrade price effective at the date for which the UpgradeInfo object was generated.