Skip to main content

 

Stay Connected and Keep Current

 

Keeping you informed with the latest and greatest.

 

 

a lightbulb

A Deep Dive into E2E NDC Reservation Management with the Booking Management API

API
Booking Management API

Pawel Dobrzanski | August 2021

Authored by: Pawel Dobrzanski, Malgorzata Slota, Lukasz Kuczynski, Mateusz Gawron, Heiner Press, Tomasz Drag, Krysztof Sikora, Alexandre Meneghello and Ken Tabor.

Why use it?

When the NDC (New Distribution Capability) program was launched by IATA, NDC-focused APIs started to be developed. To book and interact with NDC content customers needed to integrate, on top of traditional services, those new services. Managing different kinds of services, switching between them in different scenarios, or handling different types of errors adds additional costs and complexity for customers. To minimize the integration effort with NDC-based APIs while using traditional booking services at the same time, the Booking Management API can be used.

The Booking Management API lets you manage your Sabre reservations/bookings in a more efficient way by providing a normalized set of services that manage both traditional content (Sabre Passenger Name Records, or PNRs) and NDC content (Sabre Orders).

By using the Booking Management API, you don’t have to build your own API call orchestrations – we are taking care of that for you.

Using the Booking Management API, it’s easy to execute all typical operations on the booking. It allows users to quickly create, read or cancel reservations. It also makes it possible to access tickets information, e.g., check their status or perform operations such as void/refund. Additionally, if you are a customer who uses Sabre Profiles you may not been able to easily leverage the Profiles capabilities within an NDC booking workflow. And the good news is that we can help you with that issue as well. Our API could be used to book traditional and NDC content for Sabre Profiles! Moreover, the Booking Management API is exposed via RPC/JSON, so no more complex, difficult to read XMLs! We prioritize designing simple, user friendly, and intuitive-to-build requests. And regardless of the content you are managing (NDC/traditional) we provide normalized, simple and human readable responses.

All of services from the Booking Management API are based on the same API model. So there is no need to perform any additional operation between models. It doesn’t matter which service you want to call. If you want to create reservation, get all data from your travel segments and then cancel them all – you would use the same model to save your time and simplify integration process.

The Booking Management API gives you:

  • Normalized set of services that manage both traditional and NDC content
  • Sabre Profile utilization (you can also add traveler’s data directly in a request if you want)
  • Easy integration process because the API is exposed via RPC/JSON
  • User friendly error handling with descriptive error messages, so no more odd errors codes with meaningless error messages

How does it work?

Below two figures show how the Booking Management API fits into overall Sabre Platform.

Sabre Platform

Sabre Platform

Currently the Booking Management API contains six endpoints:

Endpoints

The first three endpoints presented above allow you to create traditional/NDC booking, view your reservation and cancel it. At the time of writing this article 3 last endpoints work only for ATPCO bookings because of some downline services limitations. In this article we will guide you through createBooking/getBooking/cancelBooking endpoints with emphasis on booking NDC context.

All endpoints are orchestrated services designed to simplify customers workflows. This is achieved by performing internal calls to other Sabre services and creating consolidated, normalized response. The official Booking Management API documentation can be found here.

How to integrate the model into your application

Integrate once, run everywhere! Especially while using the Booking Management API, where all services uses the same API model. Every release we are exposing to our clients current model which you can find in Sabre Dev Studio under Reference documentation of the Booking Management API – you can find it at the top of that tab.

image 4

API model needs to be imported into client’s application using swagger codegen plugin. This is as simple as adding single entry inside your build->plugins section in pom.

Example of the simplest integration can be found below, but if you need any additional features - let's dive into swagger codegen plugin github page and customize it on your own later.

API model integration with swagger codegen plugin.

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.3.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/client.yaml</inputSpec>
                <language>java</language>
                <configOptions>
                   <sourceFolder>src/gen/java/main</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Starting with authentication token

You must provide an authentication token to all endpoints in the Booking Management API. Tokens can be generated in 2 ways:

If the stateless token (ATK) is used, once you have the successful response from this API (TokenCreateRS), you can find the BinarySecurityToken element, which contains the ATK token.

Example of TokenCreateRS containing BinarySecurityToken (ATK)

<SOAP-ENV:Envelope>
      ...
      <wsse:BinarySecurityToken valueType="String" EncodingType="wsse:Base64Binary">T1RLAQKv...UhrH6gQg**</wsse:BinarySecurityToken>
      ...
  </SOAP-ENV:Envelope>

For stateful token (ATH), the response from session generation service (SessionCreateRS) also contains BinarySecurityToken element with value that will be used for authorization.

Example of SessionCreateRS containing BinarySecurityToken (ATH)

<SOAP-ENV:Envelope>
      ...
      <wsse:BinarySecurityToken valueType="String" EncodingType="wsse:Base64Binary"> Shared/IDL:IceSess...!380374!0</wsse:BinarySecurityToken>
      ...
  </SOAP-ENV:Envelope>

After generating the token using one of the methods above, the received value should be added as a Bearer authorization header of the actual request to the Booking Management API.

Template of authorization setup for the Booking Management API endpoints

 Authorization: Bearer <BinarySecurityToken>

For the example TokenCreateRS and ATK token value listed above, the authorization header would look like below.

Example of authorization setup for the Booking Management API endpoints (ATK token)

 Authorization: Bearer T1RLAQKv...UhrH6gQg**

If ATH token should be used, the authorization setup based on the SessionCreateRS will look like the following example.

Example of authorization setup for the Booking Management API endpoints (ATH token)

 Authorization: Bearer Shared/IDL:IceSess...!380374!0

Let’s practice with provided examples!

Before we start our journey through the Booking Management API, we would like to encourage you to deep dive into it on your own. We have prepared a helpful Postman collection with all mentioned requests, where you would be able to play with them.

image 5

The Collection was divided into 5 folders and you should call one request from each of them - one after another. For Creating and Cancelling services there are many samples, but please remember that for each sample you should go through the same process:

  1. Authorization
  2. Bargain Finder Max /v2
  3. Offers Price /v1
  4. CreateBooking (one sample)
  5. GetBooking /v1 General
  6. Cancel Booking /v1 (one sample)

There could be some more versions of services, so proper versions were provided as a service suffix and linked directly there. Let’s download collection from the Resources section at the bottom of this article and take your Sabre experience to the next level.

Create Booking

Create Booking is a service that creates an air booking for different content sources (NDC, ATPCO, CSL, LCC) in a single API call.

In order to create NDC booking content you have to prepare a valid data returned by Bargain Finder Max v2 and price it by Offer Price API (offerPriceResponseData):

  • price_offer_id (from offerPriceResponseData.response.offers[].id),
  • price_offer_item_id (from offerPriceResponseData.response.offers[].offerItems[].id),
  • price_passenger_id (from offerPriceResponseData. response.offers[].offerItems[].passengers[].id)

Here are various examples of JSON body requests. Each matches a distinct NDC booking creation scenario.

Simple NDC Booking for a Single Traveler

{
    "flightOffer":{
        "offerId":"{{price_offer_id}}",
        "selectedOfferItems":[
            "{{price_offer_item_id}}"
        ]
    },
    "travelers":[
        {
            "id":"{{price_passenger_id}}",
             "givenName":"John",
             "surname":"Kowalski",
            "birthDate":"1970-01-23"
        }
    ],
    "contactInfo":
    {
      "emails":[
        "travel@sabre.com"
      ],
      "phones":[
        "123456"
      ]
    }
}

Before you will call flow with usage of profile, please remember to create your own. In section extras we have added a service flow which can help you with that.

image 6

Simple NDC booking using Sabre Profile data by providing profile name:

{
  "flightOffer": {
    "offerId": "{{price_offer_id}}",
    "selectedOfferItems": [
      "{{price_offer_item_id}}"
    ]
  },
  "travelers": [
    {
      "id": "{{price_passenger_id}}",
      "givenName": "John",
      "surname": "Kowalski",
      "birthDate": "1970-01-23"
    }
  ],
  "contactInfo": {
    "emails": [
      "travel@sabre.com"
    ],
    "phones": [
      "123456"
    ]
  }
}

Notes: profileName – contains unique profile name and is used to blind move profile into AAA profileTypeCode – contains unique profile type code domainId – usually this is the user PCC but it could be a specific customer code as well.

Simple NDC booking using Sabre Profile data by providing profile’s unique id:

{
    "flightOffer":{
        "offerId":"{{price_offer_id}}",
        "selectedOfferItems":[
            "{{price_offer_item_id}}"
        ]
    },
    "profiles":[
        {
            "uniqueId":"ABC123",
             "profileTypeCode":"TVL",
             "domainId":"AAAA"
        }
    ],
    "travelers":[
        {
            "id":"{{price_passenger_id}}"
        }
    ],
    "contactInfo":
    {
      "emails":[
        "travel@sabre.com"
      ],
      "phones":[
        "123456"
      ]
    }
}

Notes: uniqueId – contains unique profile ID number and is used to blind move profile into AAA, profileTypeCode – contains unique profile type code domainId – usually this is the user PCC but it could be a specific customer code as well.

NDC booking for single traveler with identity documents information:

{
    "flightOffer": {
        "offerId": "{{price_offer_id}}",
        "selectedOfferItems": [
            "{{price_offer_item_id}}"
        ]
    },
    "travelers": [
        {
            "id": "{{price_passenger_id}}",
            "givenName": "John",
            "surname": "Kowalski",
            "birthDate": "1970-01-23",
            "identityDocuments": [
        {
                "documentNumber": "0123456789",
                "documentType": "PASSPORT",
                "expiryDate": "2024-07-09",
                "issuingCountryCode": "US",
                "residenceCountryCode": "US",
                "givenName": "John",
                "middleName": "Jack",
                "surname": " Kowalski ",
                "birthDate": "1970-01-23",
                "gender": "MALE"
        },
        {
                "documentNumber": "0123456789",
                "documentType": "VISA",
                "placeOfIssue": "FR",
                "hostCountryCode": "US",
                "issueDate": "2019-07-09"
             }
            ]
        }
    ],
    "contactInfo":
    {
      "emails": [
        "travel@sabre.com"
      ],
      "phones": [
        "123456"
      ]
    }
}

Notes: Create Booking supports following identity document types:
VISA, DESTINATION_ADDRESS, REDRESS_NUMBER, KNOWN_TRAVELER_NUMBER, NATIONAL_ID_CARD, ALIEN_RESIDENT, MILITARY, NEXUS_CARD, PASSPORT, NATURALIZATION_CERTIFICATE, REFUGEE_REENTRY_PERMIT, SECURE_FLIGHT_PASSENGER_DATA, BORDER_CROSSING_CARD, FACILITATION_DOCUMENT, PERMANENT_RESIDENT, RESIDENCE_ADDRESS

Booking NDC content with different target city (Pseudo City Code, or PCC) for single traveler:

{
    "targetPcc":"G7HEAAAA",
    "flightOffer":{
        "offerId":"{{price_offer_id}}",
        "selectedOfferItems":[
            "{{price_offer_item_id}}"
        ]
    },
    "travelers":[
        {
            "id":"{{price_passenger_id}}",
             "givenName":"John",
             "surname":"Kowalski",
            "birthDate":"1970-01-23"
        }
    ],
    "contactInfo":
    {
      "emails":[
        "travel@sabre.com"
      ],
      "phones":[
        "123456"
      ]
    }
}

Notes: targetPcc – is used to specify that API should change context to a desired pseudo city code. The API does not revert context after completing the booking.

Display Booking

The Get Booking Service simplifies the booking retrieval process by removing the need to use individual/granular APIs to retrieve a reservation. It retrieves a normalized view of the reservation regardless of the content sources (PNR, NDC Order or mixed per PNR). The result has less complexity with fewer API calls.

Also, it provides additional data relevant for travelers (e.g. fare rules) as well as data elements that are not stored in the Sabre PNR (e.g. ticket details, profiles and more). Itprovides a holistic view of Sabre reservations and to support traveler-oriented use cases (for example, "Can I change my ticket?"). Note that it retrieves reservation in a stateless way.

How it works

The Get Booking Service executes the following three steps to display a booking:

  1. At the beginning, it retrieves reservation data by the given confirmationID (PNR locator and Order ID).
  2. The API calls proper downline services in parallel to retrieve additional data in an optimized way.
  3. At the end, maps retrieved data to a normalized data model.

Vision of usage

The Get Booking API is ready to return a booking in a single API call, which can contain:

  • Traditional segments (Air/Hotel/Car)CSL Hotels (Traditional & Aggregators)
  • NDC Orders (Air)Additional data elements outside of Sabre’s PNR

The Service does not plan to expose every data element present in the PNR & Order. Sabre downline services contains plenty of data not necessary for most standard usages and receiving full set of them could be time and efficiency costly. We guarantee data selection and the lack of redundant data in the Get Booking API Response. However, to handle specific business scenarios, we are always open to discuss extending the schema.

The API can be profitably integrated as a self-service tool to retrieve traveler-oriented reservation data in human readable way. We can recommend API usage for mid/back office as well. With complete PNR, ticketing, accounting data and many more received in a one call, working with clients will be successful and effective.

How to use the Get Booking Service

Display whole booking

Use of the Get Booking Service is simple and convenient. To ensure successful booking retrieval, the request should contain at least confirmationId. We will verify what kind of data had been written on your PNR and return you all of them.

Just add confirmationId (PNR Locator or Order Id) in the Get Booking request:

{
    "confirmationId": "GLEBNY"
}

Displays all booking information based on confirmationId from PNR.

And the content of reservation will be returned form the Get Booking Service. Example response containing most fields and structures can be found here under the “Response 200” section. We encourage you to have a look at it and find the data your system could use.

image 7

Pic. Example response containing most fields and structures which can be found on project page in Sabre Dev Studio under this link for “Responses: 200”.

Response Data Types

Response from the Get Booking Service covers many data types grouped by functionalities. You can find here simple fields (like isCancelable or isTicketed) as well as advanced structures full of reservation information (such as ContactInfo, Flights, Fares or many more).

The complete list of Response Data Types can be found under Reference documentation for the GetBookingResponse:

image 8

After choosing each data type, you will see a meaningful description with a list of fields which covers selected data type.

image 9

There is so much reservation data in our model, that it would be the most beneficial to have them in the most updated version directly from Reference documentation on Sabre Dev Studio. Feel free to use them and validate how usage of the Get Booking Service can help your company with delivering results.

There is so much reservation data in our model, that it would be the most beneficial to have them in the most updated version directly from Reference documentation on Sabre Dev Studio. Feel free to use them and validate how usage of the Get Booking Service can help your company with delivering results.

Cancel Booking

The Cancel Booking is a service that provides a unified way of cancelling reservations from different sources (ATPCO, NDC). It is possible to cancel all items from the reservation (such as flights, hotels etc.) or just partially cancel selected segments and leave all the others active.

Using the Cancel Booking Service, the client can also perform actions on tickets (which are specified by ticket numbers or by reservation identifier) such as void and refund. Moreover, the service exposes check operation, which returns information whether it is possible to void or refund given ticket. It is also possible to combine cancellation of segments and void/refund operation of the tickets in a single request – don’t waste your organization time and automate the whole process in one integration using the Booking Management API.

From the NDC perspective, you can use cancel endpoint. Voiding, checking and refunding are not NDC compliant yet, as building NDC flows for them is under construction. But while looking at new Sabre services which handle NDC and pace of development, we are sure there will be some new one soon. Stay tuned for them.

We have prepared some examples for you to speed up your learning curve. Let’s have a look below and learn how you can use the Cancel Booking Service with features we’ve prepared for NDC segments.

The first and simplest example shows cancelling all segments within the reservation. You can do it by specifying cancelAll as true in the request. The request contains the confirmationId parameter, which is mandatory for booking cancellation operation. If you need to implement your logic in a concise way, this could be the starting and ending point for you! As simple as below:

Cancel Booking request with cancelAll = true

{
  "confirmationId": "ABCDEF",
  "cancelAll": true,
}

When cancelling a reservation, the client can provide an optional property, which specifies the source of the booking. Possible values are SABRE_ORDER (for NDC) and SABRE (for ATPCO):

Cancel Booking request with bookingSource = SABRE_ORDER

{
  "confirmationId": "1SXXXABCD1EF23",
  "cancelAll": true,
  "bookingSource": "SABRE_ORDER"
}

Optionally, the Cancel Booking Service can return the booking data after cancellation was finished. The current state of the booking is attached to the response if retrieveBooking property with value true is defined in the request.

Cancel Booking request with retrieveBooking = true

{
  "confirmationId": "ABCDEF",
  "cancelAll": true,
  "retrieveBooking": true
}

You can always combine all the options mentioned above and build yourself a powerful, fully customizable request with all options in one place. For example, you can call service for NDC segments only (even if PNR contains some ATPCO segments as well!). Then cancel and void all of them and return results from the Get Booking Service automatically at the end of the call. All operations in one place!

Complete Cancel Booking request for NDC with voiding and retrieving results afterwards.

{
    "confirmationId": "ABCDEF",
    "cancelAll": true,
    "bookingSource": "SABRE_ORDER",
    "flightTicketOperation": "VOID",
    "retrieveBooking": true
}  

Conclusion

We would like to invite you to the Booking Management API world. Once integrated, you can reap the benefits of many downline Sabre services. You can create both NDC and ATPCO bookings using single, simple, concise, and fast service – the Create Booking Service. When it comes to retrieving data, simple integration with the Get Booking Service will allow you to get many travel data, such as: flights, hotels, cars, cruises, reservations, passenger data, tickets, taxes, fares, baggage and many more. If needed, any of them can be cancelled using the Cancel Booking Service. Common data API model, service speed, performance optimization and possibility of customization every request with more advanced parameters we’ve implemented will take your product to the next level. Your developers will love the Booking Management API, we have no doubt about that.

We would be honored if you would like to be our guest and try the Booking Management API by Sabre. Please book some time and play with samples provided to the article, which shows end-to-end usage our API. More advanced examples (for both NDC and ATPCO flows) can be found under Sabre Dev Studio’s Github.

In the words of Lao Tzu, “A journey of a thousand miles must begin with a single step,”

With the Booking Management API all those steps can be simple and fun.

Resources