DIGITAL SERVICES. API Documentation Product Pricing

Size: px

Start display at page:

Download "DIGITAL SERVICES. API Documentation Product Pricing"

Phillip Carpenter
6 years ago
Views:

1 DIGITAL SERVICES API Documentation Product Pricing Document Version Reason for change Author Signed-off by Status 0.10 Creation Gary Inkpen Final Draft 2016 Avios Group (AGL) Limited. All rights reserved. 1 Version 0.10

2 Contents 1. Overview Avios API Overview Product Pricing Overview Introduction Business context Technical context Important Technical Notes Pre-conditions Post-conditions Service details URI Parameters Request Headers Request Message Definition Request Message Diagram Product Pricing Request Product Segment Schedule Request Elements Response Message Definition Response Message Diagram Product Pricing Response Price Segment Schedule Response Elements Exception Message Definition Exception Message Diagram Product Pricing Error Exception Message Elements Error codes...27 Appendix A: Example of a Request Call...28 Appendix B: Example of a Response...30 Appendix C: Example of an Error Response...32 Glossary of Terms Avios Group (AGL) Limited. All rights reserved. 2 Version 0.10

3 1. Overview Avios API Overview This document is a specification of the Product Pricing API. An overview of this API is provided below in 1.2 and an overview of the entire Avios API service, including a general description that is relevant to all APIs, is contained in a separate document entitled API Overview. This overview is stored within the project s Reference Library. Any text that is shown italicised and underlined in the body of an API document refers to an entry in the Reference Library. The contents of the library are summarised in the following table: Title Description Location/Link API Overview This general description is relevant to all APIs. Reference Library 1.2 Product Pricing Overview The Product Pricing service is also known as Dynamic Pricing. The Pay with Avios Dynamic Discount Pricing Service allows Partners to setup discount prices which are dynamic in nature. The discount can be based on Route, Carrier, Date of travel, Fare and Currency. For a given fare, this service will return the discount points which are setup in the system (based on the input parameters). Discount pricing points are checked for validity to ensure that they do not exceed a threshold limit. If there are no discount pricing points, the default pricing points will be returned by the service. Discount pricing points contain two values: Cash discounted value. AVIOS points value, which will be redeemed for the cash discount Avios Group (AGL) Limited. All rights reserved. 3 Version 0.10

4 1.2.1 Introduction Business context The process is illustrated in the following swim-lanes diagram: The process flow is described as follows: The member undertakes a product purchase journey. As part of this journey, the member will need to view the pricing points of the product selected. An application within the partner channel will determine the flight journey that is of interest to the member. These details are passed to the Product Pricing service. This service obtains the relevant pricing points, as follows: a) If possible, pricing points are determined by using the details supplied in the request message (these are determined using the Avios database). b) If no pricing points are available then a default discount price is returned in the response message. The resulting pricing information is returned in the response message Avios Group (AGL) Limited. All rights reserved. 4 Version 0.10

5 Technical context The Product Pricing service does not depend upon member information being supplied. It can be called at any stage either before or after member registration. The following steps are performed by the Product Pricing application: Analyse details of the pricing request. Identify applicable pricing points for the specified itinerary. If no pricing points exist for the route, then default price points are returned. An overview of the entire Avios API journey is shown in the following diagram. This positions the Product Pricing API within the overall application: THE AVIOS API JOURNEY FORGOTTEN DETAILS JOIN PROGRAMME REGISTER ACCOUNT CREATE TOKEN RETRIEVE TRANSACTIONS Note 1: For ticket pricing in isolation, it is not necessary to have previously invoked the Create Token service. Note 2: It is possible to use the Product Pricing service without a member having activated an account (ie: prior to invoking the Join Programme and Register Account services). PRODUCT PRICING RETRIEVE MEMBER UPDATE MEMBER To debit a currency the Create Token, Product Pricing & Retrieve Member services must all have previously been invoked. DEBIT CURRENCY REVERSE TRANSACTION Important Technical Notes It is not necessary for the member to have logged-in in order to use the Product Pricing service. All enumerated values must be recorded in upper case ASCII characters. Response messages will be returned in upper case Avios Group (AGL) Limited. All rights reserved. 5 Version 0.10

6 1.2.2 Pre-conditions A product price must be supplied in the request message Post-conditions Success outcome: One or more product pricing points are returned in the API response message. Error outcome: Service error is returned. Refer to Section 5 for a list of service errors Avios Group (AGL) Limited. All rights reserved. 6 Version 0.10

7 2. Service details Version v1.0 Type Http method Endpoint REST POST Test environment: host = api.avios.com version = test/v1 programme-identifier = ATRP Request format Response format XML, JSON XML, JSON 2016 Avios Group (AGL) Limited. All rights reserved. 7 Version 0.10

8 2.1 URI Parameters Name Required Data type Format Description Example programme-identifier Mandatory String Min length = 1. Max Length = 20. Alphabetic only. The identifier for the loyalty programme to which the member belongs. This will have been provided to the member as part of the Avios API partner on-boarding process along with your API key and Mashery credentials. Avios, BAEC 2.2 Request Headers Name Required Data type Format Description Example accept Mandatory String application/<content-type> The Accept request-header field is used to specify certain media types which are acceptable for the response. Application/XML, Application/JSON content-type Mandatory String application/<content-type> The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Application/XML, Application/JSON 2016 Avios Group (AGL) Limited. All rights reserved. 8 Version 0.10

13 3.2 Request Elements The elements that make up the request message are detailed in the following table. The following rules apply to request elements: Default values are not assigned to elements that have not been supplied within a request message. All enumerated values must be recorded in upper case ASCII characters. Response messages will be returned in upper case. Appendix A shows an example of a Product Pricing API request call, expressed in JSON format. Name Required Data type Format Description pricesearchcriteria Mandatory Complex pricesearchcriteria/pricetype Mandatory String Enumeration Type of price. Specifies the price option. Must be DISCOUNT. pricesearchcriteria/pricesource Mandatory String Enumeration Source of price. Must be CACHED. pricesearchcriteria/product Mandatory Complex type [1..n] pricesearchcriteria/product/flight Mandatory Complex type [1..n] pricesearchcriteria/product/flight/price Mandatory Complex pricesearchcriteria/product/flight/price/monetaryamount Mandatory Complex Product is the generalised element for which different price options are required. This element further analyses the product. In this case, the element describes a flight. The price of the flight for a particular schedule. The flight s price details. pricesearchcriteria/product/flight/price/monetaryamount/amount Mandatory Big Decimal Numeric The price of the flight. Eg: 45 pricesearchcriteria/product/flight/price/monetaryamount/currency Mandatory Complex The units in which the price is presented Avios Group (AGL) Limited. All rights reserved. 13 Version 0.10

14 Name Required Data type Format Description pricesearchcriteria/product/flight/price/monetaryamount/currency/ code Mandatory String Enumeration The currency code in which the price is denominated. This must be one of following USD GBP CAD EUR pricesearchcriteria/product/flight/price/priceoptiontype Mandatory String Enumeration Specifies the price option. Must be DISCOUNT. pricesearchcriteria/product/flight/segment Mandatory Complex type [1..n] pricesearchcriteria/product/flight/segment/leg Mandatory Complex type [1..n] pricesearchcriteria/product/flight/segment/leg/schedule Mandatory Complex pricesearchcriteria/product/flight/segment/leg/ schedule/arrivaldaterange Mandatory Complex Flight Segment. This describes the flight schedule and the related operational details. One point-to-point journey in a flight segment. This element describes the route of a leg within the segment of a flight. The flight schedule identifies the arrival date, arrival location, departure date and departure location. The arrival date range. pricesearchcriteria/product/flight/segment/leg/ schedule/arrivaldaterange/ startdatetime Mandatory Date ISO-8601 Calendar date format. YYYY-MM- DDThh:mm:ss.sTZD Start date and time of inbound journey. Eg: T13:39: :00 pricesearchcriteria/product/flight/segment/leg/schedule/arrivaldaterange/ enddatetime Mandatory Date ISO-8601 Calendar date format. YYYY-MM- DDThh:mm:ss.sTZD End date and time of inbound journey. Eg: T13:39: :00 pricesearchcriteria/product/flight/segment/leg/ schedule/departuredaterange Mandatory Complex The departure date range Avios Group (AGL) Limited. All rights reserved. 14 Version 0.10

15 Name Required Data type Format Description pricesearchcriteria/product/flight/segment/leg/ schedule/departuredaterange/ startdatetime Mandatory Date ISO-8601 Calendar date format. YYYY-MM- DDThh:mm:ss.sTZD Start date and time of outbound journey. Eg: T13:39: :00 pricesearchcriteria/product/flight/segment/leg/ schedule/departuredaterange/ enddatetime Mandatory Date ISO-8601 Calendar date format. YYYY-MM- DDThh:mm:ss.sTZD End date and time of outbound journey. Eg: T13:39: :00 pricesearchcriteria/product/flight/segment/leg/ schedule/arrivallocation Mandatory Complex pricesearchcriteria/product/flight/segment/leg/ schedule/arrivallocation/id Mandatory String Alphabetic. Maximum of 3 characters. Inbound location of a particular leg for this route. The IATA 3 letter code that identifies the arrival location. Eg: JFK pricesearchcriteria/product/flight/segment/leg/ schedule/arrivallocation/type Mandatory String Enumeration Type of arrival location. Must be AIRPORT. pricesearchcriteria/product/flight/segment/leg/ schedule/departurelocation Mandatory Complex pricesearchcriteria/product/flight/segment/leg/ schedule/departurelocation/id Mandatory String Alphabetic. Maximum of 3 characters. Outbound location of a particular leg for this route. The IATA 3 letter code that identifies the arrival location. Eg: LHR pricesearchcriteria/product/flight/segment/leg/ schedule/departurelocation/ type Mandatory String Enumeration Type of departure location. Must be AIRPORT. pricesearchcriteria/product/flight/segment/leg/ marketingcarrier Mandatory Complex pricesearchcriteria/product/flight/segment/leg/ marketingcarrier/iatacode Mandatory Complex The marketing carrier of the flight. The flight s IATA code Avios Group (AGL) Limited. All rights reserved. 15 Version 0.10

16 Name Required Data type Format Description pricesearchcriteria/product/flight/segment/leg/ marketingcarrier/iatacode/ code Mandatory String Alphabetic. Maximum of 2 characters. The flight s IATA code value. Eg: EI pricesearchcriteria/product/flight/segment/leg/ operatingcarrier/ Mandatory Complex pricesearchcriteria/product/flight/segment/leg/ operatingcarrier/iatacode Mandatory Complex The name of the carrier operating the flight. The flight s IATA code. This element is essential for the identification of an airline pricesearchcriteria/product/flight/segment/leg/ operatingcarrier/iatacode / code Mandatory String Alphabetic. Maximum of 2 characters. The flight s IATA code value. Eg: EI 2016 Avios Group (AGL) Limited. All rights reserved. 16 Version 0.10

1.2 Price 2016 Avios Group (AGL) Limited.

20 4.2 Response Elements The elements that make up the request message are detailed in the following table. Response elements will always be returned in upper case ASCII characters. Appendix B shows an example of a Product Pricing API response message, expressed in JSON format. Name Presence? Data type Format Description product Yes Complex type [1..n] Product is the generalised element for which different price options are required. product/flight Yes Complex type [1..n] product/flight/segment Yes Complex product/flight/segment/leg/ Yes Complex product/flight/segment/leg/schedule Yes Complex product/flight/segment/leg/schedule/arrivaldaterange Yes Complex product/flight/segment/leg/schedule/arrivaldaterange startdatetime Yes Date ISO-8601 Calendar date format. This element further analyses the product. In this case, the element describes a flight. Flight Segment. This describes the flight schedule and the related operational details. One point-to-point journey in a flight segment. This element describes the route of a leg within the segment of a flight. The flight schedule identifies the arrival date, arrival location, departure date and departure location. The arrival date range. Start date and time of inbound journey. Eg: T12:39:16.213Z YYYY-MM- DDThh:mm:ss.s TZD 2016 Avios Group (AGL) Limited. All rights reserved. 20 Version 0.10

21 Name Presence? Data type Format Description product/flight/segment/leg/schedule/arrivaldaterange enddatetime Yes Date ISO-8601 Calendar date format. YYYY-MM- DDThh:mm:ss.s TZD End date and time of inbound journey. Eg: T12:39:16.213Z product/flight/segment/leg/schedule/departuredaterange Yes Complex product/flight/segment/leg/schedule/departuredaterange/startdatetime Yes Date ISO-8601 Calendar date format. The departure date range. Start date and time of outbound journey. Eg: T12:39:16.213Z YYYY-MM- DDThh:mm:ss.s TZD product/flight/segment/leg/schedule/departuredaterange/enddatetime Yes Date ISO-8601 Calendar date format. End date and time of outbound journey. Eg: T12:39:16.213Z YYYY-MM- DDThh:mm:ss.s TZD product/flight/segment/leg/schedule/arrivallocation Yes Complex product/flight/segment/leg/schedule/arrivallocation/id Yes String Alphabetic. Maximum of 3 characters. Inbound location of a particular leg for this route. Eg: LHR The IATA 3 letter code that identifies the arrival location. Eg: JFK product/flight/segment/leg/schedule/arrivallocation/type Yes String Enumeration Type of arrival location. Must be AIRPORT Avios Group (AGL) Limited. All rights reserved. 21 Version 0.10

22 Name Presence? Data type Format Description product/flight/segment/leg/schedule/departurellocation Yes Complex Outbound location of a particular leg for this route. product/flight/segment/leg/schedule/departurellocation/id Yes String Alphabetic. Maximum of 3 characters. The IATA 3 letter code that identifies the arrival location. Eg: LHR product/flight/segment/leg/schedule/departurellocation/type Yes String Enumeration Type of departure location. Must be AIRPORT. product/flight/segment/leg/marketingcarrier Yes Complex product/flight/segment/leg/marketingcarrier/iatacode Yes Complex product/flight/segment/leg/marketingcarrier/iatacode/code Yes String Alphabetic. product/flight/segment/leg/operatingcarrier Yes Complex product/flight/segment/leg/operatingcarrier/iatacode Yes Complex Maximum of 2 characters. product/flight/segment/leg/operatingcarrier/iatacode/code Yes String Alphabetic. Maximum of 2 characters. The marketing carrier of the flight. The flight s IATA code. The flight s IATA code value. Eg: EI The name of the carrier operating the flight. The flight s IATA code. This element is essential for the identification of an airline The flight s IATA code value. Eg: EI 2016 Avios Group (AGL) Limited. All rights reserved. 22 Version 0.10

23 Name Presence? Data type Format Description product/flight/segment/pricescheme Yes String Enumeration Valid scheme for the flight s inbound and outbound dates. This element identifies if the given route at the particular travel time is a peak or off peak. Most likely, default prices will be returned if the price scheme for the given route is NOT_KNOWN. Will be one of the following: PEAK OFF-PEAK NOT_KNOWN product/flight/price Yes Complex product/flight/price/monetaryamount Yes Complex The flight s price. The flight s price details. product/flight/price/monetaryamount/amount Yes Big Decimal Numeric The price of the flight. This will either contain the cash discounted price or the AVIOS value of the cash discount. Eg: 1500/45 product/flight/price/monetaryamount/currency Yes Complex Currency is the complex type for a specific unit of currency. product/flight/price/monetaryamount/currency/code Yes String Enumeration Currency of the respective flight s price amount. This will be one of the following: USD GBP CAD EUR AVIOS product/flight/price/sequencenumber Yes Integer Numeric Sequence number of the price option. Eg: 1 product/flight/price /priceoptiontype Yes String Enumeration Specifies the price option. Will be PART_AVIOS_PART_CASH Avios Group (AGL) Limited. All rights reserved. 23 Version 0.10

25 5.2 Exception Message Elements The exception message responses may be formatted in either upper or lower case. An example of an error response is shown in Appendix C. Name Presence? Data type Format Description error/ Conditional Complex Type [0..1] Will only be present if an error has been detected and reported by the API. error/code Yes String Alphabetic plus underscore (_). Error code. Eg: REQUEST_INVALID error/businessmessage Yes String Alphabetic Error message to business. Eg: Request Invalid error/developermessage Yes String Alphabetic Error message specific to client developer. error/developerlink Yes String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). error/childerror/ Conditional Array of complex type [0..n] error/childerror/code Yes String Alphabetic plus underscore (_). A URL link to a web page containing more detailed information about the error code. Eg: Will only be present if an error has been detected and reported by the API. Error code. Eg: INVALID_PRICE_AMOUNT 2016 Avios Group (AGL) Limited. All rights reserved. 25 Version 0.10

26 Name Presence? Data type Format Description error/childerror/path Yes String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Path of the node on which error occurred. Eg: retrieveproductpricingrequest.pricesearchcriteria.product.flight.price.monetaryamount.amount error/childerror/businessmessage Yes String Alphabetic Error message to business. Eg: Invalid price amount. error/childerror/developermessage Yes String Alphabetic Error message specific to client developer. error/childerror/developerlink Yes String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code. Eg: Avios Group (AGL) Limited. All rights reserved. 26 Version 0.10

27 5.3 - Error codes All the errors from the service are returned in <Parent error code> <Child error code> format. The table below shows a full list of error codes. Parent error code Child error code Description REQUEST_INVALID MARSHALLING_FAILED Invalid enumeration in request or request not properly formed. REQUEST_INVALID DATA_FAILED Request payload failed schema validation. REQUEST_INVALID ARRIVAL_LOCATION_ID_INVALID Arrival location id is not in required format. REQUEST_INVALID ARRIVAL_LOCATION_ID_MISSING Arrival location id is empty string. REQUEST_INVALID DEPARTURE_LOCATION_ID_INVALID Departure location id is not in required format. REQUEST_INVALID DEPARTURE_LOCATION_ID_MISSING Departure location id is empty string. REQUEST_INVALID INVALID_PRICE_AMOUNT Flight price is negative or zero. REQUEST_INVALID INVALID_CURRENCY Currency code in request is not valid. REQUEST_INVALID INVALID_DEPARTURE_START_DATE Should have valid value and should be a FUTURE date when compared to SYSDATE. REQUEST_INVALID ARRIVAL_DATE_EARLIER_THAN_DEPARTURE_DATE Departure date should be earlier than arrival date. REQUEST_INVALID INVALID_OPERATING_CARRIER_CODE IATA code in operating carrier is invalid. REQUEST_INVALID INVALID_MARKETING_CARRIER_CODE IATA code in marketing carrier is invalid. SYSTEM_UNAVAILABLE When a system is not available. See Appendix C for an example of an API error response message Avios Group (AGL) Limited. All rights reserved. 27 Version 0.10

28 Appendix A: Example of a Request Call The following is an example of a request call to the Product Pricing API: { "pricesearchcriteria":{ "pricesource":"cached", "pricetype":"discount", "product":[{ "flight":{ "price":[{ "monetaryamount":[{ "amount":"45", "currency":{ "code":"usd" } }], "priceoptiontype":"discount" }], "segment":[{ "leg":[{ "schedule":{ "arrivaldaterange":{ "startdatetime":" t13:39: :00", "enddatetime":" t13:39: :00" }, "departuredaterange":{ "startdatetime":" t13:39: :00", "enddatetime":" t13:39: :00" }, "arrivallocation":{ "id":"jfk", "type":"airport" }, "departurelocation":{ "id":"lhr", "type":"airport" } }, "marketingcarrier":{ "iatacode":{ "code":"ei" } }, "operatingcarrier":{ "iatacode":{ "code":"ei" } } }] }] 2016 Avios Group (AGL) Limited. All rights reserved. 28 Version 0.10

30 Appendix B: Example of a Response The following is an example of a response generated by the Product Pricing API: { "product": [{ "flight": { "segment": [{ "numberofconnections": 0, "leg": [{ "schedule": { "arrivaldaterange": { "startdatetime": " T12:39:16.213Z", "enddatetime": " T12:39:16.213Z" }, "departuredaterange": { "startdatetime": " T12:39:16.213Z", "enddatetime": " T12:39:16.213Z" }, "arrivallocation": { "id": "JFK", "type": "AIRPORT" }, "departurelocation": { "id": "LHR", "type": "AIRPORT" } }, "marketingcarrier": { "iatacode": { "code": "EI" } }, "operatingcarrier": { "iatacode": { "code": "EI" } } }], "pricescheme": "PEAK" }], "price": [{ "monetaryamount": [{ "amount": "1500", "currency": { "code": "AVIOS" } }, { "amount": "36.75", "currency": { "code": "USD" 2016 Avios Group (AGL) Limited. All rights reserved. 30 Version 0.10

32 Appendix C: Example of an Error Response The following shows an example of an error response generated by the Product Pricing API: { "error": { "code": "REQUEST_INVALID", "businessmessage": "Request Invalid", "developerlink": " "childerror": [ { "code": "INVALID_PRICE_AMOUNT", "path": "retrieveproductpricingrequest.pricesearchcriteria.product.flight.price.monetaryamount.amount", "businessmessage": "Invalid Price Amount", "developerlink": " } ] } } 2016 Avios Group (AGL) Limited. All rights reserved. 32 Version 0.10

33 Glossary of Terms Acronym API APID ATRP Avios BAEC ISO JSON Mashery on-boarding SOAP URI and URL Description Application Program Interface: a set of routines, protocols and tools for building software applications. The API specifies how software components should interact and APIs are used when programming graphical user interface (GUI) components. Avios Partner Identification Avios Travel Rewards Programme. The Avios reward programme. British Airways Executive Club. International Standards Organisation Java Script Object Notation: An open standard format that uses humanreadable text to transmit data objects consisting of attribute value pairs. It is the primary data format used for asynchronous browser/server communication (AJAJ), largely replacing XML (used by AJAX). A cloud hosted component of the API handling process. This function adds or modifies certain API parameters when a call is received and prior to processing by the called Avios application. The process of signing-up a partner commercially and getting them up to speed with Avios. Simple Object Access Protocol: a protocol specification for exchanging structured information in the implementation of web services in computer networks. It uses the XML Information Set for its message format, and relies on other application layer protocols, most notably Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission A Uniform Resource Locator (URL), commonly informally termed a web address is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. A URL is a specific type of Uniform Resource Identifier (URI) although many people use the two terms interchangeably. A URL implies the means to access an indicated resource, which is not true of every URI. URLs are most commonly used to reference web pages (http), but are also used for file transfer (ftp), (mailto), database access (JDBC) and many other applications Avios Group (AGL) Limited. All rights reserved. 33 Version 0.10

34 Acronym XML Description Extensible Markup Language: a mark-up language that defines a set of rules for encoding documents in a format which is both humanreadable and machine-readable. End of Document 2016 Avios Group (AGL) Limited. All rights reserved. 34 Version 0.10

DIGITAL SERVICES. API Documentation Retrieve Transactions

DIGITAL SERVICES. API Documentation Retrieve Transactions DIGITAL SERVICES API Documentation Retrieve Transactions Document Version Reason for change Author Signed-off by Status 0.12 Creation Gary Inkpen Final Draft 2016 Avios Group (AGL) Limited. All rights