API Messages with Examples

There are two versions of our API, both using the IATA 17.2 standard.

  • V1 is based on Fare Families, an old concept used by our web whereby fares a grouped together in “Families” based on common criteria, such as changeability, refundability, etc….

  • V2 is based on Branded Fares, an industry standard way for airlines to clearly identify the Features and Attributes of different fare products.

We recommend that V2 is used from now on. We will continue to support V1 with bug fixes and new functionality when and where possible.

Please note that some functionalities and come message elements will only be released in V2. For example the BaggageAllowanceList, PenaltyList , together with various parts of the FareComponent are only included in V2.

The differences between V1 and V2 are highlighted in the tables that explain the message elements, and are identified as per the following legend:

 New or modified element

To be removed/deprecated

Unique to v2 - Branded Fares

Unique to V1 - Fare Families

Both versions include Fare/Product information in the PriceClassList section of the AirShoppingRS and OfferPriceRS messages.

The big difference is that the V1 information is free text maintained in an external database, whereas the V2 information is loaded in the Fares Distribution System (ATPCo) and is standard. This is clearly seen in the following examples:

 

V1 Fare Families

V2 Branded Fares

V1 Fare Families

V2 Branded Fares

<PriceClassList> <PriceClass PriceClassID="BFLROES"> <Name>Business Flexible</Name> <Code>BFLROES</Code> <Descriptions> <Description ObjectKey="CABINABUSINESSFLEXIBLE"> <Text>Cabina: Business</Text> </Description> <Description ObjectKey="EQMANOBUSINESSFLEXIBLE"> <Text>Equipaje de mano: 1 bulto (56x40x25cm)</Text> </Description> <Description ObjectKey="EQBODEGABUSINESSFLEXIBLE"> <Text>Equipaje en bodega: 2 piezas</Text> </Description> <Description ObjectKey="COMIDABUSINESSFLEXIBLE"> <Text>Comida: Incluido</Text> </Description> <Description ObjectKey="ASIENTOBUSINESSFLEXIBLE"> <Text>Selección de asiento: Incluido</Text> </Description> <Description ObjectKey="ASIENTODELANTEROBUSINESSFLEXIBLE"> <Text>Asiento delantero: No aplica</Text> </Description> <Description ObjectKey="ASIENTOPREFERENTEBUSINESSFLEXIBLE"> <Text>Asiento preferente: Incluido</Text> </Description> <Description ObjectKey="ASIENTOXLBUSINESSFLEXIBLE"> <Text>Asiento espacio extra: No aplica</Text> </Description> <Description ObjectKey="EMBARQUEBUSINESSFLEXIBLE"> <Text>Prioridad de Embarque: Sí, grupo 1</Text> </Description> <Description ObjectKey="CAMBIOBUSINESSFLEXIBLE"> <Text>Cambios: Permitido sin coste, salvo excepciones.</Text> </Description> <Description ObjectKey="REEMBOLSOBUSINESSFLEXIBLE"> <Text>Reembolso (por sentido): Permitido sin penalización, excepto en caso de no presentarse al vuelo (no show), que no tendrá reembolso</Text> </Description> <Description ObjectKey="CHECKINDESKBUSINESSFLEXIBLE"> <Text>Mostrador check-in exclusivo: Sí</Text> </Description> <Description ObjectKey="SALAVIPBUSINESSFLEXIBLE"> <Text>Acceso a salas VIP: Si</Text> </Description> <Description ObjectKey="FASTTRACKBUSINESSFLEXIBLE"> <Text>Fast Track: Sí</Text> </Description> <Description ObjectKey="EQPPRIORBUSINESSFLEXIBLE"> <Text>Entrega prioritaria equipaje: Si</Text> </Description> <Description ObjectKey="AVIOBUSINESSFLEXIBLE"> <Text>AVIOS: Si</Text> </Description> <Description ObjectKey="WIFIBUSINESSFLEXIBLE"> <Text>WiFi: De pago</Text> </Description> </Descriptions> <ClassOfService refs="IB385220240107MADACE IDNOY2"> <Code SeatsLeft="7">I</Code> <MarketingName>BUSINESS</MarketingName> </ClassOfService> <ClassOfService refs="IB385420240107MADACE IDNOY2"> <Code SeatsLeft="4">I</Code> <MarketingName>BUSINESS</MarketingName> </ClassOfService> <ClassOfService refs="IB385820240107MADACE RDNOY2"> <Code SeatsLeft="4">R</Code> <MarketingName>BUSINESS</MarketingName> </ClassOfService> </PriceClass>
<PriceClassList> <PriceClass PriceClassID="BASICHTiqZA4er2V"> <Name>BASIC</Name> <Code>BASIC</Code> <Descriptions> <Description ObjectKey="CFFIB210EG210EGBASIC050"> <Text>BF/SE/050/BS//STANDARD SEAT SELECTION/CHARGE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASICIB5"> <Text>BF/SE/IB5///XL SEAT SELECTION/CHARGE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC05Z"> <Text>BF/SE/05Z/Premium//EMERGENCY SEAT SELECTION/CHARGE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASICIB3"> <Text>BF/SE/IB3///FRONT SEAT SELECTION/CHARGE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASICIB4"> <Text>BF/SE/IB4///STD SEAT SEL 24H BEFORE DEPART/CHARGE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC0B3"> <Text>ML//0B3///MEAL/DISPLAYED-BUT-NOT-OFFERED</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASICIC3"> <Text>ML//IC3///SNACK OR DRINK/CHARGE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC0BX"> <Text>LG//0BX///LOUNGE ACCESS/DISPLAYED-BUT-NOT-OFFERED</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC0LW"> <Text>TS/SY/0LW/Priority//PRIORITY SECURITY/DISPLAYED-BUT-NOT-OFFERED</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC0LF"> <Text>TS/PY/0LF///PRIORITY BAGGAGE/DISPLAYED-BUT-NOT-OFFERED</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC0G6"> <Text>TS/PR/0G6///PRIORITY BOARDING GROUP 1/DISPLAYED-BUT-NOT-OFFERED</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASICIC2"> <Text>TS/PR/IC2///PRIORITY BOARDING GROUP 2/DISPLAYED-BUT-NOT-OFFERED</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC03P"> <Text>TS/PO/03P///PRIORITY CHECK IN/DISPLAYED-BUT-NOT-OFFERED</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASIC09A"> <Text>TS/DE/09A/WW/LV/WIFI CONNECTION/CHARGE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASICIB0"> <Text>BF//IB0///AVIOS/FREE</Text> </Description> <Description ObjectKey="CFFIB210EG210EGBASICIB1"> <Text>BF//IB1///AVIOS ELITE/FREE</Text> </Description> </Descriptions> <ClassOfService refs="IB053020230829MADVGO AAUOB5"> <Code SeatsLeft="9">A</Code> <MarketingName CabinDesignator="5">Economy</MarketingName> </ClassOfService> <ClassOfService refs="IB891420230829MADVGO ADNOB4"> <Code SeatsLeft="2">A</Code> <MarketingName CabinDesignator="5">Economy</MarketingName> </ClassOfService> <ClassOfService refs="IB053820230829MADVGO ADNOB4"> <Code SeatsLeft="9">A</Code> <MarketingName CabinDesignator="5">Economy</MarketingName> </ClassOfService> <ClassOfService refs="IB053220230829MADVGO ODNOB4"> <Code SeatsLeft="5">O</Code> <MarketingName CabinDesignator="5">Economy</MarketingName> </ClassOfService> </PriceClass>

What are Branded Fares

Branded Fares are an industry standard way for airlines to clearly identify the Features and Attributes available as part of a fare product, some of which may be included in the price, and others that may be purchasable for an additional fee. It is also an industry wide solution, that allows Fares/Brands with similar features and attributes to be grouped together for comparison.

This allows us to promote Features and Attributes that differentiate one fare product from another, and gives travellers the opportunity to select the product that best fits their preferences and the purpose of their journey.

We use the the ATPCo Optional Services Industry Sub Codes, together with Iberia specific ones, to be able to offer products in a more structured and informative way.

This list of Attributes is dynamic and can and will change and grow over time, and includes things such as:

  • PREMIUM SEAT

  • BASIC SEAT

  • PRIORITY BOARDING

  • PRIORITY SECURITY

  • PRIORITY CHECK IN

Elements and how to use them

The Branded Fares Fields that we return group each Brand/Product by a PriceClassID, this information is returned in the PriceClassList, and which represents the following elements: 

  • ObjectKey - unique reference for internal Iberia use.

  • programCode - The owner airline CFF** (** = airline owner)

  • programText

The following two elements identify the Branded Fare/Product

  • brandText: The commercial name of the product (ie BUSINESS FLEXIBLE, or Basic, etc…) to be displayed to the customer.

  • brandCode: The code associated to the brandText - (BUSFLEX) - used to identify the product

The following are used to identify and group together the various Features and Attributes of the Product:

  • attributeGroup - The top level of grouping, such as Baggage, Meals, Frequent Flyer, In-flight Entertainment, etc., that uses the ATPCo Optional Services Industry Sub Codes “Group”.

  • attributeSubGroup - The second level of grouping, to group attributes within an attributeGroup, such as Sporting Equipment or Speciality Items within Baggage, using the ATPCo Optional Services Industry Sub Codes “Sub Group”.

  • Subcode - This is the industry, or airline specific, “Sub Code” used to identify each individual attribute (such as specific seat type, first bag, first bag at 15kg, etc) and may be taken from the ATPCo Optional Services Industry Sub Codes.

  • Description1 - description of subcode if applicable, to be displayed to the customer.

  • Description2 - additional description of subcode if applicable, to be displayed to the customer.

  • ComercialName - This is applicable to the Subcode if it has a specific name/identity, and should be displayed to the customer.

  • tierApplication - Describes whether the attribute is:

    • Free

    • Chargeable

    • Displayed but not offered (such as priority bags delivery on all fares except business) (can be used to compare products)

    • Not offered attribute that is not applicable to product, (ie. seating is not offered of products that include seats at sale).

Example 1:

<Description ObjectKey="CFFIB210210COMFORT0LF"> <Text>TS/PY/0LF///PRIORITY BAGGAGE/DISPLAYED-BUT-NOT-OFFERED</Text> </Description>

The above example is for:

TS - is the attributeGroup, which as per the ATPCo Optional Services Industry Sub Codes is “Travel Services”

PY - is the attributeSubGroup, which as per the ATPCo Optional Services Industry Sub Codes is “Priority Baggage”

0LF - is the RFISC (Reason for Issuance Sub Code) used to identify the individual attribute. If the service required the issue of an EMD this would be used for its issue.

Both Description1 and Description2 are empty

PRIORITY BAGGAG - is the ComercialName as per the ATPCo Optional Services Industry Sub Codes

DISPLAYED-BUT-NOT-OFFERED - is the tierApplication. In this case the feature could be diplayed greyed out as it is not offered with this product.

Example 2:

The above example is for:

ML - is the attributeGroup, which as per the ATPCo Optional Services Industry Sub Codes is “Meal”

There is no attributeSubGroup for this feature.

IC3- is the RFISC (Reason for Issuance Sub Code) used to identify the individual attribute. If the service required the issue of an EMD this would be used for its issue. In this case the RFISC is specific to Iberia.

Both Description1 and Description2 are empty in this example.

SNACK OR DRINK - is the ComercialName given by Iberia to this feature.

CHARGE - is the tierApplication. In this case the feature is purchasable for a fee. As the service is not in our ServiceList API this is only purchasable at place of delivery.

 

In the following pages you have all the messages with the functionality our API supports with the message structure.

There are many examples with full end to end message flows that will help you. Messages for the same Order must be processed sequentially, the next message should not be sent until after receipt of the response to the previous message.

3-D Secure payment is being mandated in many markets and is ONLY supported in our 17.2 version using an augmentation point.