Tour Service ============== The tour service provides endpoints that allow access to information about tours. A Tour is something that tracks unique item purchases within a category of items. This can be used to incentivize and reward guests to try new items. An example could be a brewery that wants their patrons to try different styles of beer or a ice cream brand that wants guests try all of their ice cream flavors. All purchase tracking is done through the POS integration; the tour service provides information about the tours available to each guest their progress. .. contents:: Topics Endpoints --------- Get Active Tours ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: tour/activeTours.json Obtains a list of tours that are currently active for a given merchant. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] tours: *(required)* The list of tours that are currently active for the merchant. See :http:jsonentity:`ActiveTour` for the format of these objects. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Get Tour Status ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: tour/tourStatus.json Retrieves a guest's progress for a given tour. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :query String tourCode: *(required)* The code uniquely identifying the tour to query. :query String printedCardNumber: *(required)* Printed card number associated with the account for which to retrieve tour information. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String firstName: *(optional)* The guest's first name if known. :jsonparam String lastName: *(optional)* The guest's last name if known. :jsonparam String tier: *(required)* The tier of the guest. :jsonparam String maskedCardNumber: *(required)* The guest's card number masked for display. :jsonparam List[Object] purchasedItems: *(required)* The list of items the guest has purchased as part of this tour. See :http:jsonentity:`PurchasedItemInfo` for the format of these objects. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Reply Objects ------------- .. http:jsonentity:: ActiveTour Information about a Tour that is currently active. :jsonparam String code: *(required)* Unique code of the tour. :jsonparam String label: *(required)* A displayable label for the tour. :jsonparam DateTime startDate: *(optional)* Date and time that the tour begins if applicable. :jsonparam DateTime endDate: *(optional)* Date and time that the tour ends if applicable. :jsonparam Object trackedProduct: *(required)* The category of items tracked by this tour. See :http:jsonentity:`TrackedProdcut` for the format of this object. .. http:jsonentity:: TrackedProduct Information about a category of menu items tracked as part of a tour. :jsonparam String productType: *(required)* Describes the scope of the tracked category. Valid values are ``MAJOR_GROUP`` and ``MINOR_GROUP``. :jsonparam String id: *(required)* The unique category identifier. :jsonparam String definition: *(optional)* An optional product definition. .. http:jsonentity:: PurchasedItemInfo Information about an item purchased as part of a tour. :jsonparam String itemId: *(required)* The identifier of this purchased item. :jsonparam String itemName: *(required)* The item name. :jsonparam DateTime purchaseDatetime: *(required)* The date when this item was purchased :jsonparam Object purchaseStore: *(required)* Information about the store where this item was purchased. See :http:jsonentity:`StoreInfo` for the format of this object. .. http:jsonentity:: StoreInfo Information about a store. :jsonparam String code: *(required)* The store's unique code. :jsonparam String name: *(required)* The name of this location. Error Codes ----------- The following are the possible codes and messages that can be returned by the Tour Service. There are other system-level errors which may be returned which are not documented here. The caller display the returned message end user or, if different wording is desired, can provide their own mapping of code to message. +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | Code | Message | +===================================================+===========================================================================================+ | ``active_tours_failure.general`` | Failed to retrieve active tours error | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``active_tours_failure.invalid_merchant_id`` | Invalid merchant id | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.general`` | Failed to retrieve tour status | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.invalid_merchant_id`` | Invalid merchant id | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.invalid_tour_code`` | Invalid tour code | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.invalid_card_number`` | Invalid card number | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.user_information_error`` | Unable to find account user information | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.store_locations_error`` | Unable to get store locations | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.store_info_error`` | Unable to get store info | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.purchased_item_error`` | Unable to get purchased item history | +---------------------------------------------------+-------------------------------------------------------------------------------------------+ | ``tour_status_failure.item_info_error`` | Unable to get purchased item info | +---------------------------------------------------+-------------------------------------------------------------------------------------------+