@gojinko/api-client 1.2.1 → 2.0.0

package/public-api.yaml

@@ -0,0 +1,2378 @@
+openapi: 3.0.0
+info:
+  title: Jinko Public API
+  version: 0.1.0
+  description: Curated public REST surface for Jinko. Authenticated with jnk_ API
+    keys. See https://docs.gojinko.com for guides.
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+  schemas:
+    HealthResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        service:
+          type: string
+          enum:
+            - jinko-api
+        version:
+          type: string
+          example: 0.1.0
+      required:
+        - status
+        - service
+        - version
+    Amount:
+      type: object
+      properties:
+        value:
+          type: number
+        currency:
+          type: string
+        decimal_places:
+          type: integer
+      required:
+        - value
+        - currency
+    Itinerary:
+      type: object
+      properties:
+        id:
+          type: string
+        origin:
+          type: object
+          properties:
+            code:
+              type: string
+            name:
+              type: string
+          required:
+            - code
+        destination:
+          type: object
+          properties:
+            code:
+              type: string
+            name:
+              type: string
+          required:
+            - code
+        total:
+          $ref: "#/components/schemas/Amount"
+        cabin_class:
+          type: string
+        deep_link:
+          type: string
+      required:
+        - id
+        - origin
+        - destination
+    DestinationSuggestion:
+      type: object
+      properties:
+        city_name:
+          type: string
+        iata_code:
+          type: string
+        image_url:
+          type: string
+        location:
+          type: object
+          properties:
+            latitude:
+              type: number
+            longitude:
+              type: number
+          required:
+            - latitude
+            - longitude
+        lowest_fare:
+          $ref: "#/components/schemas/Itinerary"
+        flights:
+          type: array
+          items:
+            $ref: "#/components/schemas/Itinerary"
+      required:
+        - flights
+    FindDestinationResponse:
+      type: object
+      properties:
+        destinations:
+          type: array
+          items:
+            $ref: "#/components/schemas/DestinationSuggestion"
+        total:
+          type: number
+        next_page_token:
+          type: string
+      required:
+        - destinations
+    ErrorResponse:
+      type: object
+      properties:
+        error:
+          type: object
+          properties:
+            code:
+              type: string
+            message:
+              type: string
+            doc_url:
+              type: string
+          required:
+            - code
+            - message
+      required:
+        - error
+    DateRange:
+      type: object
+      properties:
+        start:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        end:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+      required:
+        - start
+        - end
+      example:
+        start: 2026-06-01
+        end: 2026-06-30
+    FlightDiscoveryRequest:
+      type: object
+      properties:
+        origins:
+          type: array
+          items:
+            type: string
+          example:
+            - JFK
+            - EWR
+        destinations:
+          type: array
+          items:
+            type: string
+        origin_type:
+          type: string
+          enum: &a1
+            - city
+            - airport
+          default: city
+        destination_type:
+          type: string
+          enum: *a1
+          default: city
+        departure_dates:
+          type: array
+          items:
+            type: string
+            pattern: ^\d{4}-\d{2}-\d{2}$
+        departure_date_ranges:
+          type: array
+          items:
+            $ref: "#/components/schemas/DateRange"
+        return_dates:
+          type: array
+          items:
+            type: string
+            pattern: ^\d{4}-\d{2}-\d{2}$
+        return_date_ranges:
+          type: array
+          items:
+            $ref: "#/components/schemas/DateRange"
+        stay_days:
+          type: integer
+          minimum: 0
+          exclusiveMinimum: true
+        stay_days_range:
+          type: object
+          properties:
+            min:
+              type: integer
+            max:
+              type: integer
+          required:
+            - min
+            - max
+        trip_type:
+          type: string
+          enum: &a2
+            - oneway
+            - roundtrip
+        cabin_class:
+          type: string
+          enum: &a3
+            - economy
+            - premium_economy
+            - business
+            - first
+        direct_only:
+          type: boolean
+        adults:
+          type: integer
+          minimum: 0
+        children:
+          type: integer
+          minimum: 0
+        infants_in_lap:
+          type: integer
+          minimum: 0
+        infants_in_seat:
+          type: integer
+          minimum: 0
+        youth:
+          type: integer
+          minimum: 0
+        student:
+          type: integer
+          minimum: 0
+        ages:
+          type: array
+          items:
+            type: integer
+            minimum: 0
+        residency_country:
+          type: string
+          minLength: 2
+          maxLength: 2
+        max_total:
+          type: number
+          minimum: 0
+          exclusiveMinimum: true
+        currency:
+          type: string
+          example: USD
+        locale:
+          type: string
+          example: en-US
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+        offset:
+          type: integer
+          minimum: 0
+          default: 0
+        sort_by:
+          type: string
+          enum:
+            - lowest
+            - recommendation
+          default: lowest
+    FindDestinationRequest:
+      allOf:
+        - $ref: "#/components/schemas/FlightDiscoveryRequest"
+        - type: object
+          properties:
+            flights_per_destination:
+              type: integer
+              minimum: 1
+              maximum: 10
+              default: 1
+    FlightCalendarResponse:
+      type: object
+      properties:
+        itineraries:
+          type: array
+          items:
+            $ref: "#/components/schemas/Itinerary"
+        next_page_token:
+          type: string
+      required:
+        - itineraries
+    FlightLeg:
+      type: object
+      properties:
+        origin:
+          type: string
+        destination:
+          type: string
+        departure_datetime:
+          type: string
+        arrival_datetime:
+          type: string
+        duration_minutes:
+          type: number
+        airline:
+          type: string
+        airline_name:
+          type: string
+        stops:
+          type: number
+    Money:
+      type: object
+      properties:
+        amount:
+          type: number
+        value:
+          type: number
+        currency:
+          type: string
+        decimal_places:
+          type: integer
+    Fare:
+      type: object
+      properties:
+        trip_item_token:
+          type: string
+        cabin_class:
+          type: string
+        brand_name:
+          type: string
+        total_price:
+          $ref: "#/components/schemas/Money"
+        price_per_person:
+          $ref: "#/components/schemas/Money"
+        included_baggage:
+          type: string
+        carry_on_baggage:
+          type: string
+        is_changeable:
+          type: boolean
+    FlightOffer:
+      type: object
+      properties:
+        offer_id:
+          type: string
+        provider:
+          type: string
+        provider_name:
+          type: string
+        origin:
+          type: object
+          properties:
+            code:
+              type: string
+            name:
+              type: string
+        destination:
+          type: object
+          properties:
+            code:
+              type: string
+            name:
+              type: string
+        is_round_trip:
+          type: boolean
+        total_duration_minutes:
+          type: number
+        outbound:
+          $ref: "#/components/schemas/FlightLeg"
+        inbound:
+          $ref: "#/components/schemas/FlightLeg"
+        fares:
+          type: array
+          items:
+            $ref: "#/components/schemas/Fare"
+      required:
+        - offer_id
+        - origin
+        - destination
+        - fares
+    FlightSearchResponse:
+      type: object
+      properties:
+        offers:
+          type: array
+          items:
+            $ref: "#/components/schemas/FlightOffer"
+        exact_match_found:
+          type: boolean
+      required:
+        - offers
+    FlightSearchRequest:
+      type: object
+      properties:
+        origin:
+          type: string
+          example: JFK
+        destination:
+          type: string
+          example: LAX
+        departure_date:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        return_date:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        trip_type:
+          type: string
+          enum: *a2
+        cabin_class:
+          type: string
+          enum: *a3
+        direct_only:
+          type: boolean
+        max_price:
+          type: number
+          minimum: 0
+          exclusiveMinimum: true
+        include_carriers:
+          type: array
+          items:
+            type: string
+        exclude_carriers:
+          type: array
+          items:
+            type: string
+        adults:
+          type: integer
+          minimum: 1
+          default: 1
+        children:
+          type: integer
+          minimum: 0
+        infants:
+          type: integer
+          minimum: 0
+        currency:
+          type: string
+        locale:
+          type: string
+        offer_token:
+          type: string
+      required:
+        - origin
+        - destination
+        - departure_date
+    MonitoredMoney:
+      type: object
+      properties:
+        amount:
+          type: number
+        value:
+          type: number
+        currency:
+          type: string
+        decimal_places:
+          type: integer
+    MonitoredCarrier:
+      type: object
+      properties:
+        code:
+          type: string
+        name:
+          type: string
+        flight_number:
+          type: string
+    MonitoredFlight:
+      type: object
+      properties:
+        offer_token:
+          type: string
+        total_price:
+          $ref: "#/components/schemas/MonitoredMoney"
+        outbound_carrier:
+          $ref: "#/components/schemas/MonitoredCarrier"
+        inbound_carrier:
+          $ref: "#/components/schemas/MonitoredCarrier"
+        outbound_stops:
+          type: number
+        inbound_stops:
+          type: number
+        outbound_duration_minutes:
+          type: number
+        inbound_duration_minutes:
+          type: number
+        outbound_departure_local:
+          type: string
+        outbound_arrival_local:
+          type: string
+        inbound_departure_local:
+          type: string
+        inbound_arrival_local:
+          type: string
+        cabin_class:
+          type: string
+        fare_brand:
+          type: string
+    PriceMonitoringResponse:
+      type: object
+      properties:
+        status:
+          type: string
+        monitored_at:
+          type: string
+        flight:
+          $ref: "#/components/schemas/MonitoredFlight"
+        request_echo:
+          nullable: true
+      required:
+        - status
+    PriceMonitoringRequest:
+      type: object
+      properties:
+        origin:
+          type: string
+          example: PAR
+        destination:
+          type: string
+          example: NYC
+        departure_date:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        return_date:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        origin_type:
+          type: string
+          enum: &a4
+            - city
+            - airport
+        destination_type:
+          type: string
+          enum: *a4
+        cabin_class:
+          type: string
+          enum: *a3
+        direct_only:
+          type: boolean
+        max_price:
+          type: number
+          minimum: 0
+          exclusiveMinimum: true
+        include_carriers:
+          type: array
+          items:
+            type: string
+        exclude_carriers:
+          type: array
+          items:
+            type: string
+        adults:
+          type: integer
+          minimum: 1
+          default: 1
+        children:
+          type: integer
+          minimum: 0
+        infants:
+          type: integer
+          minimum: 0
+        currency:
+          type: string
+        locale:
+          type: string
+      required:
+        - origin
+        - destination
+        - departure_date
+    TripResponse:
+      type: object
+      properties:
+        trip_id:
+          type: string
+        status:
+          type: string
+        actions_performed:
+          type: array
+          items:
+            type: string
+        items:
+          type: array
+          items:
+            type: object
+            properties:
+              item_id:
+                type: string
+              kind:
+                type: string
+              price:
+                type: object
+                properties:
+                  amount:
+                    type: number
+                  value:
+                    type: number
+                  currency:
+                    type: string
+                  decimal_places:
+                    type: integer
+              pax_count:
+                type: number
+              available_ancillaries:
+                type: array
+                items:
+                  nullable: true
+              selected_ancillaries:
+                type: array
+                items:
+                  nullable: true
+        travelers:
+          type: array
+          items:
+            nullable: true
+        contact:
+          type: object
+          properties:
+            email:
+              type: string
+            phone:
+              type: string
+        totals:
+          type: object
+          properties:
+            currency:
+              type: string
+            total:
+              type: number
+      required:
+        - trip_id
+    Traveler:
+      type: object
+      properties:
+        first_name:
+          type: string
+        last_name:
+          type: string
+        date_of_birth:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        gender:
+          type: string
+          enum:
+            - MALE
+            - FEMALE
+        passenger_type:
+          type: string
+          enum:
+            - ADULT
+            - CHILD
+            - INFANT
+        nationality:
+          type: string
+        passport_number:
+          type: string
+        passport_expiry:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        passport_country:
+          type: string
+      required:
+        - first_name
+        - last_name
+        - date_of_birth
+        - gender
+        - passenger_type
+    TripRequest:
+      type: object
+      properties:
+        trip_id:
+          type: string
+        add_item:
+          type: object
+          properties:
+            trip_item_token:
+              type: string
+          required:
+            - trip_item_token
+        remove_item:
+          type: object
+          properties:
+            item_id:
+              type: string
+          required:
+            - item_id
+        upsert_travelers:
+          type: object
+          properties:
+            travelers:
+              type: array
+              items:
+                $ref: "#/components/schemas/Traveler"
+            contact:
+              type: object
+              properties:
+                email:
+                  type: string
+                  format: email
+                phone:
+                  type: string
+              required:
+                - email
+          required:
+            - travelers
+    GetTripResponse:
+      type: object
+      properties:
+        trip_id:
+          type: string
+        status:
+          type: string
+        travelers:
+          type: array
+          items:
+            nullable: true
+        contact:
+          type: object
+          properties:
+            email:
+              type: string
+            phone:
+              type: string
+        items:
+          type: array
+          items:
+            nullable: true
+        total_amount:
+          type: object
+          properties:
+            amount:
+              type: number
+            value:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        quote:
+          type: object
+          properties:
+            quoted_cart_id:
+              type: number
+            status:
+              type: string
+            expires_at:
+              type: string
+        fulfillment:
+          type: object
+          properties:
+            fulfillment_cart_id:
+              type: number
+            status:
+              type: string
+            phase:
+              type: string
+        bookings:
+          type: array
+          items:
+            nullable: true
+        created_at:
+          type: string
+        updated_at:
+          type: string
+      required:
+        - trip_id
+    AncillaryResponse:
+      type: object
+      properties:
+        trip_id:
+          type: string
+        quoted_item_id:
+          type: number
+        selected_ancillaries:
+          type: array
+          items:
+            nullable: true
+        total_with_ancillaries:
+          type: object
+          properties:
+            amount:
+              type: number
+            value:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+    AncillaryRequest:
+      type: object
+      properties:
+        trip_id:
+          type: string
+        item_id:
+          type: string
+        selections:
+          type: array
+          items:
+            type: object
+            properties:
+              offer_id:
+                type: string
+              category:
+                type: string
+              pax_ref_id:
+                type: string
+              segment_ref_ids:
+                type: array
+                items:
+                  type: string
+              journey_ref_id:
+                type: string
+              quantity:
+                type: number
+              provider_metadata:
+                type: object
+                additionalProperties:
+                  type: string
+            required:
+              - offer_id
+      required:
+        - trip_id
+        - item_id
+        - selections
+    BookResponse:
+      type: object
+      properties:
+        session_id:
+          type: string
+        checkout_url:
+          type: string
+        status:
+          type: string
+        expires_at:
+          type: string
+        total_amount:
+          type: object
+          properties:
+            amount:
+              type: number
+            value:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        items:
+          type: array
+          items:
+            nullable: true
+    BookRequest:
+      type: object
+      properties:
+        trip_id:
+          type: string
+      required:
+        - trip_id
+    HotelSearchResponse:
+      type: object
+      properties:
+        hotels:
+          type: array
+          items:
+            type: object
+            properties:
+              hotel_id:
+                type: string
+              name:
+                type: string
+              address:
+                type: string
+              city:
+                type: string
+              country_code:
+                type: string
+              star_rating:
+                type: number
+              rating:
+                type: number
+              review_count:
+                type: number
+              images:
+                type: array
+                items:
+                  type: string
+              thumbnail_url:
+                type: string
+              rooms:
+                type: array
+                items:
+                  nullable: true
+        total:
+          type: number
+    Occupancy:
+      type: object
+      properties:
+        adults:
+          type: integer
+          minimum: 1
+        children_ages:
+          type: array
+          items:
+            type: integer
+      required:
+        - adults
+    HotelSearchRequest:
+      type: object
+      properties:
+        query:
+          type: string
+          example: Paris
+        city_name:
+          type: string
+        country_code:
+          type: string
+          minLength: 2
+          maxLength: 2
+        latitude:
+          type: number
+        longitude:
+          type: number
+        radius_km:
+          type: number
+          minimum: 0
+          exclusiveMinimum: true
+          maximum: 50
+        place_id:
+          type: string
+        hotel_ids:
+          type: array
+          items:
+            type: string
+        checkin:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        checkout:
+          type: string
+          pattern: ^\d{4}-\d{2}-\d{2}$
+        occupancies:
+          type: array
+          items:
+            $ref: "#/components/schemas/Occupancy"
+        adults:
+          type: integer
+          minimum: 1
+        children:
+          type: array
+          items:
+            type: integer
+        rooms:
+          type: integer
+          minimum: 1
+        currency:
+          type: string
+        guest_nationality:
+          type: string
+          minLength: 2
+          maxLength: 2
+        min_rating:
+          type: number
+        min_star_rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        star_rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        max_star_rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        min_reviews:
+          type: integer
+        max_results:
+          type: integer
+        hotel_type_ids:
+          type: array
+          items:
+            type: string
+        chain_ids:
+          type: array
+          items:
+            type: string
+        facility_ids:
+          type: array
+          items:
+            type: string
+      required:
+        - checkin
+        - checkout
+    HotelDetailsResponse:
+      type: object
+      properties:
+        hotel:
+          type: object
+          properties:
+            id:
+              type: string
+            name:
+              type: string
+            description:
+              type: string
+            star_rating:
+              type: number
+            address:
+              type: string
+            city:
+              type: string
+            country_code:
+              type: string
+            coordinates:
+              type: object
+              properties:
+                latitude:
+                  type: number
+                longitude:
+                  type: number
+            images:
+              type: array
+              items:
+                type: string
+            facilities:
+              type: array
+              items:
+                type: string
+            policies:
+              type: array
+              items:
+                nullable: true
+            checkin_time:
+              type: string
+            checkout_time:
+              type: string
+        rooms:
+          type: array
+          items:
+            nullable: true
+    GetBookingResponse:
+      type: object
+      properties:
+        booking:
+          nullable: true
+    GetBookingRequest:
+      type: object
+      properties:
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+      required:
+        - booking_ref
+        - last_name
+    RefundCheckResponse:
+      type: object
+      properties:
+        is_refundable:
+          type: boolean
+        is_automatable:
+          type: boolean
+        support_level:
+          type: string
+        refund_amount:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        penalty_amount:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        total_paid:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        expires_at:
+          type: string
+        warnings:
+          type: array
+          items:
+            type: string
+    RefundCheckRequest:
+      type: object
+      properties:
+        order_id:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+        ticket_numbers:
+          type: array
+          items:
+            type: string
+        provider:
+          type: string
+    RefundCommitResponse:
+      type: object
+      properties:
+        refund_status:
+          type: string
+        confirmed_refund_amount:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        refund_reference:
+          type: string
+        warnings:
+          type: array
+          items:
+            type: string
+    RefundCommitRequest:
+      type: object
+      properties:
+        order_id:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+        ticket_numbers:
+          type: array
+          items:
+            type: string
+        provider:
+          type: string
+    RefundStatusResponse:
+      type: object
+      properties:
+        refund_status:
+          type: string
+        provider_status:
+          type: string
+        refund_amount:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        refund_reference:
+          type: string
+        warnings:
+          type: array
+          items:
+            type: string
+    RefundStatusRequest:
+      type: object
+      properties:
+        order_id:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+        ticket_numbers:
+          type: array
+          items:
+            type: string
+        provider:
+          type: string
+        refund_reference:
+          type: string
+    ExchangeShopResponse:
+      type: object
+      properties:
+        support_level:
+          type: string
+        offers:
+          type: array
+          items:
+            nullable: true
+        warnings:
+          type: array
+          items:
+            type: string
+    ExchangeShopRequest:
+      type: object
+      properties:
+        order_id:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+        ticket_numbers:
+          type: array
+          items:
+            type: string
+        provider:
+          type: string
+        segments_to_exchange:
+          type: array
+          items:
+            nullable: true
+        preferred_departure_date:
+          type: string
+    ExchangePriceResponse:
+      type: object
+      properties:
+        payment_outcome:
+          type: string
+        fare_difference:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        penalty_amount:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        total_due:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        total_refund:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        session_reference:
+          type: string
+        expires_at:
+          type: string
+        warnings:
+          type: array
+          items:
+            type: string
+    ExchangePriceRequest:
+      type: object
+      properties:
+        order_id:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+        ticket_numbers:
+          type: array
+          items:
+            type: string
+        provider:
+          type: string
+        offer_id:
+          type: string
+      required:
+        - offer_id
+    ExchangeCommitResponse:
+      type: object
+      properties:
+        exchange_reference:
+          type: string
+        new_order_id:
+          type: string
+        new_ticket_numbers:
+          type: array
+          items:
+            type: string
+        status:
+          type: string
+        payment_outcome:
+          type: string
+        warnings:
+          type: array
+          items:
+            type: string
+    ExchangeCommitRequest:
+      type: object
+      properties:
+        order_id:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+        ticket_numbers:
+          type: array
+          items:
+            type: string
+        provider:
+          type: string
+        offer_id:
+          type: string
+        session_reference:
+          type: string
+      required:
+        - offer_id
+        - session_reference
+    ExchangeStatusResponse:
+      type: object
+      properties:
+        status:
+          type: string
+        new_ticket_numbers:
+          type: array
+          items:
+            type: string
+        confirmed_payment_outcome:
+          type: string
+        warnings:
+          type: array
+          items:
+            type: string
+    ExchangeStatusRequest:
+      type: object
+      properties:
+        order_id:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+        ticket_numbers:
+          type: array
+          items:
+            type: string
+        provider:
+          type: string
+    HotelCancelResponse:
+      type: object
+      properties:
+        provider_booking_id:
+          type: string
+        provider:
+          type: string
+        status:
+          type: string
+        refund_amount:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        penalty_amount:
+          type: object
+          properties:
+            value:
+              type: number
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        connector_reference:
+          type: string
+        cancelled_at:
+          type: string
+        idempotent:
+          type: boolean
+    HotelCancelRequest:
+      type: object
+      properties:
+        provider_booking_id:
+          type: string
+        provider:
+          type: string
+        booking_ref:
+          type: string
+        last_name:
+          type: string
+  parameters: {}
+paths:
+  /health:
+    get:
+      tags:
+        - system
+      summary: Service health
+      responses:
+        "200":
+          description: Service is up
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResponse"
+  /v1/find_destination:
+    post:
+      tags:
+        - flights
+      summary: Discover destinations reachable from an origin (cache-backed)
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FindDestinationRequest"
+      responses:
+        "200":
+          description: Matching destinations
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FindDestinationResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/flight_calendar:
+    post:
+      tags:
+        - flights
+      summary: Discover flights for a route + flexible dates (cache-backed)
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FlightDiscoveryRequest"
+      responses:
+        "200":
+          description: Matching itineraries
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlightCalendarResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/flight_search:
+    post:
+      tags:
+        - flights
+      summary: Live-price a route (or re-price an offer_token)
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FlightSearchRequest"
+      responses:
+        "200":
+          description: Priced offers
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlightSearchResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/price_monitoring:
+    post:
+      tags:
+        - flights
+      summary: Poll the cheapest cached price for a fixed route + dates (cache-only)
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PriceMonitoringRequest"
+      responses:
+        "200":
+          description: Cheapest cached itinerary, or stale on a cache miss
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PriceMonitoringResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/trip:
+    post:
+      tags:
+        - cart
+      summary: Create or update a trip (add/remove item, set travelers)
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TripRequest"
+      responses:
+        "200":
+          description: The trip
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TripResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/trip/{trip_id}:
+    get:
+      tags:
+        - cart
+      summary: Get a trip by id
+      security:
+        - ApiKeyAuth: []
+      parameters:
+        - schema:
+            type: string
+          required: true
+          name: trip_id
+          in: path
+      responses:
+        "200":
+          description: The trip
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GetTripResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/select_ancillaries:
+    post:
+      tags:
+        - cart
+      summary: Select ancillaries for a trip item
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AncillaryRequest"
+      responses:
+        "200":
+          description: Updated ancillary selection
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AncillaryResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/book:
+    post:
+      tags:
+        - cart
+      summary: Checkout a trip (returns a payment/checkout URL)
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BookRequest"
+      responses:
+        "200":
+          description: Checkout session
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BookResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/hotel_search:
+    post:
+      tags:
+        - hotels
+      summary: Search hotels by destination, dates, and occupancy
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/HotelSearchRequest"
+      responses:
+        "200":
+          description: Matching hotels
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HotelSearchResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/hotel_details/{hotel_id}:
+    get:
+      tags:
+        - hotels
+      summary: Rich metadata for a single hotel
+      security:
+        - ApiKeyAuth: []
+      parameters:
+        - schema:
+            type: string
+          required: true
+          name: hotel_id
+          in: path
+        - schema:
+            type: string
+          required: false
+          name: checkin
+          in: query
+        - schema:
+            type: string
+          required: false
+          name: checkout
+          in: query
+      responses:
+        "200":
+          description: Hotel detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HotelDetailsResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/get_booking:
+    post:
+      tags:
+        - post-booking
+      summary: Retrieve a booking (flight + hotel) by reference + last name
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GetBookingRequest"
+      responses:
+        "200":
+          description: Retrieve a booking (flight + hotel) by reference + last name
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GetBookingResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/refund_check:
+    post:
+      tags:
+        - post-booking
+      summary: Check flight refund eligibility
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RefundCheckRequest"
+      responses:
+        "200":
+          description: Check flight refund eligibility
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RefundCheckResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/refund_commit:
+    post:
+      tags:
+        - post-booking
+      summary: Initiate a flight refund
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RefundCommitRequest"
+      responses:
+        "200":
+          description: Initiate a flight refund
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RefundCommitResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/refund_status:
+    post:
+      tags:
+        - post-booking
+      summary: Poll a flight refund
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RefundStatusRequest"
+      responses:
+        "200":
+          description: Poll a flight refund
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RefundStatusResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/exchange_shop:
+    post:
+      tags:
+        - post-booking
+      summary: Shop flight exchange alternatives
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExchangeShopRequest"
+      responses:
+        "200":
+          description: Shop flight exchange alternatives
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExchangeShopResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/exchange_price:
+    post:
+      tags:
+        - post-booking
+      summary: Price a flight exchange offer
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExchangePriceRequest"
+      responses:
+        "200":
+          description: Price a flight exchange offer
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExchangePriceResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/exchange_commit:
+    post:
+      tags:
+        - post-booking
+      summary: Execute a flight exchange
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExchangeCommitRequest"
+      responses:
+        "200":
+          description: Execute a flight exchange
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExchangeCommitResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/exchange_status:
+    post:
+      tags:
+        - post-booking
+      summary: Poll a flight exchange
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExchangeStatusRequest"
+      responses:
+        "200":
+          description: Poll a flight exchange
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExchangeStatusResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/hotel_cancel:
+    post:
+      tags:
+        - post-booking
+      summary: Cancel a hotel booking
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/HotelCancelRequest"
+      responses:
+        "200":
+          description: Cancel a hotel booking
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HotelCancelResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"