# 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.

| Environment    | URL                               | Purpose                 |
| -------------- | --------------------------------- | ----------------------- |
| **Production** | `https://api.ttdbooking.com`      | Live commercial traffic |
| **Testing**    | `https://api-test.ttdbooking.com` | Development and testing |

### Step 1: Get authentication

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

```bash
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:**

```json
{
  "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:

```http
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

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

header

```json
{
  "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.

```bash
# 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:

```typescript
// 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

| Feature Module      | Endpoint                        | Method | Description                                   |
| ------------------- | ------------------------------- | ------ | --------------------------------------------- |
| **Authentication**  | `/api/auth/ticket`              | POST   | Get access token                              |
| **Hotel rates**     | `/api/search/hotelList`         | POST   | Hotel list search                             |
| **Hotel rates**     | `/api/search/hotelRates`        | POST   | Rate query                                    |
| **Make bookings**   | `/api/search/checkAvail`        | POST   | check ARI                                     |
| **Make bookings**   | `/api/trade/book`               | POST   | Smart booking                                 |
| **Manage bookings** | `/api/trade/queryOrders`        | POST   | Order query                                   |
| **Manage bookings** | `/api/trade/cancel`             | POST   | Cancel order                                  |
| **Content**         | `/api/search/hotelsMetadata`    | POST   | Hotels metadata with pagination               |
| **Content**         | `/api/search/hotelStaticDetail` | POST   | Hotel static details — ⚠️ **[DEVELOPMENT]**   |
| **Content**         | `/api/search/destinations`      | POST   | Destinations where your customers book hotels |

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

---

### Performance targets

| Metric               | Value                               | Description                                                                               |
| -------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------- |
| **API Process Time** | < 1000ms                            | P95 process time (+1s network)                                                            |
| **Request ceiling**  | 10–100 requests / second / endpoint | Per client IP, by endpoint group — see [Rate limit](/hotel-api/docs/guides/rate-limit) |

---

### Overall architecture diagram

```mermaid
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.

| Language       | Status  |
| -------------- | ------- |
| **Java**       | Planned |
| **Go**         | Planned |
| **PHP**        | Planned |
| **JavaScript** | Planned |
| **TypeScript** | Planned |
| **Python**     | Planned |

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>.