T3 External API Usage Guide

1. Overview

The T3 External API is organized into several key sections:

• Health Check: Verify that the API is up and running.
• Catalog: Retrieve static data (countries, locations, hotels, and various choices) that you can use for filtering and populating your UI.
• Inventory: Manage client data (create, read, update, delete).
• Bookings: Handle the complete booking workflow—from creating booking requests to managing quotes, cancellations, and payments.

Each endpoint typically requires you to be authenticated via a bearer token.

2. Authentication

Most endpoints are secured and require an API token. Include your token in the HTTP header for every request:

Authorization: Bearer <your_token>

Make sure to replace <your_token> with your actual API token.

3. API Workflow

Below is the typical flow when using the API.

Step 1: Verify API Health

Before initiating any complex operations, confirm that the API is running correctly by using the health check endpoint.

• Endpoint: GET /ext/healthcheck
• Request Example:

GET /ext/healthcheck HTTP/1.1
Host: api.example.com
Authorization: Bearer <your_token>

• Response Example:

{
  "status": "ok"
}

If the response returns "ok", you can safely proceed with further API calls.

Step 2: Retrieve Catalog Information

The catalog endpoints provide the necessary reference data for your application. This includes data on countries, locations, hotels, and various selectable choices used in bookings.

Countries

• Endpoint: GET /ext/catalog/countries
• Purpose: Lists all supported countries.
• Query Parameters: Optional filters like search, ordering, limit, and offset.

Locations

• Endpoint: GET /ext/catalog/locations
• Purpose: Lists available locations (cities, regions) where bookings can be made.
• Query Parameters: Similar to the countries endpoint.

Hotels

• Endpoint: GET /ext/catalog/hotels
• Purpose: Lists hotels, supporting filters for rating, language, currency, and geolocation (latitude, longitude, radius).
• Query Parameters: Filter by rating, search term, ordering, etc.

Choices

Several endpoints under Catalog > Choices provide enumerated options (e.g., booking statuses, meal plans, ratings) that you can use to populate dropdowns or filter bookings in your application.

Step 3: Manage Client Inventory

If your application manages clients (for example, travel agencies or end users), use the Inventory endpoints to create and maintain client records.

List Clients

• Endpoint: GET /ext/inventory/clients
• Purpose: Retrieve a paginated list of clients, optionally filtered by market, timezone, country, or location.

Create a Client

• Endpoint: POST /ext/inventory/clients
• Purpose: Add a new client.
• Request Body Example:

{
  "your_id": "CL-001",
  "name": "Acme Travel",
  "client_type": "b2b",
  "phone": "+123456789",
  "address": "123 Main Street",
  "zipcode": "10001",
  "country_id": "US",
  "location_id": 10
}

Retrieve, Update, and Delete a Client

• Retrieve: GET /ext/inventory/clients/{client_id}
• Update: PUT /ext/inventory/clients/{client_id}
• Delete: DELETE /ext/inventory/clients/{client_id}

These endpoints help you manage client records throughout their lifecycle.

Step 4: Handle Bookings

Bookings are at the heart of the API. The booking process may include several steps:

A. Listing and Retrieving Bookings

• List Bookings:
  • Endpoint: GET /ext/bookings
  • Purpose: Retrieve bookings with filters such as request type, status, category, and date ranges.
• Retrieve a Booking:
  • Endpoint: GET /ext/bookings/{booking_id}
  • Purpose: Get detailed information on a specific booking.

B. Creating Booking Requests

There are two main types of booking requests:

1. Estimated Booking Requests:
   • Purpose: Generate initial quotes.
   • Endpoints:
     • POST /ext/bookings/estimated
     • GET /ext/bookings/estimated/{booking_id}
2. Deferred Booking Requests:
   • Purpose: Initiate a booking to be confirmed later.
   • Endpoints:
     • POST /ext/bookings/deferred
     • GET /ext/bookings/deferred/{booking_id}

C. Managing Bookings

• Cancel a Booking:
  • Endpoint: POST /ext/bookings/{booking_id}/cancel
  • Purpose: Cancel an existing booking by providing a cancellation reason and notes.
• Accept a Booking Quote:
  • Endpoint: POST /ext/bookings/{booking_id}/quotes/{quote_id}/accept
  • Purpose: Confirm a booking by accepting a provided quote.

D. Handling Payments

• Pending Payments:
  • Endpoint: GET /ext/bookings/{booking_id}/payments/pending
  • Purpose: List payments that are pending for a booking.
• Completed Payments:
  • Endpoint: GET /ext/bookings/{booking_id}/payments/completed
  • Purpose: Retrieve a list of payments that have been completed.

4. Example Booking Flow

Here’s an example of how you might use the API in a typical booking scenario:

1. Check API Health: Ensure the API is responsive by calling the health check endpoint.
2. Fetch Catalog Data: Retrieve available hotels (using /ext/catalog/hotels) along with the associated countries and locations. This data is used to populate search filters and booking options.
3. Create or Retrieve a Client:
   • If the client is new, create a client record using POST /ext/inventory/clients.
   • If the client already exists, retrieve their details with GET /ext/inventory/clients/{client_id}.
4. Initiate a Booking Request:
   • Create an estimated booking request via POST /ext/bookings/estimated to get an initial quote based on the desired check-in/check-out dates, hotel rating, and meal plan.
   • The response will provide details such as quote price, available rooms, and payment conditions.
5. Review and Accept a Quote: Once the client reviews the quote, accept the quote with POST /ext/bookings/{booking_id}/quotes/{quote_id}/accept.
6. Manage Payments:
   • Check for any pending payments with GET /ext/bookings/{booking_id}/payments/pending.
   • Once payment is made, confirm it via GET /ext/bookings/{booking_id}/payments/completed.
7. Cancellation (if necessary): If the booking needs to be canceled, use POST /ext/bookings/{booking_id}/cancel along with a cancellation reason.

5. Error Handling

The API uses standard HTTP status codes and returns error details in JSON format. Some common responses include:

• 200 OK: Successful retrieval or update.
• 201 Created: A resource has been successfully created.
• 400 Bad Request: The request is invalid (e.g., missing required parameters).
• 404 Not Found: The requested resource could not be found.
• 409 Conflict: There is a conflict (for example, when trying to delete a client that is in use).

Example Error Response:

{
  "code": "invalid_request",
  "reason": "The 'name' field is required."
}

The following error codes are returned by the API to indicate specific errors. If an error code is not explicitly mapped to an HTTP status code, the default is 400.

Generic (E0)

Error Code	Description	HTTP Code
E0000	unknown error	400
E0001	field '%s' cannot have more than %d characters	400
E0002	field '%s' email address '%s' is invalid	400

Countries (E1)

Error Code	Description	HTTP Code
E1000	unknown country error	400
E1001	specified country '%s' does not exist	404
E1002	no town found near to latitude '%.6f' and longitude '%.6f'	400

Locations (E2)

Error Code	Description	HTTP Code
E2000	unknown location error	400
E2001	specified location '%s' does not exist	404
E2002	country_id '%s' for this location_id '%s' is invalid	400
E2003	location_id or latitude and longitude is required	400
E2004	latitude must be between -90 and 90	400
E2005	longitude must be between -180 and 180	400
E2006	radius must be between 0 and 50	400

Clients (E3)

Error Code	Description	HTTP Code
E3000	unknown client error	400
E3001	name is required	400
E3002	there is already a client with this name	400
E3003	your_id is required	400
E3004	there is already a client with this your_id	400
E3005	there is already a client with this fiscal_name	400
E3006	there is already a client with this fiscal_number	400
E3007	client '%s' does not exist	404
E3008	client '%s' cannot be deleted due associated requests	409

Hotels (E4)

Error Code	Description	HTTP Code
E4000	unknown hotel error	400
E4001	specified hotel '%s' does not exist	404

Bookings (EB)

Error Code	Description	HTTP Code
EB000	unknown booking error - %s	400
EB001	rooms counts must be greater than 0	400
EB002	rooms types must be different in the same request	400
EB003	estimation unavailable for this request - %s	400
EB004	no location info specified	400
EB005	booking '%s' not found error	404
EB006	estimation '%s' does not exists	400
EB007	quote '%d' for booking '%s' does not exists	404
EB008	quote '%d' is not available for booking '%s'	400
EB009	quote '%d' is not available anymore for booking '%s'	400
EB010	quote '%d' for booking '%s' cannot be accepted because is auctioning	409
EB011	quote '%d' for booking '%s' cannot be accepted due booking is cancelled	409
EB012	quote '%d' for booking '%s' is already accepted	409
EB013	quote '%d' for booking '%s' cannot be accepted due another quote was accepted before	409
EB014	booking '%s' already cancelled	400
EB015	booking '%s' already closed	400
EB016	booking '%s' cancellation already requested	400

Conclusion

The T3 External API is a comprehensive tool designed to manage the full lifecycle of travel bookings—from retrieving catalog data and managing clients to initiating and processing bookings and payments. By following the flow outlined in this guide, developers can integrate the API into their systems, ensuring a smooth and consistent user experience.

For detailed information on each endpoint, parameters, and schema definitions, please refer to the full API documentation.

Happy integrating!