ETG API v3

This documentation contains a general overview of our API Partner Program. Prior to starting the usage of API, a corresponding agreement shall be signed. After integration is completed, certification may be required.

Authorization

Our API uses two API key sets granting you different kinds of access: test (sandbox) access and production access. Test API keys can be only used to book test hotels (test_hotel, test_hotel_do_not_book), while production API keys let you book all the hotels available via API of Emerging Travel Group (currently, it 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, e.g. to book properties across different markets. API keys, that were created for your contract can be found in API section of your contract's settings.

For access to the corresponding section, Master type of account is required.

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

It is essential to consider, that every API-key has limitation for requests amount. This limitation is only applied to the total amount of hotel/rates and hotelpage requests. For discussing the changes to this limitation, please, contact your account-manager.

There is also a separate limitation for hotel data search requests - 30 requests per 60 seconds. Amount of requests limit per specified period of time, amount of the remaining requests per current period and the timestamp of limitation period's expiration are specified in the response headers (for those requests that fall under requests limitation):

X-RateLimit-Per ->60 # amount of seconds, within which a number of requests not exceeding "X-RateLimit-Limit" can be executed
X-RateLimit-Limit ->30 # maximum amount of requests that can be executed within "X-RateLimit-Per" seconds
X-RateLimit-Remaining ->29 # the remaining amount of requests (out of "X-RateLimit-Limit") in the current period of "X-RateLimit-Per" seconds count
X-RateLimit-Reset ->1483975260 # Unix Timestamp (UTC+0) of expiration for period of "X-RateLimit-Per" 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 only for one type of an API partner contract.

Important:

Make sure, that an email for API related questions was mentioned in the contract properties (contact's type - Technical questions and API) - all notifications related with API and API-support will be forwarded only to this email. Corresponding changes can be made in Contacts section of your contract's settings.

Requests 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:


POST example:

Response Format

Response format is always json.

Top-level response keys

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:

Errors

Syntax error

JSON has syntax rules that describe how the data must be stored. If the data gets corrupted and doesn't maintain the rules, an error occurs:

"Exceed limit" error

If you have exceeded the requests amount limit for your endpoint, the following error will be returned: For discussing the changes to this limitation please contact your account manager.

"Is active" error

If your endpoint was deactivated, the following error will be returned: For discussing 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: For discussing the changes to this, please, contact your account manager.

Error in case of using incorrect API credentials / having no permission to use API

If you used incorrect API credentials (or if you have no permission to use API), the following error will be returned: Please note, that in case of recurring unauthorized requests lasting withing a considerable period of time, we can ban the IP-address from which such requests are sent.

"Auth header" error

If you do not use the correct authorization: Check the Authoriation part of the documentation.

"Invalid params" error

If you do not input all required data: Check the validation_error and add required data.

"Lock" error

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

"Not allowed host" error

If it is forbidden to make a request from your host, the following error will be returned: Please contact API support team.

"Overdue debt" error

If you have an overdue debt, the following error will be returned: Please contact your account manager.

"Unexpected method" error

If you use request with unsupported GET/POST method: Use POST/GET instead.

Unknown error (example)

When something went wrong: Errors with status 500 may be returned, for example, because of internal Emerging Travel Group services' timeout. A request shall be sent again (the number of recurrent identical requests must be limited).

API Support request recommendations

Common recommendations

  • Specify the issue as clear as possible.
  • Always highlight the goal you want to achieve.
  • Please note, that existing functionality of 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 a request's example, that causes the issue (in 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 timestamp of the issue - it can also help to determine the issue's reason.

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 API is forwarded to non-tech support manager, it's processing can take longer time - as you may be forwarded to 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 longer time as well, as you may be forwarded to your account manager (or, if applicable - to another responsible manager).

PUBLISHER

Ostrovok

CATEGORIES

Imports

10+