openapi: 3.0.3
info:
  title: Virtual Interlining API
  version: 2.4.0
  description: |
    # Introduction

    ## What is Virtual Interlining?
    ​
    Interlining is an airline-industry-specific term. Carriers come to an agreement with others, or join an alliance, and then passengers can fly to their destination using all of those airlines in agreement. 

    Virtual interlining is where the technology behind the scenes organizes the means for passengers to travel on multiple carriers on a single itinerary even without an agreement. Our virtual interlining technology not only gives your more content in addition to GDS, it also gives contents with more competitive pricing.

    ## OpenAPI specification

    This API specification can be downloaded in [OpenAPI](https://openapis.org) format. Many [code generator tools](https://openapi-generator.tech/docs/generators) are available to generate client code in different programming languages based on the specification file.

    For example, to generate client code in Java, run following command.

    ```text
    openapi-generator-cli generate -g java -o newpathfly -i openapi.yaml
    ```

  contact:
    name: newpathfly

servers:
  - url: http://uat-api.newpathfly.com/v2
  - url: http://api.newpathfly.com/v2

tags:
  - name: Shopping
    description: |
      Search for virtual interlining offerings of cheapest flights.

  - name: Booking
    description: |
      Place booking orders of virtually interlined flights.

  - name: Payments
    description: |
      Make payments to booking orders of virtually interlined flights.

  # Enums
  - name: FareClass
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/FareClass" />

  - name: SeatStatus
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SeatStatus" />

  - name: TripType
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/TripType" />

  # Common Schemas
  - name: Flight
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Flight" />

  - name: Segment
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Segment" />

  - name: SegmentGroup
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SegmentGroup" />

  # Shopping Schemas
  - name: SearchRequest
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SearchRequest" />

  - name: SearchResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SearchResponse" />

  - name: SearchResultPoll
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SearchResultPoll" />

  - name: PollResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/PollResponse" />

  - name: Query
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Query" />

  - name: Trip
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Trip" />

  - name: Price
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Price" />

  # Booking Schemas
  - name: Check
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Check" />

  - name: CheckResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CheckResponse" />

  - name: CheckStatus
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CheckStatus" />

  - name: CheckStatusResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CheckStatusResponse" />

  - name: Order
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Order" />

  - name: OrderResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrderResponse" />

  - name: OrdersResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrdersResponse" />

  - name: OrderStatus
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrderStatus" />

  - name: OrderStatusResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/OrderStatusResponse" />

  - name: Customer
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Customer" />

  - name: Passenger
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Passenger" />

  - name: TravelDocument
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/TravelDocument" />

  # Payment Schemas
  - name: Payment
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Payment" />

  - name: PaymentResponse
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/PaymentResponse" />

  - name: CreditCard
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CreditCard" />

x-tagGroups:
  - name: API
    tags:
      - Shopping
      - Booking
      - Payments

  - name: Enums
    tags:
      - FareClass
      - SeatStatus
      - TripType

  - name: Common Schemas
    tags:
      - Flight
      - Segment
      - SegmentGroup

  - name: Shopping Schemas
    tags:
      - SearchRequest
      - SearchResponse
      - SearchResultPoll
      - PollResponse
      - Query
      - Trip
      - Price

  - name: Booking Schemas
    tags:
      - Check
      - CheckResponse
      - CheckStatus
      - CheckStatusResponse
      - Order
      - OrderResponse
      - OrdersResponse
      - OrderStatus
      - OrderStatusResponse
      - Customer
      - Passenger
      - TravelDocument

  - name: Payment Schemas
    tags:
      - Payment
      - PaymentResponse
      - CreditCard

paths:
  # Shopping
  /shopping/searches:
    post:
      summary: Create a search request
      description: A `requestId` will be returned given a valid search request. This `requestId` is required for polling for search results later on.
      operationId: createSearch
      tags:
        - Shopping
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
      responses:
        "200":
          $ref: "#/components/responses/SearchResponseOK"
        "400":
          $ref: "#/components/responses/SearchResponseBadRequest"

  /shopping/polls:
    post:
      summary: Poll for search results
      description: |
        Given a `requestId` obtained from search, corresponding search results will be returned in full (NOT incremental). Different response status code indicates whether another poll is neccessary until entire full results are returned.
      operationId: createPoll
      tags:
        - Shopping
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchResultPoll"
      responses:
        "200":
          $ref: "#/components/responses/PollResponseOK"
        "206":
          $ref: "#/components/responses/PollResponsePartial"
        "400":
          $ref: "#/components/responses/PollResponseBadRequest"

  # booking
  /booking/checks:
    post:
      summary: Create a booking check of specific flight
      description: |
        A specific flight contains a list of specific `segmentGroups` returned from flight search.
        
        Given a list of `segmentGroups` and information of `passengers`, a check request with an unique `checkId` will be returned.

        An optional map of `key:value` pairs can be passed to `extended`, to assoicate certain custom data with this particular request for future tracking. For example, it is recommended to pass a client side order ID to this `extended` map, so later when a response is returned it is convenient to identify the corresponding order at client side.

      operationId: createCheck
      tags:
        - Booking
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Check"
      responses:
        "200":
          $ref: "#/components/responses/CheckResponseOK"
        "400":
          $ref: "#/components/responses/CheckResponseBadRequest"

  /booking/checks/{checkId}:
    get:
      summary: Retrieve information about a booking check
      description: |
        Given a `checkId` previously returned, a check request with the same `checkId` will be returned.

        An optional map of `key:value` pairs can be passed to `extended`, to assoicate certain custom data with this particular request for future tracking. For example, it is recommended to pass a client side order ID to this `extended` map, so later when a response is returned it is convenient to identify the corresponding order at client side.

      operationId: getCheck
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/CheckId"
      responses:
        "200":
          $ref: "#/components/responses/CheckResponseOK"
        "404":
          $ref: "#/components/responses/CheckResponseNotFound"

  /booking/checks/{checkId}/status:
    get:
      summary: Retrieve the status of a booking check
      description: |
        The status of a booking check with specified `checkId` will be returned. 

        If the `segmentGroups` from the check request are available for booking with respect to the information of `passengers`, the a success `checkStatus` of will be returned along with a `totalAmount` in particular `currency`.

        For any reason for which the check failed, a error `checkStatus` will be returned.

        > See response of `200 OK` for status definitions.

      operationId: getCheckStatus
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/CheckId"
      responses:
        "200":
          $ref: "#/components/responses/CheckStatusResponseOK"
        "404":
          $ref: "#/components/responses/CheckStatusResponseNotFound"

  /booking/orders:
    post:
      summary: Create a booking order of specific flight
      description: |
        Given a unique `checkId` previously returned, and information of `customer` and `passengers`, a booking order with an unique `orderId` will be returned along with `totalAmount` in particular `currency`.

        An optional map of `key:value` pairs can be passed to `extended`, to assoicate certain custom data with this particular request for future tracking. For example, it is recommended to pass a client side order ID to this `extended` map, so later when a response is returned it is convenient to identify the corresponding order at client side.
      operationId: createOrder
      tags:
        - Booking
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        "200":
          $ref: "#/components/responses/OrderResponseOK"
        "400":
          $ref: "#/components/responses/OrderResponseBadRequest"

    get:
      summary: Retrieve one or more booking orders
      description: |
        Given one or more criteria in the query string, one or more matching booking orders will be returned.

        Results will also be paged based on `offset` and `size`.
      operationId: getOrders
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/CustomerPhoneNumber"
        - $ref: "#/components/parameters/CustomerEmail"
        - $ref: "#/components/parameters/PassengerTravelDocumentNumber"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Size"
        - $ref: "#/components/parameters/DateTimeStart"
        - $ref: "#/components/parameters/DateTimeEnd"
        - $ref: "#/components/parameters/OrderStatus"
      responses:
        "200":
          $ref: "#/components/responses/OrdersResponseOK"
        "400":
          $ref: "#/components/responses/OrdersResponseBadRequest"

  /booking/orders/{orderId}:
    get:
      summary: Retrieve information about a booking order
      description: |
        A booking order with specified `orderId` will be returned.
      operationId: getOrder
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          $ref: "#/components/responses/OrderResponseOK"
        "404":
          $ref: "#/components/responses/OrderResponseNotFound"

    delete:
      summary: Cancel a booking order that is neither cancelled nor completed
      description: |
        The booking order with specified `orderId` will be cancelled, if its status is neither `cancelled` nor `completed`.

        > IMPORTANT:
        >
        > Calling this endpoint does not cancel a `completed` booking order, i.e. a booking order that is already paid. It certainly does not provide any refund because it can only cancel a booking order that is not already paid.

      operationId: cancelOrder
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          $ref: "#/components/responses/EmptyOK"
        "400":
          $ref: "#/components/responses/EmptyBadRequest"
        "404":
          $ref: "#/components/responses/EmptyNotFound"

  /booking/orders/{orderId}/status:
    get:
      summary: Retrieve the status of a booking order
      description: |
        The status of a booking order with specified `orderId` will be returned. 

        > See response of `200 OK` for status definitions.

      operationId: getOrderStatus
      tags:
        - Booking
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          $ref: "#/components/responses/OrderStatusResponseOK"
        "404":
          $ref: "#/components/responses/OrderStatusResponseNotFound"

  # Payment
  /booking/payments:
    post:
      summary: Make a payment to a booking order recently placed
      description: |
        Given the `orderId`, `totalAmount` in specific `currency` along with `creditCard` information, a payment with an unique `paymentId` will be made and returned.
      operationId: createPayment
      tags:
        - Payments
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Payment"
      responses:
        "200":
          $ref: "#/components/responses/PaymentResponseOK"
        "400":
          $ref: "#/components/responses/PaymentResponseBadRequest"
        "402":
          $ref: "#/components/responses/PaymentResponseFailed"
        "409":
          $ref: "#/components/responses/PaymentResponseConflict"

  /booking/payments/{paymentId}:
    get:
      summary: Retrieve information about a payment
      description: |
        Given a `paymentId`, information about the corresponding payment will be returned.
      operationId: getPayment
      tags:
        - Payments
      parameters:
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "200":
          $ref: "#/components/responses/PaymentResponseOK"
        "400":
          $ref: "#/components/responses/PaymentResponseBadRequest"

components:
  parameters:
    # Booking
    CheckId:
      name: checkId
      in: path
      required: true
      schema:
        type: string
        description: UUID
        example: 23246c8e-11ad-4105-845b-07ad855649c3

    OrderId:
      name: orderId
      in: path
      required: true
      schema:
        type: string
        description: UUID
        example: a7dd1cf6-dc96-490b-bdf6-8685dbf5bb87

    OrderStatus:
      name: orderStatus
      description: |
        For status definition, see `OrderStatus` under *Order Schemas*.
      in: query
      schema:
        type: string
        enum:
          - creating
          - ready
          - cancelled
          - completed
          - error

    CustomerPhoneNumber:
      name: customerPhoneNumber
      description: Customer phone number (without country code)
      in: query
      schema:
        type: string
        example: "1234567890"

    CustomerEmail:
      name: customerEmail
      description: Customer email address
      in: query
      schema:
        type: string
        example: peter_parker@yahoo.com

    PassengerTravelDocumentNumber:
      name: passengerTravelDocumentNumber
      description: Travel document number, such as passport number, of a passenger
      in: query
      schema:
        type: string
        example: EG12345678

    # Payment
    PaymentId:
      name: paymentId
      in: path
      required: true
      schema:
        type: string
        description: UUID
        example: 956de7da-ece8-4ba1-acf4-37aeda78cb13

    # Common
    DateTimeStart:
      name: dateTimeStart
      description: |
        A start date-time earlier than any booking order returned. It should be in ISO 8601 format (UTC).
      in: query
      schema:
        type: string
        format: date-time

    DateTimeEnd:
      name: dateTimeEnd
      description: |
        A end date-time later than any booking order returned. It should be in ISO 8601 format (UTC).
      in: query
      schema:
        type: string
        format: date-time

    # Pagination
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0

    Size:
      name: size
      in: query
      schema:
        type: integer
        minimum: 1
        default: 20

  responses:
    # Search
    SearchResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchResponse"

    SearchResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchResponse"
          example:
            message: "Bad Request"

    PollResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PollResponse"

    PollResponsePartial:
      description: Partial
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PollResponse"

    PollResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PollResponse"
          example:
            message: "Bad Request"

    # Booking
    CheckResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckResponse"

    CheckResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckResponse"
          example:
            message: "Bad Request"

    CheckResponseNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckResponse"
          example:
            message: "Not Found"

    CheckStatusResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckStatusResponse"

    CheckStatusResponseNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CheckStatusResponse"
          example:
            message: "Not Found"

    OrderResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderResponse"

    OrderResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderResponse"
          example:
            message: "Bad Request"

    OrderResponseNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderResponse"
          example:
            message: "Not Found"

    OrdersResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrdersResponse"

    OrdersResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrdersResponse"
          example:
            message: "Bad Request"

    OrderStatusResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderStatusResponse"

    OrderStatusResponseNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrderStatusResponse"
          example:
            message: "Not Found"

    # Payment
    PaymentResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"

    PaymentResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"
          example:
            message: "Bad Request"

    PaymentResponseFailed:
      description: Payment Required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"
          example:
            message: "Payment Required"

    PaymentResponseConflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentResponse"
          example:
            message: "Conflict"

    # Common
    EmptyOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"

    EmptyBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"
          example:
            message: "Bad Request"

    EmptyNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"
          example:
            message: "Not Found"

  schemas:
    # Common
    BaseResponse:
      properties:
        message:
          readOnly: true
          description: message returned by server side if there is any
          type: string
          example: ""

    FareClass:
      description: This is the fare class, which is one of `Economy`, `PremiumEconomy`, `Business` and `First`.
      type: string
      default: Economy
      enum:
        - Economy
        - PremiumEconomy
        - Business
        - First

    Flight:
      description: A flight is a pair of original departure to final destination.
      properties:
        segments:
          description: A flight consists of one or more segments. For example, a direct flight from Toronto (YYZ) to London (LON) is a flight consists of exactly one flight segment.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Segment"

    SegmentGroup:
      description: |
        A list of segment groups, where each segment group is a list of segments suggested to be placed within the same booking order.
      properties:
        segmentGroupId:
          type: string
          description: UUID
          readOnly: true
          example: 1feefb95-7b9e-49e4-828c-b1844dd9d9ec
        depDate:
          description: This is the departure date in `YYYYMMDD` format.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        depAirport:
          description: This is the departure airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: LON
        arrAirport:
          description: This is the arrival airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: CGN
        carrier:
          description: This is the 2-letter IATA carrier code
          type: string
          minLength: 2
          maxLength: 2
          example: AC
        retDate:
          description: This is the return date in `YYYYMMDD` format. Only available when type == RT.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        type:
          $ref: "#/components/schemas/TripType"
        segments:
          description: A segment group consists of one or more segments. For example, a direct flight from Toronto (YYZ) to London (LON) is a flight consists of exactly one flight segment.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Segment"

    Segment:
      description: A segment is a pair of departure and arrival without any stop in-between.
      properties:
        fareClass:
          $ref: "#/components/schemas/FareClass"
        depDate:
          description: This is the departure date in `YYYYMMDD` format.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        depTime:
          description: This is the departure time in `HH:mm` format.
          type: string
          readOnly: true
          pattern: "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$"
          example: "12:45"
        depAirport:
          description: This is the departure airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: LON
        arrDate:
          description: This is the arrival date in `YYYYMMDD` format.
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"
        arrTime:
          description: This is the arrival time in `HH:mm` format.
          type: string
          readOnly: true
          pattern: "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$"
          example: "17:50"
        arrAirport:
          description: This is the arrival airport specified using its IATA code.
          type: string
          minLength: 3
          maxLength: 3
          example: CGN
        flightNo:
          description: This is the flight number starting with carrier IATA code.
          type: string
          example: AC103
        carrier:
          description: This is the 2-letter IATA carrier code
          type: string
          minLength: 2
          maxLength: 2
          example: AC

    Extended:
      description: |
        Extended data from client side to associate. This is useful for storing some information later needs to be retrieved, such as client side order ID. The data is in form of `key:value` pairs. All data will be returned in response.
      type: object
      additionalProperties:
        type: string
        description: |
          a custom value associated with this booking order
      example:
        clientsideOrderId: O1234
        clientsideCustomField1: A
        clientsideCustomField2: B
        clientsideCustomField3: C

    # Search Request
    SearchRequest:
      description: This is the payload to be sent when calling `/searches` endpoint.
      required:
        - queries
        - adultAmount
      properties:
        queries:
          description: This is a list containing the same number of queries as the number of flights for the trip. For one-way trip there should be one query, whereas for round trip there should be two queries.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Query"
        type:
          $ref: "#/components/schemas/TripType"
        adultAmount:
          description: This is the number of adult passengers
          type: integer
          minimum: 1
        childAmount:
          description: This is the number of child passengers
          type: integer
          minimum: 0
        infantAmount:
          description: This is the number of infant passengers
          type: integer
          minimum: 0
        fareClass:
          $ref: "#/components/schemas/FareClass"

    SearchResponse:
      description: This is the response when a `SearchRequest` is accepted.
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        requestId:
          description: This value should be included in the polling later on.
          type: string
          example: "OW|Economy|1-0-0|UnlimitedStarter-UnlimitedCandidate|20210901:@YTO:@AMS"

    # Poll
    SearchResultPoll:
      description: This is the payload to be sent when calling `/polls` endpoint. The virtual interlining engine will mostly likely keep generating results at the backend, so stop calling this endpoint when number of results is good enough as a general practice.
      required:
        - requestId
      properties:
        requestId:
          description: This is the request ID for which to be polled.
          type: string
          example: "OW|Economy|1-0-0|UnlimitedStarter-UnlimitedCandidate|20210901:@YTO:@AMS"
        offset:
          description: This is the offset of the results to be polled next.
          type: integer
          minimum: 0
          default: 100
        size:
          description: This is the maximum number of results to be polled. The actual number of results might be less when there is no more results available at the moment.
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        currency:
          description: Currency code of results to be polled.
          type: string
          minLength: 3
          maxLength: 3
          example: USD
          default: USD

    PollResponse:
      description: This result contains up to the number of flight trips specified by `size` in the request.
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        currencyCode:
          description: This is the 3-letter currency code in which price is provided.
          type: string
          minLength: 3
          maxLength: 3
          example: EUR
        trips:
          description: This is a list of trips based on `queries` and `TripType` in the corresponding `SearchRequest`.
          type: array
          items:
            $ref: "#/components/schemas/Trip"

    # Domain Models
    Query:
      description: This is a flight query from departure airport to arrival airport on specific departure date. This query corresponding to a single flight in a trip, where a one-way trip contains only one flight and a round trip contains two flights.
      required:
        - depCity
        - depAirport
        - arrCity
        - arrAirport
        - date
      properties:
        depCity:
          description: This is the departure city specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: LON
        depAirport:
          description: This is the departure airport specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: LON
        arrCity:
          description: This is the arrival city specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: PAR
        arrAirport:
          description: This is the arrival airport specified using its IATA code.
          type: string
          minLength: 0
          maxLength: 3
          example: CGN
        date:
          description: This is the departure date in `YYYYMMDD` format
          type: string
          pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
          example: "20210401"

    Trip:
      description: A trip is one complete travel. It can be one-way trip or a round trip, depending on the number of included flights.
      properties:
        flights:
          description: A one-way trip consists of one flight. A round-trip consists of two flights going forth and back between two places.
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Flight"
        segmentGroups:
          description: |
            A list of segment groups, where each segment group is a list of segments suggested to be placed within the same booking order.
          type: array
          readOnly: true
          minItems: 1
          items:
            $ref: "#/components/schemas/SegmentGroup"
        prices:
          description: This is a map between each price type and the actual pricing information. `ADT`, `CHD` and `INF` correspond to each individual passenger type. `ALL` corresponds to all passengers. The total price in `ALL` should equal to `ADT` * `adultAmount` + `CHD` * `childAmount` + `INF` * `infantAmount`.
          properties:
            ADT:
              $ref: "#/components/schemas/Price"
            CHD:
              $ref: "#/components/schemas/Price"
            INF:
              $ref: "#/components/schemas/Price"
            ALL:
              $ref: "#/components/schemas/Price"

    Price:
      description: This is the pricing information including `price`, `tax` and `totalPrice`.
      properties:
        price:
          description: This it the before tax price.
          type: number
          format: double
          minimum: 0
          example: 123.45
        tax:
          description: This it the tax.
          type: number
          format: double
          minimum: 0
          example: 6.78
        totalPrice:
          description: This it the total price including tax.
          type: number
          format: double
          minimum: 0
          example: 130.23
        seatsStatus:
          $ref: "#/components/schemas/SeatStatus"
        currencyCode:
          description: This is the 3-letter currency code in which price is provided.
          type: string
          minLength: 3
          maxLength: 3
          example: EUR

    SeatStatus:
      description: Seat status is `EMPTY` when there is no seat. Else, it is `LIMITED` when there are less than 8 seats. Else, it is `ENOUGH`.
      type: string
      enum:
        - EMPTY
        - ENOUGH
        - LIMITED
      example: ENOUGH

    TripType:
      description: This is the trip type, where `OW` is for one-way trip and `RT` is for round trip.
      type: string
      default: OW
      enum:
        - OW
        - RT

    # Booking
    Check:
      required:
        - segmentGroups
        - passengers
      properties:
        checkId:
          type: string
          description: UUID
          readOnly: true
          example: 23246c8e-11ad-4105-845b-07ad855649c3
        currency:
          type: string
          readOnly: true
          description: |
            3-letter currency code in ISO 4217 format
          example: EUR
        totalAmount:
          type: number
          readOnly: true
          description: |
            Total price amount of all passengers for the flight, including tax and miscellaneous fees.
          example: 456.78
        segmentGroups:
          type: array
          description: |
            A list of segment groups, where each segment group is a list of segments suggested to be placed within the same booking order.
          minItems: 1
          items:
            $ref: "#/components/schemas/SegmentGroup"
        passengers:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Passenger"
        extended:
          $ref: "#/components/schemas/Extended"

    CheckResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        check:
          $ref: "#/components/schemas/Check"

    CheckStatus:
      properties:
        status:
          description: |
            | status     | description               |
            |------------|---------------------------|
            |`pending`   | booking check in progress |
            |`completed` | booking check succeeded   |
            |`error`     | booking check error       |
          readOnly: true
          type: string
          default: pending
          enum:
            - pending
            - completed
            - error
        lastUpdated:
          readOnly: true
          description: |
            Update date-time when check status was last changed. It should be in ISO 8601 format (UTC).
          type: string
          format: date-time

    CheckStatusResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        checkStatus:
          $ref: "#/components/schemas/CheckStatus"

    Order:
      required:
        - checkId
        - customer
        - passengers
      properties:
        orderId:
          type: string
          description: UUID
          readOnly: true
          example: a7dd1cf6-dc96-490b-bdf6-8685dbf5bb87
        createdAt:
          type: string
          readOnly: true
          description: |
            Creation date/time of the booking order in ISO 8601 format (UTC)
          format: date-time
        currency:
          type: string
          readOnly: true
          description: |
            3-letter currency code in ISO 4217 format
          example: EUR
        totalAmount:
          type: number
          readOnly: true
          description: |
            Total price amount of all passengers for the flight, including tax and miscellaneous fees.
          example: 456.78
        checkId:
          type: string
          description: UUID
          example: 23246c8e-11ad-4105-845b-07ad855649c3
        customer:
          $ref: "#/components/schemas/Customer"
        passengers:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Passenger"
        extended:
          $ref: "#/components/schemas/Extended"

    OrderResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        order:
          $ref: "#/components/schemas/Order"

    OrdersResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        orders:
          type: array
          items:
            $ref: "#/components/schemas/Order"

    OrderStatus:
      properties:
        status:
          description: |
            | status    | description                              |
            |-----------|------------------------------------------|
            |`creating` | the booking order is getting created     |
            |`ready`    | the booking order is to be paid          |
            |`cancelled`| manually cancelled or timed out          |
            |`completed`| paid booking order                       |
            |`error`    | some error happened to the booking order |

          readOnly: true
          type: string
          default: ready
          enum:
            - creating
            - ready
            - cancelled
            - completed
            - error
        paymentId:
          readOnly: true
          nullable: true
          type: string
          description: UUID
          example: 956de7da-ece8-4ba1-acf4-37aeda78cb13
        lastUpdated:
          readOnly: true
          description: |
            Update date-time when booking order status was last changed. It should be in ISO 8601 format (UTC).
          type: string
          format: date-time

    OrderStatusResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        orderStatus:
          $ref: "#/components/schemas/OrderStatus"

    Customer:
      description: |
        Customer information, including contact information for booking order related issues
      allOf:
        - $ref: "#/components/schemas/Person"
        - properties:
            phoneCountryCode:
              type: string
              description: |
                Country calling code defined by ITU, starting with international dialing prefix `+`
              example: "+1"
            phoneNumber:
              type: string
              description: |
                Phone number including area code without any punctuation
              example: "1234567890"
            email:
              type: string
              example: "peter_parker@yahoo.com"

    Passenger:
      allOf:
        - $ref: "#/components/schemas/Person"
        - properties:
            type:
              type: string
              description: |
                - Adult
                - Child
                - Infant
              default: ADT
              enum:
                - ADT
                - CHD
                - INF
            birthday:
              type: string
              description: |
                Passenger birthday in `YYYY-MM-DD` format
              format: date
              example: "2001-01-01"
            gender:
              type: string
              enum:
                - F
                - M
            travelDocument:
              $ref: "#/components/schemas/TravelDocument"

    Person:
      properties:
        firstName:
          type: string
          example: Peter
        lastName:
          type: string
          example: Parker

    TravelDocument:
      description: |
        Passenger travel document
      properties:
        type:
          description: |
            Type of travel document
          type: string
          default: PASSPORT
          enum:
            - DRIVER_LICENSE
            - NATIONAL_ID
            - PASSPORT
        number:
          type: string
          description: |
            Travel document number
          example: EG12345678
        expiryDate:
          type: string
          description: |
            Travel document expiry date in `YYYY-MM-DD` format
          format: date
        placeOfIssue:
          type: string
          description: |
            Place (e.g. country, province, city) where the travel document was issued
          example: USA

    # Payment
    Payment:
      required:
        - orderId
        - currency
        - totalAmount
        - creditCard
      properties:
        paymentId:
          readOnly: true
          type: string
          description: UUID
          example: 956de7da-ece8-4ba1-acf4-37aeda78cb13
        createdAt:
          readOnly: true
          description: |
            Creation date/time of the payment in ISO 8601 format (UTC)
          type: string
          format: date-time
        orderId:
          type: string
          description: UUID
          example: a7dd1cf6-dc96-490b-bdf6-8685dbf5bb87
        currency:
          type: string
          example: EUR
        totalAmount:
          type: number
          example: 456.78
        creditCard:
          $ref: "#/components/schemas/CreditCard"

    PaymentResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
      properties:
        payment:
          $ref: "#/components/schemas/Payment"

    CreditCard:
      properties:
        type:
          type: string
          enum:
            - MASTERCARD
            - VISA
        number:
          type: string
          example: "5250567933594297"
        cvc:
          type: string
          example: "123"
        expiryMonth:
          type: string
          example: "08"
        expiryYear:
          type: string
          example: "24"
        holderFirstName:
          type: string
          example: Peter
        holderLastName:
          type: string
          example: Parker
        address:
          type: string
          example: "738 Winter Garden Drive"
        city:
          type: string
          example: New York
        zipCode:
          type: string
          example: "11375"
        countryCode:
          type: string
          example: US
          description: |
            2-letter ISO country code (alpha-2) as listed at https://en.wikipedia.org/wiki/ISO_3166-1