> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spaportal.cz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get booking configuration

> Matches partial booking parameters such as destination name, visit type name, hotel name, room type category, and dates.

The response can contain any matched destination, visit type, hotel, room type, price, lowest price, and availability. If the query is incomplete or ambiguous, some fields can be omitted or `availability` can be `null`.

`price.amount` and `lowest_price` include any active discount promotions; individual promotions are itemized in `price.price_breakdown.promotions`.




## OpenAPI

````yaml /api/v1/openapi.yaml get /booking
openapi: 3.0.3
info:
  title: SpaPortal API v1
  version: '1.0'
  description: Public API for booking clients that integrate with SpaPortal.
servers:
  - url: https://spaportal.cz/api/v1
    description: Production
security:
  - bearerAuth: []
  - accessTokenQuery: []
tags:
  - name: System
  - name: Catalog
  - name: Availability
  - name: Pricing
  - name: Booking
paths:
  /booking:
    get:
      tags:
        - Booking
      summary: Get booking configuration
      description: >
        Matches partial booking parameters such as destination name, visit type
        name, hotel name, room type category, and dates.


        The response can contain any matched destination, visit type, hotel,
        room type, price, lowest price, and availability. If the query is
        incomplete or ambiguous, some fields can be omitted or `availability`
        can be `null`.


        `price.amount` and `lowest_price` include any active discount
        promotions; individual promotions are itemized in
        `price.price_breakdown.promotions`.
      operationId: getBookingConfiguration
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - name: destination_name
          in: query
          schema:
            type: string
          description: Destination name in any supported language.
        - name: visit_type_name
          in: query
          schema:
            type: string
          description: Visit type name in any supported language.
        - name: hotel_name
          in: query
          schema:
            type: string
          description: Hotel name in any supported language.
        - name: room_type_category
          in: query
          schema:
            type: string
          description: Room type category in any supported language.
        - $ref: '#/components/parameters/DateFrom'
        - $ref: '#/components/parameters/DateTo'
      responses:
        '200':
          description: Matched booking configuration, availability, and price data.
          headers:
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingConfiguration'
              examples:
                default:
                  $ref: '#/components/examples/BookingConfigurationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    AcceptLanguage:
      name: Accept-Language
      in: header
      schema:
        type: string
        example: cs_CZ,de
      description: >-
        Comma-separated list of languages to include. See
        [Localization](/api/v1/localization) for details.
    DateFrom:
      name: date_from
      in: query
      schema:
        type: string
        format: date
      description: Start date in `YYYY-MM-DD` format.
    DateTo:
      name: date_to
      in: query
      schema:
        type: string
        format: date
      description: End date in `YYYY-MM-DD` format.
  headers:
    ContentLanguage:
      description: Languages included in the response.
      schema:
        type: string
        example: cs_CZ,de
  schemas:
    BookingConfiguration:
      type: object
      properties:
        availability:
          type: string
          nullable: true
          enum:
            - NOT_AVAILABLE
            - AVAILABLE
            - ON_DEMAND
        date_from:
          type: string
          format: date
        date_to:
          type: string
          format: date
        destination:
          $ref: '#/components/schemas/Destination'
        hotel:
          $ref: '#/components/schemas/Hotel'
        visit_type:
          $ref: '#/components/schemas/VisitType'
        room_type:
          $ref: '#/components/schemas/RoomType'
        price:
          $ref: '#/components/schemas/PriceByLanguage'
        lowest_price:
          $ref: '#/components/schemas/LowestPriceByLanguage'
    Destination:
      type: object
      required:
        - id
        - name
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          type: integer
        name:
          $ref: '#/components/schemas/LocalizedString'
    Hotel:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          type: integer
        name:
          type: string
        stars:
          type: integer
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
        phone_number:
          type: string
        email:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/LocalizedString'
        equipment:
          $ref: '#/components/schemas/LocalizedString'
        services:
          $ref: '#/components/schemas/LocalizedString'
        lowest_price:
          $ref: '#/components/schemas/LowestPriceByLanguage'
        commercial_slogan:
          $ref: '#/components/schemas/LocalizedString'
        image:
          type: string
          nullable: true
        thumbnail:
          type: string
          nullable: true
        booking_url:
          $ref: '#/components/schemas/LocalizedString'
        destination:
          $ref: '#/components/schemas/Destination'
        roomTypes:
          type: array
          items:
            $ref: '#/components/schemas/RoomType'
    VisitType:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          oneOf:
            - type: integer
            - type: string
        priority_position:
          type: integer
        on_demand:
          type: boolean
        name:
          $ref: '#/components/schemas/LocalizedString'
        visit_type_categories:
          type: array
          items:
            $ref: '#/components/schemas/VisitTypeCategory'
        booking_url:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/LocalizedString'
        nights_min:
          type: integer
        nights_max:
          type: integer
        reservation_time_span:
          type: string
          enum:
            - DAYS
            - WEEKS
        time_constraints:
          type: array
          items:
            $ref: '#/components/schemas/TimeConstraint'
        procedures:
          type: integer
        procedure_frequency:
          type: string
          enum:
            - DAY
            - WEEK
            - VISIT
        procedures_per_day:
          type: integer
        boarding:
          type: string
        available_boardings:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        lowest_price:
          $ref: '#/components/schemas/LowestPriceByLanguage'
        promotions:
          type: array
          description: >-
            Active current-or-future promotions for this visit type's price
            list, scoped to the caller's channel (empty when none apply).
          items:
            $ref: '#/components/schemas/Promotion'
        commercial_slogan:
          $ref: '#/components/schemas/LocalizedString'
        notice:
          $ref: '#/components/schemas/LocalizedString'
        services:
          $ref: '#/components/schemas/LocalizedString'
        hotels:
          type: array
          items:
            type: object
            properties:
              _id:
                $ref: '#/components/schemas/ObjectId'
              id:
                type: integer
              name:
                type: string
              lowest_price:
                $ref: '#/components/schemas/LowestPriceByLanguage'
              promotions:
                type: array
                description: Promotions from the visit-type set that apply to this hotel.
                items:
                  $ref: '#/components/schemas/Promotion'
        loyalty_programs:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyProgram'
    RoomType:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          type: integer
        category:
          $ref: '#/components/schemas/LocalizedString'
        facilities:
          type: array
          items:
            type: string
        beds:
          type: integer
        image:
          type: string
          nullable: true
        thumbnail:
          type: string
          nullable: true
        booking_url:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/LocalizedString'
        lowest_price:
          $ref: '#/components/schemas/LowestPriceByLanguage'
        hotel:
          type: object
          description: Included on price list room type items.
          properties:
            _id:
              $ref: '#/components/schemas/ObjectId'
            id:
              type: integer
            name:
              type: string
            stars:
              type: integer
              nullable: true
    PriceByLanguage:
      type: object
      additionalProperties:
        allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
          - type: object
            properties:
              price_breakdown:
                type: object
                description: >-
                  How the top-level `amount` is composed: `base_price` minus
                  loyalty discounts and promotions.
                additionalProperties: true
                properties:
                  base_price:
                    type: number
                    description: Pre-discount total for the stay, in the response currency.
                  discounts:
                    type: array
                    description: Loyalty-program discounts (per guest).
                    items:
                      type: object
                      additionalProperties: true
                  promotions:
                    type: array
                    description: >-
                      Discount promotions applied to the stay. The top-level
                      `amount` already accounts for them.
                    items:
                      $ref: '#/components/schemas/PromotionLine'
    LowestPriceByLanguage:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/LowestPriceAmount'
    ErrorResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
    ValidationErrorResponse:
      type: object
      required:
        - success
        - message
        - errors
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            additionalProperties: true
    ObjectId:
      type: string
      pattern: ^[0-9a-fA-F]{24}$
      description: Object id (24-character hex string) for the same entity.
      example: 66f16191f739705faa020001
    LocalizedString:
      type: object
      additionalProperties:
        type: string
        nullable: true
      example:
        cs_CZ: Frantiskovy Lazne
        de: Franzensbad
    Address:
      type: object
      properties:
        address_line:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
    VisitTypeCategory:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          oneOf:
            - type: integer
            - type: string
        name:
          $ref: '#/components/schemas/LocalizedString'
        visitTypes:
          type: array
          items:
            $ref: '#/components/schemas/VisitTypeSummary'
    TimeConstraint:
      type: object
      properties:
        date_from:
          type: string
          format: date
        date_to:
          type: string
          format: date
    Tag:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          oneOf:
            - type: integer
            - type: string
        name:
          $ref: '#/components/schemas/LocalizedString'
        color:
          type: string
          description: Hex color without the `#` prefix.
    Promotion:
      type: object
      description: >-
        A discount promotion advertised for a visit type's price list (and per
        hotel), listed by GET /visit-types. Includes promotions running now OR
        starting in the future (expired ones are omitted), scoped to the
        caller's channel. The discounted "from" price is already reflected in
        `lowest_price` (`amount_per_night` vs `original_amount_per_night`); this
        object adds the promotion's name, percentage and validity for a
        label/badge. Itemized per-stay discounts (with amount/nights) remain in
        `price_breakdown.promotions` on GET /price.
      properties:
        name:
          $ref: '#/components/schemas/LocalizedString'
        percentage:
          type: number
          description: Discount percentage (0-100).
        valid_from:
          type: string
          format: date
          description: First day of the promotion's stay-date validity (UTC `YYYY-MM-DD`).
        valid_to:
          type: string
          format: date
          nullable: true
          description: >-
            Exclusive end of the validity window (UTC `YYYY-MM-DD`); null for
            unlimited.
    LoyaltyProgram:
      type: object
      additionalProperties: true
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          oneOf:
            - type: integer
            - type: string
        name:
          $ref: '#/components/schemas/LocalizedString'
    CurrencyAmount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          nullable: true
        currency:
          type: string
          enum:
            - CZK
            - EUR
    PromotionLine:
      type: object
      description: >-
        A discount promotion reflected in the price breakdown. The top-level
        `amount` already has it subtracted.
      properties:
        name:
          $ref: '#/components/schemas/LocalizedString'
        percentage:
          type: number
          description: Discount percentage (0-100).
        amount:
          type: number
          description: >-
            Discount amount for this promotion, for the whole room, in the
            response currency.
        nights:
          type: integer
          description: Number of stay nights the promotion applies to.
        valid_from:
          type: string
          format: date
          description: First discounted night (UTC `YYYY-MM-DD`).
        valid_to:
          type: string
          format: date
          description: >-
            Exclusive end of the discounted range (UTC `YYYY-MM-DD`); the night
            of this date is not discounted. This is the range actually applied —
            the overlap of the promotion's validity with the stay.
    LowestPriceAmount:
      type: object
      properties:
        amount_per_night:
          type: number
          nullable: true
          description: >-
            Lowest per-night, per-guest price, including any active discount
            promotions.
        original_amount_per_night:
          type: number
          nullable: true
          description: >-
            Per-night price before any discount. Equals `amount_per_night` when
            no promotion applies; higher when a promotion is active.
        currency:
          type: string
          enum:
            - CZK
            - EUR
    VisitTypeSummary:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ObjectId'
        id:
          oneOf:
            - type: integer
            - type: string
        priority_position:
          type: integer
        on_demand:
          type: boolean
        name:
          $ref: '#/components/schemas/LocalizedString'
        nights_min:
          type: integer
        nights_max:
          type: integer
        reservation_time_span:
          type: string
          enum:
            - DAYS
            - WEEKS
  examples:
    BookingConfigurationResponse:
      summary: Booking configuration
      value:
        destination:
          _id: 66f16191f739705faa020001
          id: 1
          name:
            cs_CZ: Frantiskovy Lazne
            de: Franzensbad
        visit_type:
          _id: 66f16191f739705faa020004
          id: 1
          priority_position: 1
          on_demand: false
          name:
            cs_CZ: Frantiskolazenska lecebna kura
            de: Franzensbader Heilkur
          nights_min: 1
          nights_max: 3
          reservation_time_span: DAYS
        hotel:
          _id: 66f16191f739705faa020002
          id: 1
          name: Pawlik
          stars: 4
        room_type:
          _id: 66f16191f739705faa020003
          id: 1
          category:
            cs_CZ: Prezidentske apartma
            de: App. Aquaforum
          beds: 2
        date_from: '2026-12-02'
        date_to: '2026-12-16'
        price:
          cs_CZ:
            amount: 10200
            currency: CZK
            price_breakdown:
              base_price: 12000
              discounts: []
              promotions:
                - name:
                    cs_CZ: Letní sleva
                    de: Sommerrabatt
                    en: Summer discount
                  percentage: 15
                  amount: 1800
                  nights: 4
                  valid_from: '2026-06-21'
                  valid_to: '2026-06-25'
          de:
            amount: 408
            currency: EUR
            price_breakdown:
              base_price: 480
              discounts: []
              promotions:
                - name:
                    cs_CZ: Letní sleva
                    de: Sommerrabatt
                    en: Summer discount
                  percentage: 15
                  amount: 72
                  nights: 4
                  valid_from: '2026-06-21'
                  valid_to: '2026-06-25'
        lowest_price:
          cs_CZ:
            amount_per_night: 1024.5
            original_amount_per_night: 1205.29
            currency: CZK
          de:
            amount_per_night: 40
            original_amount_per_night: 47.06
            currency: EUR
        availability: ON_DEMAND
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - $ref: '#/components/schemas/ValidationErrorResponse'
    Unauthorized:
      description: Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Resource exists but cannot be used for this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        See [Authentication](/api/v1/authentication) for how to obtain and send
        your API key.
    accessTokenQuery:
      type: apiKey
      in: query
      name: access_token
      description: >-
        See [Authentication](/api/v1/authentication) for how to obtain and send
        your API key.

````