TI2 Bokun Plugin

This is a TourConnect TI2 plugin for integrating with the Bokun booking platform using REST V1 APIs.

Prerequisites

This plugin is designed to work with the TourConnect TI2 Docker environment. Make sure you have:

• Docker and Docker Compose installed
• The TI2 container running from ../bbtesting

Installation

The plugin is automatically mounted into the TI2 container via the docker-compose-ti2.yml configuration.

To install dependencies within the TI2 container:

# From the bbtesting directory
cd ../bbtesting
docker-compose exec ti2 bash -c "cd /ti2-bokun && npm install"

Or if you have Node.js installed locally:

npm install

Configuration

The plugin uses the following configuration:

API Credentials

The accessKey and secretKey are provided via:

1. TI2 instantiation - Passed when creating the plugin instance (production use)
2. Environment variables - For testing: ti2_bokun_accesskey and ti2_bokun_secretkey (already configured in Docker)

User Configuration Parameters

The following parameters are configured by the user through TI2:

• endpoint: The Bokun API endpoint (default: https://api.bokun.io, use https://api.bokuntest.com for testing)
• tenant: Your Bokun vendor subdomain (the hostname prefix before .bokun.io / .bokuntest.com). Used with endpoint to build publicUrl and privateUrl when the API does not return them (same idea as ti2-rezdy deriving URLs from the configured API host).
• testMode: Boolean flag to use test environment

Booking URLs: BothpublicUrl / privateUrl (or related fields) are derived from endpoint + tenant: customer publicUrl as https://{tenant}.{domain}/sales/{confirmationCode}, and privateUrl as https://{tenant}.{domain}/booking/{confirmationCode} (same subdomain as your Bokun vendor site). Adjust paths if Bokun changes routing.

Features

The plugin supports the following TI2 operations:

• Token Validation: Validates Bokun API credentials
• Product Search: Retrieves and translates Bokun products
• Availability Search: Checks product availability and pricing
• Availability Calendar: Returns availability in calendar format
• Pickup Points: Retrieves pickup locations for products
• Create Booking: Creates new bookings in Bokun
• Cancel Booking: Cancels existing bookings
• Search Booking: Retrieves booking details

API Compliance

This plugin uses the Bókun REST v1 API (OpenAPI spec). Endpoints used:

| TI2 operation | Method | Endpoint | Spec | |-----------------|--------|----------|------| | Token validation | POST | /activity.json/search | ActivityQuery body: { page, pageSize } | | Product search | POST | /activity.json/search | ActivityQuery body: { page, pageSize, currency? } | | Product by ID | GET | /activity.json/{id} | Query: currency?, lang? | | Availability | GET | /activity.json/{id}/availabilities | Query: start (required), end (required), currency?, includeSoldOut? | | Pickup places | GET | /activity.json/{id}/pickup-places | — | | Create booking | POST | /checkout.json/submit then /checkout.json/confirm-reserved/{confirmationCode} | Checkout submit + confirm flow | | Cancel booking | POST | /booking.json/cancel-booking/{confirmationCode} | Body: { note?, notify? } | | Get booking | GET | /booking.json/booking/{confirmationCode} | Query: currency?, lang? |

API Authentication

The plugin implements Bokun's HMAC-SHA1 signature authentication as described in their API documentation. Each request includes:

• X-Bokun-Date: Request timestamp in UTC
• X-Bokun-AccessKey: Your access key
• X-Bokun-Signature: HMAC-SHA1 signature of the request

Testing

To run tests within the TI2 container:

# From the bbtesting directory
cd ../bbtesting
docker-compose exec ti2 bash -c "cd /ti2-bokun && npm test"

Or if you have Node.js installed locally in this plugin directory:

npx jest "index.test.js" --config='{}'

To run only the core operations covered in current regression tests:

npx jest "index.test.js" --config='{}' --runInBand --testNamePattern="searchAvailability|createBooking|cancelBooking|searchBooking|validateToken|searchProducts|availabilityCalendar"

Note: some negative-path tests intentionally exercise error handling (for example invalid token, malformed availability key, or booking lookup failures). Those tests may print console.error lines while still passing.

Environment Setup

For development and testing, you can use Bokun's test environment:

• Test Extranet: https://.bokuntest.com
• Test API: https://api.bokuntest.com
• Test App Store: https://appstore.bokuntest.com

License

GPL-3.0