Operators will have one or more Channels in their account, with an API key for each Channel. Marketplace Agents will be connected to one or more Channels, but use a single API key for all Channels they connect with.
Operators will send their Channel ID any time they make an API call. For Travel Agents, most endpoints such as those returning details on a specific tour, or making viewing bookings will need to be called with the appropriate Channel ID (i.e. multiple Operators will have a Tour with ID 1, or a booking with ID 1234). There are some API endpoints, for example those allowing Marketplace Agents to search for tours or bookings across any connected Channel where a Channel ID is not required and technically will be sent as 0.
Authentication is handled by passing in two special headers when making any request to the API:
First we build our string to sign, in the following format:
CHANNEL_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.
VERB should be the HTTP method of the request in uppercase (GET | POST).
OUTBOUND_TIME should be replaced by the current unix timestamp, e.g. 1696122473, this must match the value sent in the x-tourcms-date header, e.g x-tourcms-date: Sun, 01 Oct 2023 01:07:53 GMT
PATH should be the path endpoint we are calling, including any querystring, e.g. rate_limit_status.xml.
Our full string then for Operator request checking our API endpoint for search tours on channel 3930 would be:
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 yPd2KGsR4XCXrrL5nNh99iXn%2BCiPukV%2BMuBc2iU7uxo%3D meaning our final headers would be:
x-tourcms-date: Sun, 01 Oct 2023 01:07:53 GMT Authorization: TourCMS 3930:0:yPd2KGsR4XCXrrL5nNh99iXn%2BCiPukV%2BMuBc2iU7uxo%3D Content-type: application/xml