Worldwide activity ticketing with Tiqet¶

The tiqet.com is a new supplier that provides access to worldwide tickets and exposes APIs for integration of product browsing and booking. This document explains how this supplier is expected to be integrated and used within TQPro system.

Approach and basic usage patterns¶

Available approaches¶

Tiqet.com provides a set of integration APIs that allow for browsing and booking of entrance tickets and vouchers for various attractions, museums, tours and other activities. The product offerings can be browsed and managed in two general approaches: - Product - based browsing (location, product name etc) - Experience - based browsing (first list all experiences in a given location, then select a product related to this experience) In TQPro, we will implement the second approach - experience based browsing (https://developers.tiqets.dev/integration-guides/product-integration/how-to-find-and-display-experiences-using-the-tiqets-api)

Usage patterns¶

We are looking at two typical usage patterns: 1. When a customer is browsing the public site to select the experience / purchase a ticket (or more tickets) and receive an online voucher 2. When an agent / employee is creating an itinerary for a client where multiple experiences can be bundled and included into a full itinerary with airline tickets, accommodations, transfers and other services - in this case there is no online payment and/or separate payment and voucher issuance but the result is a quotation for the customer. This should be a part of the Trip Management feature that is already partially implemented.

Workflows within the system¶

Public usage workflow (public ticketing site - part of BookMyHoliday web)¶

The public workflow will be destination-based and implemented within the BookMyHoliday webpage, enabled for public access. There will be set of destination pages (one webpage per destination) as currently implemented. In the current implementation, the page has a selected set of travel packages with their short descriptions and prices. In addition to this, there should be a list of experiences that are available at the selected destination. This list of experiences will be retrieved from the supplier (tiqet.com) with the usage of Experience APIs. Once an experience is selected, a specific experience page will be opened, which will be fully dynamic and will be created on the basis of the information retrieved from tiqet. The page will have a general layout of a hero image with header, basic text information about the experience, followed by a list of products available for this experience. This list of products will be represented in a "card" view of 4 cards per screen row, each card will contain the small photo for the product, star rating, price, basic short text information and activity button ("more info"). Selection of a product, either with a click on the image, name or "more info" button, will forward the customer to a third page (product page) with information about that particular product, and ability to select and add to cart (or proceed to checkout). The product information, as well as the checkout information, will be retrieved using the Product APIs from tiqet.

Post browsing, the customer will be allowed to proceed to check-out and payment to receive the purchased tickets and vouchers.

Agent usage workflow (tqweb admin site)¶

The agent workflow will be similar; when working within the Trip Management workspace (see the information), the agent will be presented with a list of experiences in the selected location; this list will be a vertical list of low-height rows, each row containing one horizontal card with a small activity picture in the left area, name of the activity with a short one-line description, and a "select" button; on selection, a popup will open with a list of available products for the experience with their price, and allow the agent to select one or more and to add them to the quotation with the associated price.

APIs exposed for usage in the applications¶

The system will expose the required APIs for usage in the BookMyHoliday webpage as well as the TqWeb Admin application. These APIs will follow all standards of other TQPro APIs and will not be directly reused from tiqet. Exposed APIs will follow the TQPro standard with parameters in the request body (not the HTTP URL parameters) and will return a structured response like the other TQPro APIs, and will have public (guest) access. The access will be restricted only for the APIs that are agent-specific (for use only in the TQWeb Admin application).

Public use APIs (for customer browsing)¶

Following APIs will be exposed for use on webpages: - List experiences per location - Get experience details - List products per experience - List products per location - Get product details

Private APIs (for agent use)¶

In addition to publicly accessible APIs, following APIs will be used for the agent interface during trip itinerary management: - List experiences per multiple locations (with list of locations as input) - Add product(s) to quote (i.e. to trip / itinerary) as mandatory or optional - Remove products(s) from quote

APIs consumed from supplier (tiqet.com)¶

Available APIs and their definitions can be found on the supplier webpage and they are openly accessible. For every API the link to the documentation is provided:

Cities and countries¶

Get list of countries: https://developers.tiqets.dev/basics/openapi/content-api/tags-cities-and-countries/get-list-of-countries
Get single country: https://developers.tiqets.dev/basics/openapi/content-api/tags-cities-and-countries/get-single-country
Get list of cities: https://developers.tiqets.dev/basics/openapi/content-api/tags-cities-and-countries/get-list-of-cities
Get single city: https://developers.tiqets.dev/basics/openapi/content-api/tags-cities-and-countries/get-single-city

Tags¶

Get tag types: https://developers.tiqets.dev/basics/openapi/content-api/tags-cities-and-countries/get-tag-types
Get list of tags: https://developers.tiqets.dev/basics/openapi/content-api/tags-cities-and-countries/get-list-of-tags
Get single tag: https://developers.tiqets.dev/basics/openapi/content-api/tags-cities-and-countries/get-a-single-tag

Experiences¶

Search and filter experiences: https://developers.tiqets.dev/basics/openapi/content-api/experiences/search-and-filter-experiences
Get single experience: https://developers.tiqets.dev/basics/openapi/content-api/experiences/get-single-experience

Products, availability and pricing¶

Search and filter products: https://developers.tiqets.dev/basics/openapi/content-api/products/search-and-filter-products
Get single product: https://developers.tiqets.dev/basics/openapi/content-api/products/get-single-product
Get product checkout information: https://developers.tiqets.dev/basics/openapi/content-api/products/get-product-checkout-information
Get product active variants: https://developers.tiqets.dev/basics/openapi/availability-and-pricing-api/get-all-active-product-variants
Get product calendar: https://developers.tiqets.dev/basics/openapi/availability-and-pricing-api/get-products-calendar
Get product opening times: https://developers.tiqets.dev/basics/openapi/availability-and-pricing-api/get-product-opening-times
Get availability and pricing: https://developers.tiqets.dev/basics/openapi/availability-and-pricing-api/get-product-availability-and-pricing

Product ratings¶

Get product reviews: https://developers.tiqets.dev/basics/openapi/content-api/product-rating-and-reviews/get-product-reviews
Get reviews summary: https://developers.tiqets.dev/basics/openapi/content-api/product-rating-and-reviews/get-reviews-summary

Orders and booking¶

Rules and regulatives for orders and booking are provided in the following page: https://developers.tiqets.dev/basics/openapi/booking-api/implementation-rules and https://developers.tiqets.dev/basics/openapi/booking-api/additional-visitor-details. API descriptions are following: - Create order: https://developers.tiqets.dev/basics/openapi/booking-api/create-order - Confirm order: https://developers.tiqets.dev/basics/openapi/booking-api/confirm-order - Get order information: https://developers.tiqets.dev/basics/openapi/booking-api/get-order-information - Retrieve tickets: https://developers.tiqets.dev/basics/openapi/booking-api/retrieve-tickets - Cancel order: https://developers.tiqets.dev/basics/openapi/booking-api/cancel-order - List orders: https://developers.tiqets.dev/basics/openapi/booking-api/list-orders

Implementation guideline¶

Internal API and web implementation¶

Internal (TQPro) APIs¶

The internal APIs need to follow the implementation principles of all TQPro APIs: - HTTP POST with JSON body, no URL arguments - Responses wrapped in a TQApiResponse structure - Facade for implementation of API logic - Canonical data structures for all objects interchanged between the backend and the frontend - Mapping between the canonical structures and the native supplier data model - Service layer implementing the supplier native services and wrapping them in the NTS service model

Integration with the supplier APIs¶

The supplier integration needs to follow a set workflow with rules. Below are the web pages with guidelines where that is explained: - JWT signing for secure APIs (not all APIs are considered secure): https://developers.tiqets.dev/integration-guides/jwt-signing-for-secure-api-requests - Product information for display to customers: https://developers.tiqets.dev/integration-guides/product-integration/sharing-essential-product-information-with-your-customers - Language selection for multilanguage products: https://developers.tiqets.dev/integration-guides/product-integration/how-to-implement-language-selection - Using products with multiple sources: https://developers.tiqets.dev/integration-guides/product-integration/maximising-availability-using-multi-sourcing - Cross-selling and upselling: https://developers.tiqets.dev/integration-guides/product-integration/how-to-implement-cross-and-upselling-using-product-groups - Marketing restrictions: https://developers.tiqets.dev/integration-guides/product-integration/how-to-comply-with-marketing-restrictions - Pre-selections in affiliate links: https://developers.tiqets.dev/integration-guides/product-integration/how-to-pass-pre-selected-fields-in-the-affiliate-link - Experience API: https://developers.tiqets.dev/integration-guides/product-integration/how-to-find-and-display-experiences-using-the-tiqets-api