openapi: 3.0.3
info:
  title: MirAmica Public & Partner API
  version: '1.0'
  description: |
    Stage 110 — public widget, guest portal, and partner endpoints.
    Partner API is a **hotel integration toolkit** (`ping`, hotel `bookings`) —
    not marketplace orders. Live: `/api/partner/v1`. Sandbox: `/api/partner/sandbox/v1` (mock only).
servers:
  - url: http://localhost:4000/api
    description: Local API
tags:
  - name: public
  - name: guest-portal
  - name: partner
    description: Hotel integration toolkit (live) — ping + hotel bookings export
  - name: partner-sandbox
    description: Hotel integration toolkit (sandbox fixtures) — mock ping + sample bookings
paths:
  /public/hotel:
    get:
      tags: [public]
      summary: Hotel widget bootstrap
      parameters:
        - name: publicKey
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Hotel meta for widget
  /public/availability:
    get:
      tags: [public]
      summary: Room availability for dates
      parameters:
        - name: publicKey
          in: query
          required: true
          schema: { type: string }
        - name: checkIn
          in: query
          required: true
          schema: { type: string, format: date }
        - name: checkOut
          in: query
          required: true
          schema: { type: string, format: date }
      responses:
        '200':
          description: Availability + rates
  /public/bookings:
    post:
      tags: [public]
      summary: Create booking from widget
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [publicKey, checkIn, checkOut, guestName]
              properties:
                publicKey: { type: string }
                checkIn: { type: string, format: date }
                checkOut: { type: string, format: date }
                guestName: { type: string }
                guestEmail: { type: string }
                guestPhone: { type: string }
                roomTypeId: { type: string }
                guestsCount: { type: integer }
      responses:
        '201':
          description: Booking created
        '200':
          description: Booking created
  /public/widget/analytics:
    post:
      tags: [public]
      summary: Widget funnel beacon
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                publicKey: { type: string }
                event: { type: string, enum: [view, start, book] }
      responses:
        '200':
          description: OK
  /public/guest-portal/{token}:
    get:
      tags: [guest-portal]
      summary: Guest portal booking view
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Voucher / stay summary
  /public/guest-portal/{token}/check-in:
    post:
      tags: [guest-portal]
      summary: Request self check-in
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Check-in requested
  /public/guest-portal/{token}/late-checkout:
    post:
      tags: [guest-portal]
      summary: Request late checkout
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Late checkout requested
  /public/guest-portal/{token}/addons:
    post:
      tags: [guest-portal]
      summary: Request add-on charge
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Addon pending
  /public/guest-portal/{token}/document:
    post:
      tags: [guest-portal]
      summary: Upload check-in document
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Document stored
  /partner/v1/ping:
    get:
      tags: [partner]
      summary: Hotel toolkit — live ping
      description: |
        Health check for the hotel integration toolkit install.
        Not a marketplace endpoint.
      security: [{ ApiKeyAuth: [] }]
      responses:
        '200':
          description: Tenant + app ok
  /partner/v1/bookings:
    get:
      tags: [partner]
      summary: Hotel toolkit — live hotel bookings export
      description: |
        Exports hotel bookings for the install’s tenant.
        Hotel integration toolkit — not marketplace orders.
        On a marketplace-vertical demo tenant this list is usually empty.
      security: [{ ApiKeyAuth: [] }]
      parameters:
        - name: from
          in: query
          schema: { type: string, format: date }
        - name: to
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: Hotel bookings list (not marketplace orders)
  /partner/sandbox/v1/ping:
    get:
      tags: [partner-sandbox]
      summary: Hotel toolkit — sandbox ping (mock)
      description: |
        Sandbox health for the hotel integration toolkit.
        Requires install `sandbox=true`. Not marketplace.
      security: [{ ApiKeyAuth: [] }]
      responses:
        '200':
          description: sandbox true
        '403':
          description: Install not sandbox
        '429':
          description: Rate limited
  /partner/sandbox/v1/bookings:
    get:
      tags: [partner-sandbox]
      summary: Hotel toolkit — sandbox sample hotel bookings
      description: |
        Fixture hotel bookings for sandbox integrators.
        Hotel integration toolkit — not marketplace orders.
      security: [{ ApiKeyAuth: [] }]
      parameters:
        - name: from
          in: query
          schema: { type: string, format: date }
        - name: to
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: Fixture hotel bookings (not marketplace orders)
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key