AegeanBot Bookings API

openapi: 3.2.0
info:
  title: Whitelabel PMS Bookings API
  version: 0.1.0
tags:
- name: Bookings
paths:
  /bookings:
    post:
      summary: Create Booking
      operationId: create_booking_bookings_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
    get:
      summary: List Bookings
      description: 'blocks=1 includes the mirror''s ''blocked'' rows — the calendars need them

        (a closed night is exactly their point); the reservations list does not.'
      operationId: list_bookings_bookings_get
      parameters:
      - name: blocks
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Blocks
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/adjacent:
    get:
      summary: Booking Adjacent
      description: 'The live booking on this listing that ENDS on `checkin`, if any — the

        Multicalendar drawer asks before the owner types, so an extra night for the

        guest already in the unit is entered as a linked extension (one check-out

        reminder, one Climate-fee link, the guest told on their own thread), not

        as an unrelated stay. Guest match is left to the drawer/endpoint: here any

        stay ending that day is returned so the banner can name it.'
      operationId: booking_adjacent_bookings_adjacent_get
      parameters:
      - name: property_id
        in: query
        required: true
        schema:
          type: string
          title: Property Id
      - name: checkin
        in: query
        required: true
        schema:
          type: string
          format: date
          title: Checkin
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/manual:
    post:
      summary: Create Manual Booking
      description: 'Owner-entered reservation from the Multicalendar: inserted as a hold, then

        committed through the SAME confirm path as an owner-confirmed request

        (_do_confirm_request → Channex CRS booking OFL-*, dates closed on every

        channel, Guesty mirror pushed). Cash is the payment mode; ''paid_cash'' marks it

        settled. No guest email is sent here — the check-in / climate-fee / checkout

        automations pick the row up when contact details are present.'
      operationId: create_manual_booking_bookings_manual_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManualBookingIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/local-removal:
    post:
      summary: Remove Booking From Local Calendar
      description: 'Suppress one OTA booking locally without cancelling it at its source.


        The source reservation, payment, and Channex inventory remain untouched.

        An OTA date change automatically invalidates this dated override.'
      operationId: remove_booking_from_local_calendar_bookings__booking_id__local_removal_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
    delete:
      summary: Restore Booking To Local Calendar
      operationId: restore_booking_to_local_calendar_bookings__booking_id__local_removal_delete
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/cancel:
    post:
      summary: Cancel Booking
      operationId: cancel_booking_bookings__booking_id__cancel_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/detail:
    get:
      summary: Booking Detail
      description: 'Unified reservation page: everything about ONE booking in one call —

        the row, financials, pre-check-in, payout leg, review state, message

        thread, and an activity timeline. Accepts the booking_id or the

        guest-facing ref_code, so links can use whichever they have.'
      operationId: booking_detail_bookings__booking_id__detail_get
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/envfee:
    get:
      summary: Get Envfee Status
      description: 'Force-refresh one climate-fee status for the reservation/inbox panel.


        A guest saying "paid" is never treated as proof; this endpoint asks EnvFee

        and returns the same verified view used by reservation detail.'
      operationId: get_envfee_status_bookings__booking_id__envfee_get
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
    put:
      summary: Set Envfee Manual
      description: 'Manual climate-fee mark: the guest paid the host directly (and/or a

        different amount). Sets envfee_manual_* on the reservation; the report then

        shows ''paid'' with this amount instead of envfee''s, and the envfee link

        sender leaves the guest alone. paid=false clears the mark (amount/note kept

        for audit). Owner-scoped; platform operators may mark any booking.'
      operationId: set_envfee_manual_bookings__booking_id__envfee_put
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/arrival-unlock:
    put:
      summary: Set Arrival Unlock
      description: 'Owner force-unlock of the arrival pack for ONE reservation (My Stay §7):

        overrides completeness/fee/balance/timing, never a revoked link.'
      operationId: set_arrival_unlock_bookings__booking_id__arrival_unlock_put
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}:
    put:
      summary: Amend Booking
      description: 'Amend a direct/CRS booking''s dates, guests or guest details. Price is recomputed

        server-side from the calendar. OTA bookings are rejected (manage on the channel).'
      operationId: amend_booking_bookings__booking_id__put
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/settle:
    post:
      summary: Settle Booking
      description: '"Mark as paid": the guest paid the whole amount outside the platform (cash,

        bank transfer, on the OTA, card terminal, other). From here on nothing shows

        a deposit or a remaining balance — badge, drawer, /mystay, reminders, payouts.

        The guest is NOT notified (owner bookkeeping).'
      operationId: settle_booking_bookings__booking_id__settle_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
    delete:
      summary: Unsettle Booking
      description: 'Undo "Mark as paid": the balance shows as owed again (deposit-paid or unpaid).'
      operationId: unsettle_booking_bookings__booking_id__settle_delete
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/move-to-dummy:
    post:
      summary: Move Booking To Dummy
      description: 'Guest relocated / stay handled elsewhere: move the reservation onto the

        tenant''s "dummy" listing on the same dates. The OTA keeps its reservation

        (nothing we can change there); the ORIGINAL listing reopens on Booking.com

        and the other channels (availability recompute + Guesty reopen); a direct

        booking''s Channex CRS twin is cancelled. Guest, money and messages stay.'
      operationId: move_booking_to_dummy_bookings__booking_id__move_to_dummy_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
  /bookings/{booking_id}/move-back:
    post:
      summary: Move Booking Back
      description: 'Undo the move: back onto the original listing (refused when those nights

        were re-sold there). The nights close again on the channels. A direct

        booking whose Channex twin was cancelled stays a local booking.'
      operationId: move_booking_back_bookings__booking_id__move_back_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Bookings
components:
  schemas:
    ManualBookingIn:
      properties:
        property_id:
          type: string
          title: Property Id
        checkin:
          type: string
          format: date
          title: Checkin
        checkout:
          type: string
          format: date
          title: Checkout
        adults:
          type: integer
          title: Adults
          default: 1
        children:
          type: integer
          title: Children
          default: 0
        infants:
          type: integer
          title: Infants
          default: 0
        pets:
          type: integer
          title: Pets
          default: 0
        origin:
          type: string
          title: Origin
          default: manual
        status:
          type: string
          title: Status
          default: confirmed
        amount:
          type: number
          title: Amount
        currency:
          type: string
          title: Currency
          default: EUR
        first_name:
          type: string
          title: First Name
        last_name:
          type: string
          title: Last Name
          default: ''
        guest_email:
          type: string
          title: Guest Email
          default: ''
        guest_phone:
          type: string
          title: Guest Phone
          default: ''
        address:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Address
        notes:
          type: string
          title: Notes
          default: ''
        paid_cash:
          type: boolean
          title: Paid Cash
          default: false
        settled_via:
          type: string
          title: Settled Via
          default: cash
        replaces_booking_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Replaces Booking Id
        cleaning_fee:
          anyOf:
          - type: number
          - type: 'null'
          title: Cleaning Fee
        extends_booking_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Extends Booking Id
      type: object
      required:
      - property_id
      - checkin
      - checkout
      - amount
      - first_name
      title: ManualBookingIn
      description: 'A reservation the owner enters on the Multicalendar (phone / walk-in /

        repeat guest): confirmed at once, no guest-facing page. Mirrors the fields

        of a PMS ''new reservation'' dialog. Amount is the owner''s total, not computed.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BookingIn:
      properties:
        unit_id:
          type: string
          title: Unit Id
        rate_plan_id:
          type: string
          title: Rate Plan Id
        checkin:
          type: string
          format: date
          title: Checkin
        checkout:
          type: string
          format: date
          title: Checkout
        amount:
          type: number
          title: Amount
        currency:
          type: string
          title: Currency
          default: EUR
        guest_name:
          type: string
          title: Guest Name
          default: ''
        channel:
          type: string
          title: Channel
          default: direct
      type: object
      required:
      - unit_id
      - rate_plan_id
      - checkin
      - checkout
      - amount
      title: BookingIn
      description: 'A direct/manual booking the owner enters themselves. OTA bookings arrive

        via the Channex feed, not this endpoint.'