AHWS Registration

Welcome to Amadeus Hospitality Web Services for Data File Exchange (DFE) APIs! This document will walk you through the basics from authenticating with Amadeus Hospitality Web Services (AHWS) in order to retrieve ETL Files from DFE. As we guide you through this process it is expected you will have some familiarity with REST however you do not need to be an expert. Connecting with AHWS can be achieved by even the most inexperienced developers. NOTE: Before your first API call, you must register as an AHWS partner and log into the portal. Please see our home page for more details.

Before an application subscribes to Notifications from AHENS, the application is required to be registered as a partner (Channel) with AHWS. The registration process creates a ‘channel’ for data flow between integrating applications and provisions credentials to be used for data exchange.

Data File Exchange

Who is this document intended for?

This document is intended to be a reference for developers working with the DFE service.

What is DFE?

DFE Process Flow

Data File Exchange is a product offering from Amadeus Hospitality to deliver a complete view of sales & catering data to our Enterprise customers (Brands, Management Companies) to support their information management strategies via the distribution of data files containing Delphi.FDC centric content. DFE provides REST API endpoints for a consumer to get this data. Consumers will be required to set up a subscription to Amadeus Hospitality Event Notification Service (AHENS) so that when changes are published, a consumer will poll for an AHENS Notification indicating new data is available. After receiving a notification the Data File Exchange endpoint can be used to retrieve the data. For more information on how notifications work with AHENS refer to the AHENS Documentation.

How long are files available for?

Files will be available for 30 days after they are created. When notification/receive is called, the user will be presented with all available files ready for download via the manifest. If the notifcation is committed or canceled, this does not affect the files. They will still be available for download for 30 days. However, the notification that is committed or canceled will no longer be presented to the user the next time notification receive is called. For further information regarding notification states & restaging, please view the Notification Restaging section in the AHENS Documentation.

Included APIs

What's Included?

  1. Authentication
  2. AHENS Notifications
  3. Data File Exchange

You must be logged in with an active subscription to view these APIs.

Endpoints

The following are the endpoints used to retrieve Manifest information and ETL files through the Data File Exchange Product. A Manifest is a container holding data file names ready for retrieval through the Get ByFileName endpoint. For more detailed models of headers, requests, and responses find the Data File Exchange Product here and browse through the endpoints supplied.

Authentication APIs

Post Access Token

Any consumer calling Amadeus endpoints must authenticate using the Authentication API. The following is an example of an AccessToken endpoint call. This endpoint allows a user to retrieve a token to be used in the header information of all endpoints contained in the DFE Product.

POST /2.0/OAuth2/AccessToken
Host: api.newmarketinc.com
Ocp-Apim-Subscription-Key: xxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
{
  "grant_type": "password",
  "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "client_secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "xxxxxxx@xxxxxxx.xxx",
  "password": "xxxxxxxxxxxxxxxxxx"
}
                
Grant type will always be set as "password". Client Id and Secret are provided by Amadeus. Username and password are created through a subscription process to be completed with Amadeus. For more information on AHWS Authentication and OAuth Tokens refer to the AHWS Authentication documentation.

The returning response will contain your new access token and a refresh token to be used during a Refresh Access Token endpoint call. The expiry time of the token will also be returned in the response; all Access Tokens last 15 minutes.

{
	"access_token": "1cBZBtY4Nfcrx/PlVf+nmGgiUbZdMPLWM0g4Qh4r5y5KQOoVhshYRNihi4/ja6p+CZ2hNEih2t/YR7UL6pn7iw0QisRDZKD032dSzB70DKiOWREYX+hH+IRphp8E/Ip
	DUhDVHr8acEj6TH0sPoHMQr7F06WTbzcCBjomrY8YOcBs1h9pdyFS9nYXb1RARxoicX24QjkRWfjfbXmJvaJ3Rg9kNVGAVIboZWDZ6n176MSazjM0WteAs5UdsmB70qB6HHmzbF5+jmoKcqQ1
	UHpjLfqxUvcOO3HyIz71tR04gldO3/e1mfOMSPTeesoAXU3quYcjcGeY2s+gf5jlURnZWosB4xyPtacXwEV0bdL+3ppi+iQRFhiDK0cvbdo/DgkwRzJm0KfJWl31WL9EsHYe2I0jv3xMByooIc
	o7LH6DKsYRqW7RAXA5bZX4pFf+aVRCgV6vjXWg5WIUbnAOZnzpPUtMSJIKnEVal63e8+UHS4R9ToEI1bm7wNPxgk9O1Bf4Cw8DlsuQWTuhhXg/mVMeIMZuWlQBUkU3nZYZWtSGCZ+CRISBMySgF
	IMadxF/AVJd9Xo0uy9nck20tlBQRuprssxPd9VZI5GPOCOQkgBTOZGNdanAdVt9emZYYANnYRt5",
	"expires_in": 900,
	"refresh_token": "GXwOwRlXc54zVafcV8NyscDS1AvIUTHBifQwv8TDZsX3mEq1hEKjoWegwgErlhnJftoTA+FrBwb70Am07kQzD572h+mAbN\/XTMu\/eVHtQ4vwQhp7fkPwyCitAVhMsGvi
	QjfV4Y8AiQGIAVXPhvBVXzX7RLEds64jtBdGriNbG9twFUFfLIuBEYZuspTs3AIeUrhVjQzP8f5kYMKtir+XH4+ogrdDIMQ4u8YXuc91oseH77tS+8s0qRclDJeGVcysSR2n3gxI6TvsHWDRI\/AE
	J\/Haq\/XE5eoS1QxpDkk+kn5ciAOGd2BY58pgJnd5LwSb\/N1uFEj\/1pB4J5F1oxUt5Ruq68w\/qvVGdWorPyngKyPNKe4DjZ++SyJFbQqN75as6NCEUjdzpU\/7zyXXD5+57OkhJFAaliraXfAz
	2jzUD4PW3yeEtQuIIOwL8kmjcsIm10OGfWuvl+6nLo6gg4wF+sY4MWct0Jt\/J6Mog65W4bSed8q5r2QLNrOClEJp+pwAEh9qkbtvDgVTfTJzhDrDvr0U7dyqdQEYqo4lmqGRBJIC7QhCYN31tbYs
	JAVAp+UM+0G4bKY6FxlIrB7mKg\/Zm+RvUx4cBVlyuw1UtWzxV3DEwHP4pAoLFEzs6CWkgFECx8a3\/ETd86ivlMcM15Wy0mm9uXoW6Qcr3Y5hrmho\/BU9SKk2Fyq0fY8r0hhiCGl55TU6rF8yLAE
	EvIdxSsHEiLynywGUhD6xAhyKYKyzk5wbp\/XzE8eneezEFWuRmUJJ",
	"token_type": "bearer"
}
			

Post Refresh Access Token

Access tokens expire over time and to retrieve a new Access Token use the Refresh Token provided in the response body of the Post Access Token endpoint call. For more information on Refresh Tokens refer to the AHWS Authentication documentation. Here is an example request:

POST /2.0/OAuth2/RefreshAccessToken 
Host: api.newmarketinc.com
Ocp-Apim-Subscription-Key: xxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
{
  "grant_type": "refresh_token",
  "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
                

The returning response will contain the same information as the response of the Access Token endpoint.

AHENS Notifications APIs

Post Receive

In order to receive Notifications containing Manifest data, the below request is required:

POST /api/AHENS/Notification/Receive
Host: api.newmarketinc.com
Ocp-Apim-Subscription-Key: xxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Authorization: OAuth xxxxxxxxxxxxxxxxxxxx
                
There is no information required in the request body of a call to Notification Receive, all data is provided to the enpoint through the Access Token supplied in the headers. The returned Manifest data will be contained within the "eventData" sub-document of the response body. This is where you will find the file names used to construct the Get ByFileName endpoint.

[
    {
        "id": "xxxxxxxxxxxxxxxxxxxxxxx",
        "eventId": "xxxxxxxxxxxxxxxxxxxxxxx",
        "pubSubMapId": "xxxxxxxxxxxxxxxxxxxxxxx",
        "eventDetail": {
            "resourceId": "Manifest",
            "resourceType": "Manifest",
            "eventData": {
                "header": {
                  "execution": {
                    "correlationId": "string",
                    "dateRange": {
                      "ingestStartDate": "2019-08-05T11:33:14.33Z",
                      "ingestEndDate": "2019-08-06T11:26:30.278Z"
                    }
                  },
                  "metadata": {
                    "key": "orgId",
                    "value": "string"
                  }
                },
                "datasets": [
                  {
                    "name": "Account",
                    "links": []
                  },
                  {
                    "name": "objectName",
                    "links": [
                      {
                        "rel": "part",
                        "href": "objectName_orgId_ingestEndDate_guid.gz",
                        "recordCount": "int"
                      }
                    ]
                  }
                ]
            },
            "publishedOn": "xxxxxxxxxxxxxxxxxxxxxxx"
        },
        "correlationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "Received",
        "lastStatusChangeOn": "xxxxxxxxxxxxxxxxxxxxxxx",
        "lastSubscribedOn": "xxxxxxxxxxxxxxxxxxxxxxx",
        "receivedCount": 1,
        "trackingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "createdOn": "xxxxxxxxxxxxxxxxxxxxxxx",
        "modifiedOn": "xxxxxxxxxxxxxxxxxxxxxxx",
        "recordStatus": "Active"
    }
]
            

Post Commit

Received Notifications should be marked committed in order to complete the Notification process, so as not to receive them again. You may receive the same Notification over an extended period of time, commit the Notification in order to not receive it any longer. Multiple Notifications can be committed at a time. Below is an example request:

POST /api/AHENS/Notification/Commit
Host: api.newmarketinc.com
Ocp-Apim-Subscription-Key: xxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Authorization: OAuth xxxxxxxxxxxxxxxxxxxx

{
  "notificationIds": [
    "xxxxxxxxxxxxxxxa1",
	"xxxxxxxxxxxxxxxa2"
  ]
}				
				

A response to a Notification Commit endpoint call will look similar to the response below. Each Notification Committed will correspond to a document in the response body, giving a status code of commit success along with the NotificationId supplied.

[
    {
        "statusCode": 200,
        "message": "OK",
        "resourceId": "xxxxxxxxxxxxxxxa1"
    },
    {
        "statusCode": 200,
        "message": "OK",
        "resourceId": "xxxxxxxxxxxxxxxa2"
    }
]
			

Post Cancel

If a notification did not process successfully or you wish to no longer process the notification you may cancel it. Below is an example request:

POST /api/AHENS/Notification/Cancel
Host: api.newmarketinc.com
Ocp-Apim-Subscription-Key: xxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Authorization: OAuth xxxxxxxxxxxxxxxxxxxx

{
  "notificationIds": [
    "xxxxxxxxxxxxxxxa1",
	"xxxxxxxxxxxxxxxa2"
  ]
}				
				

A response to a Notification Cancel endpoint call will look similar to the response below. Each Notification Canceled will correspond to a document in the response body, giving a status code of cancel success along with the NotificationId supplied.

[
    {
        "statusCode": 200,
        "message": "OK",
        "resourceId": "xxxxxxxxxxxxxxxa1"
    },
    {
        "statusCode": 200,
        "message": "OK",
        "resourceId": "xxxxxxxxxxxxxxxa2"
    }
]
			

Data File Exchange APIs

Get ByFileName

When calling the Get By File Name endpoint the file name, found in the Manifest Data contained in an AHENS Notification, needs to be passed as a parameter. The file name will be the full name of the file including the .gz extension. For example:

GET /api/dfe/ByFileName/file_to_retrieve.gz 
Host: api.newmarketinc.com
Ocp-Apim-Subscription-Key: xxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Authorization: OAuth xxxxxxxxxxxxxxxxxxxx
				
The Get By File Name endpoint will return a binary gzip file in the content of the response. The consumer should save this to disk as a .gz extension. Once saved the file needs to be decompressed to access the data.

More Information

AHWS Authentication Documentation

Here is where you can find more information around Authentication with AHWS in order to access any AHWS API you are subscribed to.

AHENS Documentation

Here is where you can find more information about Amadeus Hospitality Event Notification Service.

Subscribed Products

Here is where you can find all of the AHWS Products you are subscribed to.

Error Scenarios

Calling OAuth APIs

The most common error status code you will get from the OAuth service is a 403 - Forbidden. The error property in the response body will tell you what was not accepted. Here are a few areas to check first:

  • Incorrect or misspelled Username and/or Password. The user might not exist or the password provided was wrong.

  • Swapped or misspelled Client Id and/or Secret. Make sure your Clint Id and Secret are correct.

  • Incorrect grant type. Grant type for an Access Token call should be "password" and for a Refresh Access Token call it should be "refresh_token".

Calling AHENS Notification APIs

In the case of an error returned from a Notification API, the AHENS Documentation will outline troubleshooting options.

Calling Data File Exchange API

When the GET endpoint successfully returns a file you will get a 200 - OK status code.

If you receive something other than a 200 there may have been an authentication issue or the server had trouble requesting the file you specified. Refer to the table below for more information on the possible status codes returned from the endpoint.

Error Response Model

{
    Error Response String
}

Expected Http Statuses

Response Reason
200 The server has successfully processed the request.
400 The request could not be understood. Please check the response for additional information.
401 The request did not include the correct authentication.
403 The server understood the request but is not able to fulfill because of insufficient permission.
404 The requested resource was not found.
429 Specific to rate limits - rate limit has been exceeded
500 The server has encountered a problem, please try again.
503 The service is temporarily unavailable. This is likely the case if the server is unavailable or temporarily under maintenance.

In the rare event you get a 500 or 503 status code, simply retry the action later.

Access Restriction Policies

In order for us to be able to monitor and protect our platform, this product will have Quotas and Rate Limits enforced on the calling users. This is set as a maximum number of calls you can make against all the APIs in the product over a period of time.

What is a Quota?

A Quota is a limitation on the number of API calls you can make over a fixed period of time. After your time window your quota limit will reset.

How Quotas Work with DFE

All APIs within the DFE product will have a daily cap of 50,000 calls for a time period of 24 hours per subscription key. When you register for API management your user is assigned a primary and secondary subscription key. If you reach your maximum quota limit using your primary subscription key, you may swap your primary key for your secondary. This will give you another 50,000 calls for an additional 24 hours. The 24 hour period starts at the time your first call is made for that subscription key, and will reset after 24 hours has elapsed.

What is a Rate Limit?

Rate limits, like quotas impose a limit on the number of API calls you can make over a period of time. Rate limits are different in that the time limit is imposed on each API call, up to your maximum limit.

How Rate Limits Work with DFE

DFE allows 860 calls for all endpoints/API's under the DFE subscription over a 5 minute window. This includes all Authorization(Access Token, Refresh Access Token), Notification(Cancel, Commit, Receive) with the exception of DFE (ByFileName), which has its own limitation of 840 calls over a 5 minute window. We've set things up this way so that the number of calls you make to Notification and Authorization won't impact the calls you make to DFE ByFileName endpoint. In essence, you have 840 calls to DFE and another 20 for other operations to the Authorization and Notification API's. The expected volume of these operations is much lower than the ByFileName.

What if I reach my limit too soon?

These thresholds are designed so that a standard implementation will have the flexibility to make necessary calls without worrying about hitting it's limits. The limits are imposed as a means of protecting you (the customer) and us (the provider). Enforcing limits prevents our services from suffering against external attack such as DOS (Denial of Service) and ensures the system is used in a way to provide seamless interaction. These limits are set so the system can perform optimally while giving you the flexibility to use our services in a safe and professional way.

Exceeding Rate Limits or Quotas

If you go over your quota or rate limit, you will receive an HTTP response with a message indicating that your limit is exceeded. Within the response you will get an HttpStatus of 429. The response body will look like this:

{ 
   "statusCode": 429, 
   "message": "Rate limit is exceeded. Try again in xxx seconds/minutes." 
}
            

Notification Restaging

Notification Limits

While it doesn’t frequently happen, in case there are more than 5000 Notifications available to the caller, 5000 Notifications will be returned at each call. A continuation token will be made available in the response header for retrieval of the remaining Notification batches. The mentioned token can be provided in the request body as a field.

Active Subscriber Notification Restaging

Notification Stage Diagram

For Active Notification Subscribers, the Amadeus Hospitality Event Notification Service utilizes an internal workflow to manage Notifications to ensure that partners are processing all of their Notifications. The workflow has configurable timers and counters to tailor it to our partners' needs. These configuration options can be set by your Amadeus Partner Success representative.

For Active Subscribers, when the Recieve API method is called, the Notifications are put in the Received state. If after a period of time (defaults to 1 hour) these Notifications have not been Commited or Canceled, these Notifications will be restaged to the New state, allowing them to be Received again. Only Notifications in the New state can be Received.

Each time a Notification is Received, the Notification ReceivedCount is incremented. If you Receive a Notification with a ReceivedCount greater than one, that Notification has gone through the restage workflow due to not being Committed or Cancelled before the Restage Check timer has expired.

If the ReceivedCount is incremented more than the maximum allowed (defaults to five), the Notification will be put in a Failed state. These Notifications can no longer be Received, and will no longer be processed in the Notification workflow. If you would like Receive your Failed Notifications, contact your Amadeus Partner Success representative and they will restage them for you.

Passive Subscriber Notification Restaging

Passive Subscribers will receive their Notifications via HTTP Post to a url supplied by the subscriber. If the subscriber responds with a HTTP 200 level response code, the Notifications will be commited. If the subscriber responds with an error code (400 - 599), AHENS will retry the HTTP Post after waiting a period of time. If the HTTP Post continues to fail, the Notification will be changed to the Failed state, and will not be resent. If you would like Receive your Failed Notifications, contact your Amadeus Partner Success representative and they will restage them for you.