docs.emergingtravel.com
Open in
urlscan Pro
35.173.109.157
Public Scan
Submitted URL: http://docs.emergingtravel.com/
Effective URL: https://docs.emergingtravel.com/
Submission: On May 04 via api from US — Scanned from DE
Effective URL: https://docs.emergingtravel.com/
Submission: On May 04 via api from US — Scanned from DE
Form analysis
0 forms found in the DOMText 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).