openapi: 3.1.0
info:
  title: FullHotel Public API
  version: 1.0.0
  description: |
    Stable public APIs for availability, booking, reservation changes, self check-in and selected public webhooks.
servers:
  - url: https://{tenant-host}
    variables:
      tenant-host:
        default: demo.fullhotel.test
tags:
  - name: Availability
  - name: Booking
  - name: Self Check-in
  - name: Webhooks
paths:
  /api/v1/booking/availability/search:
    post:
      tags: [Availability]
      summary: Search available room types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hotel_id, check_in, check_out, adults]
              properties:
                hotel_id: { type: integer, example: 1 }
                check_in: { type: string, format: date, example: "2026-06-10" }
                check_out: { type: string, format: date, example: "2026-06-13" }
                adults: { type: integer, example: 2 }
                children: { type: integer, example: 0 }
                rooms_count: { type: integer, example: 1 }
      responses:
        "200":
          description: Availability result
  /api/v1/booking/quote:
    post:
      tags: [Booking]
      summary: Build a booking quote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hotel_id, check_in, check_out, adults]
              properties:
                hotel_id: { type: integer, example: 1 }
                check_in: { type: string, format: date }
                check_out: { type: string, format: date }
                adults: { type: integer, example: 2 }
                children: { type: integer, example: 0 }
                rooms_count: { type: integer, example: 1 }
                selected_services:
                  type: array
                  items: { type: integer }
      responses:
        "200":
          description: Quote result
  /api/v1/booking/reservations:
    post:
      tags: [Booking]
      summary: Create a reservation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hotel_id, rate_plan_id, check_in, check_out, guest_first_name, guest_last_name, guest_email]
              properties:
                hotel_id: { type: integer, example: 1 }
                rate_plan_id: { type: integer, example: 22 }
                check_in: { type: string, format: date }
                check_out: { type: string, format: date }
                guest_first_name: { type: string, example: "Luca" }
                guest_last_name: { type: string, example: "Bianchi" }
                guest_email: { type: string, format: email, example: "guest@example.com" }
                payment_option: { type: string, example: "deposit_now" }
      responses:
        "201":
          description: Reservation created
  /api/v1/booking/reservations/{reservation}:
    patch:
      tags: [Booking]
      summary: Modify a reservation
      parameters:
        - in: path
          name: reservation
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Reservation updated
  /api/v1/booking/reservations/{reservation}/cancel:
    post:
      tags: [Booking]
      summary: Cancel a reservation
      parameters:
        - in: path
          name: reservation
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Reservation cancelled
  /api/v1/checkin/sessions:
    post:
      tags: [Self Check-in]
      summary: Start a self check-in session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reservation_id]
              properties:
                reservation_id: { type: integer, example: 145 }
      responses:
        "201":
          description: Session created
  /api/v1/checkin/sessions/{session}:
    get:
      tags: [Self Check-in]
      summary: Read a signed self check-in session
      parameters:
        - in: path
          name: session
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Session payload
  /api/v1/checkin/sessions/{session}/step:
    post:
      tags: [Self Check-in]
      summary: Advance a self check-in step
      parameters:
        - in: path
          name: session
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [step]
              properties:
                step: { type: string, example: "identity" }
      responses:
        "200":
          description: Step processed
  /api/v1/tenant/webhooks/whatsapp-cloud:
    get:
      tags: [Webhooks]
      summary: Verify public WhatsApp inbound webhook
      responses:
        "200":
          description: Verification challenge accepted
    post:
      tags: [Webhooks]
      summary: Receive public WhatsApp inbound events
      responses:
        "200":
          description: Event accepted
  /api/v1/tenant/webhooks/bookingcom:
    post:
      tags: [Webhooks]
      summary: Receive Booking.com webhook events
      responses:
        "200":
          description: Event accepted
  /api/v1/tenant/webhooks/{connector}:
    post:
      tags: [Webhooks]
      summary: Receive generic public channel manager webhook events
      parameters:
        - in: path
          name: connector
          required: true
          schema:
            type: string
            enum: [bookingcom, beddy, expedia, airbnb]
      responses:
        "200":
          description: Event accepted
