Operator API Integration Guide¶

This guide describes how operators can integrate with the TBT Operator API to retrieve booking events.

Authentication¶

All requests must be authenticated using your API Token. You can obtain your API Token and Base URL by contacting us at [email protected].

We support three methods for passing your API token:

1. Query Parameter¶

Pass the token as a query parameter named token.

GET /operator-api/v1/events?token=YOUR_API_TOKEN

2. Custom Header¶

Pass the token in the X-API-KEY header.

GET /operator-api/v1/events
X-API-KEY: YOUR_API_TOKEN

3. Authorization Header (Bearer)¶

Pass the token in the standard Authorization header with the Bearer scheme.

GET /operator-api/v1/events
Authorization: Bearer YOUR_API_TOKEN

Endpoints¶

Get Events¶

Retrieve a list of recent webhook events (bookings, updates, etc.) specifically for your operator account.

URL: /operator-api/v1/events
Method: GET

Query Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter events by status. Common statuses: `NEW`, `DELIVERED`, `FAILED`.
`after`	string	No	Filter events created after a specific point. Accepts: 1. ISO 8601 Datetime (e.g., `2023-10-27T10:00:00`) 2. Unix Timestamp (seconds or float) 3. Event ID (e.g., `evt_123`) - fetches events created after this event.
`limit`	integer	No	Number of events to return. Default is 10, maximum is 100.

Behavior:

Returns a maximum of 100 events (default is 10).
If after is NOT provided, only returns events created in the last 24 hours.
If after IS provided, returns events created strictly after the specified time or event.
Events are sorted by creation date (newest first).

Response Format:

Returns a JSON array of event objects.

[
  {
    "id": "evt_12345",
    "event_name": "bookings.create",
    "payload": {
      "booking": {
        "contact_first_name": "John",
        "contact_last_name": "Doe",
        "date_booked": "2023-10-27T09:55:00Z",
        "date_paid": "2023-10-27T10:00:00Z",
        "departure_area": "Bangkok",
        "departure_area_id": "area_bkk",
        "departure_station": "Khaosan Road",
        "departure_station_id": "stat_khaosan",
        "destination_area": "Koh Tao",
        "destination_area_id": "area_kohtao",
        "destination_station": "Mae Haad Pier",
        "destination_station_id": "stat_maehaad",
        "status": "CONFIRMED",
        "price": 1500,
        "group_size": 2,
        "date_departure": "2023-10-28",
        "time_departure": "06:00:00",
        "datetime_departure": "2023-10-28T06:00:00",
        "date_arrival": "2023-10-28",
        "time_arrival": "14:00:00",
        "datetime_arrival": "2023-10-28T14:00:00",
        "route_name": "Bangkok -> Koh Tao",
        "route_id": "rout_bkk_kt",
        "extra_params": null,
        "operator_code": "OP_CODE_123",
        "code": "BOOK_ID_123"
      }
    },
    "status": "NEW",
    "date_created": "2023-10-27T10:00:00Z",
    "date_delivered": null
  }
]

Event Statuses¶

NEW: The event has been created but not yet processed or pushed to a webhook (if configured).
DELIVERED: The event was successfully pushed to your configured webhook URL.
FAILED: The system attempted to push the event to your webhook but failed after retries.
INACTIVE: No webhook URL is configured for your account, but the event is available via this API.

Examples¶

cURL¶

Retrieve new events using cURL with header authentication:

curl -X GET "https://api.thailandboattickets.com/operator-api/v1/events?status=NEW" \
     -H "X-API-KEY: YOUR_API_TOKEN" \
     -H "Accept: application/json"

Polling with 'after'¶

Retrieve events created after a specific event ID (useful for polling loops):

curl -X GET "https://api.thailandboattickets.com/operator-api/v1/events?after=evt_last_processed_id" \
     -H "X-API-KEY: YOUR_API_TOKEN"

Python Script¶

Here is a complete Python script to fetch new events and process them.

import requests
import time

# Configuration
API_BASE_URL = "https://api.thailandboattickets.com/operator-api/v1"
API_TOKEN = "YOUR_API_TOKEN"  # Replace with your actual token

def fetch_new_events():
    """
    Fetch NEW events from the Operator API.
    """
    endpoint = f"{API_BASE_URL}/events"
    headers = {
        "X-API-KEY": API_TOKEN
    }
    params = {
        "status": "NEW",
        "limit": 10  # Optional: specify limit
    }

    try:
        response = requests.get(endpoint, headers=headers, params=params)
        response.raise_for_status()
        events = response.json()
        return events
    except requests.exceptions.RequestException as e:
        print(f"Error fetching events: {e}")
        return []

def process_booking(booking_data):
    """
    Process a single booking object.
    """
    print(f"Processing booking: {booking_data.get('code')} "
          f"for {booking_data.get('contact_first_name')} {booking_data.get('contact_last_name')}")

    # Example: Accessing fields
    route = booking_data.get('route_name')
    departure = booking_data.get('date_departure')
    print(f"  Route: {route}")
    print(f"  Departure: {departure}")

    # TODO: Add your own logic here (e.g., save to database, send ticket)

def main():
    print("Fetching new events...")
    events = fetch_new_events()

    if not events:
        print("No new events found.")
        return

    print(f"Found {len(events)} events.")

    for event in events:
        event_name = event.get("event_name")
        payload = event.get("payload", {})

        if event_name == "bookings.create":
            booking = payload.get("booking")
            if booking:
                process_booking(booking)
            else:
                print(f"Event {event.get('id')} missing booking data.")
        else:
            print(f"Skipping unhandled event type: {event_name}")

if __name__ == "__main__":
    main()