{
  "openapi": "3.0.3",
  "info": {
    "title": "Электронная очередь — API предварительной записи",
    "version": "1.0.0",
    "description": "Публичный API предварительной записи. Все методы требуют API-ключ (X-API-Key или Authorization: Bearer). Тестовый ключ создаёт изолированные брони is_test=true. В примерах используется основной домен timira.ru; каждая копия системы работает на своём внешнем IP или домене, путь /api/queue/booking при этом не меняется."
  },
  "servers": [
    { "url": "https://timira.ru/api/queue/booking", "description": "Основной домен в примерах (не для запросов к копиям клиентов)" },
    {
      "url": "https://{host}/api/queue/booking",
      "description": "Копия клиента: подставьте свой внешний домен или IP",
      "variables": {
        "host": {
          "default": "queue.client.ru",
          "description": "Внешний домен или IP установки клиента (например, queue.client.ru или 203.0.113.10)"
        }
      }
    }
  ],
  "security": [{ "ApiKeyAuth": [] }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "schemas": {
      "Customer": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "maxLength": 150 },
          "phone": { "type": "string", "maxLength": 40 },
          "email": { "type": "string", "maxLength": 150, "format": "email" }
        }
      },
      "CreateBookingRequest": {
        "type": "object",
        "required": ["service_id"],
        "properties": {
          "service_id": { "type": "integer", "example": 3 },
          "scheduled_at": { "type": "string", "example": "2026-12-01T14:30:00+03:00", "description": "ISO 8601 со смещением. Альтернатива — date + time." },
          "date": { "type": "string", "example": "2026-12-01" },
          "time": { "type": "string", "example": "14:30" },
          "customer": { "$ref": "#/components/schemas/Customer" },
          "note": { "type": "string", "maxLength": 2000 }
        }
      },
      "Booking": {
        "type": "object",
        "properties": {
          "booking_ref": { "type": "string", "example": "hXk2m9Qb1sA7cD4e" },
          "number": { "type": "string", "example": "A-014" },
          "status": { "type": "string", "enum": ["booked", "cancelled", "completed", "called", "in_progress", "waiting"] },
          "scheduled_at": { "type": "string", "format": "date-time" },
          "scheduled_at_local": { "type": "string", "example": "2026-12-01 14:30" },
          "timezone": { "type": "string", "example": "Europe/Moscow" },
          "service": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" } } },
          "queue": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } },
          "customer": { "$ref": "#/components/schemas/Customer" },
          "note": { "type": "string" },
          "is_test": { "type": "boolean" },
          "callable": { "type": "boolean" },
          "booking_source": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Slot": {
        "type": "object",
        "properties": {
          "time": { "type": "string", "example": "14:30" },
          "iso": { "type": "string", "format": "date-time" },
          "available": { "type": "boolean" },
          "reason": { "type": "string", "nullable": true, "enum": ["past", "booked", null] },
          "capacity": { "type": "integer" },
          "booked": { "type": "integer" },
          "remaining": { "type": "integer" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string", "example": "slot_taken" }
        }
      }
    },
    "parameters": {
      "BookingRef": {
        "name": "ref", "in": "path", "required": true, "schema": { "type": "string" },
        "description": "Публичный код брони (booking_ref)"
      },
      "Date": { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } },
      "ServiceId": { "name": "service_id", "in": "query", "schema": { "type": "integer" } }
    },
    "responses": {
      "Error": {
        "description": "Ошибка",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/services": {
      "get": {
        "summary": "Очереди и услуги, доступные ключу",
        "description": "Требуется право services.read.",
        "responses": {
          "200": { "description": "Список очередей", "content": { "application/json": { "schema": { "type": "object", "properties": { "queues": { "type": "array", "items": { "type": "object" } } } } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/schedule": {
      "get": {
        "summary": "Правила записи",
        "description": "Требуется право slots.read.",
        "responses": {
          "200": { "description": "Правила", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/slots": {
      "get": {
        "summary": "Свободные слоты на дату",
        "description": "Требуется право slots.read.",
        "parameters": [
          { "$ref": "#/components/parameters/ServiceId" },
          { "$ref": "#/components/parameters/Date" }
        ],
        "responses": {
          "200": {
            "description": "Слоты",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "timezone": { "type": "string" },
                    "capacity": { "type": "integer" },
                    "closed": { "type": "boolean" },
                    "slots": { "type": "array", "items": { "$ref": "#/components/schemas/Slot" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/": {
      "get": {
        "summary": "Список броней",
        "description": "Требуется право booking.list. По умолчанию — за сегодня, status=booked.",
        "parameters": [
          { "$ref": "#/components/parameters/Date" },
          { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "$ref": "#/components/parameters/ServiceId" },
          { "name": "queue_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["booked", "cancelled", "completed", "all"] } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Список",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } },
                    "page": { "type": "integer" },
                    "limit": { "type": "integer" },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      },
      "post": {
        "summary": "Создать бронь",
        "description": "Требуется право booking.create. Поддерживается Idempotency-Key.",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingRequest" } } }
        },
        "responses": {
          "201": { "description": "Создано", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } },
          "200": { "description": "Повтор идемпотентного запроса", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/{ref}": {
      "get": {
        "summary": "Прочитать бронь",
        "description": "Требуется право booking.read. Ключ видит только свои брони, если нет booking.read_all.",
        "parameters": [{ "$ref": "#/components/parameters/BookingRef" }],
        "responses": {
          "200": { "description": "Бронь", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/{ref}/cancel": {
      "post": {
        "summary": "Отменить бронь",
        "description": "Требуется право booking.cancel.",
        "parameters": [{ "$ref": "#/components/parameters/BookingRef" }],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 200 } } } } }
        },
        "responses": {
          "200": { "description": "Отменено", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/{ref}/reschedule": {
      "post": {
        "summary": "Перенести бронь",
        "description": "Требуется право booking.reschedule.",
        "parameters": [{ "$ref": "#/components/parameters/BookingRef" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scheduled_at": { "type": "string", "example": "2026-12-02T10:00:00+03:00" },
                  "date": { "type": "string", "example": "2026-12-02" },
                  "time": { "type": "string", "example": "10:00" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Перенесено", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  }
}
