Hotel Search API — Shopping

naftiko: "1.0.0-alpha2"
info:
  label: "Hotel Search API — Shopping"
  description: 'Hotel Search API — Shopping. 2 operation(s). Lead operation: Amadeus GetMultiHotelOffers. Self-contained Naftiko capability covering one Amadeus business surface.'
  tags:
    - Amadeus
    - Travel
    - Shopping
  created: "2026-05-29"
  modified: "2026-05-29"
binds:
  - namespace: env
    keys:
      AMADEUS_TOKEN: AMADEUS_TOKEN
capability:
  consumes:
    - type: http
      namespace: hotel-search-shopping
      baseUri: https://test.api.amadeus.com/v3
      description: Hotel Search API — Shopping business capability. Self-contained, no shared references.
      authentication:
        type: bearer
        token: '{{env.AMADEUS_TOKEN}}'
      resources:
        - name: shopping-hotel-offers
          path: /shopping/hotel-offers
          operations:
            - name: getMultiHotelOffers
              method: GET
              description: Amadeus GetMultiHotelOffers
              inputParameters:
                - name: hotelIds
                  in: query
                  type: array
                  required: true
                  description: Amadeus property codes on 8 chars. Mandatory parameter for a search by predefined list of hotels.
                - name: adults
                  in: query
                  type: integer
                  required: false
                  description: Number of adult guests (1-9) per room.
                - name: checkInDate
                  in: query
                  type: string
                  required: false
                  description: Check-in date of the stay (hotel local date). Format YYYY-MM-DD. The lowest accepted value is the present date (no dates in the past). If not present, the default value will be today's date in the GMT
                - name: checkOutDate
                  in: query
                  type: string
                  required: false
                  description: Check-out date of the stay (hotel local date). Format YYYY-MM-DD. The lowest accepted value is checkInDate+1. If not present, it will default to checkInDate +1.
                - name: countryOfResidence
                  in: query
                  type: string
                  required: false
                  description: Code of the country of residence of the traveler expressed using ISO 3166-1 format.
                - name: roomQuantity
                  in: query
                  type: integer
                  required: false
                  description: Number of rooms requested (1-9).
                - name: priceRange
                  in: query
                  type: string
                  required: false
                  description: "Filter hotel offers by price per night interval (ex: 200-300 or -300 or 100).\nIt is mandatory to include a currency when this field is set."
                - name: currency
                  in: query
                  type: string
                  required: false
                  description: "Use this parameter to request a specific currency. ISO currency code (http://www.iso.org/iso/home/standards/currency_codes.htm).\nIf a hotel does not support the requested currency, the prices for the "
                - name: paymentPolicy
                  in: query
                  type: string
                  required: false
                  description: Filter the response based on a specific payment type. NONE means all types (default).
                - name: boardType
                  in: query
                  type: string
                  required: false
                  description: "Filter response based on available meals:\n        * ROOM_ONLY = Room Only\n        * BREAKFAST = Breakfast\n        * HALF_BOARD = Diner & Breakfast (only for Aggregators)\n        * FULL_BOARD = Full Bo"
                - name: includeClosed
                  in: query
                  type: boolean
                  required: false
                  description: Show all properties (include sold out) or available only. For sold out properties, please check availability on other dates.
                - name: bestRateOnly
                  in: query
                  type: boolean
                  required: false
                  description: Used to return only the cheapest offer per hotel or all available offers.
                - name: lang
                  in: query
                  type: string
                  required: false
                  description: "Requested language of descriptive texts. \nExamples: FR , fr , fr-FR.\nIf a language is not available the text will be returned in english.\nISO language code (https://www.iso.org/iso-639-language-codes."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: shopping-hotel-offers
          path: /shopping/hotel-offers/{offerId}
          operations:
            - name: getOfferPricing
              method: GET
              description: Amadeus GetOfferPricing
              inputParameters:
                - name: offerId
                  in: path
                  type: string
                  required: true
                  description: Unique identifier of an offer. Either the GDS booking code or the aggregator offerId with a limited lifetime.
                - name: lang
                  in: query
                  type: string
                  required: false
                  description: "Requested language of descriptive texts. \nExamples: FR , fr , fr-FR.\nIf a language is not available the text will be returned in english.\nISO language code (https://www.iso.org/iso-639-language-codes."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
  exposes:
    - type: rest
      namespace: hotel-search-shopping-rest
      port: 8080
      description: REST adapter for Hotel Search API — Shopping. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/shopping/hotel-offers
          name: shopping-hotel-offers
          description: REST surface for shopping-hotel-offers.
          operations:
            - method: GET
              name: getMultiHotelOffers
              description: Amadeus GetMultiHotelOffers
              call: hotel-search-shopping.getMultiHotelOffers
              with:
                hotelIds: rest.hotelIds
                adults: rest.adults
                checkInDate: rest.checkInDate
                checkOutDate: rest.checkOutDate
                countryOfResidence: rest.countryOfResidence
                roomQuantity: rest.roomQuantity
                priceRange: rest.priceRange
                currency: rest.currency
                paymentPolicy: rest.paymentPolicy
                boardType: rest.boardType
                includeClosed: rest.includeClosed
                bestRateOnly: rest.bestRateOnly
                lang: rest.lang
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/shopping/hotel-offers/{offer-id}
          name: shopping-hotel-offers
          description: REST surface for shopping-hotel-offers.
          operations:
            - method: GET
              name: getOfferPricing
              description: Amadeus GetOfferPricing
              call: hotel-search-shopping.getOfferPricing
              with:
                offerId: rest.offerId
                lang: rest.lang
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      namespace: hotel-search-shopping-mcp
      port: 9090
      transport: http
      description: MCP adapter for Hotel Search API — Shopping. One tool per consumed operation, routed inline through this capability's consumes block.
      tools:
        - name: getmultihoteloffers
          description: Amadeus GetMultiHotelOffers
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: hotel-search-shopping.getMultiHotelOffers
          with:
            hotelIds: tools.hotelIds
            adults: tools.adults
            checkInDate: tools.checkInDate
            checkOutDate: tools.checkOutDate
            countryOfResidence: tools.countryOfResidence
            roomQuantity: tools.roomQuantity
            priceRange: tools.priceRange
            currency: tools.currency
            paymentPolicy: tools.paymentPolicy
            boardType: tools.boardType
            includeClosed: tools.includeClosed
            bestRateOnly: tools.bestRateOnly
            lang: tools.lang
          outputParameters:
            - type: object
              mapping: $.
        - name: getofferpricing
          description: Amadeus GetOfferPricing
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: hotel-search-shopping.getOfferPricing
          with:
            offerId: tools.offerId
            lang: tools.lang
          outputParameters:
            - type: object
              mapping: $.