docs.emergingtravel.com Open in urlscan Pro
35.173.109.157  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Public


Documentation Settings

ENVIRONMENT
No Environment

LAYOUT
Double Column

LANGUAGE
cURL - cURL



ETG API v3
Introduction
Authorization
Partner Contract Type
Request methods & format
Response Format
Errors
Integration Guideline
API Support request recommendations
Hotel


ETG API V3

This documentation contains a general overview of the Emerging Travel Group API
Partner Program.

To know more about the benefits of our API integration or to sign up please
check ourwebsite.

Prior to starting to use the API, the respective agreement should be signed.
After integration is completed, certification may be required.


AUTHORIZATION

Emerging Travel Group API uses two API key sets granting you different kinds of
access: test (sandbox) access and production access. Test API keys can only be
used to book test hotels (test_hotel_do_not_book, test_hotel), while production
API keys let you book all the hotels available via the Emerging Travel Group API
(currently, this is the only difference between these 2 types of API keys).

API key looks like key_id:key, where:

key_id

API key id

key

API key token


You may have several production keys across different contracts, e.g. to book
properties across different markets.

The API keys that were created for your contract can be found in the API section
of your contract's settings.

For access to the relevant section, a Master account type is required.

The required authorization method is HTTP Basic Authentication (Basic Auth).

It is essential to bear in mind that every API-key endpoint has a limit to the
number of requests. To discuss changes to this limit, please contact your
account-manager.

The limit to the number of requests per specified time period and number of
remaining requests per current period and the timestamp of the limitation
period's expiration are specified in the response:

View More
Plain Text


"X-RateLimit-SecondsNumber": 1 # amount of seconds, within which a number of requests not exceeding "X-RateLimit-RequestsNumber" can be executed
"X-RateLimit-RequestsNumber": 10 # maximum amount of requests that can be executed within "X-RateLimit-SecondsNumber" seconds
"X-RateLimit-Remaining": 9 # the remaining amount of requests (out of "X-RateLimit-RequestsNumber") in the current period of "X-RateLimit-SecondsNumber" seconds count
"X-RateLimit-Reset": "2018-08-14T08:54:11" # DateTime (UTC+0) of expiration for period of "X-RateLimit-SecondsNumber" seconds' count.


PARTNER CONTRACT TYPE

Emerging Travel Group Partner Program offers two contract types:

affiliate

Affiliate API

b2b

B2B API


For more details on both types, please contact your Emerging Travel Group
account-manager. Note that you can use one API key type for only one type of API
partner contract.


IMPORTANT:

> Make sure that an email address for API-related questions is saved in the
> contract properties (contact type - Technical questions and API) - all
> notifications related to API and API-support will be forwarded only to this
> email address. Respective changes can be made in the Contacts section of your
> contract settings.


REQUEST METHODS & FORMAT

Requests are made through HTTPS protocol via GET or POST methods.
Request data are always passed in json format in the request body (when using
POST) or in GET-parameter data (when using GET).

GET example:

View More
Plain Text


curl -g --user 'key_id:key' 'https://api.worldota.net/api/b2b/v3/hotel/info/?data={"id":"city_hotel_berlin_east","language":"en"}'

POST example:

View More
Plain Text


curl --user 'key_id:key' --data '{"id":"city_hotel_berlin_east","language":"en"}' "https://api.worldota.net/api/b2b/v3/hotel/info/"


RESPONSE FORMAT

Response format is always json.

Top-level response keys

View More
data

Main content of the response.

debug

Additional content to the response, containing initial requests parameters in
json format and/or http status code value.

error

Fields with error description, shown if error occurs.

status

Response status code.


For example:

Plain Text


{
    "data": {
        "data_3ds": null,
        "partner_order_id": "asd123",
        "percent": 100
    },
    "debug": null,
    "error": null,
    "status": "ok"
}


ERRORS


SYNTAX ERROR

JSON has syntax rules that describe how the data must be stored. If the data
gets corrupted and no longer complies with the rules, an error occurs:

View More
Plain Text


{
    "data": null,
    "debug": {
        "api_endpoint": {
            "endpoint": "api/b2b/v3/hotel/info/",
            "is_active": true,
            "is_limited": true,
            "remaining": 9,
            "requests_number": 10,
            "reset": "2018-08-16T12:12:37",
            "seconds_number": 1
        },
        "api_key_id": 1304,
        "method": "GET",
        "real_ip": "62.76.100.3",
        "request_id": "68c1141361db8c82835ea268486d7c6f",
        "utcnow": "2018-08-16T12:12:36.328390"
    },
    "error": "decoding_json",
    "status": "error"
}


"EXCEED LIMIT" ERROR

If you have exceeded the requests number limit for your endpoint, the following
error will be returned:

View More
Plain Text


{
    "data": null,
    "debug": {
        "api_endpoint": {
            "endpoint": "api/b2b/v3/hotel/info/",
            "is_active": true,
            "is_limited": true,
            "remaining": -1,
            "requests_number": 1,
            "reset": "2018-08-16T12:32:40",
            "seconds_number": 20
        },
        "api_key_id": 496,
        "method": "GET",
        "real_ip": "10.11.0.23",
        "request_id": "8dd3efd24bdd6a9272770936e5108f8c",
        "utcnow": "2018-08-16T12:32:26.161565"
    },
    "error": "endpoint_exceeded_limit",
    "status": "error"
}

To discuss the changes to this limit please contact your account manager.


"IS ACTIVE" ERROR

If your endpoint was deactivated, the following error will be returned:

View More
Plain Text


{
    "data": null,
    "debug": {
        "api_endpoint": {
            "endpoint": "api/b2b/v3/hotel/info/",
            "is_active": false,
            "is_limited": true,
            "requests_number": 1,
            "seconds_number": 20
        },
        "api_key_id": 496,
        "method": "GET",
        "real_ip": "10.11.0.23",
        "request_id": "61c015d15d325f0bb945db5d027fc35c",
        "utcnow": "2018-08-16T12:38:38.481018"
    },
    "error": "endpoint_not_active",
    "status": "error"
}

To discuss the changes to this activation please contact your account manager.


"ENDPOINT NOT FOUND" ERROR

If you do not have permission to use this method, the following error will be
returned:

View More
Plain Text


{
    "data": null,
    "debug": {
        "api_key_id": 1775,
        "method": "POST",
        "real_ip": "10.11.0.23",
        "request_id": "45141c733a1f4d534a0518c513d3641b",
        "status": 403,
        "utcnow": "2018-08-14T12:51:58.715639"
    },
    "error": "endpoint_not_found",
    "status": "error"
}

To discuss the changes to this please contact your account manager.


ERROR IN CASE OF USING INCORRECT API CREDENTIALS / HAVING NO PERMISSION TO USE
THE API

If you used incorrect API credentials (or if you don't have permission to use
the API), the following error will be returned:

Plain Text


{
    "data": null,
    "debug": {
        "real_ip": "52.29.104.100",
        "request_id": "e6ff36a9e635825743e7ded8c05739a0",
        "utcnow": "2018-08-23T09:34:43.673713"
    },
    "error": "incorrect_credentials",
    "status": "error"
}

Please note that in case of recurring unauthorized requests over a considerable
period of time, we may ban the IP-address from which such requests are sent.


"AUTH HEADER" ERROR

If you do not use the correct authorization:

Plain Text


{
    "data": null,
    "debug": {
        "real_ip": "52.29.104.100",
        "request_id": "563c919d77000963a4ef9ade0988b21b",
        "utcnow": "2018-08-23T10:03:28.794712"
    },
    "error": "no_auth_header", #or "invalid_auth_header"
    "status": "error"
}

Check the

Authorization section

of the documentation.


"INVALID PARAMS" ERROR

If you do not input all the required data:

View More
Plain Text


{
    "data": null,
    "debug": {
        "api_endpoint": {
            "endpoint": "api/b2b/v3/hotel/order/info/",
            "is_active": true,
            "is_limited": true,
            "remaining": 9,
            "requests_number": 10,
            "reset": "2018-08-23T09:59:38",
            "seconds_number": 1
        },
        "api_key_id": 1304,
        "method": "POST",
        "real_ip": "52.29.104.100",
        "request_id": "7f4937bdabe8bb13d4980dcd77a16117",
        "utcnow": "2018-08-23T09:59:37.495757",
        "validation_error": "value \"page_number\" is required but None"
    },
    "error": "invalid_params",
    "status": "error"
}

Check the validation_error and add the required data.


"LOCK" ERROR

In case you try to make the same request with the same partner_order_id more
than once at the same time, the following error will be returned:

Plain Text


{
    "data": null,
    "debug": {
        "real_ip": "52.29.104.100",
        "request_id": "2c2264a2f3f64b9032624e99ddd49976",
        "utcnow": "2018-08-23T11:43:27.101799"
    },
    "error": "lock",
    "status": "error"
}


"NOT ALLOWED HOST" ERROR

If it is forbidden to make a request from your host/IP, the following error will
be returned:

Plain Text


{
    "data": null,
    "debug": {
        "real_ip": "52.29.104.100",
        "request_id": "7b76e52a742f714e6686761fab48cfa3,
        "utcnow": "2018-08-23T11:31:44.235203"
    },
    "error": "not_allowed_host",
    "status": "error"
}

Please contact the API support team.


"NOT ALLOWED" ERROR

If it is forbidden to make a request with this endpoint, the following error
will be returned:

Plain Text


{
    "data": null,
    "debug": {
        "real_ip": "52.29.104.100",
        "request_id": "7b76e52a742f714e6686761fab48cfa3,
        "utcnow": "2018-08-23T11:31:44.235203"
    },
    "error": "not_allowed",
    "status": "error"
}

Please contact your account manager.


"OVERDUE DEBT" ERROR

If you have an overdue debt, the following error will be returned:

Plain Text


{
    "data": null,
    "debug": {
        "real_ip": "52.29.104.100",
        "request_id": "36f4a2ae479cc0eba8e3ddf7d09bba14",
        "utcnow": "2018-08-23T10:11:08.045023"
    },
    "error": "overdue_debt",
    "status": "error"
}

Please contact your account manager.


"UNEXPECTED METHOD" ERROR

If you make a request with an unsupported GET/POST method:

Plain Text


{
    "data": null,
    "debug": {
        "api_key_id": 1304,
        "real_ip": "52.29.104.100",
        "request_id": "19925f65c2763212bbe37294178b6fa6",
        "utcnow": "2018-08-23T09:56:37.677774"
    },
    "error": "unexpected_method",
    "status": "error"
}

Use POST/GET instead.


UNKNOWN ERROR (EXAMPLE)

When something has gone wrong:

Plain Text


{
    "data": null,
    "debug": null,
    "error": "unknown",
    "status": "error"
}

Errors with HTTP status codes 5xx (500-526) may be returned, for example,
because of an internal Emerging Travel Group services' timeout. A request shall
be sent again (the number of recurrent identical requests must be limited).


INTEGRATION GUIDELINE

Recommended workflow:

   
 * Hotel Static
   

   
 * Hotel Data Dump (should be used for downloading full content and mapping
   hotels)
   
 * Hotel Data Search
   

2. Search

   
 * Search Engine Results Page (should be used for available hotels searches)
   
 * Hotelpage (should be used only for hotels that your end-user wants to know
   about; that is, you should not initiate HP search automatically for all
   hotels, returned by a region search)
   
 * Prebook (This method updates the availability of the requested rate)
   

3. Booking

   
 * Order Booking Form + Order Booking Finish (should be used for creating a new
   booking)
   
 * Order Status Webhook or / and Order Booking Finish Status (should be used for
   receiving final booking status)
   

4. Post Booking

   
 * Order Information (should be used for receiving information on a completed
   booking)
   
 * Order Cancellation (should be used for a booking cancellation, if needed)
   

It is important to note that if the Emerging Travel Group system returns one of
5xx errors, this does not mean that the request was unsuccessful. Errors with
status 500 may be returned, for example, because of internal Emerging Travel
Group services' timeout. The request should be sent again (the number of
recurrent identical requests must be limited).

Recommendations for usage of static data:

   
 * It is recommended to update the static data every day via Hotel Incremental
   Data Dump. Otherwise the static data should be updated at least once a week
   via Hotel Data Dump.
   
 * It is obligatory to show hotels "important information"
   ("metapolicy_extra_info" and "metapolicy_struct" params in the dump file), as
   these params include hotel rules and information on a chargeable services.
   

Search flow recommendations:

Generally, while using the first search step (Search Engine Results Pages) we
recommend showing one or two of the cheapest rates for each hotel and on the
second search step showing all the rates for one specific hotel.

We do not recommend using rates matching because:

   
 * not all the suppliers allow you to make a booking from the first search step
   
 * not all the suppliers provide all the necessary response data (e.g.
   cancellation policies) at the first search step
   
 * not all the suppliers provide all available rates for the hotel at the first
   search step (e.g. there are suppliers that respond only with one rate, the
   "cheapest", so you will miss other rates)
   
 * the first search step is slower so not all the rates will be returned if you
   have a short search timeout
   
 * the first search step has a longer cache life
   

The point is that when using rates matching flow you are missing lots of the
rates and have a higher fail-ratio at the valuation step.

If you still intend to match the rates between theSearch Engine Results
PageandHotelpagesteps please use the `match_hash` param from the search
response.

Other important points of the search flow:

It is obligatory to showing taxes, which Emerging Travel Group provides in the
rate details.

The full room type (“room_name”) received in the rates details should be shown
on your side.

Booking flow recommendations:

To obtain the final status of the booking you can use theOrder Booking Finish
StatusorOrder Status Webhook.

If you use the Order Booking Finish Status we recommend that you check the
status of the booking every 5 seconds until the final status is obtained. If you
have any limitations for this step, please discuss it with our API support team.

Please note that this Guide does not include all the possible API usage rules.
Every endpoint has a detailed description and a description of available params.
If you have any questions related to API usage, please send it to the API
support team.

After the integration is completed you need to proceed with the certification
and provide access to your test/dev website where our API is implemented.


API SUPPORT REQUEST RECOMMENDATIONS


COMMON RECOMMENDATIONS

 * Specify the issue as clearly as possible.

 * Always highlight the goal you want to achieve.

 * Please note, that existing functionality of the API is always described in
   the documentation.


REPORTING DETAILS OF THE ISSUES (OR INQUIRIES)

 * Always mention the exact method (with its endpoint in URL).

 * Provide an example of a request that causes the issue (in the format in which
   it was sent to us).

 * If you provide response logs, please specify them in JSON format (the only
   format, that is currently supported).

 * Specify the issue's timestamp - this can also help to determine the issue's
   cause.


IDENTIFICATION

 * Specify your contract's number for easier identification.

 * Specify the key_id of the API key you were using.


ADDRESSEES OF THE REQUEST

 * If the question regarding the API is forwarded to na on-tech support manager,
   its processing can take a longer time - as you may be forwarded to an API
   tech support manager.

 * In case an inquiry which is not related to API is forwarded to API tech
   support manager, it's processing can take a longer time as well, as you may
   be forwarded to your account manager (or, if applicable, to another
   responsible manager).