# API Reference This section documents every operation exposed by the TTDbooking Stays API. Each endpoint has its own page covering the complete request and response contract; this page explains how those endpoints fit together and the order to call them in. All operations use `POST` and are served over HTTPS. --- ## Base URLs | Environment | Base URL | | ----------- | --------------------------------- | | Test | `https://api-test.ttdbooking.com` | | Production | `https://api.ttdbooking.com` | Build and certify against the test environment first, then switch the base URL to production when you go live. Nothing else in your integration needs to change. --- ## Recommended integration flow The diagram below shows the calls a typical integration makes, from authentication through to reading back an order. ```mermaid sequenceDiagram participant C as Client participant A as API Gateway participant S as Search Service participant T as Trade Service participant P as Supplier Center Note over C, P: 1. Authentication C ->> A: POST /api/auth/ticket A ->> C: JWT Token Note over C, P: 2. Hotel Search C ->> A: POST /api/search/hotelList (with JWT) A ->> S: Hotel list request S ->> P: Call supplier search P ->> S: Return hotel list [with rates] S ->> A: Process and cache results A ->> C: Return hotel list [with rates] Note over C, P: 3. Rate Query [Optional] C ->> A: POST /api/search/hotelRates A ->> S: Rate query request S ->> P: Get real-time rates P ->> S: Return rate information S ->> A: Return rate details A ->> C: Return rate package information Note over C, P: 4. CheckAvail (price confirmation) [Optional] C ->> A: POST /api/search/checkAvail A ->> S: checkAvail request S ->> P: checkAvail request P ->> S: Return availability & price confirmation S ->> A: Return confirmation details A ->> C: Return confirmation details Note over C, P: 5. Booking (instant confirmation) C ->> A: POST /api/trade/book A ->> T: booking request T ->> P: Forward booking to supplier P ->> T: Return booking confirmation T ->> C: Booking confirmation Note over C, P: 6. Order Status Query C ->> A: POST /api/trade/queryOrders A ->> T: Query order T ->> A: Return order status with details A ->> C: Return order status with details ``` ### Sequence at a glance | Step | Operation | Method and path | Required? | | ---- | ----------- | ----------------------------- | --------- | | 1 | Ticket | `POST /api/auth/ticket` | Yes | | 2 | HotelList | `POST /api/search/hotelList` | Yes | | 3 | HotelRates | `POST /api/search/hotelRates` | Optional | | 4 | CheckAvail | `POST /api/search/checkAvail` | Optional | | 5 | Book | `POST /api/trade/book` | Yes | | 6 | QueryOrders | `POST /api/trade/queryOrders` | Yes | Steps 3 and 4 are marked optional because the flow is technically valid without them. In practice both are strongly recommended: `HotelRates` is how you obtain the full set of bookable packages for a property, and `CheckAvail` re-confirms price and availability immediately before you commit the booking. --- ## Authentication Call `POST /api/auth/ticket` to exchange your credentials for a JWT. Send that token with every subsequent request — search, booking and order-management calls are all authenticated the same way. See the [Ticket](/hotel-api/docs/api-reference/ticket) reference for the credential fields, token lifetime and how to present the token on later calls. ### OAuth 2.0 as an alternative If your HTTP client already speaks OAuth 2.0, you can use the `client_credentials` grant (RFC 6749 §4.4) instead of the ticket exchange, on the same endpoints. Ask your account manager to register a client; you will receive a `client_id` and `client_secret`. ```http POST /api/v1/oauth/token Content-Type: application/json { "grant_type": "client_credentials", "client_id": "...", "client_secret": "...", "scope": "search:read booking:write" } ``` The response carries an opaque `access_token` that you present exactly as you would a ticket: `Authorization: Bearer `. Three differences are worth knowing before you choose: - **Scopes are mandatory.** A ticket issued before scopes existed carries an empty list and has full access; an access token must carry the scope for each operation it calls — `search:read`, `content:read`, `booking:read`, `booking:write`, `booking:cancel` — and a token with no scopes is refused. You may request a subset of what your client is registered for; asking for anything else returns `invalid_scope`. - **Tokens are revocable.** They are stored, not stateless, so a revocation takes effect immediately rather than when the token would have expired. - **Order-status callbacks need a ticket credential.** `callbackUrl` on `POST /api/trade/book` registers a webhook signed with your Trade API key's secret, which an OAuth client does not have. Authenticate with a ticket to register callbacks, or poll [QueryOrders](/hotel-api/docs/api-reference/query-orders) instead. --- ## Endpoint catalogue ### Authentication | Endpoint | Path | What it does | | ------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- | | [Ticket](/hotel-api/docs/api-reference/ticket) | `POST /api/auth/ticket` | Exchanges your `appKey` / `appSecret` for the JWT that authorises every other call. | ### Content Static content endpoints describe destinations and properties. They are not priced or date-bound, so their responses can be cached and refreshed on your own schedule rather than fetched per search. | Endpoint | Path | What it does | | ------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Destinations](/hotel-api/docs/api-reference/destinations) | `POST /api/search/destinations` | Returns destination records — standard or detailed — looked up by destination ancestor ID or by country code. | | [HotelsMetadata](/hotel-api/docs/api-reference/hotels-metadata) | `POST /api/search/hotelsMetadata` | Returns property metadata for a destination, with pagination. | | [HotelStaticDetail](/hotel-api/docs/api-reference/hotel-static-detail) | `POST /api/search/hotelStaticDetail` | ⚠️ **[DEVELOPMENT]** This API is still under development. For production use, please refer to the [HotelsMetadata](/hotel-api/docs/api-reference/hotels-metadata) API first. | ### Search | Endpoint | Path | What it does | | ---------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [HotelList](/hotel-api/docs/api-reference/hotel-list) | `POST /api/search/hotelList` | Searches for properties on destination, stay dates and guest configuration, and returns the matching results with rates. | | [HotelRates](/hotel-api/docs/api-reference/hotel-rates) | `POST /api/search/hotelRates` | Expands a single property into its full set of room rates and availability. | ### Make bookings | Endpoint | Path | What it does | | ---------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | [CheckAvail](/hotel-api/docs/api-reference/check-avail) | `POST /api/search/checkAvail` | Re-verifies availability and confirms the price before you book, so inventory or rate movement is caught before the booking attempt. | | [Book](/hotel-api/docs/api-reference/book) | `POST /api/trade/book` | Places the booking order and reserves the room for the specified rate package. | ### Manage bookings | Endpoint | Path | What it does | | -------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | [QueryOrders](/hotel-api/docs/api-reference/query-orders) | `POST /api/trade/queryOrders` | Retrieves booking orders with filtering. Also the endpoint used for post-booking verification of an order's final state. | | [OrderVoucher](/hotel-api/docs/api-reference/order-voucher) | `POST /api/trade/orderVoucher` | Retrieves the hotel voucher for an order — the travel document your guest presents at the hotel, as a time-limited link or inline base64 PDF. | | [Cancel](/hotel-api/docs/api-reference/cancel) | `POST /api/trade/cancel` | Cancels a booking order and moves it to its cancelled state. | --- ## Related guides - [Booking flow](/hotel-api/docs/booking-flow) — the four-call search-to-confirmation sequence explained step by step. - [Error handling](/hotel-api/docs/guides/error-handling) — response codes and how to react to each class of failure. - [Rate limit](/hotel-api/docs/guides/rate-limit) — per-endpoint request limits and throttling behaviour. --- ## Need help? Questions about the API or your integration: **integrations@ttdbooking.com** Full documentation: **[developer.ttdbooking.com/hotel-api/docs](https://developer.ttdbooking.com/hotel-api/docs)**