ng-tourcms
AngularJS service for accessing the TourCMS API.
Table of Contents
- Status
- Dependencies / Requirements
- Installation / Configuration
- Broadcast messages
- API method wrappers
Status
Fairly stable, see Issues for more detail. Not all API methods implemented.
Dependencies / Requirements
-
Requires SHA256.js
-
Optionally, add X2JS to receive JSON back rather than the default XML
-
At the time of writing TourCMS API does not support CORS, thus this library is largely intended for use developing with AngularJS in native wrapper environments such as Cordova (Phonegap).
If using Cordova (Phonegap) you may need to whitelist network access to the TourCMS API onhttps://api.tourcms.com and - if you are linking to TourCMS hosted images - our media CDN on http://media.tourcms.com and http://*.rackcdn.com.
Installation / Configuration
Ensure ng-tourcms.js is included in your project, tourcms.ng-tourcms is required by your module and tourcmsApiService is injected wherever it will be used.
Call the configure method on tourcmsApiService to set your API parameters. channelID can alternatively be passed when
making API calls; those accessing the API as an Agent and thus working with multiple Channels will likely work in that way
rather than configuring here.
Typical Tour Operator configuration:
tourcmsApiService.configure({
private_key: 'Your API Key',
channel_id: 'Your Channel ID'
});Also supports multiple channel credentials, passed as an array
tourcmsApiService.configure([
{
private_key: 'Your API Key',
channel_id: 'Your Channel ID'
},
{
private_key: 'Your second API Key',
channel_id: 'Your second Channel ID'
}
]);Typical Marketplace Agent configuration (working with multiple Channels):
tourcmsApiService.configure({
private_key: 'Your API Key',
marketplace_id: 'Your Marketplace ID'
});Broadcast messages
In addition to returning error messages provided by TourCMS directly, the app will also broadcast messages to rootScope in certain situations. All messages are prefaced ng-tourcms:.
The current list is:
ng-tourcms:FAIL_SESSION_EXPIRED_IDLE- Transmitted whenever an API call is rejected due to a timeout on the users API credentialsng-tourcms:FAIL_SESSION_EXPIRED_DURATION- Transmitted whenever an API call is rejected due to an expiry of the users API credentialsng-tourcms:FAIL_SIG- Transmitted when a "FAIL_SIG" response is encountered, likely due to incorrect API credentials
Currently requires X2JS (see Dependencies / Requirements above).
API method wrappers
General/ Housekeeping APIs
API Rate Limit Status
Check the current API rate limit status.
tourcmsApiService.apiRateLimitStatus({channelId: 3930})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Generic API request
Provides an interface for calling APIs with no specific wrapper function.
E.g. to simulate API Rate Limit Status (above):
tourcmsApiService.genericRequest({
channelId: 3930,
path: '/api/rate_limit_status.xml'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Can also provide a verb (default is 'GET') and
postData, which - if provided - must be a DOM document representing the XML data
to post to the API.
Channel (Operator / Supplier) APIs
List Channels
List channels.
tourcmsApiService.listChannels()
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Show Channel
Show details on a specific channel.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.showChannel({channelId: 3930})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Channel Performance
List top 50 Channels by number of unique visitor clicks (or check performance for a specific channel).
Optonally supply an object containing a channelId to just return a specific Channel.
tourcmsApiService.ChannelPerformance()
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Tour (Product) APIs
Search Tours
Search Tours.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.searchTours({
channelId: 3930,
qs: {
k: 'rafting',
order: 'price_down'
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});List Tours
List Tours.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.listTours({
channelId: 3930
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Also supports passing of the various query string parameters
tourcmsApiService.listTours({
channelId: 3930,
qs: {
booking_style: "booking",
qc: 1
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Show Tour
Show details of a specific Tour.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.showTour({
channelId: 3930,
tourId: 1
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Also supports passing of the various query string parameters
tourcmsApiService.showTour({
channelId: 3930,
tourId: 1,
qs: {
show_options: 1,
show_offers: 1
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Show Tour Dates and Deals
List the dates available for a specific tour.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.showTourDatesDeals({
channelId: 3930,
tourId: 1
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Also supports passing of the various query string parameters
tourcmsApiService.showTourDatesDeals({
channelId: 3930,
tourId: 1,
qs: {
has_offer: 1,
distinct_start_dates: 1
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Show Departure
Show a departure, designed for managing dates and prices rather than displaying to customers. Includes the loaded rates, spaces, special offer details, bookings etc.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.showDeparture({
channelId: 3930,
tourId: 1,
departureId: 8117
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Update Departure
Update a departure.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
If X2JS is being used, departure data can be provided as an object
tourcmsApiService.updateDeparture({
channelId: 3930,
departure: {
tour_id: 1,
departure_id: 1234,
special_offer: {
offer_price: 45,
offer_note: "Early booking discount"
}
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});If X2JS is not being used, tour data must be provided as an XML string
tourcmsApiService.updateDeparture({
channelId: 3930,
tour: '<departure> ... <special_offer><offer_price>45</offer_price></special_offer></departure>'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Check Tour Availability
Check availability for a specific date and number of people on a specific tour.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
The following example checks availability for 2 people on the first rate (e.g. usually "2 Adults") on the 30th Jan 2015 for Tour ID 1 on Channel 3930.
tourcmsApiService.checkTourAvailability({
channelId: 3930,
qs: {
id: 1,
date: '2015-01-30',
r1: 2
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Check Option Availability
Check for Option availability.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
If X2JS is being used, tour data can be provided as an object
tourcmsApiService.checkOptionAvailability({
channelId: 3930,
qs: {
booking_id: 12662,
tour_component_id: 8052295
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Update Tour
Update the main details on a Tour, currently supports updating the Tour URL only.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
If X2JS is being used, tour data can be provided as an object
tourcmsApiService.updateTour({
channelId: 3930,
tour: {
tour_id: 1,
tour_url: '/example-tour_1/'
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});If X2JS is not being used, tour data must be provided as an XML string
tourcmsApiService.updateTour({
channelId: 3930,
tour: '<tour><tour_id>1</tour_id><tour_url>/example-tour_1/</tour_url></tour>'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Show Promo Code
Get details on a promotional code. Ueful for checking whether a promo code is valid for a certain channel, and if so, whether a membership number or similar is required to verify the promo.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
The following example tries to show promo code 'TENPERCENT' on Channel 3930.
tourcmsApiService.showPromo({
channelId: 3930,
promo: 'TENPERCENT'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Booking APIs
Search Bookings
Search for bookings, view basic details about each.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
The following example searches for active bookings made in June 2014 on Channel 3930.
tourcmsApiService.searchBookings({
channelId: 3930,
qs: {
active: 1,
made_date_start: '2014-06-01',
made_date_end: '2014-06-30'
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Show Booking
Get details on a specific Booking.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
The following example tries to show Booking 3770 on Channel 3930.
tourcmsApiService.showBooking({
channelId: 3930,
bookingId: 3770
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Start New Booking
Create a temporary booking, holding stock.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
If X2JS is being used, booking data can be provided as an object
tourcmsApiService.startNewBooking({
channelId: 3930,
booking: {
total_customers: 2,
components: {
component: [
{
component_key: 'YYY-YYYYYYY-YYYYY',
note: 'Some text'
},
{
component_key: 'ZZZ-ZZZZZZZ-ZZZZZ',
note: 'Extra info',
pickup_key: 'TTT-TTTTTTTTT-TTTTTT'
}
]
}
customers: {
customer: [
{
firstname: 'Joe',
surname: 'Bloggs'
}
]
}
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});If X2JS is not being used, booking data must be provided as an XML string
tourcmsApiService.startNewBooking({
channelId: 3930,
booking: '<booking><total_customers>2</totalcustomers><components> ... etc ... </components></booking>'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Delete Booking
Delete a temporary booking, releasing stock.
If a booking has been committed (see below) it can no longer be deleted, instead cancel it using the "Cancel Booking" method.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.deleteBooking({
channelId: 3930,
bookingId: 1234
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Commit Booking
Convert a temporary booking into a proper booking.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
If X2JS is being used, booking data can be provided as an object
tourcmsApiService.commitBooking({
channelId: 3930,
booking: {
booking_id: 1234,
suppress_email: 1
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});If X2JS is not being used, booking data must be provided as an XML string
tourcmsApiService.commitBooking({
channelId: 3930,
booking: '<booking><booking_id>1234</booking_id><suppress_email>1</suppress_email></booking>'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Cancel Booking
Cancel a committed booking.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.cancelBooking({
channelId: 3930,
bookingId: 1234,
note: 'Some reason for cancellation'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Add Note to Booking
Add a note to a booking.
There are multiple note types that can be used, see the API documentation linked above for details.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.addNoteToBooking({
channelId: 3930,
bookingId: 1234,
noteType: 'AUDIT',
noteText: 'Some text to add to booking'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Search Vouchers
Provide the barcode data from a TourCMS (or OTA) voucher and receive a list of matching components.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
NB: At the time of writing the text displayed under the barcode on TourCMS vouchers is not the same as the text contained within the barcode. For testing purposes grab the barcode_data from one of the Booking APIs or decode the QR code on a voucher.
tourcmsApiService.searchVouchers({
channelId: 3930,
voucherString: 'TOURCMS|4069|4112'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Redeem Voucher
Redeem (Check in) a particular component using a key obtained from "Search Vouchers".
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.redeemVoucher({
channelId: 3930,
key: 'Ax9SLSJFLSFJLS/oZu9NhurfJ8RMibtHmrL2kT6w=',
note: 'Optionally add a note here'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Add booking component
Add a Tour (with or without Options) to a booking, or add Options to an existing Tour that is already on a booking.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.addBookingComponent({
channelId: 3930,
booking: {
booking_id: 12920,
component: {
component_key: '500II4/cOf21qGqulu6E5lU9rjOa5qvmibXKFMh3otSkgCsUAbrdap/7CTxDKl+p'
}
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Remove booking component
Remove a tour from a regular (i.e. non-temporary, non-archived) booking.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.removeBookingComponent({
channelId: 3930,
booking: {
booking_id: 12920,
component: {
component_id: 8285991
}
}
})
.success(function(data, status) {
console.log('Success');
console.info(data);
})
.error(function(data, status) {
console.info(data || "Request failed");
console.info(status);
});Update booking component
Change some details of a particular booking component (tour/option/fee).
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.updateBookingComponent({
channelId: 3930,
booking: {
booking_id: 12920,
component: {
component_id: 8286001,
sale_quantity: 3
}
}
})
.success(function(data, status) {
console.log('Success');
console.info(data);
})
.error(function(data, status) {
console.info(data || "Request failed");
console.info(status);
});Send booking email
Send one of the pre-configured email templates.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.sendBookingEmail({
booking: {
booking_id: 12920,
email_type: 1
}
})
.success(function(data, status) {
console.log('Success');
console.info(data);
})
.error(function(data, status) {
console.info(data || "Request failed");
console.info(status);
});Payment APIs
Create Payment
Store details of a payment in TourCMS.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.createPayment({
channelId: 3930,
bookingId: 1234,
paymentValue: 100,
creditcardFeeType: 0,
paymentType: "Amex"
currency: 'GBP'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Spreedly Create Payment
Specialised version of "Create Payment" for those using TourCMS Spreedly integration.
Accepts a Spreedly payment method token, processes the payment via Spreedly and in the case of a successful payment, commits the booking and records details of the payment in TourCMS.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.createPayment({
spreedlyPaymentMethod: 'SPREEDLY_PAYMENT_METHOD_TOKEN'
channelId: 3930,
bookingId: 1234,
paymentValue: 100,
creditcardFeeType: 0,
paymentType: "Amex"
currency: 'GBP'
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Customer / Enquiry APIs
Show Customer
Get details on a specific customer.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.showCustomer({
channelId: 3930,
customerId: 1
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Travel Agents
Search Agents
Get a list of Travel Agents.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.searchAgents({
channelId: 3930,
qs: {
order: 'toprecent',
filter: 'staff_ui'
}
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});Internal Supplier APIs
Show Supplier
Get details on a specific Supplier.
If a Channel ID is not provided, the function will use the Channel ID configured on the service.
tourcmsApiService.showBooking({
channelId: 3930,
supplierId: 1
})
.success(function(data, status) {
console.log('Success');
console.log(data);
})
.error(function(data, status) {
console.log(data || "Request failed");
console.log(status);
});