openapi: 3.1.0
info:
  title: TAAP Push API
  description:  TAAP Push API allows partners to receive webhook events with core itinerary updates.
  version: v1

tags:
  - name: TAAP Push API

servers:
  - url: https://analytics.ean.com/taap/v1

webhooks:
  taapItineraryEvents:
    post:
      parameters:
        - $ref: '#/components/parameters/WebhookAuthorizationHeader'
      requestBody:
        description: Webhook event payload containing the itinerary data
        content:
          application/cloudevents+json:
            schema:
              $ref: "#/components/schemas/ItineraryReportingEvent"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
              example:
                status: "success"
                message: "Webhook event processed successfully"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
              example:
                status: "error"
                message: "Invalid payload"
        "401":
          description: Unauthorized
          headers:
            WWW-Authenticate:
              description: Provides an example of the Authorization header.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
              example:
                status: "error"
                message: "Unauthorized"

        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
              example:
                status: "error"
                message: "Internal Server Error"

        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
              example:
                status: "error"
                message: "Service Unavailable"

components:
  schemas:
    # Webhook payload and response schemas
    ItineraryReportingEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          example: "1.0"
        type:
          $ref: "#/components/schemas/EventType"
        source:
          type: string
          example: "https://analytics.ean.com/taap/v1"
        id:
          type: string
          format: uuid
          example: "d79d3925-0ca3-4344-bf5e-293373959698"
        time:
          type: string
          format: date-time
          example: "2024-05-17T23:00:00Z"
        datacontenttype:
          type: string
          example: "application/json"
        data:
          oneOf:
            - $ref: '#/components/schemas/Itinerary'

    EventType:
      type: string
      description: The type of event to subscribe/subscribed to.
      enum:
        - taap.itinerary.change


    WebhookResponse:
      type: object
      #      WebhookResponse is nullable because the response is not always guaranteed from partner
      description: Response object from partners for webhook event
      properties:
        status:
          type: string
          enum: [ "success", "error" ]
          description: Status of the webhook event
        message:
          type: string
          description: Message of the webhook event

    Itinerary:
      type: object
      properties:
        itinerary_id:
          type: "string"
          description: The itinerary id
          example: 12345678910111
        status:
          type: "string"
          enum: [ "Confirmed", "Cancelled" ]
          description: The status of the itinerary one of Confirmed/Cancelled.
          example: Confirmed
        update_date_time:
          type: "string"
          description: The last update date time for the itinerary in ISO-8601 date format (YYYY-MM-dd"T"HH:mm:ss.SSSZ).
          example: 2024-05-17T23:00:00Z
        creation_date:
          type: "string"
          description: The date when the itinerary was created/booked in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-05-16
        online:
          type: "boolean"
          description: Indicates whether the booking made was an online booking or an offline via a support agent.
        point_of_sale_country_code:
          type: "string"
          description: The country code for the point of sale from which customer made the booking
            in two-letter ISO 3166-1 alpha-2 format.
          example: US
        purchaser:
          $ref: "#/components/schemas/Purchaser"
        agency:
          $ref: "#/components/schemas/Agency"
        payment:
          $ref: "#/components/schemas/Payment"
        property_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/PropertyBookingItem"
        flight_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/FlightBookingItem"
        car_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/CarBookingItem"
        activity_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/ActivityBookingItem"
        insurance_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/InsuranceBookingItem"
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 100.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 20.5
        earnings:
          $ref: "#/components/schemas/Earnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 9.0
            service_charge:
              amount:
                billable_currency:
                  currency: USD
                  value: 12.5
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.0
    Purchaser:
      type: "object"
      properties:
        first_name:
          type: "string"
          description: The first name of the end purchaser of the itinerary, the traveler.
          example: John
        last_name:
          type: "string"
          description: The last name of the end purchaser of the itinerary, the traveler.
          example: Doe
        email:
          type: "string"
          description: The email address of the end customer of the itinerary, the traveler.
          example: john@doe.com
    Agency:
      type: "object"
      properties:
        id:
          type: "string"
          description: Unique identifier of the TAAP Agency.
          example: WS02555
        name:
          type: "string"
          description: The name of the TAAP Agency.
          example: Dorian Grey & Sons Travel
        agent:
          type: object
          properties:
            first_name:
              type: "string"
              description: The first name of the TAAP agent who placed the booking.
              example: Dorian
            last_name:
              type: "string"
              description: The last name of the TAAP agent who placed the booking.
              example: Grey
            email:
              type: "string"
              description: Email of the TAAP agent who placed the booking.
              example: dorian@dgstravel.com
    Payment:
      type: "object"
      properties:
        payment_type:
          type: "string"
          description: The payment type used for the booking.
          example: Credit Card
        status:
          type: "string"
          enum: [ "paid", "unpaid" ] # need to confirm these values, potentially can be a boolean flag instead
          description: The payment status of the booking one of paid/unpaid.
          example: unpaid
        deferred:
          type: "boolean"
          description: Indicates whether the payment was deferred or not.
          example: true
        payment_due_date:
          type: "string"
          description: The payment due date in ISO-8601 date format (YYYY-MM-dd). Only applicable for deferred payments.
          example: 2024-08-10
        payee:
          type: "string"
          description: The entity responsible for making the payment for the itinerary, which could be the customer or agent
          example: customer
    ItemEarnings:
      type: object
      properties:
        commission:
          $ref: "#/components/schemas/CommissionValue"
    Earnings:
      type: object
      properties:
        commission:
          $ref: "#/components/schemas/CommissionValue"
        service_charge:
          $ref: "#/components/schemas/ServiceCharge"

    ServiceCharge:
      type: object
      description: The service charge amount for the booking
      properties:
        amount:
          type: object
          properties:
            billable_currency:
              $ref: "#/components/schemas/BillableAmount"
              example:
                currency: USD
                value: 12.5
        taxes_and_fees:
          $ref: "#/components/schemas/TaxesAndFees"

    PropertyBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case a room.
          example: 1400882912
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
        checkin_date:
          type: "string"
          description: The checkin date at the property in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-02
        checkout_date:
          type: "string"
          description: The checkout date at the property in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-17
        property:
          $ref: "#/components/schemas/Property"
        room_name:
          type: "string"
          description: The room type booked e.g Double Room, Private Bathroom.
          example: Comfort Double Room, Private Bathroom
        adult_count:
          type: "number"
          description: Number of adults accounted for within the room.
          example: 1
        child_count:
          type: "number"
          description: Number of children accounted for within the room.
          example: 1
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        property_confirmation_id:
          type: "string"
          description: The confirmation id provided by the hotel or vacation rental company.
          example: 1516171819
        rate:
          $ref: "#/components/schemas/PropertyRate"
          example:
            refundable: true
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 50.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 5.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 5.0
    Property:
      type: object
      properties:
        id:
          type: "string"
          example: 123456
        chain_name:
          type: "string"
          description: Chains represent a parent company associated with the property.
          example: Independent
        brand_name:
          type: "string"
          description: Represents the brand associated with the chain, a chain can have multiple brands.
          example: Savoy Signature
        name:
          type: "string"
          description: Property name
          example: Hotel 1
        city:
          type: "string"
          description: The name of the city where the property is located.
          example: Toronto
        state_province_name:
          type: "string"
          description: The name of the state or province where the property is located.
          example: Ontario
        country_code:
          type: "string"
          description: The country code for the property location in two-letter ISO 3166-1 alpha-2 format.
          example: CA
        star_rating:
          type: "number"
          description: Star rating of the property
          example: 4
    PropertyRate:
      type: object
      properties:
        refundable:
          type: "boolean"
          description: Whether the booking is refundable or not. Only applicable for lodging items.
        pricing:
          $ref: "#/components/schemas/Pricing"
    Rate:
      type: object
      properties:
        pricing:
          $ref: "#/components/schemas/Pricing"

    FlightBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case a flight ticket.
          example: 1400882911
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
          example: Confirmed
        departure_date:
          type: "string"
          description: The departure date in ISO-8601 date format (YYYY-MM-dd).
          example: 2023-10-02
        arrival_date:
          type: "string"
          description: The arrival date in ISO-8601 date format (YYYY-MM-dd).
          example: 2023-10-02
        airline:
          $ref: "#/components/schemas/Airline"
        carrier_pnr:
          type: "string"
          description: Supplier provided Air Passenger Name Record(PNR)
          example: BCDEFG
        trip_type:
          type: "string"
          enum: ["One Way", "Round Trip", "Multiple Destinations"]
          description: The type of trip e.g `One Way`, `Round Trip`, `Multiple Destinations`
          example: One Way
        fare_class:
          type: "string"
          description: The fare class of the ticket e.g Economy, Business
          example: Business Class
        airport_origin_code:
          type: "string"
          description: The airport code for the origin airport in IATA format.
          example: LHR
        airport_destination_code:
          type: "string"
          description: The airport code for the destination airport in IATA format.
          example: YYZ
        airport_origin_location:
          type: "string"
          description: The location of the origin airport.
          example: London, GB (LHR-Heathrow)
        airport_destination_location:
          type: "string"
          description: The location of the destination airport.
          example: Toronto, ON (YYZ-Lester B. Pearson Intl.)
        ticket_number:
          type: "number"
          description: The ticket number for the flight ticket.
          example: 123456789101
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        segment_count:
          type: "number"
          description: The number of segments in the flight ticket.
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 25.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 2.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 2.0
    Airline:
      type: object
      properties:
        plating_carrier_name:
          type: "string"
          description: The plating carrier name for the airline ticket.
          example: Air Canada
        plating_carrier_code:
          type: "string"
          description: The plating carrier code for the airline ticket.
          example: AC

    CarBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case a car rental.
          example: 1400882910
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
        pickup_date:
          type: "string"
          description: The pickup date for the car rental in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-02
        return_date:
          type: "string"
          description: The return/drop-off date for the car rental in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-02
        rental_company:
          $ref: "#/components/schemas/RentalCompany"
        car_type:
          type: "string"
          description: The type of car rented e.g 2/4 Door_Compact, 4 Door_Sedan
          example: 2/4 Door_Compact
        pickup_location:
          type: "string"
          description: The pickup location for the car rental.
          example: Deer Lake, NL (YDF-Deer Lake Regional)
        pickup_country_code:
          type: "string"
          description: The country code for the pickup location in two-letter ISO 3166-1 alpha-2 format.
          example: CA
        return_location:
          type: "string"
          description: The return/drop-off location for the car rental.
          example: Deer Lake, NL (YDF-Deer Lake Regional)
        return_country_code:
          type: "string"
          description: The country code for the return/drop-off location in two-letter ISO 3166-1 alpha-2 format.
          example: CA
        trip_type:
          type: "string"
          enum: ["One Way", "Round Trip", "Multiple Destinations"]
          description: The type of trip e.g., `One Way`, `Round Trip`, `Multiple Destinations`
          example: Round Trip
        rental_company_confirmation_id:
          type: "string"
          description: The confirmation id provided by the car rental.
          example: ABC1234
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 10.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 1.0
    RentalCompany:
      type: object
      properties:
        name:
          type: "string"
          description: The name of the car rental company.
          example: Hertz

    ActivityBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case an activity.
          example: 1400882910
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
        activity_start_date:
          type: "string"
          description: The start date of the activity in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-08
        activity_end_date:
          type: "string"
          description: The end date of the activity in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-08
        vendor:
          $ref: "#/components/schemas/ActivityVendor"
        offering_name:
          type: "string"
          description: The offering name of the activity booked.
          example: Passions of Paradise Great Barrier Reef
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 10.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 1.0
    ActivityVendor:
      type: object
      properties:
        name:
          type: "string"
          description: The name of the vendor providing the activity.
          example: Viator
        city:
          type: "string"
          description: The city where the activity vendor is located.
          example: Deer Lake
        country_code:
          type: "string"
          description: The country code for the activity vendor in two-letter ISO 3166-1 alpha-2 format.
          example: CA

    InsuranceBookingItem:
      type: object
      description: An insurance component/booking item.
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case an insurance.
          example: 1400882610
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          example: Confirmed
          description: The status of the booking item one of Confirmed/Cancelled.
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 4.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.5

    CommissionValue:
      type: object
      description: The commission amount of the booking or the booking item. This is part of the gross booking value.
      properties:
        billable_currency:
          $ref: "#/components/schemas/BillableAmount"
    GrossBookingValue:
      type: object
      description: The gross booking value of the booking.
      properties:
        billable_currency:
          $ref: "#/components/schemas/BillableAmount"
          example:
            currency: USD
            value: 100.25
    TaxesAndFees:
      type: object
      description: The taxes and fees associated with the booking.
      properties:
        billable_currency:
          $ref: "#/components/schemas/BillableAmount"
          example:
            currency: USD
            value: 10.5

    Pricing:
      type: object
      properties:
        gross_booking_value:
          $ref: "#/components/schemas/GrossBookingValue"
        taxes_and_fees:
          $ref: "#/components/schemas/TaxesAndFees"

    BillableAmount:
      type: object
      description: An object representing a billable amount which contains the currency and value of that amount.
      properties:
        currency:
          type: string
          description: Currency Code (ISO 4217) for the billable monetary value.
          example: USD
        value:
          type: number
          description: The monetary value
          example: 100.25



  parameters:

    WebhookAuthorizationHeader:
      in: header
      name: authorization
      required: true
      schema:
        type: string
      description: The authorization header that contains the hmac signature and the information related. Format \
        "MAC id="{apikey}",ts="{epochTimestamp}",nonce="{guid}",bodyhash="{bodyhash}",mac="{mac}".
      example: MAC id='testApiKey',ts='1724941754807',nonce='fdcb4da6-43cb-4b98-9c20-1b1cb29936cf',bodyhash='mWnHESR9lqBxFGdvZ2nZmz5hcaSSQoZA8Xrnn78TCyw=',mac='l56tjzaDJ48DyJWQ22wzF6qJPYeMU2VIpwbmdLeDZbg='