ng-tourcms

AngularJS service for accessing the TourCMS API.

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 credentials
ng-tourcms:FAIL_SESSION_EXPIRED_DURATION - Transmitted whenever an API call is rejected due to an expiry of the users API credentials
ng-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);
    });

Type	Name	Latest commit message	Commit time
	Failed to load latest commit information.
	LICENSE
	README.md
	TODO.md
	ng-tourcms.js

TourCMS/ng-tourcms

Join GitHub today

Clone with HTTPS

Launching GitHub Desktop...

Launching GitHub Desktop...

Launching Xcode...

Launching Visual Studio...

README.md

ng-tourcms

Table of Contents

Status

Dependencies / Requirements

Installation / Configuration

Broadcast messages

API method wrappers

General/ Housekeeping APIs

Generic API request

Channel (Operator / Supplier) APIs

Tour (Product) APIs

Booking APIs

Payment APIs

Customer / Enquiry APIs

Travel Agents

Internal Supplier APIs