openapi: 3.1.0
info:
  title: Blinkerbot booking connection contract
  version: 1.0.0
  summary: The single endpoint your booking system exposes so Blinkerbot can read free slots and create real bookings.
  description: |
    Blinkerbot calls **one URL on your side** (`POST {endpoint_url}`) for every
    operation; the operation name is inside the signed JSON body. This file
    describes that call as an OpenAPI `webhook` (`bookingContract`) plus the
    one Blinkerbot API your package calls during setup (`POST /public/v1/pair`).

    **Signature (Standard Webhooks v1).** Every request carries
    `webhook-id`, `webhook-timestamp` (Unix seconds) and `webhook-signature`
    (`v1,<base64 HMAC-SHA256>`, several space-separated signatures are possible
    while a secret is being rotated - accept the request if any one matches).
    The signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`; the
    key is the base64-decoded part after `whsec_` of your signing secret.
    Read the raw body before parsing, reject timestamps more than 5 minutes
    away, compare in constant time, answer HTTP 401 when the check fails.

    **Answers.** Success: HTTP 200 `{"ok":true,"data":...}`. Business error:
    HTTP 200 `{"ok":false,"error":{"code":"...","message":"..."}}` with one of
    the `BusinessErrorCode` values. The `message` is never shown to the
    assistant or the customer. Timeouts, 5xx, 429, HTML or non-JSON answers
    and `request_in_progress` count as "unreachable" (Blinkerbot keeps the
    request pending and retries with the same idempotency key). Every 5xx,
    501 included, is "unreachable", so never answer 5xx for something you do
    not support. Any other status code (400, 403, 404, 3xx...) is a permanent
    error. Answers over 65536 bytes are refused (permanent error).

    **Not implemented.** An operation you do not support (the optional
    `get_booking`, an unknown operation) answers HTTP 200
    `{"ok":false,"error":{"code":"not_implemented"}}`. `not_implemented` is
    not a business code: Blinkerbot treats it as a permanent "not supported
    here" (the panel test skips an optional step that answers it).

    **Capabilities.** `ping` may list optional features in
    `data.capabilities`. Send `["replaces_booking_id"]` when `create_booking`
    handles `replaces_booking_id` in one transaction; without it Blinkerbot
    moves a booking by creating the new one first and cancelling the old one
    afterwards (which fails when the two times overlap for the same staff).

    **Idempotency.** `create_booking` (and `cancel_booking`) carry an
    `idempotency_key`. The same key with the same `operation` + `data` must
    return the first answer without creating anything new; the same key with
    other content returns `idempotency_mismatch`; a request still running with
    the same key returns `request_in_progress` (or waits and returns the same
    answer). Keep keys at least 7 days and write them in the same database
    transaction as the booking. Content is compared with the SHA-256 of the
    canonical JSON (sorted keys, no spaces) of `{"data":...,"operation":...}`.

    **Test mode.** `test: true` runs the operation fully but rolls the
    transaction back: nothing is kept (the answer for the idempotency key may
    be kept so that a repeated test request returns the same booking id).

    **Time limits (ms).** Phone: find_slots 2500, create/cancel/get 3500.
    Chat: find_slots 5000, create/cancel/get 8000. ping/list_services 5000.
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://api.blinkerbot.com
    description: Blinkerbot API (only used for pairing)
paths:
  /public/v1/pair:
    post:
      operationId: pair
      summary: Exchange a one-time pairing code for the signing secret
      description: |
        Called once by your package when the owner pastes the `blk_pair_...`
        code (valid 2 hours, single use). Blinkerbot stores your endpoint
        URL and returns the signing secret exactly once. Store it in a private
        file (mode 0600, outside the web root) and never print it. A wrong,
        used or expired code always gets the same answer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PairRequest'
      responses:
        '200':
          description: Paired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairSuccess'
        '400':
          description: Wrong, used or expired code, or an endpoint URL that is not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairFailure'
        '429':
          description: Too many attempts
webhooks:
  bookingContract:
    post:
      operationId: bookingContract
      summary: Every booking operation, sent by Blinkerbot to your endpoint URL
      parameters:
        - name: webhook-id
          in: header
          required: true
          description: Unique message id, new for every attempt.
          schema:
            type: string
            maxLength: 256
        - name: webhook-timestamp
          in: header
          required: true
          description: Unix seconds. Reject if more than 300 seconds away from your clock.
          schema:
            type: string
            pattern: '^[0-9]{1,12}$'
        - name: webhook-signature
          in: header
          required: true
          description: '`v1,<base64>`; several values may be separated by spaces.'
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractRequest'
      responses:
        '200':
          description: Success, business error, or not_implemented (an operation you do not support; never a 5xx)
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - $ref: '#/components/schemas/BusinessErrorResponse'
                  - $ref: '#/components/schemas/NotImplementedResponse'
        '400':
          description: Signed but malformed request (permanent error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TechnicalErrorResponse'
        '401':
          description: Signature or timestamp rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TechnicalErrorResponse'
components:
  schemas:
    Operation:
      type: string
      enum: [ping, list_services, find_slots, create_booking, get_booking, cancel_booking]
    BusinessErrorCode:
      type: string
      enum:
        - slot_unavailable
        - invalid_service
        - invalid_staff
        - outside_hours
        - invalid_customer
        - booking_not_found
        - cancellation_not_allowed
        - idempotency_mismatch
        - request_in_progress
    Timestamp:
      type: string
      description: ISO 8601 with UTC offset, e.g. 2026-11-20T14:00:00+03:00
      pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$'
    TimeZone:
      type: string
      description: IANA time zone, e.g. Europe/Istanbul
      examples: [Europe/Istanbul]
    Envelope:
      type: object
      required: [operation, request_id, idempotency_key, account, test, data]
      properties:
        operation:
          $ref: '#/components/schemas/Operation'
        request_id:
          type: string
          description: Unique per request, for your logs.
        idempotency_key:
          type: [string, 'null']
          maxLength: 255
          description: Required for create_booking. Same key + same content -> same answer.
        account:
          type: [string, 'null']
          description: Set only when one endpoint serves several businesses (software vendors). Usually null.
        test:
          type: boolean
          description: true -> run the operation but keep nothing (roll the transaction back).
        data:
          type: object
    ContractRequest:
      oneOf:
        - $ref: '#/components/schemas/PingRequest'
        - $ref: '#/components/schemas/ListServicesRequest'
        - $ref: '#/components/schemas/FindSlotsRequest'
        - $ref: '#/components/schemas/CreateBookingRequest'
        - $ref: '#/components/schemas/GetBookingRequest'
        - $ref: '#/components/schemas/CancelBookingRequest'
      discriminator:
        propertyName: operation
        mapping:
          ping: '#/components/schemas/PingRequest'
          list_services: '#/components/schemas/ListServicesRequest'
          find_slots: '#/components/schemas/FindSlotsRequest'
          create_booking: '#/components/schemas/CreateBookingRequest'
          get_booking: '#/components/schemas/GetBookingRequest'
          cancel_booking: '#/components/schemas/CancelBookingRequest'
    PingRequest:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            operation:
              const: ping
            data:
              type: object
    ListServicesRequest:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            operation:
              const: list_services
            data:
              type: object
    FindSlotsRequest:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            operation:
              const: find_slots
            data:
              $ref: '#/components/schemas/FindSlotsData'
    CreateBookingRequest:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            operation:
              const: create_booking
            idempotency_key:
              type: string
              minLength: 1
              maxLength: 255
            data:
              $ref: '#/components/schemas/CreateBookingData'
    GetBookingRequest:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            operation:
              const: get_booking
            data:
              $ref: '#/components/schemas/BookingRef'
    CancelBookingRequest:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            operation:
              const: cancel_booking
            data:
              $ref: '#/components/schemas/BookingRef'
    FindSlotsData:
      type: object
      required: [service_id, from, to, timezone]
      properties:
        service_id:
          type: string
        staff_id:
          type: string
          description: Only slots of this staff member.
        from:
          $ref: '#/components/schemas/Timestamp'
        to:
          $ref: '#/components/schemas/Timestamp'
        timezone:
          $ref: '#/components/schemas/TimeZone'
        limit:
          type: integer
          minimum: 1
          maximum: 500
          description: |
            Answer at most this many slots, the earliest first (sorted by
            start). Absent -> at most 500. Keep the whole answer under 65536
            bytes; a larger answer is refused. The panel test sends 50.
    Customer:
      type: object
      required: [name, phone]
      properties:
        name:
          type: string
          minLength: 1
        phone:
          type: string
          minLength: 1
          description: E.164, e.g. +905551112233
        email:
          type: string
    CreateBookingData:
      type: object
      required: [service_id, start, end, timezone, customer, channel]
      properties:
        service_id:
          type: string
        staff_id:
          type: string
        start:
          $ref: '#/components/schemas/Timestamp'
        end:
          $ref: '#/components/schemas/Timestamp'
        timezone:
          $ref: '#/components/schemas/TimeZone'
        customer:
          $ref: '#/components/schemas/Customer'
        channel:
          type: string
          description: whatsapp, instagram, messenger, webchat, phone, telegram, tiktok, panel
        note:
          type: string
          description: Short note. Never sent for health businesses (clinic, dental, health centre).
        replaces_booking_id:
          type: string
          description: Time change. Cancel this booking and create the new one in the same transaction, then answer replaced:true.
    BookingRef:
      type: object
      required: [booking_id]
      properties:
        booking_id:
          type: string
    Service:
      type: object
      required: [id, name, duration_minutes]
      properties:
        id:
          type: string
        name:
          type: string
          maxLength: 120
        duration_minutes:
          type: integer
          minimum: 1
        price:
          type: [number, 'null']
        staff:
          type: array
          items:
            $ref: '#/components/schemas/Staff'
    Staff:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
        name:
          type: string
          maxLength: 120
    Slot:
      type: object
      required: [start, end]
      properties:
        start:
          $ref: '#/components/schemas/Timestamp'
        end:
          $ref: '#/components/schemas/Timestamp'
        staff_id:
          type: string
    PingResult:
      type: object
      properties:
        pong:
          type: boolean
        package:
          type: string
        package_version:
          type: string
        contract_version:
          type: integer
          const: 1
        capabilities:
          type: array
          maxItems: 32
          items:
            type: string
            maxLength: 64
          description: |
            Optional features. `replaces_booking_id`: create_booking cancels
            the old booking and creates the new one in the same transaction
            (the official packages send it).
          examples: [[replaces_booking_id]]
    ListServicesResult:
      type: object
      required: [services]
      properties:
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
    FindSlotsResult:
      type: object
      required: [slots]
      properties:
        slots:
          type: array
          items:
            $ref: '#/components/schemas/Slot'
    BookingResult:
      type: object
      required: [booking_id, status, start, end]
      properties:
        booking_id:
          type: string
        status:
          type: string
          enum: [confirmed, pending, cancelled]
          description: create_booking answers confirmed or pending; get_booking may also answer cancelled.
        start:
          $ref: '#/components/schemas/Timestamp'
        end:
          $ref: '#/components/schemas/Timestamp'
        staff_id:
          type: string
        replaced:
          type: boolean
          description: Only when replaces_booking_id was sent.
    CancelResult:
      type: object
      required: [booking_id, status]
      properties:
        booking_id:
          type: string
        status:
          const: cancelled
    SuccessResponse:
      type: object
      required: [ok, data]
      properties:
        ok:
          const: true
        data:
          oneOf:
            - $ref: '#/components/schemas/PingResult'
            - $ref: '#/components/schemas/ListServicesResult'
            - $ref: '#/components/schemas/FindSlotsResult'
            - $ref: '#/components/schemas/BookingResult'
            - $ref: '#/components/schemas/CancelResult'
    BusinessErrorResponse:
      type: object
      required: [ok, error]
      properties:
        ok:
          const: false
        error:
          type: object
          required: [code]
          properties:
            code:
              $ref: '#/components/schemas/BusinessErrorCode'
            message:
              type: string
              description: For your logs and the owner's call log only; never shown to the assistant.
    NotImplementedResponse:
      type: object
      required: [ok, error]
      description: HTTP 200. The operation is not supported by this endpoint (not a business code).
      properties:
        ok:
          const: false
        error:
          type: object
          required: [code]
          properties:
            code:
              const: not_implemented
            message:
              type: string
              description: For your logs and the owner's call log only.
    TechnicalErrorResponse:
      type: object
      required: [ok, error]
      properties:
        ok:
          const: false
        error:
          type: object
          required: [code]
          properties:
            code:
              type: string
              description: e.g. unauthorized, bad_request (not a business code)
    PairRequest:
      type: object
      required: [code, endpoint_url, package_kind, package_version]
      properties:
        code:
          type: string
          pattern: '^blk_pair_[A-Za-z2-7]{26}$'
        endpoint_url:
          type: string
          format: uri
          description: Full https URL of your endpoint (port 443).
        package_kind:
          type: string
          examples: [php, node, python, custom]
        package_version:
          type: string
        account:
          type: [string, 'null']
    PairSuccess:
      type: object
      required: [ok, data]
      properties:
        ok:
          const: true
        data:
          type: object
          required: [signing_secret, workspace_name, contract_version]
          properties:
            signing_secret:
              type: string
              pattern: '^whsec_[A-Za-z0-9+/]+={0,2}$'
            workspace_name:
              type: string
            contract_version:
              const: 1
    PairFailure:
      type: object
      required: [ok, error]
      properties:
        ok:
          const: false
        error:
          type: object
          required: [code]
          properties:
            code:
              const: pairing_failed
