openapi: 3.0.3

info:
  title: Hotel Search API (GRE + TBO)
  description: Unified hotel APIs integrating GRE, GRN and TBO providers
  version: 1.2.0

servers:
  - url: https://all.flightapi.co.in/all-hotels/api
    description: Production server

tags:
  - name: Hotel Search
  - name: PreBook
  - name: Booking
  - name: Booking Status
  - name: Booking Cancellation



paths:

  # =============================
  # SEARCH
  # =============================
  /hotels/search:
    post:
      summary: Unified hotel search (GRE + TBO)
      tags:
        - Hotel Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnifiedHotelSearchRequest'
      responses:
        '200':
          description: Combined hotel search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelSearchResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # =============================
  # OLD SUGGESTIONS
  # =============================
  /hotels/suggestions:
    post:
      summary: Hotel & City suggestions (GRE + TBO)
      tags:
        - Hotel Search
      description: |
        MakeMyTrip-style autocomplete suggestions.
        Searches hotels and cities from GRE and TBO tables.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelSuggestionRequest'
      responses:
        '200':
          description: Suggestions response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelSuggestionResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # =============================
  # NEW SUGGESTIONS (MMT STYLE)
  # =============================
  /hotels/suggestions-new:
    post:
      summary: Advanced hotel & city suggestions (MMT-style)
      tags:
        - Hotel Search
      description: |
        Semantic, intent-based suggestions like:
        - kids friendly hotels
        - family stays
        - villas in city
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelSuggestionNewRequest'
      responses:
        '200':
          description: Advanced suggestions response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelSuggestionNewResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # =============================
  # PREBOOK (GRN + TBO)
  # =============================
  /hotels/prebook:
    post:
      summary: Unified PreBook API (GRN + TBO)
      tags:
        - PreBook
      description: |
        Single pre-book endpoint for GRN and TBO.
        Provider is selected using the `source` field.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreBookRequest'
      responses:
        '200':
          description: PreBook success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreBookResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: PreBook failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # =============================
  # BOOKING (GRN + TBO) ✅ ADDED
  # =============================
  /hotels/book:
    post:
      summary: Unified Hotel Booking API (GRN + TBO)
      tags:
        - Booking
      description: |
        Final booking endpoint.
        Select provider using `source` and pass provider-specific JSON in `payload`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingRequest'
            examples:
              GRN:
                summary: GRN Booking
                value:
                  source: GRN
                  payload:
                    search_id: iyzejucanpmm3iirwlcq7i6qa4
                    hotel_code: "1796373"
                    city_code: "122861"
                    group_code: xgirbylkwb6xtgj647fdssmex6nkls5b7oz6luy
                    checkin: "2026-01-25"
                    checkout: "2026-01-26"
                    payment_type: AT_WEB
                    holder: {}
                    booking_items: []
              TBO:
                summary: TBO Booking
                value:
                  source: TBO
                  payload:
                    request:
                      BookingCode: "1033899!TB!..."
                      IsVoucherBooking: true
                      GuestNationality: IN
                      EndUserIp: "103.80.161.62"
                      RequestedBookingMode: 5
                      NetAmount: 4750.19
                      HotelRoomsDetails: []
      responses:
        '200':
          description: Booking success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '400':
          description: Invalid booking request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Booking failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # =============================
  # BOOKING STATUS (GRN + TBO)
  # =============================
  /hotels/booking/status:
    post:
      summary: Unified Booking Status API (GRN + TBO)
      tags:
        - Booking Status
      description: |
        Check booking status for GRN and TBO.
        Select provider using `source`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingStatusRequest'
            examples:
              GRN:
                summary: GRN Booking Status
                value:
                  source: GRN
                  booking_id: gusqL7Rd1de5xycV
                  type: GRN
              TBO:
                summary: TBO Booking Status
                value:
                  source: TBO
                  booking_id: "456789"
      responses:
        '200':
          description: Booking status fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingStatusResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Status fetch failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


  # =============================
  # BOOKING CANCELLATION (GRN + TBO)
  # =============================
  /hotels/booking/cancel:
    post:
      summary: Unified Booking Cancellation API (GRN + TBO)
      tags:
        - Booking Cancellation
      description: |
        Cancel a confirmed booking for GRN or TBO.
        Provider is selected using `source`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCancelRequest'
            examples:
              GRN:
                summary: GRN Cancellation
                value:
                  source: GRN
                  booking_id: gusqL7Rd1de5xycV
                  comments: test
                  reason: 1
              TBO:
                summary: TBO Cancellation
                value:
                  source: TBO
                  booking_id: "456789"
                  remarks: test
      responses:
        '200':
          description: Cancellation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingCancelResponse'
        '400':
          description: Invalid cancellation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Cancellation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


  /hotels/static-availability:
    post:
      summary: Unified Static Availability (GRN + TBO)
      tags:
        - Hotel Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - city
                - checkin
                - checkout
                - adults
              properties:
                city:
                  type: string
                  example: Bangkok
                checkin:
                  type: string
                  format: date
                checkout:
                  type: string
                  format: date
                adults:
                  type: integer
                  example: 2
                children:
                  type: integer
                  example: 0
      responses:
        '200':
          description: Availability results

  /hotels/search/by-hotel-code:
    post:
      summary: Search specific hotel by hotel_code (TBO / GRN / GRE)
      tags:
        - Hotel Search
      description: |
        Fetch live rates for a single hotel using its provider hotel code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelSearchByCodeRequest'
            examples:
              TBO:
                value:
                  source: TBO
                  hotel_code: "123456"
                  checkin: "2026-02-01"
                  checkout: "2026-02-02"
                  nationality: IN
                  rooms:
                    - adults: 2
                      children: 0
                      childrenAges: []
              GRN:
                value:
                  source: GRN
                  hotel_code: "1796373"
                  checkin: "2026-02-01"
                  checkout: "2026-02-02"
                  nationality: IN
                  rooms:
                    - adults: 2
                      childrenAges: []
      responses:
        '200':
          description: Hotel search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelSearchResponse'


components:
  schemas:

    # ----------------------------
    # SEARCH REQUEST
    # ----------------------------
    UnifiedHotelSearchRequest:
      type: object
      required:
        - checkin
        - checkout
        - nationality
        - rooms
        - city
      properties:
        city:
          type: string
          example: Delhi
        country:
          type: string
          example: IN
        checkin:
          type: string
          format: date
          example: "2026-01-19"
        checkout:
          type: string
          format: date
          example: "2026-01-20"
        nationality:
          type: string
          example: IN
        rooms:
          type: array
          items:
            type: object
            required:
              - adults
            properties:
              adults:
                type: integer
                example: 2
              children:
                type: integer
                example: 0
              childrenAges:
                type: array
                items:
                  type: integer
                example: []

    # ----------------------------
    # SEARCH RESPONSE
    # ----------------------------
    HotelSearchResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        total:
          type: integer
          example: 25
        hotels:
          type: array
          items:
            type: object

    # ----------------------------
    # PREBOOK REQUEST
    # ----------------------------
    PreBookRequest:
      type: object
      required:
        - source
        - booking_code
      properties:
        source:
          type: string
          enum: [GRN, TBO]
          example: GRN
        booking_code:
          type: string
          example: iyzejucanpmm3iirwlcq7i6qa4
        rates:
          type: string
          description: Only applicable for GRN
          example: comprehensive

    # ----------------------------
    # PREBOOK RESPONSE
    # ----------------------------
    PreBookResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        source:
          type: string
          example: GRN
        prebook:
          type: object
          properties:
            bookingId:
              type: string
            price:
              type: number
            currency:
              type: string
            rooms:
              type: array
              items:
                type: object
            cancellationPolicy:
              type: array
              items:
                type: object

    # =============================
    # BOOKING SCHEMAS ✅ ADDED
    # =============================
    BookingRequest:
      type: object
      required:
        - source
        - payload
      properties:
        source:
          type: string
          enum: [GRN, TBO]
          example: GRN
        payload:
          type: object
          description: Provider-specific booking JSON
          additionalProperties: true

    BookingResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        source:
          type: string
          example: GRN
        booking:
          type: object
          properties:
            bookingId:
              type: string
            confirmationNo:
              type: string
            status:
              type: string
            error:
              type: string
              nullable: true
            raw:
              type: object

    # =============================
    # OLD SUGGESTION SCHEMAS
    # =============================
    HotelSuggestionRequest:
      type: object
      required:
        - q
      properties:
        q:
          type: string
          minLength: 2
          example: Bang

    HotelSuggestionResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        hotels:
          type: array
          items:
            $ref: '#/components/schemas/HotelSuggestionItem'
        cities:
          type: array
          items:
            $ref: '#/components/schemas/CitySuggestionItem'

    HotelSuggestionItem:
      type: object
      properties:
        type:
          type: string
        source:
          type: string
        id:
          type: string
        name:
          type: string
        city:
          type: string
        country:
          type: string
        rating:
          type: number
        lat:
          type: string
        lng:
          type: string

    CitySuggestionItem:
      type: object
      properties:
        type:
          type: string
        name:
          type: string
        country:
          type: string

    # =============================
    # NEW SUGGESTION SCHEMAS
    # =============================
    HotelSuggestionNewRequest:
      type: object
      required:
        - q
      properties:
        q:
          type: string
        adults:
          type: integer
        rooms:
          type: integer
        country:
          type: string

    HotelSuggestionNewResponse:
      type: object
      properties:
        success:
          type: boolean
        suggestions:
          type: array
          items:
            $ref: '#/components/schemas/SemanticSuggestionItem'

    SemanticSuggestionItem:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        cityCode:
          type: string
        score:
          type: number
        iconType:
          type: string
        centre:
          type: object
          properties:
            lat:
              type: number
            lng:
              type: number
        semanticPayload:
          type: object

    # ----------------------------
    # ERROR
    # ----------------------------
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string

    # =============================
    # BOOKING STATUS
    # =============================
    BookingStatusRequest:
      type: object
      required:
        - source
        - booking_id
      properties:
        source:
          type: string
          enum: [GRN, TBO]
          example: GRN
        booking_id:
          type: string
          example: gusqL7Rd1de5xycV
        type:
          type: string
          description: Required only for GRN
          example: GRN

    BookingStatusResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        source:
          type: string
          example: GRN
        status:
          type: object
          properties:
            bookingId:
              type: string
            confirmationNo:
              type: string
            status:
              type: string
              example: CONFIRMED
            voucherIssued:
              type: boolean
            error:
              type: string
              nullable: true
            raw:
              type: object

    # =============================
    # BOOKING CANCELLATION
    # =============================
    BookingCancelRequest:
      type: object
      required:
        - source
        - booking_id
      properties:
        source:
          type: string
          enum: [GRN, TBO]
          example: GRN
        booking_id:
          type: string
          example: gusqL7Rd1de5xycV
        comments:
          type: string
          description: GRN only
          example: test
        reason:
          type: integer
          description: GRN only
          example: 1
        remarks:
          type: string
          description: TBO only
          example: test

    BookingCancelResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        source:
          type: string
          example: GRN
        cancellation:
          type: object
          properties:
            bookingId:
              type: string
            status:
              type: string
              example: CANCELLED
            refundAmount:
              type: number
              example: 2500
            currency:
              type: string
              example: INR
            error:
              type: string
              nullable: true
            raw:
              type: object

    HotelSearchByCodeRequest:
      type: object
      required:
        - source
        - hotel_code
        - checkin
        - checkout
        - rooms
      properties:
        source:
          type: string
          enum: [TBO, GRN, GRE]
          example: TBO
        hotel_code:
          type: string
          example: "123456"
        checkin:
          type: string
          format: date
        checkout:
          type: string
          format: date
        nationality:
          type: string
          example: IN
        rooms:
          type: array
          items:
            type: object
            properties:
              adults:
                type: integer
                example: 2
              children:
                type: integer
                example: 0
              childrenAges:
                type: array
                items:
                  type: integer
