Quick start

This page walks you from zero to a first booking call against the TTDbooking API. Work through the environment table, mint a ticket, then follow the four-step search-to-book sequence.

Environment setup

Point your client at the environment that matches what you are doing. Development and certification work belongs on the test host; only switch the base URL once you are live.

Step 1: Get authentication

A shared sandbox credential, ttdbooking_api_demo, is available so you can start integrating before your own keys are issued.

It reaches a simulated supplier only — no real hotel is ever booked — and everyone reading these docs shares it, so:

• send your own unique customerReferenceNo on every booking, and never real guest details;
• callbackUrl is not accepted on the shared key: poll queryOrders instead, or ask integrations@ttdbooking.com for your own test credentials to exercise order-status callbacks;
• its usage is capped across all its users, so a 429 means the shared budget is spent — try again shortly.

curl -X POST https://api-test.ttdbooking.com/api/auth/ticket \
  -H "Content-Type: application/json" \
  -d '{
    "appKey": "ttdbooking_api_demo",
    "appSecret": "ttdbooking_api_demo",
    "ttl": 3600
  }'

Response Example:

{
  "code": 0,
  "msg": "success",
  "data": {
    "ticket": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Step 2: Search hotels

Call POST /api/search/hotelList to find properties. See the HotelList reference at https://developer.ttdbooking.com/hotel-api/docs.

Step 3: Search rates

Call POST /api/search/hotelRates to price the properties you shortlisted. See the HotelRates reference at https://developer.ttdbooking.com/hotel-api/docs.

Step 4: CheckAvail

Call POST /api/search/checkAvail to confirm availability, rates and inventory before you commit. See the CheckAvail reference at https://developer.ttdbooking.com/hotel-api/docs.

Step 5: Book

Call POST /api/trade/book to create the reservation. See the Book reference at https://developer.ttdbooking.com/hotel-api/docs.

Essential headers

Send these on every authenticated request:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
Request-Id: uuid-v4
Trace-Id: trace-id
Session-Id: session-id
Language: en-US
Currency: USD
Timeout-Milliseconds: 5000

Standard response format

Every response uses the same envelope, so you can handle code and msg once and unwrap data per endpoint.

body

{
  "code": 0,
  "msg": "success",
  "data": {
    // Business data
  }
}

header

{
  "Request-Id": "request-id",
  "Trace-Id": "trace-id",
  "Server-Cost-Milliseconds": 500,
  "Session-Id": "verified-session-id"
}

Recommended practices during development

1. Drive configuration from environment variables

Keep hosts and credentials out of your source tree so promoting from test to production is a config change, not a code change.

# Required
TTDBOOKING_API_URL=https://api-test.ttdbooking.com
TTDBOOKING_APP_KEY=ttdbooking_api_demo
TTDBOOKING_APP_SECRET=ttdbooking_api_demo

# Optional
TTDBOOKING_TIMEOUT=10000
TTDBOOKING_RETRY_ATTEMPTS=3

2. Cache your ticket (important for performance)

Requesting a fresh ticket on every call adds avoidable latency. Hold the token in memory for its lifetime and refresh it slightly before it expires. The example below keeps a 5-minute safety margin against a 1-hour ticket:

// Cache tickets to avoid re-authentication every hour
class TicketCache {
  private cache = new Map<string, { token: string; expiresAt: number }>();

  async getTicket(appKey: string, appSecret: string): Promise<string> {
    const cached = this.cache.get(appKey);

    // Return cached token if still valid (with 5 min buffer)
    if (cached && Date.now() < cached.expiresAt - 300000) {
      return cached.token;
    }

    // Fetch new token
    const newToken = await this.fetchNewToken(appKey, appSecret);
    this.cache.set(appKey, {
      token: newToken,
      expiresAt: Date.now() + 3600000, // 1 hour
    });

    return newToken;
  }
}

// Usage
const ticketCache = new TicketCache();
const token = await ticketCache.getTicket("your_app_key", "your_app_secret");

API overview

Core interface mapping

⚠️ [DEVELOPMENT] /api/search/hotelStaticDetail is still under development. For production use, please refer to the HotelsMetadata API (/api/search/hotelsMetadata) first.

Performance targets

Overall architecture diagram

graph TB
    subgraph "Your Applications & Systems"
        A[Web Applications]
        B[Mobile Apps]
        C[Backend Systems]
    end

    subgraph "TTDbooking API Platform"
        E[Unified API Gateway<br/>Reliability/Security/Performance]
        F[Web Portal for observation & transparency<br/>Real-time monitoring, analytics, and reporting]
    end

    subgraph "Supplier Network"
        G[Contracted Hotel Suppliers]
        H[Hotel Inventory]
    end

    A --> E
    B --> E
    C --> E

    A --> F
    E --> G
    E --> H

    style E fill:#2196F3,stroke:#1976D2,stroke-width:3px,color:#fff
    style F fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff
    style G fill:#FF9800,stroke:#F57C00,stroke-width:2px,color:#fff
    style H fill:#9C27B0,stroke:#7B1FA2,stroke-width:2px,color:#fff

Infrastructure and network configuration

Most go-live delays are network problems, not code problems. Plan the items below alongside your integration work rather than at the end.

Common issues

• Waiting on IP allowlist entries to be applied
• SSL certificate setup
• Network connectivity problems
• Conflicts with your own security policies

Solutions

• Plan infrastructure early: start network configuration while you are still building
• Document your IPs: send your static IP addresses as soon as you have them
• Review security: complete your security assessment before go-live
• Use staging: validate every configuration in a pre-production environment first

Information we need from you

• Static IP addresses that will call the API
• SSL certificate requirements
• Your network security policies
• Any firewall configuration needs

SDK support (coming soon)

Native client libraries are planned for the languages below. Until they ship, integrate directly over HTTPS using the request and response formats shown above.

To be notified when an SDK becomes available, contact integrations@ttdbooking.com.

Need help?

Full endpoint references live at https://developer.ttdbooking.com/hotel-api/docs. For credentials, allowlisting, or integration questions, email integrations@ttdbooking.com.