Room Block Tutorial

Let's get started

If you are looking to build a solution with workflows based on new and updated booking data then you have come to the right place. There are a few workflows you will need to develop to get all the value out of the Room Block APIs. Each of these are described in more detail on the sections of this page.

The primary workflow you need to develop is how we notify you when booking data changes. The notifications will be made available to you via Amadeus Hospitality Event Notification Service (AHENS) which provides APIs enabling you to complete the process.

If you are a passive subscriber of Notifications, you don't need to do anything. Changes will be sent to you and the notification processing cycle will finish automatically. However, as an active subscriber, you would need to follow the steps outlined below to ensure your notifications settle in the correct state:

  • Call notification/receive endpoint to retrieve any pending notifications.
  • Every notification received will contain a call back url that can be used to retrieve your updated data.
  • Process the retrieved data in the manner that suits your integrations needs:
    • To indicate that you have finished processing a notification and mark it as committed, call the notifications/commit endpoint.
    • If you would like to cancel a notification and not process it for any reason, you may call the notification/cancel endpoint and it will be marked as canceled.

There are 2 types of entities that you will receive notifications for - Booking Synchronization and Booking. Regardless of the entityType of notification, the workflow will remain consistent.

Booking

This notification type represents a single booking that has been changed in the source system (for in-depth detail on this see the Booking Updates section).

To retrieve the BookingDocument of the associated Booking which contains all of the Booking information and related data, you will need to make a GET call to the URL specified in the notification.EventDataLink property. If the BookingDocument.Events field is populated you will use those values to get all the events for that booking.

Booking Synchronization

This notification type represents what we call Initial Sync. The Initial Sync process allows you to retrieve historical and all future booking data based on your initial configuration settings.

This notification will be generated once we have completed the configuration for a location (for more detail, see the Initial Sync section).

Other Useful Documentation

Notifications

Summary

Here we will go into detail about the different types of notifications you will receive and what is required on your side to support them.

EntityType

Callback Endpoint

Summary

Booking Synchronization Booking/Synchronization

This notification is generated by Amadeus Hospitality during location configuration, and is used for the Initial Sync of data. This will allow you to get all the available historical and future booking data for a location. For more details, see the Initial Sync tab.

Booking Booking/Get

This notification is generated anytime a Booking or any one of its children are updated in the source system. You will never receive multiple notifications for the same booking in a single receive call. The response will be a BookingDocument and you will always get the latest version of the booking and all of its related data. For more details, see the Booking Updates tab.

Room Block API leverages Amadeus Hospitality Event Notification Service (AHENS) APIs for notification handling. The process you will need to follow to process notifications on your side is detailed below.

Receiving and Processing Notifications

Subscriber Engagement Level

During initial set up phase, your application is set up to receive updates from certain publishers. At the same time, you choose if your application will actively poll AHENS to receive the latest updates or you would like to be informed by AHENS directly.

Active Subscription Workflow

A typical workflow for receiving notifications actively from AHENS is given below:

  • Actively call notification/receive API to retrieve any available updates waiting for your application
    • Once you have successfully received and processed your updates, make a call to Notification/Commit API to inform AHENS that the received Notifications have been processed.
    • In case you are not interested in processing the Notifications you just received, simply call the Notification/Cancel API so that AHENS does not re-stage the Notification for you.
    • See Recommendations and Notes below for details on Notification restaging.

Passive Subscription Workflow

  • AHENS will send you notifications containing updates of interest once they are made
    • If the notification send call receives a success response from your side, AHENS will mark the notification as committed which means no further processing will be required on the mentioned notification.
    • In case AHENS receives a failure response while pushing the notification, it will be marked as failed. Such notifications will be picked up and retried later for a configurable number of times.

Authentication with AHWS

When using the developer console in this documentation, you can simply input your AHWS credentials into "Authentication type" field as "Resource Owner Password". For a deeper dive on our authentication, check out the authentication guide.

Logging in and Accessing the APIs

Once you have your API credentials (supplied by Amadeus Hospitality), you will be able to use the APIs outlined in this document. See the authentication guide for details.

EntityType

Endpoint

Summary

Notification ahens/notification/receive

A call to the notification/receive API returns a list of available notifications to the caller. The result will return empty if there are no updates available.

Notification ahens/notification/commit

The commit method is called with a collection of NotificationIds. These are notification identifiers present in notifications received by the subscriber system.

Notification ahens/notification/cancel

Similar to commit, the cancel method is called with a collection of notification IDs.

Receiving Notifications

To receive updates, simply call notification/receive API and you will be given a list of notifications available for you.

Here are the details on this API:

 API: Notification Receive

 TYPE: HTTP POST

Request URL

https://api.newmarketinc.com/api/ahens/notification/receive

Request body

Request body:

The body of the request must be in a valid format acceptable by AHENS. A sample request body containing one Event is given below. It should be mentioned that none of the fields included below are required; i.e. the API may be called with an empty request body. While tenancyId and channelId fields are specific to the calling party and must match the exact value provided by to the caller at the time of customer registration, the remaining fields enable the user to restrict the notifications to be retrieved based on their will.

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.

[ 
  {
    "tenancyId": "ten123",
    "channelId": "chan456",
    "locationId": "loc789",
    "resourceType": "Booking",
    "limit": 100,
    "correlationId": "11111111-2222-3333-4444-555555555555"
  }
]

Response

A call to the notification/receive API returns a list of available notifications to the caller. The result will return empty if there are no updates available.

Notification Receive Diagram

Confirm That Updates Have Been Received and Processed

When you have finished processing the updated resources, you’ll need to confirm this with AHENS, so that those notifications won’t be delivered to you a second time. To do this you will need to “commit” the notifications you received earlier. Simply post the notifications you received back to the notification/commit API to commit them, indicating that all processing is complete.

The commit request is treated as an explicit acknowledgment by the subscriber system that notifications has been received successfully.

Commit Processed Notifications

 API: Notification Commit

 TYPE: HTTP POST

Request URL

https://api.newmarketinc.com/api/ahens/notification/commit

Request body

The commit method is called with a collection of NotificationIds. These are notification identifiers present in notifications received by the subscriber system. Collection of notification identifiers (List required): Notification subscriber must supply a collection of notification identifiers.

Canceling a Notification

If you did not successfully process a notification, or have no interest in processing one, you can choose to cancel it.

If you don't commit or cancel a notification, you can receive it again after it has been restaged. See Active Subscriber Notification Restaging below.

 API: Notification Cancel

 TYPE: HTTP POST

Request URL

https://api.newmarketinc.com/api/ahens/notification/cancel

Request body

Similar to commit, the cancel method is called with a collection of notification IDs.

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.

API Usage Quotas

The Room Block product applies API usage quotas to your API consumption. These limits should not affect the quality of your solution in any way.

These policies allow us to deliver a better quality of service to developers like you. Because of these policies, we would recommend a polling interval on notification/receive of once every 12 hours. For more information on polling intervals see Rate Limits and Quotas.

Initial Sync

Starting the Sync Process

To provide you with historical data, we have created an 'Initial Sync' workflow. The sync process starts when you receive a notification with an entityType of BookingSynchronization. This notification will need to be generated by someone at Amadeus Hospitality. If you need to initiate this process, please contact our Partner Success team.

The response from the sync notification's CallbackURL will be a collection of BookingDocument objects.

You will need to process each element of this collection the same way you process a single BookingDocument during the Booking Updates workflow. For each booking, you will need to check for a ContinuationCallbackResponse in the RoomBlocks , or RoomNights fields. If there is, you will call the provided URLs until you have received all of the children.

Once you have received all the children for every BookingDocument in the response, you will call the CallbackURL from the initial notification again. But for this call and all subsequent calls, you will need to provide the ContinuationToken header you received in the previous response in the next request (see Figure1 for a visual example of how to use Continuation Tokens).

After you have repeated this process enough times, you will not get a ContinuationToken in the response. When you no longer receive a ContinuationToken this means you have received all of your historical data, and you can now commit the notification that started this process.

Endpoints

The below table describes the endpoints you will end up calling throughout the initial sync process. You do not need to store any of these URLs, in fact we recommend against storing them as all URLs you will need are provided to you in a field called CallbackURL.

Resource

Endpoint

Parameter

BookingDocument

Bookings/{bookingId}

LocationId

List<BookingDocument>

Bookings?locationId={locationId}

LocationId

List<BookingRoomBlock>

Bookings/{identifier}/RoomBlocks

BookingId

List<BookingRoomNight>

Bookings/{identifier}/RoomNights

BookingId

Continuation Tokens

These endpoints may return 2 extra custom headers in the response:

ContinuationToken

string

This is the continuation token value, we will use this value to send you the next chunk of data if your request results in more records than can be returned in a single call. You will receive this information in the header of the response, and you will then provide that information in the header of your next request.

RemainingRecords

boolean

This indicates if there are any remaining records to retrieve. If a "true" value is received for this field, you would want to call the same endpoint with the continuation token provided in the previous step to retrieve another batch of records.

Continuation Token Workflow

Figure 1. Basic flow of requests/response with ContinuationToken

Considerations

  • To get all data, you must continue to call the endpoint until you get a false value for remainingRecords field and no continuation token in the header of a response.
  • Continuation Tokens do have an expiration date. By default it is good for 7 days.
  • In the rare event you get a 500 or 503 status code, simply retry the action later, with the continuation token you just used.
  • The default maximum number of records you will receive in any of these responses is 200.

Booking Updates

A notification will be generated for all valid changes that occur in the source system. If a user updates any booking, or any child data on that booking, a notification for the booking will be generated.

The notification will have an EventDataLink field which provides a URL that will return a BookingDocument resource, and you will need to follow the same process as Initial Sync to retrieve all of the children if their CallbackURLs are populated.

If multiple modifications are made to a booking or its child entities before you have received notifications, then we will only provide you a single notification. We aggregate all updates associated to a single booking into a single notification. This will not result in any missed updates.

The notification you receive will point to the latest version of that booking and ALL of its child entities. Because we are returning data in bulk, this will result in less API calls for you.

Resource Descriptions

The RoomBlock API provides a method to retrieve BookingDocuments. Additional methods are available to retrieve any of the child entities related to the BookingDocument.

The Booking endpoints return what is called a BookingDocument, which has all the standard Booking fields and four new fields to access child items. These fields will only be populated if the Booking has those child types.

{
        "Id": "03FE3MF3...",
        ...
        "RoomBlocks": {
            "CallbackURL": "https://....",
            "ContinuationToken": "4FE2FJKK3495..."
        },
        "RoomNights": null,  // this booking has no Room Nights
    }

The Booking Synchronization endpoint returns an array of BookingDocument. To retrieve children you will call the Entity.CallbackURL and put the Entity.ContinuationToken in the request header.

Now you will follow the same flow as defined in the Initial Sync section. If the Booking has no associated Events, that value will be NULL and there is no need to call in and try to retrieve those values.

Error Scenarios

When you pass the correct information in you will receive 200 - OK and 202 - Accepted status codes.

If things go wrong, you can inspect the Http Status Code and the request body to determine what failed and how to correct your call.

HTTP Status Codes

Reason

200 The server has successfully processed the request.
201 Created - resource was created.
202 Accepted - request has been accepted but the resource change has not been applied.
204 The server successfully processed the request but is returning no content.
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.
405 The server does not provide access to the URL for the HTTP Verb requested.
500 The server has encountered a problem, please try again.
503 The service is temporarily unavailable. If the length of the delay is known a Retry-After header is given. It is recommended that the client delay for this interval before sending another request to the service. If no Retry-After is provided the client should handle as a 500 error.

Calling OAuth

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.

  • access_denied means you have an incorrect Username and Password pair. The user might not exist or the password provided was wrong.

  • unauthorized_client means there is incorrect information in the client_id and client_secret fields. Ensure you are using the correct values that you received from Amadeus Hospitality when you acquired your credentials.

You may also get a 405 - Method Not Allowed if you call OAuth endpoints with the GET verb instead of POST.

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

For more information about OAuth refer to our Authentication Guide.

Calling a Sync Endpoint

There are a few different status codes you can get depending on the data you provide or the status of AHWS.

400 - Bad Request

This means that the service got your request, but was unable to complete it due to missing or invalid inputs. This could be because:

  • You did not provide a Continuation Token when you should have
  • The Continuation Token provided was invalid
  • The Continuation Token provided has expired (remember tokens expire after 7 days)
  • You used a different `identifier` in the url than the Continuation Token was assigned for

401 - Unauthorized

If there is no ChannelLocation relationship between the calling user and the Location you will receive an Unauthorized.

500 and 503

If you call an endpoint that uses a Continuation Token and get a 500 or 503 in response, resend the call a later time using the same Continuation Token you provided.

Error flow

Troubleshooting

Most 500 status codes are temporary, and normal service should return after a few seconds or minutes. You should retry a call in these instances.

If you are consistently receiving 500 status codes, you can use information in the response to help our Support team track down the error faster. The response Header will contain the following keys:

  • Ni-TrackingId
  • Ni-CorrelationId
These values can greatly decrease the time it will take to identify issues.

Rate Limits and Usage Quotas

In order for us to be able to monitor and protect our platform, this product will have usage quotas enforced on the calling users. We will have a fixed number of 200 calls you will be able to make in a 24 hour time period for this specific product.

Usage Quotas

What to expect?

We hope that these thresholds are defined well enough so that a standard implementation should not have to worry about hitting these limits. As developers though, we always need to account for the failure scenarios. When you hit your usage quota for the above APIs you will be returned a HttpStatus of 403 with a payload like:

            {
                "statusCode": 403,
                "message": "Out of call volume quota. Quota will be replenished in 09:37:46."
            } 
                    

Rate Limits

What to expect?

There is currently no rate limit on the Room Block product. Any limit in place would be to ensure that our service is protected from an enormous flood of requests in a short period of time. If you do end up hitting your rate limit you will be returned an HttpStatus of 429 with a payload like:

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