ETG API V3
API Integration and Certification Guidelines

API Integration and Certification Guidelines

This document will guide you through implementing ETG API v3 and provide you with an action plan for upcoming months.

Integration Stages Overview

The integration consists of 4 stages:

  1. At the Pre-integration Stage, the ETG manager will send you a questionnaire that needs to be filled out.
  2. The Integration Stage is where you develop the integration independently. Before you start building, we recommend:
  • reviewing this page for a summary of the key integration steps,
  • read the ETG Best Practices for API to ensure efficient implementation, and
  • explore the ETG API documentation for detailed endpoint descriptions and parameters. Please feel free to ask any questions about the API logic during this stage — we’re happy to help.
  1. The Certification Stage is where the API Launch team reviews the integration and, if necessary, requests that you make adjustments and changes. Before starting the certification, please fill in the Pre-certification Checklist that launch member sent to you.
  2. The Pre-Production Stage is where the API Launch team monitors the integration performance after certification and addresses the issues on prod at the initial stages. Please inform us when you are going live.

Below, you will find the recommended API workflow with endpoints to be integrated. Make sure to integrate all required endpoints.

Recommended Workflow

Please find the recommended workflow diagram with mandatory and required endpoints listed below:

sequenceDiagram
    autonumber
    actor Client
    participant System as "Your system"
    participant ETG as "ETG API"

    activate Client

    Note over Client,ETG: Search step
    Client->>System: Requests city search
    activate System
    System->>System: Convert city to ETG hotel ids,region or geo search
    System->>ETG: Search by Hotel IDs, Region or Geo request
    activate ETG
    ETG->>System: Search by Hotel IDs, Region or Geo response
    deactivate ETG
    System->>Client: Show city search results
    deactivate System
    Client->>Client: Chooses the hotel and moves to hotel page

    Client->>System: Opens the hotel page
    activate System    
    System->>ETG: Retrieve hotelpage request
    activate ETG
    ETG->>System: Retrieve hotelpage response
    deactivate ETG
    System->>Client: Show hotelpage with room prices
    deactivate System
    Client->>Client: Chooses the rate

    Note over Client,ETG: Prebook step

    Client->>System: Start the Prebook
    activate System  
    
    System->>ETG: Prebook request with `price_increase_percent`
    activate ETG
    ETG->>System: Prebook response
    deactivate ETG

    alt AVAILABLE
        System->>Client: Continue booking process by opening the booking form
    else AVAILABLE (Price changed)
        System->>Client: Show new price to client and ask - continue booking with new price (Y/N)?
    else NOT AVAILABLE (Error no_available_rates)
        System->>Client: Show that rate is not available and cannot be booked
    end
    deactivate System

    Note over Client,ETG: Booking step

    Client->>System: Opens the booking form
    activate System   
    System->>ETG: Create booking process request
    activate ETG
    ETG->>System: Create booking process response
    deactivate ETG
    System->>Client: Show the booking form
    deactivate System   
    Client->>Client: Fills all necessary data

    Client->>System: Starts the booking process
    activate System
    System->>ETG: Start booking process request
    activate ETG
    ETG->>System: Start booking process response
    deactivate ETG

    loop Every second, until the status is "ok"
        System->>ETG: Check booking process request
        activate ETG
        ETG->>System: Check booking process response
    end
    deactivate ETG

    System->>Client: Show the success page
    deactivate System

    deactivate Client

Each API method has request and response samples, field descriptions and corresponding error codes. You can find them in the documentation section corresponding to your API type: https://docs.emergingtravel.com/

1. Static Data Step

Hotel static data stands for all information about the hotels and includes full content like images and additional content data.

1.1 Retrieve hotel dump

Required

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/info/dump/

This tool should be used to download content and hotel mapping information. It is updated weekly.

1.2 Retrieve hotel content

Recommended

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/info/

It is used only in cases when an available hotel is not included in the downloaded hotel data dump. It can happen to new hotels in the ETG inventory.

1.3 Retrieve hotel incremental dump

Recommended

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/info/incremental_dump/

It is used to update the Retrieve hotel dump (B2B, Affiliate) static information with changes applied to hotels on the previous day. This is updated daily.

This method should be used daily to get the most up-to-date information. For example, if hotels make an important announcement, this method will provide updates.

2. Search

2.1 Search by Methods

One of the endpoints is required

Endpoints:

Search by methods are used to search for hotels with available accommodations that match specified search conditions. However, allowing users to select rates at this stage is not advisable, as the rates may not align with those presented in the subsequent single hotel search on the Retrieve hotelpage (B2B, Affiliate) and/or Prebook rate from hotelpage step (B2B, Affiliate) request.

During this first search step using Search by methods, we recommend displaying one or two of the lowest rates for each hotel. In the second step, when using Retrieve hotelpage (B2B, Affiliate) and/or Prebook rate from hotelpage step (B2B, Affiliate) for a single hotel search, all available rates for the selected hotel should be displayed.

2.2 Retrieve hotelpage

Required

Endpoint: https://api.worldota.net/api/b2b/v3/search/hp/

Retrieve hotelpage (B2B, Affiliate) should be used exclusively for hotels the end user has shown interest in. Requests should not be made for every hotel retrieved by region ID or hotel IDs; requests should only be made when the user selects a specific hotel.

The recommended storage duration for retrieved rates is up to 1 hour. The availability window for booking requests using this method may extend beyond this timeframe, varying based on internal factors.

This endpoint will provide detailed information on a particular hotel with all the prices for rates.

We do not recommend matching rates between one of the Search by methods and Retrieve hotelpage (B2B, Affiliate) responses. However, if your logic requires such matching, please let us know at [email protected], and we will advise you on how to implement it.

3. Prebook rate from hotelpage step

Required

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/prebook

Prebook rate from hotelpage step (B2B, Affiliate) updates the availability of the requested rate. This method attempts to find a comparable or similar rate if the original rate is unavailable. Implementing the Prebook rate from hotelpage step (B2B, Affiliate) method is mandatory, as it enhances the booking success ratio.

The price_increase_percent (B2B, Affiliate) feature allows ETG to identify the best alternative rate within the price increase range. If this feature is implemented, your clients should be notified of any price changes before proceeding to the booking step.

Please note that you can specify price_increase_percent and choose from 0 to 100. If that’s the case, you must notify the end user of the price change.

4. Booking step (all endpoints are required)

4.1. Create booking process

Required

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/booking/form/

This endpoint is called to create a booking on the ETG end and link that order with the order in your system.

4.2. Start booking process

Required

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/booking/finish/

This endpoint is called to start the booking process. During this step, we are sending the booking request to our suppliers and direct hotel partners to make a booking. Hence, the booking status will be in progress. Consequently, you are required to implement the last endpoint to get the final booking status.

The last endpoint is either the Check booking process (B2B, Affiliate) or Receive booking status webhook (B2B, Affiliate). Please note that you can implement them both, but one of them is required.

4.3. Check booking process

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/booking/finish/status/

This endpoint is used to receive the final booking status. One should keep calling this endpoint until the status processing changes either to ok or final failure status.

Please note that the status ok during the Check booking process (B2B, Affiliate) only indicates a successful booking.

4.4 Receive booking status webhook

If you decide to work with the Receive booking status webhook (B2B, Affiliate), ETG will send you the final booking status, and you will be only responsible for correctly responding to our webhooks.

If you would like to work with Receive booking status webhook (B2B, Affiliate), please provide us with a callback URL and indicate that you want to enable it at [email protected].

The detailed logic of how to work with webhooks can be found in Best Practices for API and API documentation.

The differences between “Check booking process” and “Receive booking status webhook” are:

“Check booking process” “Receive booking status webhook”
To obtain the final status, the partner must perform a series of requests in accordance with Retry logic (B2B, Affiliate).

The statuses will either indicate status ok, or include a list of final failure error codes.		 ETG will send the final status right after receiving the booking status from the supplier.

These statuses will be either confirmed or failed.
It will provide the reason for the booking failure. No specific reason for booking failure will be provided.

Please also find our Best Practices for API for the integration, which will give more exact recommendations and outline integration expectations.

5. Post-Booking

5.1 Retrieve bookings

Recommended

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/info/

This can be used to receive details about a successful booking. However, it should not be initiated immediately after booking completion.

⚠️

Warning:

It is important to note that:

5.2 Cancel booking

Recommended

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/cancel/

This should be used if a booking needs to be canceled.

Certification

Each product requires its independent certification, which can occur simultaneously or sequentially. Completing certification for one product doesn’t guarantee it for another. Each product is treated independently, allowing one product to be launched once certified, even if others are still undergoing the process.

The certification process usually takes 14 to 30 days. It is in written form to allow partners to make necessary changes. Please find the Pre-certification Checklist that will outline our expectations for every step of the integration:

Website Product Certification Requirements:

  • Grant access to a test environment where ETG is set up as a supplier, with test hotels mapped, enabling our specialists to conduct searches and bookings.
  • Cross-check the integration based on the Pre-certification Checklist and fill out the form.
  • If necessary, we will initiate further discussions of separate points to find the best approach in the interest of both parties. As part of these discussions, we may request specific changes to be implemented based on feedback received.

API Product Certification Requirements:

  • Provide the API documentation used by your clients for integration.
  • Provide logs for bookings created based on your product’s logic, your API request and response, and our API request and response, preferably in JSON format.
  • Cross-check the integration based on the Pre-certification Checklist and fill out the form.
  • If necessary, we will initiate further discussions of separate points to find the best approach in the interest of both parties. As part of these discussions, we may request that certain changes be implemented based on feedback received.

Mobile Product Certification Requirements:

  • Offer a detailed demo video and step-by-step screenshots covering the entire process from search to booking cancellation.
  • Provide the installation file to test the website on our mobile devices.
  • Cross-check the integration based on the Pre-certification Checklist and fill out the form.
  • If necessary, we will initiate further discussions of separate points to find the best approach in the interest of both parties. As part of these discussions, we may request that certain changes be implemented based on feedback received.

Thank you! In case you have any questions or concerns, please feel free to contact us at [email protected].