Overview

Introduction

In Short

The following requirements must be satisfied for an API request to be successful:

  • Successful authentication using an API key
  • Use of Accept header with a supported Media Type
  • Use of Accept-Language header with a supported language
  • Use of correct HTTP verb
  • Existing resource identified by the URL path

Please continue reading to get an in-depth explanation of all these requirements.

Authentication

Overview

API v2 supports OAuth2 authentication to get access to the data. You will be provided with client_id and client_secret which you'll use to authenticate yourself in the system.

Getting Access Token

The first thing you need to do is to get access token which you will then use will all your requests. This token is valid for 1 hour only. When it expires, you will need to request another one.

You can get you access token by POSTing to the /oauth2/token endpoint the following paramaters:

  • grant_type (this should always be "client_credentials")
  • client_id
  • client_secret

Example Request:

$ curl --data "grant_type=client_credentials&client_id=username&client_secret=password" https://api2.trekksoft.com/oauth2/token

Example Response:

{
    "access_token": "79ab80aba81592906b43a3d10d7c49c68cf0951a",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null
}

Authorization of requests

Once you have a valid access token, you will need to use it to sign all requests made to the TrekkSoft API.

This is done by providing Authorization HTTP header along with each of your requests in the following format:

Authorization: <token_type> <access_token>

Example Request:

$ curl -k -H"Authorization: Bearer 79ab80aba81592906b43a3d10d7c49c68cf0951a" https://api2.trekksoft.com/activities?limit=1

Resources

Merchants List

GET/merchants

Gets a list of merchants.

Request Parameters

NameRequiredTypeDescriptionExample
idOptionalArrayFilter for merchant IDs. Could be one (or several) IDs. Multiple filters are combined like this: id[]=506&id[]=716630
languageOptionalStringFilter for merchant language. If not provided, information in merchant's default language will be returnedde

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
idIntegerMerchant ID82
slugStringMerchant codebus2alps
nameStringNameBus2Alps
languageStringLanguage of the merchant detailsde
defaultLanguageStringDefault(primary) language of the merchantde
supportedLanguagesArrayA list of languages supported by the merchant['de', 'en']
userFieldsArrayA list of extra details which users are required to fill in when making a booking with this merchant[]
userFields[0]['code']StringInternal code of the user fieldmeetingpoint
userFields[0]['label']StringLabel which should be shown for the field (in current language)Meeting Point
userFields[0]['type']StringControl type of the field. Possible options are
  • text - single line text field
  • textarea - multiline text field
  • radio - group of radio buttons
  • select - select box
  • date - datepicker
Winter
userFields[0]['options']ArrayA list of options to select from for field types radio and select. NULL for other field types[]
userFields[0]['options'][0]['key']StringOption key (this should be sent to server when customer selects the option during booking process)ringgenberg
userFields[0]['options'][0]['value']StringOption value (this should be shown to the customer)Milan Hotel Ringgenberg
userFields[0]['isRequired']BooleanDefines whether this field is required or optionaltrue
currencies[]ArrayCurrencies which are supported by merchant in ISO4217 format (see https://en.wikipedia.org/wiki/ISO_4217 for more info)['USD','CHF','EUR']
partnerCurrencies[]ArrayCurrencies which are supported by merchant's partners in ISO4217 format (see https://en.wikipedia.org/wiki/ISO_4217 for more info)['USD','CHF','EUR']
defaultCurrencyStringDefault currency of the merchant in ISO4217 formatCHF
conversionRates[]ArrayConversion rates for this merchant from default currency['EUR':1, 'GBP':1.1601, 'CHF':0.8322]
multiDiscountsArrayPossible multidiscounts supported by this merchant[0, 5, 7]
formats[]ArrayVarious display formats specific to merchant (and his language!). For more info on date/time formats see http://php.net/manual/en/function.date.php[]
formats[shortDateTime]StringShort date timen/j/Y g:i A
formats[shortDate]StringShort daten/j/Y
formats[shortTime]StringShort timeg:i A

Activities List

GET/activities

Gets a list of activities information.

Request Parameters

NameRequiredTypeDescriptionExample
idOptionalArrayFilter for activity IDs. Could be one (or several) IDs. Multiple filters are combined like this: id[]=506&id[]=716630
languageOptionalStringFilter for activity language. If not provided, activity details in merchant's default language will be returnedde
merchantOptionalArrayFilter for merchant code. Could be one (or several) merchants. Multiple filters are combined like this: merchant[]=bus2alps&merchant[]=outdoor-interlaken.bus2alps
categoryOptionalArrayFilter for activity category ID. Could be one (or several) categories. Multiple filters are combined like this: category[]=12&category[]=5.12
internalOptionalBooleanEnable internal guest fields. System hide the intenal guest fields if this parameter is not empty.1
limitOptionalIntegerLimit50
offsetOptionalIntegerOffset10

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
idIntegerActivity ID82
merchantStringMerchant codebus2alps
languageStringLanguage of the activityde
defaultLanguageStringDefault(primary) language of the merchantde
titleStringActivity's title in the current languageFlorence 2 The Amalfi
highlightsStringActivity's highlights in the current language (contains HTML markup)<b>Lorem</b> ipsum
itineraryStringActivity's itinerary description in the current language (contains HTML markup)<b>Lorem</b> ipsum
customValuesArrayExtra details for the activity, different depending on merchant[]
customValues[0]['code']StringCustom field internal codeseason
customValues[0]['title']StringTitle of the custom field in the current languageSeason
customValues[0]['value']StringValue of the custom field for this activityWinter
customValues[0]['key']StringInternal value (id) of the custom field for this activitywinter
guestFieldsArrayA list of extra details which guests are required to fill in when booking this activity (merchant-defined)[]
guestFields[0]['code']StringInternal code of the guest fieldmeetingpoint
guestFields[0]['label']StringLabel which should be shown for the field (in current language)Meeting Point
guestFields[0]['type']StringControl type of the field. Possible options are
  • text - single line text field
  • textarea - multiline text field
  • radio - group of radio buttons
  • select - select box
  • date - datepicker
Winter
guestFields[0]['options']ArrayA list of options to select from for field types radio and select. NULL for other field types[]
guestFields[0]['options'][0]['key']StringOption key (this should be sent to server when customer selects the option during booking process)ringgenberg
guestFields[0]['options'][0]['value']StringOption value (this should be shown to the customer)Milan Hotel Ringgenberg
guestFields[0]['isRequired']BooleanDefines whether this field is required or optionaltrue
addonsArrayA list of addons available for this activity[]
addons[0][id]IntegerAddon ID237
addons[0][title]StringAddon's title in the current languagePrice per boat Voucher for the speedboat trip activity
addons[0][description]StringAddon's description in the current language (contains HTML markup)<b>Lorem</b> ipsum
addons[0][type]StringType of the addon. Possible options are
  • item - activity-bound addon
  • guest - guest-bound addon
guest
addons[0][price][amount]FloatPrice of this addon120.50
addons[0][price][currency]StringCurrency of this addonCHF
descriptionStringActivity's description in the current language (contains HTML markup)<b>Lorem</b> ipsum
departureArrayDeparture point for this activity. See options below for details{'country':{..}, 'city':{}}
departure['country']ArrayDeparture country (code and name){'code':'IT', 'name':'Italy'}
departure['city']ArrayDeparture city (id, UN/LOCODE and name){'id':3176, 'locode':'ZRH', 'name':'Zurich'}
categoryArrayCategory of the activity (id and name){'id':1, 'name':'Outdoor'}
_linksArrayLinks to additional resources for the activity (such as images, videos, documents). See options below for details[]
_links[images]ArrayURLs for the images for the activity, images are grouped under header, teaser and gallery keys. URLs contain template variables {width} and {height} which you need to replace with desired width and height before using them.[]
_links[images][header]StringURL for the activity header//url.com/{width}x{height}.jpg
_links[images][teaser]StringURL for the activity teaser//url.com/{width}x{height}.jpg
_links[images][gallery]ArrayA list of URLs of gallery images for the activity[]
_links[videos]ArrayURL(s) for the activity's video(s)[]
_links['documents']ArrayURL(s) for the activity's informational document(s)[]
fromPriceArrayStarting price for this activity which is set up by merchant (for reference, actual price might differ depending on selected price categories and discounts during booking process). Might be NULL if there's nothing to sell or no price specified[]
fromPrice[amount]FloatStarting price amount105.25
fromPrice[currency]StringStarting price currency (always matches owning merchant's default currency)EUR

Specific Activity

GET/activities/{activityId}

Gets information for the specific activity

Request Parameters

NameRequiredTypeDescriptionExample
activityIdRequiredInteger [url parameter] Desired activity id630
languageOptionalStringFilter for activity language. If not provided, activity details in merchant's default language will be returnedde
internalOptionalBooleanEnable internal guest fields. System hide the intenal guest fields if this parameter is not empty.1

Response

Availabilities

Request Availabilities

GET/availabilities

Requests which activities are available

Request Parameters

NameRequiredTypeDescriptionExample
activityIdOptionalArrayFilter for activity IDs. Could be one (or several) IDs. Multiple filters are combined like this: activityId[]=506&activityId[]=716630
typeOptionalArrayAvailability types to filter for. Should be one (or several) of `trip`, `day_trip`, `voucher`, e.g. type[]=trip&type[]=day_triptrip
bookingTimeOptionalStringDate/time in ISO 8601 format of when you expect booking to happen (usually you should set it to the current date and time). It would filter out availability items which are not bookable after this time.2016-08-09T18:31:42+03
seatsOptionalIntegerQuantity of required seats (defaults to 1). Providing this number would filter out availability items which don't have enough remaining seats for the booking. Bear in mind that this only applies generic filter for availability items, individual limits per price categories might apply. If your oauth key allows overbooking for certain merchants, this filter would be ignored.1
activeOnlyOptionalBooleanSet this to false to get items for all availability items (including disabled/blocked ones).true
withExclusiveOptionalBooleanSet this to true to include exclusive private events in the resulttrue
categoryOptionalArrayPrice categories to search for in format (id=>available seats), e.g. category[123]=5&category[234]=6123
merchantOptionalArrayFilter for merchant code. Could be one (or several) merchants. Multiple filters are combined like this: merchant[]=bus2alps&merchant[]=outdoor-interlaken.bus2alps
startsFromOptionalStringActivity start datetime range begin2015-03-13
startsToOptionalStringActivity start date range end2015-03-13
departureTimeOptionalStringDeparture time09:00:00
languageOptionalStringFilter for availability language. If not provided, availability details in merchant's default language will be returnedde
limitOptionalIntegerLimit50
offsetOptionalIntegerOffset10

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
merchantStringMerchant codebus2alps
languageStringLanguagede
defaultLanguageStringMerchant's default languagede
activityIdIntegerActivity ID82
availabilityRuleIdStringAvailability Rule ID42964301287
availabilityItemIdStringAvailability Item ID42964301287_attraction_20150310000000
startDateStringDeparture Date2015-03-11
startTimeStringDeparture Time10:45:00
durationStringDuration in ISO 8601 formatP1D
bookingNoteStringBooking Noteseats available
availableSeatsIntegerQuantity of available seats for availability. Note that individual limits for each category might be applied (see categories section below)30
capacityIntegerCapacity of availability (e.g. how many people can the boat contain). Note that individual limits for each category might be applied (see categories section below)100
occupancyIntegerOccupancy of availability (how many seats are reserved)50
categoriesArrayA list of all booking options, see details below[]
categories[id]IntegerPrice category ID7623933
categories[name]StringPrice category nameAll guests
categories[description]StringPrice category descriptionEverybody is welcome to book
categories[availableSeats]IntegerQuantity of available seats for price category (price categories with no available seats are not returned). Might return NULL if there is no limit for price category (in this case global available seats limit is applied, see availableSeats option above)20
categories[capacity]IntegerCapacity of availability for price category. Might return NULL if there is no limit for price category (in this case global capacity limit is applied, see capacity option above)80
categories[occupancy]IntegerOccupancy of availability for price category10
categories[minSeats]IntegerMinimum number of seats which is allowed for this price category (used for group bookings)1
categories[maxSeats]IntegerMaximum number of seats which is allowed for this price category20
categories[price][amount]FloatPrice of this price category120.50
categories[price][currency]StringCurrency of this price categoryCHF

Request Activity Availabilities

GET/activities/{activityId}/availabilities

Request Availabilities for the given activityId

Request Parameters

NameRequiredTypeDescriptionExample
activityIdOptionalInteger[url parameter] Desired activity ID630
typeOptionalArrayAvailability types to filter for. Should be one (or several) of `trip`, `day_trip`, `voucher`, e.g. type[]=trip&type[]=day_triptrip
bookingTimeOptionalStringDate/time in ISO 8601 format of when you expect booking to happen (usually you should set it to the current date and time). It would filter out availability items which are not bookable after this time.2016-08-09T18:31:42+03
seatsOptionalIntegerQuantity of required seats (defaults to 1). Providing this number would filter out availability items which don't have enough remaining seats for the booking. Bear in mind that this only applies generic filter for availability items, individual limits per price categories might apply. If your oauth key allows overbooking for certain merchants, this filter would be ignored.1
activeOnlyOptionalBooleanSet this to false to get items for all availability items (including disabled/blocked ones).true
withExclusiveOptionalBooleanSet this to true to include exclusive private events in the resulttrue
categoryOptionalArrayPrice categories to search for in format (id=>available seats), e.g. category[123]=5&category[234]=6123
merchantOptionalArrayFilter for merchant code. Could be one (or several) merchants. Multiple filters are combined like this: merchant[]=bus2alps&merchant[]=outdoor-interlaken.bus2alps
startsFromOptionalStringActivity start datetime range begin2015-03-13
startsToOptionalStringActivity start date range end2015-03-13
departureTimeOptionalStringDeparture time09:00:00
languageOptionalStringFilter for availability language. If not provided, availability details in merchant's default language will be returnedde
limitOptionalIntegerLimit50
offsetOptionalIntegerOffset10

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
merchantStringMerchant codebus2alps
languageStringLanguagede
defaultLanguageStringMerchant's default languagede
activityIdIntegerActivity ID82
availabilityRuleIdStringAvailability Rule ID42964301287
availabilityItemIdStringAvailability Item ID42964301287_attraction_20150310000000
startDateStringDeparture Date2015-03-11
startTimeStringDeparture Time10:45:00
durationStringDuration in ISO 8601 formatP1D
bookingNoteStringBooking Noteseats available
availableSeatsIntegerQuantity of available seats for availability. Note that individual limits for each category might be applied (see categories section below)30
capacityIntegerCapacity of availability (e.g. how many people can the boat contain). Note that individual limits for each category might be applied (see categories section below)100
occupancyIntegerOccupancy of availability (how many seats are reserved)50
categoriesArrayA list of all booking options, see details below[]
categories[id]IntegerPrice category ID7623933
categories[name]StringPrice category nameAll guests
categories[description]StringPrice category descriptionEverybody is welcome to book
categories[availableSeats]IntegerQuantity of available seats for price category (price categories with no available seats are not returned). Might return NULL if there is no limit for price category (in this case global available seats limit is applied, see availableSeats option above)20
categories[capacity]IntegerCapacity of availability for price category. Might return NULL if there is no limit for price category (in this case global capacity limit is applied, see capacity option above)80
categories[occupancy]IntegerOccupancy of availability for price category10
categories[minSeats]IntegerMinimum number of seats which is allowed for this price category (used for group bookings)1
categories[maxSeats]IntegerMaximum number of seats which is allowed for this price category20
categories[price][amount]FloatPrice of this price category120.50
categories[price][currency]StringCurrency of this price categoryCHF

Request Specific Availability

GET/availabilities/{availabilityItemId}

Request Specific Availability by its ID

Request Parameters

NameRequiredTypeDescriptionExample
availabilityItemIdOptionalString[url parameter] Desired availability item ID42964302142_trip_20150928093000_20150928143000
typeOptionalArrayAvailability types to filter for. Should be one (or several) of `trip`, `day_trip`, `voucher`, e.g. type[]=trip&type[]=day_triptrip
bookingTimeOptionalStringDate/time in ISO 8601 format of when you expect booking to happen (usually you should set it to the current date and time). It would filter out availability items which are not bookable after this time.2016-08-09T18:31:42+03
seatsOptionalIntegerQuantity of required seats (defaults to 1). Providing this number would filter out availability items which don't have enough remaining seats for the booking. Bear in mind that this only applies generic filter for availability items, individual limits per price categories might apply. If your oauth key allows overbooking for certain merchants, this filter would be ignored.1
activeOnlyOptionalBooleanSet this to false to get items for all availability items (including disabled/blocked ones).true
withExclusiveOptionalBooleanSet this to true to include exclusive private events in the resulttrue
categoryOptionalArrayPrice categories to search for in format (id=>available seats), e.g. category[123]=5&category[234]=6123
merchantOptionalArrayFilter for merchant code. Could be one (or several) merchants. Multiple filters are combined like this: merchant[]=bus2alps&merchant[]=outdoor-interlaken.bus2alps
startsFromOptionalStringActivity start datetime range begin2015-03-13
startsToOptionalStringActivity start date range end2015-03-13
departureTimeOptionalStringDeparture time09:00:00
languageOptionalStringFilter for availability language. If not provided, availability details in merchant's default language will be returnedde
limitOptionalIntegerLimit50
offsetOptionalIntegerOffset10

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
merchantStringMerchant codebus2alps
languageStringLanguagede
defaultLanguageStringMerchant's default languagede
activityIdIntegerActivity ID82
availabilityRuleIdStringAvailability Rule ID42964301287
availabilityItemIdStringAvailability Item ID42964301287_attraction_20150310000000
startDateStringDeparture Date2015-03-11
startTimeStringDeparture Time10:45:00
durationStringDuration in ISO 8601 formatP1D
bookingNoteStringBooking Noteseats available
availableSeatsIntegerQuantity of available seats for availability. Note that individual limits for each category might be applied (see categories section below)30
capacityIntegerCapacity of availability (e.g. how many people can the boat contain). Note that individual limits for each category might be applied (see categories section below)100
occupancyIntegerOccupancy of availability (how many seats are reserved)50
categoriesArrayA list of all booking options, see details below[]
categories[id]IntegerPrice category ID7623933
categories[name]StringPrice category nameAll guests
categories[description]StringPrice category descriptionEverybody is welcome to book
categories[availableSeats]IntegerQuantity of available seats for price category (price categories with no available seats are not returned). Might return NULL if there is no limit for price category (in this case global available seats limit is applied, see availableSeats option above)20
categories[capacity]IntegerCapacity of availability for price category. Might return NULL if there is no limit for price category (in this case global capacity limit is applied, see capacity option above)80
categories[occupancy]IntegerOccupancy of availability for price category10
categories[minSeats]IntegerMinimum number of seats which is allowed for this price category (used for group bookings)1
categories[maxSeats]IntegerMaximum number of seats which is allowed for this price category20
categories[price][amount]FloatPrice of this price category120.50
categories[price][currency]StringCurrency of this price categoryCHF

Capture Availability

POST/reservations

Captures (reserves) specific availability for future booking. Usually done on the checkout page just before placing a booking.
Important note: make sure you take into consideration `minSeats` and `maxSeats` information for availability.
E.g. if you want to book 3 single seat items (maxSeats=1) for price category 567, you have to treat them as separate: [{567:1}, {567:1}, {567:1}]
For group seats (minSeats>1) you need to specify quantity directly: [{765: 3}]
If minSeats, maxSeats or available seats limitations are exceeded, response with status 400 will be returned (with error details) and items will not be captured.

Request Parameters

NameRequiredTypeDescriptionExample
availabilityItemIdRequiredStringAvailability item ID42964301287_attraction_20150310000000
priceCategoriesRequiredArrayPrice categories to be captured in [{"id":"quantity"},...] format. Alternatively {"id":"quantity", ...} format can be used.[{12220:1}, {12223: 2}]
durationOptionalStringSpecifies for how long availability should be captured. Set this to the minimal required duration you require so that not to block bookings for other users. Note that server might limit capture duration time in case you request too long duration. Duration is set in ISO 8601 formatPT300S
referenceOptionalStringUse it for re-capturing. If reference is provided, it will be uncaptured first and a new capture is created with details provided in this requestEB573591CEF285C12701

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
referenceStringCapture reference - unique code for the captured availability. You will need it when placing a booking to uncapture availability32397D3E869EA04C71DD
releasedReferenceStringIf reference was provided in request this will contain id of the released availability captureEB573591CEF285C12701
expiresStringExpiration date and time for the capture. After this time capture reference will not longer be valid2015-03-09T13:07:04+00:00

Uncapture Availability

DELETE/reservations/{reference}

Uncaptures (releases) previously captured availability. This is usually needed when basket is cancelled to free up capacity for other users

Request Parameters

NameRequiredTypeDescriptionExample
referenceRequiredStringCapture reference received when availability was captured32397D3E869EA04C71DD

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
releasedReferenceStringCapture reference which was released32397D3E869EA04C71DD

Bookings

Create a Booking

POST/bookings

Creates a Booking

Request Parameters

NameRequiredTypeDescriptionExample
itemsOptionalArrayItems to be booked, details are explained below[]
items[0]['availabilityCaptureReference']OptionalStringAvailability capture reference which should have previously been received at Capture Availability call. When booking is created, this reference will no longer be valid.J9QR4223476AJR
items[0]['availabilityItemId']RequiredStringOne or group of Availability Item ID's (separated with comma) which need to be booked42964301287_attraction_20150310000000
items[0]['guests'][0]['occupancy']RequiredIntegerHow many seats to occupy for guest1
items[0]['guests'][0]['firstname']OptionalStringGuest firstnameJohn
items[0]['guests'][0]['lastname']OptionalStringGuest lastnameDoe
items[0]['guests'][0]['priceCategoryId']RequiredIntegerGuest price category ID41347
items[0]['guests'][0]['discountCode']OptionalStringDiscount code (if any)FREE2015
items[0]['guests'][0]['addons']OptionalArrayIds of addons applied for this guest[{id:12}, ...]
items[0]['guests'][0]['customFields']OptionalArrayA list of guest's custom field values in format id: value[{'key':'pickup', 'value':'location1'},...]
items[0]['addons']OptionalArrayAddons applied for this availability item: id and quantity[{id:12, quantity:2}, ...]
items[0]['note']OptionalStringUser note for this itemLorem ipsum
shopItemsOptionalArrayList of shop items to be booked: id and quantity[{id:3, quantity:1}, ...]
vouchersOptionalArrayList of applied vouchers['ubercode1', 'vouc2015']
noteOptionalStringBooking noteLorem ipsum
customFieldsOptionalArrayA list of bookee's custom field values in format id: value[{'key':'passport', 'value':'AS434633'},...]
contactRequiredArrayUser contact details[]
contact['type']RequiredStringContact type, possible values: email and mobileemail
contact['name']RequiredStringContact nameJonny Depp
contact['value']RequiredStringContact value, i.e. "email" or "mobile number"some@email.com
contact['notify']OptionalBooleanFlag specifying whether notification should be sent on this contact channel or not. True by default. Currently only email notifications are supportedtrue
multidiscountOptionalFloatCustom multidiscount percentage (only for agent bookings). Overrides default multidiscount (if there was any)15.5
paymentOptionalArrayOffline payment details (only for agent bookings). Omit it for creating a reservation. Details explained below[]
payment['treasurer']OptionalStringTreasurer IDmandator-11
payment['reference']OptionalIntegerPayment reference ID92
payment['amount']RequiredFloatAmount which user paid to the agent145.00
payment['currency']RequiredStringPayment's currencyCHF
creditCardOptionalArrayCredit card info. Pass this information if you are paying by credit card. You can specify either payment or credit card[]
creditCard['ccnumber']RequiredStringCredit card number1234567898765432
creditCard['expiryYear']RequiredIntegerExpiration year2030
creditCard['expiryMonth']RequiredIntegerExpiration month12
creditCard['name']RequiredStringCard holder nameJohn Doe
creditCard['cvc']RequiredIntegerSecurity code (CVC)123
numberOptionalStringCustom booking numberorder#2231

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
idIntegerCreated Basket ID10037406

List of Bookings

GET/bookings

Shows recent bookings

Request Parameters

NameRequiredTypeDescriptionExample
merchantOptionalArray | StringFilter for selling merchant. Could be one (or several) merchants. Multiple filters are combined like this: merchant[]=bus2alps&merchant[]=outdoor-interlakenoutdoor-interlaken

Response

The response is an array of objects, each containing the following properties.
NameTypeDescriptionExample
idIntegerBasket ID10037406
merchantStringSelling merchantbus2alps
totalFloatBasket total160.75
currencyStringCurrency of the bookingCHF
conversionRateFloatConversion rate1.1601
createdAtStringDate and time of basket creation2016-02-15T04:33:30+01:00
itemsArrayItems list, details are explained below[]
items[0]['id']IntegerItem id560
items[0]['caption']String
items[0]['activity']['id']IntegerActivity id623
items[0]['activity']['merchant']StringActivity's owner merchantbus2alps
items[0]['activity']['language']StringLanguage of the activityen
items[0]['activity']['defaultLanguage']StringDefault language of the activityen
items[0]['activity']['title']StringTitle of the activityRome 2 Taste of Tuscany
items[0]['activity']['departure']ArrayDeparture point for this activity. See options below for details{'country':{..}, 'city':{}}
items[0]['activity']['departure']['country']ArrayDeparture country (code and name){'code':'IT', 'name':'Italy'}
items[0]['activity']['departure']['city']ArrayDeparture city (id, UN/LOCODE and name){'id':3176, 'locode':'ZRH', 'name':'Zurich'}
items[0]['availabilityItem']['availabilityItemId']StringAvailability Item ID42964301287_attraction_20150310000000
items[0]['availabilityItem']['startDate']StringStart date2016-03-05
items[0]['availabilityItem']['startTime']StringStart time08:00:00
items[0]['availabilityItem']['timezone']StringTimezoneEurope/Berlin
items[0]['availabilityItem']['guests']ArrayGuest's info[{price:30.60, addonPrice:11.10, total: 41.70, ...}]
itemsPriceFloatPrice for all items160.75
shopItemsArrayList of shop items[]
shopItems[0]['id']IntegerShop item ID3
shopItems[0]['quantity']IntegerQuantity of the shop item2
shopItems[0]['price']FloatPrice for one shop item23.40
shopItems[0]['total']FloatTotal price for the shop item46.80
shopItemsPriceFloatTotal price for all shop items160.75
vouchersArrayA list of vouchers codes along with discount amount for each voucher.[{'code':'A','discount':12.4}]
vouchersDiscountFloatTotal discount for all vouchers160.75
multidiscountFloatMultidiscount amount7.5
taxesArrayA list of basket taxes[]
taxes[0]['title']StringTitle of the tax[]
taxes[0]['included']BooleanIndicates whether the tax is included into the price or not[]
taxes[0]['type']StringTax type, can be either percent or fixedpercent
taxes[0]['value']ArrayTax value, structure depends on tax type.
  • percent: will contain "percent" param, e.g. {'percent': 10} means "10%"
  • fixed: will contain "amount" and "currency" params, e.g. {'amount':20, 'currency':'CHF'} means "CHF 20"
{'percent':10}
feesArrayA list of fees[]
fees[0]['code']StringCode of the feebookingFee
fees[0]['value']FloatAmount of the fee2.5
userObjectUser's info{id: 24440472, name: 'John Doe', email: 'john.doe@example.com'}
agentObjectAgent's info{id: 14440472, name: 'Agent', 'commission': 5.00}

Specific Booking

GET/bookings/{bookingId}

Gets information for the specific booking

Request Parameters

NameRequiredTypeDescriptionExample
bookingIdRequiredInteger [url parameter] Desired booking id10037406
merchantOptionalArray | StringFilter for selling merchant. Could be one (or several) merchants. Multiple filters are combined like this: merchant[]=bus2alps&merchant[]=outdoor-interlakenoutdoor-interlaken

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
idIntegerBasket ID10037406
merchantStringSelling merchantbus2alps
totalFloatBasket total160.75
currencyStringCurrency of the bookingCHF
conversionRateFloatConversion rate1.1601
createdAtStringDate and time of basket creation2016-02-15T04:33:30+01:00
itemsArrayItems list, details are explained below[]
items[0]['id']IntegerItem id560
items[0]['caption']String
items[0]['activity']['id']IntegerActivity id623
items[0]['activity']['merchant']StringActivity's owner merchantbus2alps
items[0]['activity']['language']StringLanguage of the activityen
items[0]['activity']['defaultLanguage']StringDefault language of the activityen
items[0]['activity']['title']StringTitle of the activityRome 2 Taste of Tuscany
items[0]['activity']['departure']ArrayDeparture point for this activity. See options below for details{'country':{..}, 'city':{}}
items[0]['activity']['departure']['country']ArrayDeparture country (code and name){'code':'IT', 'name':'Italy'}
items[0]['activity']['departure']['city']ArrayDeparture city (id, UN/LOCODE and name){'id':3176, 'locode':'ZRH', 'name':'Zurich'}
items[0]['availabilityItem']['availabilityItemId']StringAvailability Item ID42964301287_attraction_20150310000000
items[0]['availabilityItem']['startDate']StringStart date2016-03-05
items[0]['availabilityItem']['startTime']StringStart time08:00:00
items[0]['availabilityItem']['timezone']StringTimezoneEurope/Berlin
items[0]['availabilityItem']['guests']ArrayGuest's info[{price:30.60, addonPrice:11.10, total: 41.70, ...}]
itemsPriceFloatPrice for all items160.75
shopItemsArrayList of shop items[]
shopItems[0]['id']IntegerShop item ID3
shopItems[0]['quantity']IntegerQuantity of the shop item2
shopItems[0]['price']FloatPrice for one shop item23.40
shopItems[0]['total']FloatTotal price for the shop item46.80
shopItemsPriceFloatTotal price for all shop items160.75
vouchersArrayA list of vouchers codes along with discount amount for each voucher.[{'code':'A','discount':12.4}]
vouchersDiscountFloatTotal discount for all vouchers160.75
multidiscountFloatMultidiscount amount7.5
taxesArrayA list of basket taxes[]
taxes[0]['title']StringTitle of the tax[]
taxes[0]['included']BooleanIndicates whether the tax is included into the price or not[]
taxes[0]['type']StringTax type, can be either percent or fixedpercent
taxes[0]['value']ArrayTax value, structure depends on tax type.
  • percent: will contain "percent" param, e.g. {'percent': 10} means "10%"
  • fixed: will contain "amount" and "currency" params, e.g. {'amount':20, 'currency':'CHF'} means "CHF 20"
{'percent':10}
feesArrayA list of fees[]
fees[0]['code']StringCode of the feebookingFee
fees[0]['value']FloatAmount of the fee2.5
userObjectUser's info{id: 24440472, name: 'John Doe', email: 'john.doe@example.com'}
agentObjectAgent's info{id: 14440472, name: 'Agent', 'commission': 5.00}

Calculate Booking Price

GET/bookingPrices

Calculates Booking Price

Request Parameters

NameRequiredTypeDescriptionExample
itemsOptionalArrayItems for which price should be calculated. Details are explained below[]
items[0]['availabilityItemId']RequiredStringAvailability Item ID42964301287_attraction_20150310000000
items[0]['guests'][0]['occupancy']RequiredIntegerHow many seats to occupy for guest1
items[0]['guests'][0]['priceCategoryId']RequiredIntegerGuest price category ID41347
items[0]['guests'][0]['discountCode']OptionalStringDiscount code (if any)FREE2015
items[0]['guests'][0]['addons']OptionalArrayAddons applied for this guest: id and quantity[{id:12, quantity:2}, ...]
items[0]['addons']OptionalArrayAddons applied for this availability item: id and quantity[{id:12, quantity:2}, ...]
shopItemsOptionalArrayList of shop items: id and quantity[{id:3, quantity:1}, ...]
vouchersOptionalArrayList of applied vouchers['ubercode1', 'vouc2015']
multidiscountOptionalFloatCustom multidiscount percentage (only for agent bookings). Overrides default multidiscount (if there was any)15.5
currencyRequiredStringCurrency which should be used for calculationCHF

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
merchantStringSelling merchantbus2alps
totalFloatBasket total160.75
currencyStringCurrency of the bookingCHF
conversionRateFloatConversion rate1.1601
createdAtStringDate and time of basket creation2016-02-15T04:33:30+01:00
itemsArrayItems list, details are explained below[]
items[0]['availabilityItemId']StringAvailability Item ID42964301287_attraction_20150310000000
items[0]['guests']ArrayList of guest's prices: price, addonPrice, total[{price:30.60, addonPrice:11.10, total: 41.70, ...}]
items[0]['total']FloatTotal item price160.75
itemsPriceFloatPrice for all items160.75
shopItemsArrayList of shop items[]
shopItems[0]['id']IntegerShop item ID3
shopItems[0]['quantity']IntegerQuantity of the shop item2
shopItems[0]['price']FloatPrice for one shop item23.40
shopItems[0]['total']FloatTotal price for the shop item46.80
shopItemsPriceFloatTotal price for all shop items160.75
vouchersArrayA list of vouchers codes along with discount amount for each voucher.[{'code':'A','discount':12.4}]
vouchersDiscountFloatTotal discount for all vouchers160.75
multidiscountArrayMultidiscount percent and amount{'percent':5, 'amount':7.5}
taxesArrayA list of basket taxes[]
taxes[0]['title']StringTitle of the tax[]
taxes[0]['included']BooleanIndicates whether the tax is included into the price or not[]
taxes[0]['type']StringTax type, can be either percent or fixedpercent
taxes[0]['value']ArrayTax value, structure depends on tax type.
  • percent: will contain "percent" param, e.g. {'percent': 10} means "10%"
  • fixed: will contain "amount" and "currency" params, e.g. {'amount':20, 'currency':'CHF'} means "CHF 20"
{'percent':10}
feesArrayA list of fees[]
fees[0]['code']StringCode of the feebookingFee
fees[0]['value']FloatAmount of the fee2.5

Validate Discount Code

GET/discountCodes

Validates Discount Code

Request Parameters

NameRequiredTypeDescriptionExample
discountCodeRequiredStringDiscount codeTEST-2342
activityIdRequiredIntegerActivity for which discount code is to be applied5835
priceRequiredIntegerAmount on which discount is to be applied150
currencyRequiredIntegerCurrency localede_DE

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
priceFloatPrice on which discount will be applied150
formattedPriceStringPrice on which discount will be applied, user-friendlyEUR 150
isValidBooleanIs discount code valid?true
discountFloatDiscount percentage10
discountAmountFloatDiscount amount15.0000000
formattedDiscountAmountStringDiscount amount, user-friendlyEUR 15.00
newPriceFloatPrice which will be after applying discount135.0000000
formattedNewPriceStringPrice which will be after applying discount, user-friendlyEUR 135.00

Cancel Booking

PUT/bookings/{bookingId}

Cancels specific booking

Request Parameters

NameRequiredTypeDescriptionExample
bookingIdRequiredIntegerID of booking to cancel10037406
reasonRequiredStringThe reason for the cancellationNo longer traveling
noteOptionalStringWhatever note you want to add to the bookingRefunded Customer

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
idIntegerID of canceled booking10037406

Set custom booking number

POST/booking-number

Set a custom number to a booking

Request Parameters

NameRequiredTypeDescriptionExample
idRequiredIntegerID of booking10037406
numberRequiredStringAny custom identifierorder#2231

Response

The response is an object containing the following properties.
NameTypeDescriptionExample
idIntegerID of affected booking10037406

Extras

Media Types

Custom media types are used in the API to allow developers choose the format and version of the data they wish to receive. This is done by adding one or more of the following types to the Accept header when sending a request.

application/vnd.trekksoft[.version][+format]
application/json

As of v1 of the API the following Accept header is recommended:

application/vnd.trekksoft.v1+json, application/json; q=.5

Schema

All requests to the TrekkSoft API must be over HTTPS using the domain api2.trekksoft.com.

Example Request:

$ curl -i https://api2.trekksoft.com/

Example Response (to an unauthorized request):

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=UTF-8
Date: Mon, 10 Apr 2015 10:26:20 GMT

{}

All date fields are returned in RFC 3339 format:

YYYY-MM-DDTHH:MM:SSZ

Examples:

2012-12-24T15:39:15+02:00
2013-01-14T08:12:47-03:00

HTTP Verbs

The API makes use of the HTTP verbs to indicate what kind of request you are sending.

GET    /activities           Lists all resources of the 'activities' collection.
POST   /activities           Creates a new resource in the 'activities' collection.
PUT    /activities           Updates multiple resources in the 'activities' collection.
DELETE /activities           Deletes multiple resources in the 'activities' collection.
GET    /activities/435       Reads a resource from the 'activities' collection.
PUT    /activities/435       Updates a resource in the 'activities' collection.
DELETE /activities/435       Deletes a resource in the 'activities' collection.

Please note, that not every collection supports all HTTP verbs.

Time Periods

Some date fields support additional time period notation paramters. The following syntax is supported:

[PERIOD_START][,PERIOD_END]

2014-01-01T00:00:00+02:00                               # After or at to 2014-01-01 00:00:00
2014-01-01T00:00:00+02:00,2014-01-31T23:59:59+02:00     # Between 2014-01-01 00:00:00 and 2014-01-31 23:59:59
2014-01-31T23:59:59+02:00                              # Before or at 2014-01-31 23:59:59

Pagination

Requests that return multiple items are paginated to 30 items by default. Developers can control pagination by using the offset (default: 0) and limit (default: 30) query parameters. The custom limit may not exceed 100.

GET /activities?offset=0&limit=20
GET /activities?offset=20&limit=20
GET /activities?offset=40&limit=20