EMD Exchange API User Guide - Sabre · The EMD Exchange API is a new solution available to Sabre...

EMD Exchange API

User Guide

Document version 1.0

Updated: 21 June 2019

Software version 1.4.0 2019

Document Edition 1.0

This documentation is the confidential and proprietary intellectual

property of the Sabre Airline Solution® business. Any unauthorized

use, reproduction, preparation of derivative works, performance or

display of this document or software represented by this

document, without the express written permission of Sabre Airline

Solutions is strictly prohibited.

Sabre, the Sabre, Sabre Holdings, and other names used in this

document are trademarks and/or service marks of, or an affiliate of

Sabre Inc. All other trademarks, service marks and trade names

are the property of their respective owners.

© 2019 Sabre Inc. All rights reserved. 06_2019

TN ExchangeEMD Table of Contents 27 June 2019 iii Confidential and Proprietary - Sabre Travel Network Solutions

Document Revision Information

Project Name EMD Exchange API

Project Number

Prepared by Henry Kennedy Date Prepared 21 June 2019

Revised by Henry Kennedy Date Revised

Revision Reason Original version Revision Control No. 001

Revised by Date Revised

Revision Reason Revision Control No.











TN ExchangeEMD Table of Contents 27 June 2019 iv Confidential and Proprietary - Sabre Travel Network Solutions

Table of Contents

1 I n t r o d u c t i o n

1.1 Overview................................................................................................................................................. 6 1.2 Purpose of this Guide ............................................................................................................................. 6 1.3 Examples in this Document .................................................................................................................... 7 1.4 Sabre Dev Studio ................................................................................................................................... 7 1.5 EMD Exchange WSDL and TTL files ...................................................................................................... 7 1.6 Getting Started Guide ............................................................................................................................. 7

2 U n d e r s t a n d i n g t h e E M D E x c h a n g e A P I

2.1 Security Validation .................................................................................................................................. 8

3 U s i n g t h e E M D E x c h a n g e A P I

3.1 Agency Use Cases ............................................................................................................................... 10 3.2 ExchangeEmdRQ – Request for Exchange Calculation Summary ....................................................... 10

3.2.1 Parameters for ExchangeEmdRQ Request........................................................................... 10 3.2.1.1 Sample XML for ExchangeEmdRQ Calculation Summary REQUEST ...................... 11

3.2.2 Elements in ExchangeEmdRS Response for @PriceComparison requestType .................... 12 3.2.2.1 Sample XML for ExchangeEmdRS Calculation Summary RESPONSE.................... 12

3.3 ExchangeEmdRQ – Request for Exchange Fulfillment ........................................................................ 17 3.3.1 Parameters for ExchangeEmdRQ Fulfill Request .................................................................. 17

3.3.1.1 Sample XML for ExchangeEmdRQ Fulfill REQEST .................................................. 18 3.3.2 Elements in ExchangeEmdRS Response for @Fulfill option ................................................. 20

3.3.2.1 Sample XML for ExchangeEmdRS Fulfill RESPONSE ............................................. 20

4 T r o u b l e s h o o t i n g

4.1 Introduction ........................................................................................................................................... 22 4.2 EMD Exchange Workflow Communication Points ................................................................................ 22 4.3 Common Error Responses, Reasons and Solution .............................................................................. 23

4.3.1 USG Authentication Errors ..................................................................................................... 23 4.3.1.1 USG Invalid Security Token ...................................................................................... 23 4.3.1.2 ESSM Authorization Failed ....................................................................................... 24

4.3.2 Security Violation ................................................................................................................... 25 4.3.2.1 No Branch Access ..................................................................................................... 25

4.3.3 Timeout .................................................................................................................................. 26 4.3.4 Invalid Service Version Specified in XML Request ................................................................. 26 4.3.5 Invalid Request XML Format .................................................................................................. 27

TN ExchangeEMD Table of Contents 27 June 2019 v Confidential and Proprietary - Sabre Travel Network Solutions

4.3.5.1 Request XML Validation Failed Against Schema ...................................................... 27 4.3.6 Database Response: Not Found ............................................................................................ 28

4.4 Error Response Matrix .......................................................................................................................... 30

5 G l o s s a r y

6 A p p e n d i x

6.1 Examples of EMD Exchange Calculation Summary Host Responses .................................................. 35 6.1.1 Even Exchange Example ....................................................................................................... 35 6.1.2 Additional Collection Example ................................................................................................ 36 Even Exchange with Loss of Residual Amount ............................................................................... 37

TN GetTicketingDocument Introduction

27 June 2019 6 Confidential and Proprietary Sabre Travel Network Solutions

1 Introduction

1.1 Overview

The EMD Exchange API provides Sabre Travel Network agency customers the ability to exchange one associated Electronic Miscellaneous Document (EMD-A) for another single EMD-A.

It is the responsibility of the consuming application(s) to carry out the formatting and presentation of the data provided. Sample layouts from the Sabre host version of the solution are provided in appendix 6.1 for guidance purposes.

This EMD Exchange solution is available as an addition to the existing service. TKT_ExchangeRefundRQ API (version 1.4.0 and higher), as a new operation element,

ExchangeEmdRQ.

Note: Sabre Airline Solutions customers should continue using the existing API,

ExchangeDocumentforEMDRQ, to process airline EMD exchange transactions

1.2 Purpose of this Guide

The purpose of this guide is to introduce how the API processes EMD-A Exchange requests. It is not a complete documentation of XML design. The Sabre repository for all API information can be found at Sabre Dev Studio. Please visit the site and register for an account if you have not done so already.

This introductory guide provides:

• Description of API features

• Examples of typical EMD Exchange requests and responses o EMD Exchange calculation summary o EMD Exchange fulfillment

• Common error messages that may be returned by the API along with the explanation as to why they occur and ways for fixing the problem where applicable.

It is assumed that a developer implementing ExchangeEmdRQ has a solid understanding of the underlying Sabre functionality, or that they have access to a Sabre Subject Matter Expert at the agency.

This document does to attempt to explain the purpose/functionality of airline ancillary services, EMDs, PNR’s, electronic airline document exchange transactions, agency reporting/settlement

requirements, or agency accounting processes.

1

http://cl.exct.net/?ju=fe1e1076766c007e7c1d73&ls=fdd915727265017d7715727565&m=fe5e157076650174701d&l=fe5715777c65027a7111&s=fe9516757566007a73&jb=ffcf14&t=

TN GetTicketingDocument Introduction


1.3 Examples in this Document

The purpose of the XML examples provided in this document is to present the possible content of the request and response (RQ/RS). These examples are for illustrative purposes only and in some case may be truncated to save space – they are not always complete XML documents.

1.4 Sabre Dev Studio

Sabre Dev Studio has many resources for implementing Sabre APIs including schemas, WSDL files, TTL files, full RQ/RS XML samples, design documents, workflows, and helpful related information.

Users must have a registered account to gain access to the comprehensive references available for developers implementing Sabre APIs.

1.5 EMD Exchange WSDL and TTL files

The API Description (WSDL) file provides a description of the basic formats of the API requests – how the service can be called, expected parameters and what data structures it returns – so you can easily get the service running on your development/testing tools.

The Ticketing Type Library (TTL) file is a library of common terms and elements that the ExchangeEmdRQ operation will reference when it is called by your client/GUI.

For the latest WSDL and TTL files, check the ExchangeEmdRQ Resources page at Sabre Dev Studio.

1.6 Getting Started Guide

For information on how to connect and create a session, please access Getting Started in Sabre Dev Studio.



https://developer.sabre.com/docs/read/soap_basics/getting_started

TN GetTicketingDocument Understanding the EMD Exchange API


2 Understanding the EMD Exchange API

The EMD Exchange API is a new solution available to Sabre Travel Network customers, which allows

the exchange of a single EMD-A for another, single EMD-A.

The EMD Exchange API offers Travel Agencies the ability to:

• Calculate the cost of an EMD Exchange, before committing to the exchange

• Fulfill an EMD Exchange and automatically initiate all EMD issuance post-fulfilment processes

o Creation of a new EMD record and updating the exchanged EMD record ▪ Sabre Ticketing Database (WTDB) ▪ Airline Database (WEMD)

o PNR updates ▪ *T field of PNR ▪ *AE field of PNR ▪ Addition of credit card authorization

o Addition of an EMD Exchange accounting line o Generation of an EMD Exchange Interface User Record IUR

The user request must include the EMD document number the agent wishes to exchange, the Air Extra items the user wishes to fulfill with the exchange transaction the request type (calculation summary or fulfill/process exchange), a commission amount/percent (optional), tax exemption (optional), and a form of payment (required for add/collect only). These data can be input manually by the user using the agency’s client/GUI, or orchestrated with other Sabre API’s

(GetTicketingDocumentRQ for document details, and GetReservation for PNR/AE details).

This document describes the functions of the EMD Exchange API itself. It does not attempt to describe or recommend how to implement the service in your agency. For help and guidance on orchestration with other Sabre API’s, please refer our experts at Sabre Dev Studio. Additional information is available in Sabre Format Finder under reference misfo006, or by using search keywords EMD, EXCHANGE, WEMDX.

The current release of the EMD Exchange API does not support the issuance of an EMD-S for any residual amount from the exchanged EMD. For this reason, it is highly recommended that developers implementing this API take that into consideration when designing the consuming client/GUI.

2.1 Security Validation

Security validation verifies user access to documents housed in Sabre Dev Studio and protects inhibits viewership by unauthorized parties, i.e. other Travel Agencies which do not have a branch access relationship.

2

TN GetTicketingDocument Understanding the EMD Exchange API


If the PCC in the <WorkLocation/> element of the API request, is not the originating Travel Agency’s that issued the document, the system will examine the authorized branch locations in the

issuing agency’s TJR to determine if processing will continue.

If validation fails, an error message will be returned to the user and the transaction will not be

processed.

TN GetTicketingDocument Using the EMD Exchange API


3 Using the EMD Exchange API

3.1 Agency Use Cases

Today, travelers must contact the carrier when an agency-issued Electronic Miscellaneous Document (type A) exchange is needed. With the introduction of this service, the agency can now service the customer directly.

An EMD Exchange can be needed due to:

• A voluntary or involuntary change to the itinerary, resulting in the need to exchange of the Electronic Ticket. When a flight is canceled, the Air Extra item is automatically cancelled; however, there is no automatic action take on the EMD document and the EMD will retain its value. With the introduction of this service, if the passenger desires to rebook the ancillary as well, the agency can book a new Air Extra item , complete the Ticket exchange, and then exchange the existing EMD as payment for the new Air Extra item.

• The traveler wants to apply the value of previously purchased services toward the purchase of new ancillaries.

Sabre’s launch partner for the EMD Exchange API is Air France. For this reason, you will need to do all your development testing and analysis using Air France ancillary services. As more airlines are certified for the solution, separate communications will be sent via Sabre’s customer communications channels.

This document will not be updated every time a new carrier is certified. It will only be updated when there are functional enhancements/changes to the service.

3.2 ExchangeEmdRQ – Request for Exchange Calculation Summary

ExchangeEmdRQ will issue a new EMD document to fulfill Air Extras in a Sabre PNR. The PNR must be present in your session at the time of the ExchangeEMD request.

3.2.1 Parameters for ExchangeEmdRQ Request

The ExchangeEmdRQ request parameters include the following:

Element XPath (from root ExchangeEmdRQ)

Purpose

<Company/> //POS/Company 2-digit GDS code. Either 1S (Sabre TN), 1B (Sabre TN APAC), or 1F (INFINI)

<Pseudo/> //POS/Pseudo Sabre/INFINI pseudo city code

3



<TransactionInfo requestType =PriceComparison/>

//TransactionInfo/requestType

= PriceComparison

Used for exchange calculation summary. This does not fulfill the exchange.

<TransactionInfo requestType =

Fulfill/>

//TransactionInfo/requestType = Fulfill

Used for exchange fulfillment. When used, the system will generate the new EMD, but not return the price comparison data.

<Number/> //TransactionInfo/TicketingDocument

The 13 digit EMD number being exchanged.

<TicketReference/> //TransactionInfo/TicketReference

The 1-2 digit Ticket Reference number from the *T field of the PNR

<AirExtra> //TransactionInfo/Reservation/AirExtra

The 1-3 digit Air Extra Number for the service(s) being fulfilled with the exchange transaction. The element may be repeated if the user wishes to fulfill more than 1 Air Extra with the

exchange transaction.

<Name/> //TransactionInfo/Reservation/Name

The traveler’s name reference number. This field is optional as per the schema definition, but it is required by the background systems when the PNR contains more than one name.

3.2.1.1 Sample XML for ExchangeEmdRQ Calculation Summary REQUEST

<ExchangeEmdRQ version="1.4.0" xmlns="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0" xmlns:TTL="http://www.sabre.com/ns/Ticketing/TTL/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0 "> <POS> <TTL:Company>1S</TTL:Company> <TTL:Pseudo>1Z1Z</TTL:Pseudo> </POS> <TransactionInfo requestType="PriceComparison"> <TicketingDocument> <TicketReference>3</TicketReference> </TicketingDocument> <Reservation> <AirExtra>2</AirExtra> </Reservation>



</TransactionInfo> </ExchangeEmdRQ>

3.2.2 Elements in ExchangeEmdRS Response for @PriceComparison requestType

Since an API is not limited by Sabre green screen limitations, there is much more data returned in the ExchangeEmdRS payload than in the equivalent green screen response. However, you may wish to use the Sabre green screen response to an EMD Exchange Calculation Summary request as a starting point when designing your client/API.

3.2.2.1 Sample XML for ExchangeEmdRS Calculation Summary RESPONSE

The ExchangeEmdRS XML payload contains much more information than the Sabre green screen response. If you have agents or Sabre subject matter experts who will be using the Sabre green screen version as a point of reference, you may wish to include most of the elements from the green screen response when you design your client/GUI to avoid the perception that the green screen version and the API version are functionally different. They are not – both versions use the same internal processes and apply the same business rules.

The following XML payload is the XML response to the XML request in section 3.2.1.1. The key pricing elements you will need to return a meaningful response to the consuming client are found at

the bottom of the response.

Element XPath

(from root ExchangeEmdRS)

Purpose

<Old/> //BaseComparison/Old Provides the value of the EMD

presented for exchange

<New/> //BaseComparison/New Provides the cost of the Air Extra(s) which will be fulfilled with the exchange

<Difference/> //BaseComparison/Difference Provides the difference in price between the EMD to be exchanged and the Air Extra items to be fulfilled.

<ResidualAmount/> //PriceComparison/ResidualAmount

Provides the residual amount forfeited, if the exchange is fulfilled

@currencyCode //PriceComparison/ResidualAmount@currencyCode

Currency code of the residual amount



@decimalPlaces //PriceComparison/ResidualA

mount@decimalPlaces

Decimal places in the currency code of

the residual amount.

<ExchangeEmdRS version="1.4.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0" xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0"> <Header messageID="TKTVLC650-32313-2097482375-1557262146121-20699-arex" timeStamp="2019-05-07T15:49:00.000"> <OrchestrationID>TKTVLC650-32313-2097482375-1557262146121-20699-arex</OrchestrationID> <Results> <Success> <System>TKT-DS</System> <Source>AREX</Source> </Success> </Results> </Header> <ExchangeDocuments> <ExchangeDocument number="0573092496285"> <Details> <ElectronicMiscTypes>A</ElectronicMiscTypes> <ReasonForIssue>C</ReasonForIssue> <LocalIssueDate>2019-05-07T21:47:00</LocalIssueDate> <IssueLocation>1Z1Z</IssueLocation> <Reservation>GEICCI</Reservation> <AgencyIdentifier>99999992</AgencyIdentifier> <ValidatingCarrier>AF</ValidatingCarrier> </Details> <Traveler firstName="DOE" lastName="JANE" type="ADT"/> <MiscellaneousServiceCoupon> <Fee coupon="1" description="1ST ADDITIONAL BAG" quantity="1"/> <OptionalService journeyType="P" reasonForIssuanceSubCode="0CC"/> <AssociatedTicketNumber associationType="A" couponNumber="1">0573455387442</AssociatedTicketNumber> <ServiceCoupon> <MarketingProvider>AF</MarketingProvider> <MarketingFlightNumber>1123</MarketingFlightNumber> <OperatingProvider/> <ClassOfService>Y</ClassOfService> <StartLocation>MUC</StartLocation> <StartDateTime>2019-05-25T07:15:00</StartDateTime> <EndLocation>CDG</EndLocation> <EndDateTime>2019-05-25T09:00:00</EndDateTime> <CurrentStatus>OPEN</CurrentStatus> </ServiceCoupon>



</MiscellaneousServiceCoupon> <MiscellaneousServiceCoupon> <Fee coupon="2" description="1ST ADDITIONAL BAG" quantity="1"/> <OptionalService journeyType="P" reasonForIssuanceSubCode="0CC"/> <AssociatedTicketNumber associationType="A" couponNumber="2">0573455387442</AssociatedTicketNumber> <ServiceCoupon> <MarketingProvider>AF</MarketingProvider> <MarketingFlightNumber>1580</MarketingFlightNumber> <OperatingProvider/> <ClassOfService>Y</ClassOfService> <StartLocation>CDG</StartLocation> <StartDateTime>2019-05-25T10:10:00</StartDateTime> <EndLocation>LHR</EndLocation> <EndDateTime>2019-05-25T10:35:00</EndDateTime> <CurrentStatus>OPEN</CurrentStatus> </ServiceCoupon> </MiscellaneousServiceCoupon> <Amount currencyCode="GBP" decimalPlaces="2">25.50</Amount> </ExchangeDocument> </ExchangeDocuments> <NewDocuments> <NewDocument> <Details> <ElectronicMiscTypes>A</ElectronicMiscTypes> <ReasonForIssue>C</ReasonForIssue> <Reservation>GEICCI</Reservation> <ValidatingCarrier>AF</ValidatingCarrier> </Details> <Traveler firstName="JANE" lastName="DOE" type="ADT"/> <MiscellaneousServiceCoupon> <Fee ancillaryId="34" coupon="1" description="2ND ADDITIONAL BAG" quantity="1"> <Total currencyCode="GBP" decimalPlaces="2">0</Total> </Fee> <OptionalService journeyType="P" reasonForIssuanceSubCode="0CD"/> <AssociatedTicketNumber associationType="A" couponNumber="1">0573455387442</AssociatedTicketNumber> <ServiceCoupon> <MarketingProvider>AF</MarketingProvider> <MarketingFlightNumber>1123</MarketingFlightNumber> <OperatingProvider>AF</OperatingProvider>



3.3 ExchangeEmdRQ – Request for Exchange Fulfillment

3.3.1 Parameters for ExchangeEmdRQ Fulfill Request

The mandatory request parameters for EMD Exchange fulfillment are the same as those described in section 3.2.1. The only difference in the request structure, is the attribute on the <Options/> element:

• Use PriceComparison to request an exchange calculation summary XPath //TransactionInfo/@requestType = PriceComparison

• Use Fulfill to request an exchange fulfillment XPath //TransactionInfo/@requestType = Fulfill

However, for fulfillment requests, there are some additional parameters, as indicated in the chart below. These optional qualifiers are used in addition to the mandatory parameters listed on the table in section 3.2.1.

Element XPath (from root ExchangeEmdRQ)

Purpose

<Commission/>

//@Fulfill/Commission/Commission/Amount

If the EMD Exchange is an additional collection, and that additional collection is commissionable, the agent would specify the add/collect commission with these elements

<Amount/> //@Fulfil/Commission/Commission/Amount

Used with commission amount

<Percent/> //@Fulfil/Commission/Commiss

ion/Percent Used with commission percent

<NewTicketFullCommission/>

//@Fulfill/Commission/NewTicketFullCommission

For use in ARC locations only. If the agent took commission on the old EMD, the agent would include that commission plus any commission on an additional collection with this element. Always expressed as an amount.



<Payment/> //@Fulfill/Payment Used with additional collection exchanges to show how the amount due was paid for.

<Card/> //@Fulfill/Payment/Card Used for credit cards

@vendorCode //@Fulfill/Payment/Card/@ven

dorCode

The credit card vendor code (e.g. AX for

American Express)

@number //@Fulfill/Payment/Card/@number

The credit card number

@expireDate //@Fulfill/Payment/Card/@expireDate

The credit card expiration date

@manualApprov alCode

//@Fulfill/Payment/Card/@manualApprovalCode

Used when the agency has manually obtained the credit card approval code. When used, the internal automated system credit card authorization code

will not be invoked.

<GovernmentTrav el/>

//@Fulfill/Payment/GovernmentTravel

<ReservationFOP/>

//@Fulfill/Payment/Reservatio

nFOP

If your agency uses the TJR option PNAPNR, and stores the form of Payment in the *FOP field, the user would include the *FOP reference

number with this element.

<Virtual/> //@Fulfill/Payment/Virtual If your agency accepts Virtual Credit Card payments and has an account with Conferma, the agent would use the traveler’s CAC code with this element.

<Miscellaneous/> //@Fulfill/Payment/Miscellaneous

If your agency uses Miscellaneous FOP, Sabre green screen #MS qualifier, the agent would include the miscellaneous information (a string) with this element.

3.3.1.1 Sample XML for ExchangeEmdRQ Fulfill REQEST

<SOAP-ENV:Body>



<ExchangeEmdRQ

version="1.4.0"

xmlns="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0"

xmlns:TTL="http://www.sabre.com/ns/Ticketing/TTL/1.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0 ">

<POS>

<TTL:Company>1S</TTL:Company>

<TTL:Pseudo>61N1</TTL:Pseudo>

</POS>

<TransactionInfo

requestType="Fulfill">

<TicketingDocument>

<TicketReference>3</TicketReference>

</TicketingDocument>

<Reservation>

<AirExtra>5</AirExtra>

</Reservation>

<Options>

<Fulfill>

<Payment

type="CC">

<Card expireDate="1219"

number="376701078252003" vendorCode="AX"/>

</Payment>

</Fulfill>

</Options>

</TransactionInfo>

</ExchangeEmdRQ>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0

http://www.sabre.com/ns/Ticketing/TTL/1.0

http://www.w3.org/2001/XMLSchema-instance





3.3.2 Elements in ExchangeEmdRS Response for @Fulfill option

When ExchangeEmdRQ is sent with option “Fulfill”, the response elements are related to the

transaction, not the price comparison.

Element XPath (from root ExchangeEmdRS)

Purpose

<Results/>

<Success/>

//Results

//Results/Success

To tell the user if the ExchangeEmdRQ was processed or not

<TransactionInfo>

<reservationAutoEndProcessed/>

//TransactionInfo/reservationAutoEndProcessed/@true

//TransactionInfo/reservationAutoEndProcessed/@false

Used if the agency has the TJR option for AUTOEND active.

<reservationAutoRetrievedProcessed/>

//TransactionInfo/reservationAutoRetrievedProcessed/>@true

<reservationAutoRetrievedProcessed/>@true

Used if the agency has the TJR option for AUTOER active.

<Message/> //TransactionInfo/Message Repeatable element that sends the success response a user would see in Sabre greenscreen for the same transaction. If the exchange was an additional collection, with Credit Card form of payment, the CC approval code will be sent in this element.

@type //TransactionInfo/Message/@type Attribute type = I is used to advise the invoice number issued at the time of end transaction which follows a fulfillment transaction.

3.3.2.1 Sample XML for ExchangeEmdRS Fulfill RESPONSE

<ns2:ExchangeEmdRS

version="1.4.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0"

xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0">

<ns2:Header

messageID="TKTHLI702-21454-2036826683-1561136101903-79-arex"

timeStamp="2019-06-21T11:55:00.000">

<OrchestrationID>TKTHLI702-21454-2036826683-1561136101903-79-arex</OrchestrationID>

http://www.sabre.com/ns/Ticketing/TTL/1.0




<Results>

<Success>

<System>TKT-DS</System>

<Source>AREX</Source>

</Success>

</Results>

</ns2:Header>

<ns2:TransactionInfo

reservationAutoEndProcessed="false"

reservationAutoRetrieveProcessed="true">

<ns2:Message

type="E">OK 18.00 Y76623</ns2:Message>

<ns2:Message

type="E">EMD EXCHANGE PROCESSED</ns2:Message>

<ns2:Message

type="E">OK 6.6</ns2:Message>

<ns2:Message

type="I">OK 1155 RVIJJF</ns2:Message>

<ns2:Message type="I">INVOICED - NUMBER 0006045</ns2:Message>

</ns2:TransactionInfo>

</ns2:ExchangeEmdRS>

TN GetTicketingDocument Troubleshooting


4 Troubleshooting

4.1 Introduction

When reporting an issue with an APIs, please make sure to provide full XML payload (request and response) or, if it is not possible, at least transaction ID to troubleshoot the problem.

Later in this document you will find the examples of common error responses that may help you identify the cause of issue and solve the problem.

4.2 EMD Exchange Workflow Communication Points

The steps in the ExchangeEmdRQ operation are:

• Validation of incoming requests against the current versions of the TTL, WSDL, and XSD files published on Sabre Dev Studio.

• Validation with the ICE/ESSM system whether the request comes from a user authorized to use the EMD Exchange API.

• Retrieval of the EMD presented for exchange via GetTicketingDocument

• Retrieval of the PNR details via GetReservation

• Checking status of EMD coupons using ElectronicDocumentServices

• Application of internal logic to determine the exchange cost

o For <TransactionInfo requestType="PriceComparison"> requests, the processing stops here and an EMDExchangeRS response XML payload is returned to the requestor.

o For <TransactionInfo requestType="Fulfill"> requests, the processing continues as follows:

▪ Dispensing of a new EMD number by Sabre’s host process, and association to the eTicket

• Disassociation of old EMD from the eTicket

▪ Creation and delivery of an EDIFACT 798 (EMD exchange) message to the carrier so a new EMD can be created in the carrier’s database

▪ Creation of a binary payload to be sent to Sabre’s Passenger Service system to create an EMD in Sabre’s database

▪ Initiation of downline processes

• Accounting line creation

• IUR creation

4




• PNR updates: WTDB*, *T, *AE, etc.

If any of these communication points experience a failure, it results in an XML error response returned in the ExchangeEmdRS response. If a document has been created in the carrier’s database, the background processes will automatically send an EDIFACT 802 (system cancel) message.

Note: If you wish to void an EMD resulting from an EMD that was exchanged, this may be accomplished using the Sabre green screen format (WV[line number from *T], then repeat to confirm) or the VoidTicketLLSRQ API. A void using the EMD Exchange API is not supported.

4.3 Common Error Responses, Reasons and Solution

This section provides examples of common error responses you might come across when using the EMD Exchange API together with the reasons and tips on how to resolve these problems.

For additional assistance, please contact your Sabre APIs Support desk contacts. If you are unsure, contact your Sabre Account Director.

Always provide your user ID, domain, organization and environment you use.

4.3.1 USG Authentication Errors

This type of error is returned when authorization to access the API fails for the requestor.

4.3.1.1 USG Invalid Security Token

Error:

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"> <soap-env:Header> <eb:MessageHeader xmlns:eb="http://www.ebxml.org/namespaces/messageHeader" eb:version="1.0" soap-env:mustUnderstand="1"> <eb:From> <eb:PartyId eb:type="URI"/> </eb:From> <eb:To> <eb:PartyId eb:type="URI"/> </eb:To> <eb:ConversationId>SYSTEM-T2DAILY-SYSTEM</eb:ConversationId> <eb:Action>ErrorRS</eb:Action> <eb:MessageData> <eb:MessageId>1011802746810161910</eb:MessageId> <eb:Timestamp>2019-06-11T20:44:41</eb:Timestamp> </eb:MessageData> </eb:MessageHeader> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext">



<wsse:BinarySecurityToken valueType="String" EncodingType="wsse:Base64Binary">ICE_SECURITY_TOKEN</wsse:BinarySecurityToken> </wsse:Security> </soap-env:Header> <soap-env:Body> <soap-env:Fault> <faultcode>soap-env:Client.InvalidSecurityToken</faultcode> <faultstring>Invalid or Expired binary security token: ICE_SECURITY_TOKEN <faultstring> <detail> <StackTrace>com.sabre.universalservices.base.session.SessionException: errors.session.USG_INVALID_SECURITY_TOKEN</StackTrace> </detail> </soap-env:Fault> </soap-env:Body> </soap-env:Envelope>

Reason:

Unauthorized access to ExchangeEmdRQ – no USG session created.

Solution:

Before accessing ExchangeEmdRQ , USG session needs to be created and correct BinarySecurityToken passed over in XML request. Please make sure you have correctly created USG

session.

4.3.1.2 ESSM Authorization Failed

Error:

<ns2:ExchangeEmdRS xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0" version="1.4.0"> <ns2:Header messageID="TKTHLI702-1284-662589928-1560185222097-35-arex" timeStamp="2019-06-10T11:47:00.000"> <OrchestrationID>TKTHLI702-1284-662589928-1560185222097-35-arex</OrchestrationID> <Results> <Error status="NotProcessed" timeStamp="2019-06-10T11:47:02.146" type="Application"> <Source>AREX</Source> <System>TKT-DS</System> <SystemSpecificResults> <STL:ErrorMessage code="1013">ESSM authorization failed: ICE SessionException occured</STL:ErrorMessage> <STL:ShortText>ESSM authorization failed</STL:ShortText> </SystemSpecificResults> </Error> </Results> </ns2:Header> <ns2:TransactionInfo reservationAutoEndProcessed="false" reservationAutoRetrieveProcessed="false">



<ns2:Message type="E">ESSM authorization failed/ns2:Message> </ns2:TransactionInfo> </ns2:ExchangeEmdRS>

Reason:

Unauthorized access to ExchangeEmdRQ – security authorization failed.

Solution:

Contact the Sabre APIs Support Team and provide your user ID, domain, organization and

environment you use.

4.3.2 Security Violation

4.3.2.1 No Branch Access

Error:

<ns2:ExchangeEmdRS xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0" version="1.4.0"> <ns2:Header messageID="TKTHLI702-1284-662589928-1560185222097-35-arex" timeStamp="2019-06-10T11:47:00.000"> <OrchestrationID>TKTHLI702-1284-662589928-1560185222097-35-arex</OrchestrationID> <Results> <Error status="NotProcessed" timeStamp="2019-06-10T11:47:02.146" type="Application"> <Source>AREX</Source> <System>TKT-DS</System> <SystemSpecificResults> <STL:ErrorMessage code="21221">Security violation: Not allowed to access the requested work location. Transaction failed</STL:ErrorMessage> <STL:ShortText>Security violation</STL:ShortText> </SystemSpecificResults> </Error> </Results> </ns2:Header> <ns2:TransactionInfo reservationAutoEndProcessed="false" reservationAutoRetrieveProcessed="false"> <ns2:Message type="E">XML schema version 1.5.0 is not supported</ns2:Message> </ns2:TransactionInfo> </ns2:ExchangeEmdRS>

Reason:

User PCC does not have permission to retrieve from PCC provided in the search – security authorization failed.

Solution:

Verify if the values of search parameters fields are correct and if needed, amend them and try again. If you need additional assistance, contact the Sabre API Support Team and provide your user ID, domain, organization and environment you use.



4.3.3 Timeout

Error:

<ns2:ExchangeEmdRS xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0" version="1.4.0"> <ns2:Header messageID="TKTHLI702-1284-662589928-1560185222097-35-arex" timeStamp="2019-06-10T11:47:00.000"> <OrchestrationID>TKTHLI702-1284-662589928-1560185222097-35-arex</OrchestrationID> <Results> <Error status="NotProcessed" timeStamp="2019-06-10T11:47:02.146" type="Application"> <Source>AREX</Source> <System>TKT-DS</System> <SystemSpecificResults> <STL:ErrorMessage>Downstream system did not respond within time limit: Timeout while receive a message</STL:ErrorMessage> <STL:ShortText>Downstream system did not respond within time limit</STL:ShortText> </SystemSpecificResults> </Error> </Results> </ns2:Header> <ns2:TransactionInfo reservationAutoEndProcessed="false" reservationAutoRetrieveProcessed="false"> <ns2:Message type="E">XML schema version 1.5.0 is not supported</ns2:Message> </ns2:TransactionInfo> </ns2:ExchangeEmdRS>

Reason:

There are problems receiving response from PSS/T2 DMS via MOM.

Solution:

Wait for a few minutes and try again. If the problem still exists, contact your Sabre APIs Support

desk contacts.

4.3.4 Invalid Service Version Specified in XML Request

Error:

<ns2:ExchangeEmdRS xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0" version="1.4.0"> <ns2:Header messageID="TKTHLI702-1284-662589928-1560185222097-35-arex" timeStamp="2019-06-10T11:47:00.000">



<OrchestrationID>TKTHLI702-1284-662589928-1560185222097-35-arex</OrchestrationID> <Results> <Error status="NotProcessed" timeStamp="2019-06-10T11:47:02.146" type="Application"> <Source>AREX</Source> <System>TKT-DS</System> <SystemSpecificResults> <ErrorMessage code="21212">Invalid request: Unsupported XML schema version</ErrorMessage> <ShortText>XML schema version 1.5.0 is not supported</ShortText> </SystemSpecificResults> </Error> </Results> </ns2:Header> <ns2:TransactionInfo reservationAutoEndProcessed="false" reservationAutoRetrieveProcessed="false"> <ns2:Message type="E">XML schema version 1.5.0 is not supported</ns2:Message> </ns2:TransactionInfo> </ns2:ExchangeEmdRS>

Reason:

The XML request sent uses unsupported version of schema.

Solution:

Send the request in one of the supported schema versions. If you need additional assistance, use your provided Sabre APIs Support desk contacts.

4.3.5 Invalid Request XML Format

4.3.5.1 Request XML Validation Failed Against Schema

Error:

<ns2:ExchangeEmdRS xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0" version="1.4.0"> <ns2:Header messageID="TKTHLI702-12185-757463262-1559231760861-119-arex" timeStamp="2019-05-30T10:56:00.000"> <OrchestrationID>TKTHLI702-12185-757463262-1559231760861-119-arex</OrchestrationID> <Results> <Error status="NotProcessed" timeStamp="2019-05-30T10:56:00.890" type="Application"> <Source>AREX</Source> <System>TKT-DS</System> <SystemSpecificResults> <ErrorMessage code="21208">Invalid request: XML request validation failed</ErrorMessage> <ShortText> Please amend your request and try again.</ShortText>



</SystemSpecificResults> </Error> </Results> </ns2:Header> <ns2:TransactionInfo reservationAutoEndProcessed="false" reservationAutoRetrieveProcessed="false"> <ns2:Message type="E"> Please amend your request and try again.</ns2:Message> </ns2:TransactionInfo> </ns2:ExchangeEmdRS>

Reason:

The XML request sent doesn’t match the ExchangeEmdRQ XSD schema. The input parameters

provided in the search are invalid.

Solution:

Verify XML request with XSD schema version you used and correct it.

If you need additional assistance, use your provided Sabre APIs Support desk contacts.

4.3.6 Database Response: Not Found

Error:

<ns2:ExchangeEmdRS xmlns:ns2="http://www.sabre.com/ns/Ticketing/ExchangeRefund/1.0" xmlns="http://www.sabre.com/ns/Ticketing/TTL/1.0" version="1.4.0"> <ns2:Header messageID="TKTHLI702-12185-757463262-1559231385747-115-arex" timeStamp="2019-05-30T10:49:00.000"> <OrchestrationID>TKTHLI702-12185-757463262-1559231385747-115-arex</OrchestrationID> <Results> <Error status="NotProcessed" timeStamp="2019-05-30T10:49:47.174" type="Application"> <Source>AREX</Source> <System>TKT-DS</System> <SystemSpecificResults> <ErrorMessage code="49216">Retrieving ticketing document failed, try again</ErrorMessage> <ShortText>AIRLINE SYSTEM UNABLE TO PROCESS TRANSACTION AT THIS TIME</ShortText> </SystemSpecificResults> </Error> </Results> </ns2:Header> <ns2:TransactionInfo reservationAutoEndProcessed="false" reservationAutoRetrieveProcessed="false"> <ns2:Message type="E">AIRLINE SYSTEM UNABLE TO PROCESS TRANSACTION AT THIS TIME</ns2:Message> </ns2:TransactionInfo> </ns2:ExchangeEmdRS>



Reason:

This is not an error, but a database response. The document requested was not found. The user may have entered an invalid PCC and document number combination in the search.

Solution:

Verify if the values of search parameters fields are correct and if needed, amend them and try again. If you need additional assistance, use your provided Sabre APIs Support desk contacts.



4.4 Error Response Matrix

Some errors are more common than others, because they involve the data sent in the RQ by the consuming client/API. Other errors are not likely to be returned, as they are due to internal processes outside of the EMD Exchange API, which have auto-correcting capabilities. However, both types are provided in the table below, in case you do see them in your environment.

Error Code

ErrorMessage Short Text Reason Solution

ExchangeEmdRQ Primary Errors

49000 AREX WS Generic Error

PROCESSING ERROR DETECTED - RETRY - (ERC 9400), Exception while invoking getSecurityAttributes FromATH method

There is a problem with your security token.

Contact the Sabre API Support desk.

49100 AREX WS Validation Error

EMD NOT VALID FOR

EXCHANGE

You are attempting to exchange an EMD which is already exchanged.

Check coupon status of EMD in Sabre green screen, or by using TKT_Electronic

DocumentServicesRQ.

49112 Invalid PNR selection Criteria

CHECK AE ITEM, VERIFY SELECTED AE ITEMS -

NO ELECTRONIC TICKET ASSIGNED

This error occurs when the RQ contains a name or segment which causes the internal logic to fail. If no segment is specified, the system assumes all segments.

Check PNR in green screen or using GetReservationRQ to verify the content of the PNR. Also check dates of the itinerary segments/flights. If you feel your RQ is valid, but continue to get this response, contact the Sabre API Support desk.

49216 AREX WS Generic Error

AIRLINE SYSTEM UNABLE TO PROCESS TRANSACTION AT THIS TIME

Either a connectivity issue on the airline’s side exits, or the EMD is no longer present in the airline’s database. Sabre keeps a record of the EMD for 13 months after issuance, but

Retry the request after a few minutes. If the problem persists, contact the Sabre API Support desk.



the airline may

delete sooner.

49700 Post calculation error

NEED FORM OF PAYMENT, UNABLE TO PROCESS- TKTDOC

The result of the exchange will be an additional

collection.

Resend RQ using the form of payment element. See section

3.3.1.

49801 PSS returned an error while fulfilling the

refund

TKT PRT NOT ASSIGNED/USE W*

You are attempting a fulfilment and either the ticket printer is not assigned, or it has run out of EMD stock control numbers.

Be sure your session set-up orchestration includes designating to a Sabre ticket printer and/or check with your agency’s Sabre SME to ensure that ticket numbers have been assigned

to your PCC.

49901 Invalid PNR RS with missing fields

No PNR in AAA There is something wrong with the internal orchestration between the PNR service and EMD Exchange service

on the Sabre side.

Retry request. If the problem persists, contact the Sabre API

Support desk.

ExchangeEmdRQ Secondary Errors

41002 Connect to server timed

out

I/O error: Connect to server timed out;

nested exception

Internal server error.

Retry fulfillment request. If the problem persists, contact the Sabre API Support desk.

9500 AREX WS validation warning

PROCESSING ERROR DETECTED – RETRY – (ERC 9500)

Internal communication error between Sabre and airline.

Retry fulfillment request. If the problem persists, contact the Sabre API

Support desk.

17000-17011

various EMD module A step in Sabre’s internal EMD fulfillment process

has occurred.

Retry fulfillment request. If the problem persists, contact the Sabre API Support desk.

17012 Missing agreement

IetHub EMD module The carrier does not participate in EMD Exchange, or

When new airlines are activated for EMD Exchange, you will be



between

carriers

there is incorrect data in Sabre’s carrier agreement table.

notified via Sabre’s Agency eServices. If you feel you have received this error for a valid EMD Exchange participating airline, please contact the Sabre API Support

desk.

23001-23004

various EMD Offline File The background process to create a record of the EMD Exchange transaction for the agency settlement plan (ARC, BSP, etc.) has encountered a problem. If an EMD was issued, it might not be reconcilable with your settlement plan.


28000-

28001 various IetHub EMD module The process which

tokenizes and detokenizes credit card numbers has failed and the EMD transaction was not fulfilled.

Retry exchange fulfillment request. If the problem persists, contact the Sabre API Support desk.

28002-28007

Various IetHub EMD module One of the communication processes between Sabre and the carrier has an

issue.


30001-30010

Various EMD-BSO module One of the Sabre internal processes to update the Sabre PNR after the new EMD has been dispensed has encountered a problem.

Check the PNR in Sabre green screen or using the GetReservationRQ service to ensure all the crucial data from the EMD Exchange transaction is



present. If data is missing, VOID the EMD resulting from the exchange (within void period), and perform the exchange again. If the problem persists, contact the Sabre API Support desk.

140001-

140009 Various TKT DS EMD

Association

The routine that associates the EMD to the ETKT has encountered a problem.

Check the PNR in Sabre green screen or using the GetReservationRQ service to ensure the ETKT and EMD are correctly associated. If not, VOID the EMD (within void period) and perform the EMD exchange again. If the problem persists, contact the Sabre API Support desk.

TN GetTicketingDocument Glossary


5 Glossary

Term Definition

EMD Electronic Miscellaneous Document

AE Air Extra

Ancillary service A service decoupled from the price of the eTicket. In this Sabre PNR, an ancillary is shown as an Air Extra.

5

TN GetTicketingDocument Appendix


6 Appendix

6.1 Examples of EMD Exchange Calculation Summary Host

Responses

The Sabre green screen examples below were designed to provide the agent with a concise yet comprehensive view of the EMD exchange transaction, before processing it.

Notice that the agent can see and advise the customer of the cost of the transaction, or the residual amount that will be forfeited, the name of the passenger on the EMD being exchanged, the EMD number, the remaining value of the EMD, details of the Air Extra (ancillary) item that will be fulfilled with the exchange transaction, the fee/tax/total of the Air Extra item, the description of the Air Extra item, and the current status of the Air Extra item – all before committing to the issuance of a new EMD.

6.1.1 Even Exchange Example

In this example, the agent is comparing the value of EMD 0574575721714 (45.00) against the cost of Air Extra 2 (45.00). If the agent proceeds with fulfillment, there is no additional collection, and no

value from the old EMD is lost/forfeited.

EMD EXCHANGE CALCULATION SUMMARY

TOTAL EXCHANGE COST: USD0.00

NAME: DOE/JOHH MR

EXCHANGE EMD: 0574575721714

TOTAL EMD VALUE: USD45.00 value of old EMD

CPN A/L BRDOFF AIR EXTRA STAT

1 AF LHRCDG ADDITIONAL LUGGAGE OPEN

TOTAL NEW EMD COST: USD

FEE 45.00

TTL TAX 0.00

TOTAL 45.00 cost of new EMD

AIR EXTRAS FOR NEW EMD

2. 2ND ADDITIONAL BAG

STATUS - HD1/PAYMENT REQUIRED

AMOUNT - 45.00USD

TOTAL - 45.00USD

.

6



6.1.2 Additional Collection Example

In this example, the agent is comparing the value of EMD 0574575721715 (25.00) against the cost of Air Extra 2 (45.00). If the agent proceeds with fulfillment, there is an additional collection of 20.00 required.



NAME: DOE/JOHH MR




1 AF LHRCDG 1ST ADDITIONAL BAG OPEN


FEE 45.00

TTL TAX 0.00



2. 2ND ADDITIONAL BAG

STATUS - HD1/PAYMENT REQUIRED

AMOUNT - 45.00USD

TOTAL - 45.00USD

.



Even Exchange with Loss of Residual Amount

In this example, the agent is comparing the value of EMD 0574575721714 (45.00) against the cost of Air Extra 2 (25.00). If the agent proceeds with fulfillment, there is no additional collection, BUT 20.00 of value from the old EMD IS lost/forfeited.



RESIDUAL AMOUNT FORFEITED: USD20.00

NAME: DOE/JOHH MR




1 AF LHRCDG ADDITIONAL LUGGAGE OPEN


FEE 25.00

TTL TAX 0.00



1. 1ST ADDITIONAL BAG ‡

MD«

STATUS - HD1/PAYMENT REQUIRED ‡

AMOUNT - 25.00USD

TOTAL - 25.00USD

.

EMD Exchange API User Guide - Sabre · The EMD Exchange API is a new solution available to Sabre...

Documents

Transcript of EMD Exchange API User Guide - Sabre · The EMD Exchange API is a new solution available to Sabre...