If you are connecting to the TourCMS API using PHP, .NET, JavaScript, Ruby or Python then you may find it easier to use one of the existing client libraries rather than rolling your own code.
RESTful API
The TourCMS Marketplace is a RESTful (REpresentational STate) XML based API which allows you to read (and possibly write) certain resources within TourCMS accounts that grant you access permissions.
Put simply: To call API methods you will be requesting a URL (with header information for authentication), possibly with query string parameters and receiving back an XML document. In general, calls that read information will be sent via HTTP GET and those that modify information will be sent via HTTP POST.
A full list of URLs (methods) that you can call plus the responses you will get back is available on the main API page.
Connection concept
The TourCMS Marketplace lets you connect to multiple individual TourCMS accounts via a single API. Marketplace agents accessing multiple accounts can use the /p/ (Partner) style calls as well as the /c/ style API.
Individual TourCMS accounts may only call the /c/ (Channel) style API calls (i.e. can only access their own data).
Each channel (think of a channel as a single company) has a Channel ID.
Each Marketplace agent has a Marketplace Account ID (MAID).
To connect as Marketplace Agent 10.
- Send MAID 10, Channel ID 0 - for the /p/ top level agent API calls
- Send MAID 10, Channel ID 20 - for the /c/ channel specific API calls to take data out of Channel 20
For individual TourCMS accounts (/c/ API calls only)
- Send MAID 0, Channel ID 20 - for the /c/ channel specific API calls
Authentication headers
Authentication is handled by passing in two special headers when making any request to the API:
- x-tourcms-date: The GMT date/time the request was generated
- Authorization: The text "TourCMS " and then three values separated by colons (Channel ID:Marketplace account ID:Signature)
- Channel ID - Can be 0 if you are a Marketplace agent searching multiple accounts.
- Marketplace Account ID - Your unique ID number, for Individual Operator accounts this should be left as 0
- Signature - See "Signature Generation" section below.
Example headers
x-tourcms-date: Thu, 05 Aug 201010:51:29 GMTAuthorization: TourCMS 0:1:rJaU8iuQlVWlHNi7sbAN187ziY63qIedWSFluEm4PKI%3D
Signature Generation
For a reference implementation please see the generate_signature function in the PHP Client Library or any of the other client libraries & sample code.
String to sign
First we build our string to sign, in the following format:
CHANNEL_ID/MARKETPLACE_ID/OUTBOUND_TIME/PATHCHANNEL_ID should be replaced with the ID of the Channel we are connecting to, or in the case of some Marketplace Agent API calls such as those searching across multiple Channels it can be 0.
MARKETPLACE_ID should be 0 for any Tour Operators calling the API, Marketplace Agents can find their ID in their welcome email or by logging into the Agent Portal and checking the API Settings area.
OUTBOUND_TIME should be replaced by the current unix timestamp, e.g. 1680556469, this must match the value sent in the x-tourcms-date header, e.g x-tourcms-date: Mon, 03 Apr 2023 21:14:29 GMT
PATH should be the path endpoint we are calling, including any querystring, e.g. rate_limit_status.xml.
Our full string then for Marketplace Agent 126 checking our API limit on Channel 3930 would be:
3930/126/GET/1680556469/rate_limit_status.xmlSigning the string
Generate a keyed hash value using the HMAC method with the sha256 algorithm using your TourCMS API key. This should then be base64 encoded.
Signing the above string with the API Key PASSWORD would give the signature LjnDY9uvgNwPQXrOFdSMECqFI4xabVGWO03BtNE2lcY%3D meaning our final headers would be:
x-tourcms-date: Mon, 03 Apr 2023 21:14:29 GMT
Authorization: TourCMS 3930:126:LjnDY9uvgNwPQXrOFdSMECqFI4xabVGWO03BtNE2lcY%3D
Content-type: application/xml