openapi: 3.0.3

info:
  title: TBO Hotel Booking API
  description: |
    Node.js wrapper API for TBO (TekTravel) Hotel APIs.
    Covers cities, search, availability, block room, prebook,
    booking, status, voucher and cancellation.
  version: 1.0.0

servers:
  - url: http://localhost:4000/api
    description: Local
  - url: https://all.flightapi.co.in/tbo-hotels/api
    description: Production

tags:
  - name: Cities
  - name: Static Data
  - name: Search
  - name: Availability
  - name: Block
  - name: PreBook
  - name: Booking
  - name: Voucher
  - name: Cancellation

paths:

  # ===================== CITIES =====================

  /tbo/hotels/cities:
    post:
      tags: [Cities]
      summary: Get TBO Cities by Country
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboCityRequest'
      responses:
        '200':
          description: City list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboCityResponse'
        '500':
          description: Server error

  # ===================== STATIC DATA =====================

  /tbo/hotels/countries:
    post:
      tags: [Static Data]
      summary: Fetch TBO Country List
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboCountryListRequest'
      responses:
        '200':
          description: Country sync response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboStaticSyncResponse'
        '500':
          description: Server error

  /tbo/hotels/hotel-code-list:
    post:
      tags: [Static Data]
      summary: Fetch TBO Hotel Code List
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboHotelCodeListRequest'
      responses:
        '200':
          description: Hotel code list sync response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboStaticSyncResponse'
        '400':
          description: Bad request
        '500':
          description: Server error

  /tbo/hotels/tbo-hotel-code-list:
    post:
      tags: [Static Data]
      summary: Fetch TBO TBOHotelCodeList
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboHotelCodeListRequest'
      responses:
        '200':
          description: Hotel code list sync response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboStaticSyncResponse'
        '400':
          description: Bad request
        '500':
          description: Server error

  /tbo/hotels/hotel-details:
    post:
      tags: [Static Data]
      summary: Fetch TBO Hotel Details
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboHotelDetailsRequest'
      responses:
        '200':
          description: Hotel details sync response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboStaticSyncResponse'
        '400':
          description: Bad request
        '500':
          description: Server error

  # ===================== SEARCH =====================

  /tbo/hotels/search:
    post:
      tags: [Search]
      summary: TBO Hotel Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboSearchRequest'
      responses:
        '200':
          description: Successful hotel search
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '500':
          description: Internal server error

  /tbo/hotels/search-v2:
    post:
      tags: [Search]
      summary: TBO Hotel Search (Markup + Conversion Response)
      security:
        - BearerAuth: []
      parameters:
        - in: header
          name: Authorization
          required: true
          schema:
            type: string
          description: Bearer JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboSearchRequest'
      responses:
        '200':
          description: Successful hotel search
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '500':
          description: Internal server error



  # ===================== AVAILABILITY =====================

  /tbo/hotels/availability:
    post:
      tags: [Availability]
      summary: Get Hotel Availability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboAvailabilityRequest'
      responses:
        '200':
          description: Availability response (dynamic)
          content:
            application/json:
              schema: {}
        '500':
          description: Server error

  # ===================== BLOCK =====================

  /tbo/hotels/block:
    post:
      tags: [Block]
      summary: Block Room (Price Recheck)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboBlockRequest'
      responses:
        '200':
          description: Block room response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboBlockResponse'
        '500':
          description: Server error

  # ===================== PREBOOK =====================

  /tbo/hotels/prebook:
    post:
      tags: [PreBook]
      summary: PreBook Hotel (Mandatory before booking)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboPreBookRequest'
      responses:
        '200':
          description: PreBook response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboPreBookResponse'
        '500':
          description: Server error

  # ===================== BOOKING =====================

  /tbo/bookings/book:
    post:
      tags: [Booking]
      summary: Confirm Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboBookingRequest'
      responses:
        '200':
          description: Booking response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboBookingResponse'
        '500':
          description: Server error

  # ===================== BOOKING STATUS =====================

  /tbo/bookings/status:
    post:
      tags: [Booking]
      summary: Get Booking Status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboBookingStatusRequest'
      responses:
        '200':
          description: Booking status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboBookingStatusResponse'
        '500':
          description: Server error

  # ===================== VOUCHER =====================

  /tbo/bookings/voucher:
    post:
      tags: [Voucher]
      summary: Get Booking Voucher
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboVoucherRequest'
      responses:
        '200':
          description: Voucher response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboVoucherResponse'
        '500':
          description: Server error

  # ===================== CANCELLATION =====================

  /tbo/bookings/cancel:
    post:
      tags: [Cancellation]
      summary: Cancel Booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboCancellationRequest'
      responses:
        '200':
          description: Cancellation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboCancellationResponse'
        '500':
          description: Server error



  /tbo/hotels/availability/list:
    post:
      tags: [Availability]
      summary: List available hotels from cache (DB)
      description: >
        Returns available hotels and prices from database.
        Data is populated during TBO Search API calls.
        No live TBO API call is made here.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TboAvailabilityListRequest'
      responses:
        '200':
          description: Available hotels list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TboAvailabilityListResponse'
        '400':
          description: Bad request
        '500':
          description: Server error


# ===================== SCHEMAS =====================

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:

    # -------- Cities --------
    TboCityRequest:
      type: object
      properties:
        country_code:
          type: string
          example: IN

    TboCityResponse:
      type: object
      properties:
        status:
          type: string
        data:
          type: object

    # -------- Static Data --------
    TboCountryListRequest:
      type: object
      properties:
        payload:
          type: object
          description: Optional raw payload forwarded to TBO CountryList

    TboHotelCodeListRequest:
      type: object
      properties:
        CityCode:
          type: string
          description: TBO CityCode
        city_code:
          type: string
          description: TBO CityCode (preferred)
        CountryCode:
          type: string
          description: TBO CountryCode
        country_code:
          type: string
          description: TBO CountryCode (optional)
        IsDetailedResponse:
          type: boolean
          description: TBO IsDetailedResponse flag
        is_detailed:
          type: boolean
          description: Request detailed response when supported
        payload:
          type: object
          description: Optional raw payload forwarded to TBO

    TboHotelDetailsRequest:
      type: object
      properties:
        Hotelcodes:
          type: string
          description: Comma-separated hotel codes or single code
        HotelCodes:
          type: string
          description: Comma-separated hotel codes or single code
        hotel_code:
          type: string
        hotel_codes:
          type: array
          items:
            type: string
        Language:
          type: string
        IsRoomDetailRequired:
          type: boolean
        language:
          type: string
        payload:
          type: object
          description: Optional raw payload forwarded to TBO

    TboStaticSyncResponse:
      type: object
      properties:
        status:
          type: string
        total:
          type: integer
        message:
          type: string
        source_key:
          type: string
        data:
          type: array
          items: {}

    # -------- Search --------
    TboSearchRequest:
      type: object
      required: [CheckIn, CheckOut, PaxRooms]
      properties:
        city: { type: string }
        country: { type: string }
        CheckIn:
          type: string
          format: date
        CheckOut:
          type: string
          format: date
        HotelCodes:
          type: string
          example: "1281366,1249344"
        GuestNationality:
          type: string
          example: IN
        nationality:
          type: string
          description: Alias of GuestNationality (use one; GuestNationality preferred)
        PaxRooms:
          type: array
          items:
            type: object
            properties:
              Adults:
                type: integer
              Children:
                type: integer
              ChildrenAges:
                type: array
                items:
                  type: integer
        ResponseTime:
          type: number
        IsDetailedResponse:
          type: boolean

    # -------- Availability --------
    TboAvailabilityRequest:
      type: object
      required: [trace_id, result_index]
      properties:
        trace_id:
          type: string
        result_index:
          type: integer

    # -------- Block --------
    TboBlockRequest:
      type: object
      required: [trace_id, result_index, hotel_code, rooms]
      properties:
        trace_id:
          type: string
        result_index:
          type: integer
        hotel_code:
          type: string
        rooms:
          type: array
          items:
            type: object
            properties:
              room_index:
                type: integer

    TboBlockResponse:
      type: object
      properties:
        data:
          type: object

    # -------- PreBook --------
    TboPreBookRequest:
      type: object
      required: [booking_code]
      properties:
        booking_code:
          type: string

    TboPreBookResponse:
      type: object
      properties:
        status:
          type: string
        data:
          type: object

    # -------- Booking --------
    TboBookingRequest:
      type: object
      properties:
        payload:
          type: object

    TboBookingResponse:
      type: object
      properties:
        BookingId:
          type: string
        BookingStatus:
          type: string

    # -------- Status --------
    TboBookingStatusRequest:
      type: object
      required: [booking_id]
      properties:
        booking_id:
          type: string

    TboBookingStatusResponse:
      type: object
      properties:
        BookingStatus:
          type: string

    # -------- Voucher --------
    TboVoucherRequest:
      type: object
      required: [booking_id]
      properties:
        booking_id:
          type: string

    TboVoucherResponse:
      type: object
      properties:
        BookingId:
          type: string
        Guests:
          type: array
          items:
            type: object

    # -------- Cancellation --------
    TboCancellationRequest:
      type: object
      required: [booking_id]
      properties:
        booking_id:
          type: string
        remarks:
          type: string

    TboCancellationResponse:
      type: object
      properties:
        BookingId:
          type: string
        CancellationStatus:
          type: string
        RefundAmount:
          type: number
        Currency:
          type: string

    # -------- Availability List (DB Based) --------
    TboAvailabilityListRequest:
      type: object
      required: [city_name, checkin, checkout]
      properties:
        city_code:
          type: string
          example: "Pattaya"
        checkin:
          type: string
          format: date
          example: "2026-01-28"
        checkout:
          type: string
          format: date
          example: "2026-01-29"
        numberOfAdults:
          type: integer
          example: 2
          default: 1
        numberOfChild:
          type: integer
          example: 0
          default: 0

    TboAvailabilityListResponse:
      type: object
      properties:
        status:
          type: string
          example: SUCCESS
        total:
          type: integer
          example: 12
        hotels:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 2451
              hotel_code:
                type: string
                example: "1281366"
              hotel_name:
                type: string
                example: "Lemon Tree Premier"
              images:
                type: array
                items:
                  type: string
              address:
                type: string
                example: "Connaught Place, New Delhi"
              city_name:
                type: string
                example: "Delhi"
              country_name:
                type: string
                example: "India"
              hotel_rating:
                type: integer
                example: 4
              last_min_price:
                type: number
                example: 4200
              currency:
                type: string
                example: "INR"
              last_checked_at:
                type: string
                format: date-time
                example: "2026-01-23T10:30:00Z"
