Overview

Protocol

The protocol uses JSON-based requests and HTTP as means to send key parameters. Production gate is located here: https://www.amiraltravel.net - please, pay attantion that the access to production gate is available only after certification process is successfully completed.

Authentication

The authorization process utilizes the JSON Web Tokens (JWT) method. To authenticate within the system, you must send an authentication request. The token you receive should be included in the Authorization header for all subsequent requests. Example: Authorization: Bearer {TOKEN}. The token remains valid for 24 hours, after which it expires, requiring you to request a new token via the authentication process.

Search

The search operates in asynchronous mode. To initiate a search, you need to send a Search request containing all relevant search parameters. The response will include a searchID parameter.

If you are searching for a specific hotel, use the hotels parameter, which allows you to include up to 500 hotels (you can obtain hotel IDs using the static data request Hotels). This approach accelerates the search results. If the hotelsparameter is not included, the search will cover the entire city as the search area.

• Refundable Offers:
  By including the refundable parameter, you can filter results to show only refundable (true) or nonrefundable (false) offers. Nonrefundable offers have cancellation policies that take effect immediately upon booking. However, not all hotels provide this data in the initial search response. For more precise information about nonrefundable offers, you can refer to the OfferDetails request. Keep in mind that nonrefundable offers cannot be modified.

Receiving Search Results

The finished parameter is a key indicator of search completion. It is strongly recommended to continue sending asynchronous search requests until this parameter is set to true, signifying that the search has been completed.

Keep in mind that the prices in the search results might be outdated, as they are cached on the provider's side. To obtain the most accurate and up-to-date price, you should use the OfferDetails request.

Search results are valid for 30 minutes. After this time, you will no longer be able to retrieve offer details or proceed with booking. To access updated results, you will need to initiate a new search.

Offer Details and Price Update

This step is mandatory before proceeding with booking an offer.

Since many providers use cached offers in their search responses, the information they provide may not always be up-to-date. To address this, the OfferDetails request retrieves the latest details about the offer, including updated prices, policies, and nightly rates (if available). This ensures you always have accurate information. If you receive an error in response to the OfferDetails request, it indicates that the offer is no longer available.

• Cancellation and Amendment Policies:
  The finepolicies array contains details about cancellation and amendment policies. A null value in the fromparameter signifies a policy effective immediately upon booking. This is also applicable in the Cancel Booking Item and Hotel online data responses.

• Additional Offer Information:
  The information array provides supplementary details about the offer. This may include information about additional taxes, charges, and hotel stay rules. It is strongly recommended to display this information to your clients.

• Selling Price Parameters:
  Fields such as canUseSellingPrice, minimumSellingPrice, and maximumSellingPrice indicate whether it is possible to set a custom selling price for clients and define the permissible range for it.

Booking

You can proceed with booking an offer once the search and offer details processes are complete. The booking request is immediately sent to the provider. However, before booking, you must first create an order.

Order Creation

To create an order, follow these steps:

1. Generate an Order:

Once the order is created, you can add offers to it for processing.

2. Key Parameters:

- `clientOrderID`:

Use this field to input the order number from your system. This helps simplify the process of locating the order later.

- `invoiceComment`:

Add any relevant comments for the invoice. These comments will be visible to the individual creating the invoice.

By organizing the process through order creation, you ensure a streamlined and efficient booking experience.

Booking Creation

To book an offer, you need to send a `Create Booking` request. Here are the important details and steps to ensure the process runs smoothly:

Key Points:

1. Unique Booking Requests:

You cannot send multiple `Create Booking` requests with the same `searchID` and `offerID`, as this would attempt to book the exact same room multiple times.

2. Required Parameters:

- `price`:

Specify the exact price of the offer being booked to confirm you agree to book it at this price.

- `confirmationMode`:

Indicate the type of confirmation you are requesting (e.g., online or manual).

The system rechecks the price and confirmation mode before proceeding. If any changes occur, the offer will not be sent to the provider, and you will receive an error with updated price and confirmation details.

3. Successful Booking Response:

Upon success, you will receive an `item ID` (found in the `items` array). For bookings involving multiple rooms, some providers may return multiple `item IDs`. If you need to cancel such bookings, each `item ID` must be handled separately.

4. Booking Multiple Rooms:

- When booking multiple instances of the same room, you need to assign guests to specific rooms in the `rooms` array.

- The booking request may include the same room hash multiple times, provided the total quantity matches the number of rooms listed in the `Results` or `Offer Details`.

5. Monitoring Booking Status:

After sending a booking request, it is essential to continually check the booking status.

- Some providers may take time to confirm the booking, even if the offer is marked as "online."

- Use the `Search Orders` request to check the status once per minute until the correct status is returned.

6. Setting a Selling Price:

If you wish to set a custom selling price for the offer being booked, you can do so by including the `sellingPrice` field in your request.

By following these steps, you can ensure a reliable and accurate booking process while accommodating various provider-specific requirements.

Booking Cancellation

The `Cancel Booking Item` method is used to cancel a booking within an order. Note that some providers may not process cancellations immediately. To monitor the cancellation progress, you should send a `Search Orders` request once per minute, including the `booking ID`, to check its status.

Booking Information

The system provides two methods to retrieve order details:

1. Search Orders:

This method is used to search for orders and update their statuses. It provides minimal information about the orders and a list of orders matching the search criteria.

2. Order Info:

This method delivers complete information about a specific order, including:

- Any associated financial documents.

- A detailed list of all items within the order.

By following the appropriate methods and requests, you can efficiently manage booking cancellations, retrieve booking information, and access detailed order and financial data.

Order Search

The `Order Search` method enables you to retrieve a list of orders that match specific search parameters or obtain details about a specific order. This method is particularly useful for synchronizing order information.

Key Features:

1. Order List Retrieval:

- Use this method to get a comprehensive list of orders that meet the defined search criteria.

2. Order Information Updates:

- It provides an overview of an order, including the number of invoices (`invoicesNumber`).

- If the `invoicesNumber` value has changed, you can fetch updated financial documents using the `Order Info` request.

3. First Fine Date (`firstFineDate`):

- This parameter indicates the date when the first fine for the order takes effect.

- If the `firstFineDate` is `null`, it should be interpreted as the policy being active immediately from the moment of booking.

By leveraging the `Order Search` method, you can efficiently manage and update order data, ensuring accuracy and timeliness in your system.

This is a comprehensive reference for various API endpoints related to authentication, hotel search, booking, cancellations, and fetching related data like hotel details, facilities, and geographical information. Below is a brief categorization and summary for easier navigation:

Authentication

- Endpoint: `POST /api/gateway/login`

- Description: Authenticate and obtain an API key to access subsequent endpoints.

- Parameters:

- `login` (string, required): User login.

- `password` (string, required): User password.

Hotel Search

- Initiating Search:

- Endpoint: `POST /api/hotel/gateway/search`

- Mode: Asynchronous; requires periodic result polling.

- Key Parameters:

- `checkIn`, `checkOut` (required): Dates in `date-time` format.

- `cities`: Array of integers (or null).

- `hotels`: Array of integers for specific hotels (faster search).

- `mealTypes`, `refundable`, `rooms` (required, up to 5).

- Fetch Results:

- Endpoint: `GET /api/hotel/gateway/results/{searchID}`

- Parameters:

- `searchID` (string, required).

- Pagination options: `offset`, `limit`.

Offer Details

- Endpoint: `POST /api/hotel/gateway/search/details`

- Description: Provides updated details, including price, cancellation policies, and availability.

- Key Parameters:

- `offerID` (string, required): From search results.

- `searchID` (UUID, required).

Booking

- Create Order:

- Endpoint: `POST /api/order/gateway/orders`

- Parameters:

- `clientOrderID`, `contactInfo`, `customer`, `invoiceComment`.

- Create Booking:

- Endpoint: `POST /api/hotel/gateway/book`

- Key Parameters:

- `confirmationMode`, `currency`, `offerID`, `orderID`, `price`, `rooms`, `searchID`.

Booking Cancellation

- Endpoint: `POST /api/hotel/gateway/booking_items/{ID}/cancel`

- Description: Cancels a specific booking item and returns updated booking information.

- Key Parameter:

- `ID` (string, required): Booking item ID.

Order Management

- Search Orders:

- Endpoint: `GET /api/order/gateway/orders`

- Parameters: Various filters for `orderCreatedDate`, `orderUpdatedDate`, `clientOrderID`, etc.

- Order Info:

- Endpoint: `GET /api/order/gateway/orders/{ID}`

- Key Parameter:

- `ID` (integer, required): Booking ID.

Hotel and Geo Data

- Hotels:

- Endpoint: `GET /api/dict/gateway/hotel/hotels`

- Parameters: `cityID`, `updatedAt`, pagination options.

- Hotel Types, Categories, Meals, Facilities:

- Separate endpoints available under `/api/dict/gateway/hotel/...`.

- Geographical Data:

- Countries: `GET /api/dict/gateway/geo/countries`.

- Cities: `GET /api/dict/gateway/geo/cities`.

- Locations: `GET /api/dict/gateway/geo/locations`.