{
    "openapi": "3.0.3",
    "info": {
        "title": "Рыбсток API",
        "version": "1.0.0",
        "description": "Открытый JSON API интернет-склада Рыбсток: категории, товары, поиск, расчёт доставки, проверка и оформление заказа.\n\nАвторизация не требуется. Валюта — RUB, язык — русский. Оплата только при получении (наличные или QR), заказ подтверждается звонком менеджера.\n\nЛимиты: чтение 120 запросов/мин, поиск 60/мин, расчёт доставки 30/мин, проверка заказа 30/мин, создание заказа 5/час и 20/сутки с одного IP. Для безопасного повтора создания заказа используйте заголовок Idempotency-Key.",
        "contact": {
            "name": "Рыбсток",
            "url": "https://rybstock.ru/kontakty",
            "email": "zakaz@rybstock.ru"
        }
    },
    "tags": [
        {
            "name": "Сервис",
            "description": "Индекс API, здоровье и факты о магазине"
        },
        {
            "name": "Каталог",
            "description": "Категории, товары и фасовки"
        },
        {
            "name": "Поиск",
            "description": "Умный поиск по каталогу"
        },
        {
            "name": "Доставка",
            "description": "Расчёт доставки до оформления"
        },
        {
            "name": "Заказы",
            "description": "Проверка, создание и статус заказа"
        },
        {
            "name": "Вопросы",
            "description": "Справочные ответы для людей и ИИ"
        }
    ],
    "paths": {
        "/": {
            "get": {
                "tags": [
                    "Сервис"
                ],
                "summary": "Индекс API",
                "description": "Версия, ссылки на документацию и OpenAPI, список методов, лимиты и порядок оформления заказа.",
                "operationId": "apiIndex",
                "responses": {
                    "200": {
                        "description": "Индекс API",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiIndexResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/health": {
            "get": {
                "tags": [
                    "Сервис"
                ],
                "summary": "Проверка доступности",
                "operationId": "apiHealth",
                "responses": {
                    "200": {
                        "description": "Сервис и БД доступны",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HealthResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "База данных недоступна",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/site": {
            "get": {
                "tags": [
                    "Сервис"
                ],
                "summary": "Контакты, доставка и оплата",
                "operationId": "apiSite",
                "responses": {
                    "200": {
                        "description": "Факты о магазине",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SiteResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/categories": {
            "get": {
                "tags": [
                    "Каталог"
                ],
                "summary": "Дерево категорий",
                "operationId": "apiCategories",
                "parameters": [
                    {
                        "name": "format",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "tree",
                                "flat"
                            ],
                            "default": "tree"
                        },
                        "description": "tree — вложенное дерево, flat — плоский список."
                    },
                    {
                        "name": "hide_empty",
                        "in": "query",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Скрыть категории без опубликованных товаров."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Список категорий",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CategoriesResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/categories/{slug}": {
            "get": {
                "tags": [
                    "Каталог"
                ],
                "summary": "Категория по slug",
                "operationId": "apiCategory",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CategorySlug"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Категория",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CategoryResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Категория не найдена",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/products": {
            "get": {
                "tags": [
                    "Каталог"
                ],
                "summary": "Товары с фильтрами",
                "description": "Список опубликованных товаров. Без q — листинг каталога или категории; с q — тот же умный поиск, что на сайте.",
                "operationId": "apiProducts",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Поисковый запрос."
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug или id категории; учитываются подкатегории."
                    },
                    {
                        "name": "price_min",
                        "in": "query",
                        "schema": {
                            "type": "number",
                            "minimum": 0
                        },
                        "description": "Минимальная цена фасовки, ₽."
                    },
                    {
                        "name": "price_max",
                        "in": "query",
                        "schema": {
                            "type": "number",
                            "minimum": 0
                        },
                        "description": "Максимальная цена фасовки, ₽."
                    },
                    {
                        "name": "weight_min",
                        "in": "query",
                        "schema": {
                            "type": "number",
                            "minimum": 0
                        },
                        "description": "Минимальный вес фасовки, кг."
                    },
                    {
                        "name": "weight_max",
                        "in": "query",
                        "schema": {
                            "type": "number",
                            "minimum": 0
                        },
                        "description": "Максимальный вес фасовки, кг."
                    },
                    {
                        "name": "unit",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Единица измерения: kg, g, l, ml, pcs, pack (можно через запятую)."
                    },
                    {
                        "name": "promo",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Только акционные товары."
                    },
                    {
                        "name": "new",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Только новинки."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "default",
                                "price_asc",
                                "price_desc",
                                "name_asc",
                                "newest",
                                "popularity"
                            ],
                            "default": "default"
                        },
                        "description": "Сортировка; default — по фактическим продажам за 30 дней."
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    },
                    {
                        "$ref": "#/components/parameters/Offset"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Товары",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProductsResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Некорректный фильтр",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/products/{idOrSlug}": {
            "get": {
                "tags": [
                    "Каталог"
                ],
                "summary": "Карточка товара",
                "description": "Полная карточка: описание, все доступные фасовки, цены, остатки, изображения, категории, ценовые уровни и похожие товары.",
                "operationId": "apiProduct",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ProductIdOrSlug"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Товар",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProductResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Товар не найден",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/search": {
            "get": {
                "tags": [
                    "Поиск"
                ],
                "summary": "Умный поиск",
                "description": "Поиск с исправлением опечаток, синонимами, ассоциациями и родственной подстановкой. В meta приходят corrected_query и fallback_term.",
                "operationId": "apiSearch",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Поисковый запрос."
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug или id категории."
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    },
                    {
                        "$ref": "#/components/parameters/Offset"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Результаты поиска",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProductsResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Пустой запрос",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/faq": {
            "get": {
                "tags": [
                    "Вопросы"
                ],
                "summary": "Вопросы и ответы",
                "operationId": "apiFaq",
                "responses": {
                    "200": {
                        "description": "Список ответов",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/FaqListResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/faq/{slug}": {
            "get": {
                "tags": [
                    "Вопросы"
                ],
                "summary": "Ответ целиком",
                "operationId": "apiFaqShow",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "forel-ili-semga"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ответ",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/FaqDetailResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ответ не найден",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/delivery/quote": {
            "post": {
                "tags": [
                    "Доставка"
                ],
                "summary": "Расчёт доставки",
                "description": "Считает доставку по адресу, способу получения и товарам (или сумме). Ничего не создаёт и не отправляет.",
                "operationId": "apiDeliveryQuote",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/DeliveryQuoteRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Расчёт",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeliveryQuoteResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Некорректные данные",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Превышен лимит",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/orders/validate": {
            "post": {
                "tags": [
                    "Заказы"
                ],
                "summary": "Проверка заказа без записи",
                "description": "Полная проверка контактов, товаров и доставки, расчёт итога. Ничего не пишет в БД и не отправляет письма — безопасный способ проверить заказ перед созданием.",
                "operationId": "apiOrderValidate",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderCreateRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Заказ корректен",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderValidateResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Ошибки валидации",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Превышен лимит",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/orders": {
            "post": {
                "tags": [
                    "Заказы"
                ],
                "summary": "Создать заказ",
                "description": "Создаёт реальный заказ. Цены, скидка за наличные и доставка считаются на сервере. Менеджеру уходит письмо, клиенту — копия при указанном email. Письмо отправляется синхронно, поэтому запрос может занять до 30 секунд; для безопасного повтора используйте Idempotency-Key.",
                "operationId": "apiOrderCreate",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 128
                        },
                        "description": "Ключ повтора: тот же ключ с тем же телом вернёт тот же заказ."
                    },
                    {
                        "name": "X-Client-Name",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 120
                        },
                        "description": "Имя внешнего клиента/бота для пометки в админке."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderCreateRequest"
                            },
                            "example": {
                                "customer": {
                                    "name": "Иван",
                                    "phone": "+7 967 198-10-94",
                                    "email": "ivan@example.ru"
                                },
                                "items": [
                                    {
                                        "variant_id": 12345,
                                        "quantity": 1
                                    }
                                ],
                                "delivery": {
                                    "type": "courier",
                                    "address": "Москва, ул. Привольная, 13к1",
                                    "lift": false
                                },
                                "payment_method": "cash",
                                "comment": "Позвонить за час до доставки"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Заказ создан",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Повтор по Idempotency-Key: заказ уже был создан",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Idempotency-Key уже использован для другого заказа или заказ с этим ключом сейчас создаётся",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Ошибки валидации или недоступные товары",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Превышен лимит заказов",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/orders/{orderNumber}": {
            "get": {
                "tags": [
                    "Заказы"
                ],
                "summary": "Статус заказа",
                "description": "Номер заказа и телефон должны совпадать. Иначе возвращается 404, чтобы нельзя было перебирать номера.",
                "operationId": "apiOrderStatus",
                "parameters": [
                    {
                        "name": "orderNumber",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "00015376"
                    },
                    {
                        "name": "phone",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Телефон, на который оформлен заказ (достаточно 10 цифр)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Заказ",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Заказ не найден или телефон не совпал",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Не указан телефон",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Превышен лимит",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "parameters": {
            "Page": {
                "name": "page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 1
                },
                "description": "Номер страницы."
            },
            "PerPage": {
                "name": "per_page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 24
                },
                "description": "Размер страницы (до 100)."
            },
            "Offset": {
                "name": "offset",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 0
                },
                "description": "Смещение; альтернатива page."
            },
            "CategorySlug": {
                "name": "slug",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string"
                },
                "example": "fish"
            },
            "ProductIdOrSlug": {
                "name": "idOrSlug",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string"
                },
                "example": "forel-file"
            }
        },
        "schemas": {
            "Meta": {
                "type": "object",
                "properties": {
                    "api_version": {
                        "type": "string",
                        "example": "1.0.0"
                    },
                    "request_id": {
                        "type": "string",
                        "example": "9f2c1a7b3d4e5f60"
                    },
                    "generated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "total": {
                        "type": "integer",
                        "example": 120
                    },
                    "page": {
                        "type": "integer",
                        "example": 1
                    },
                    "per_page": {
                        "type": "integer",
                        "example": 24
                    },
                    "pages": {
                        "type": "integer",
                        "example": 5
                    },
                    "query": {
                        "type": "string"
                    },
                    "corrected_query": {
                        "type": "string",
                        "nullable": true
                    },
                    "fallback_term": {
                        "type": "string",
                        "nullable": true
                    },
                    "fallback_original": {
                        "type": "string",
                        "nullable": true
                    },
                    "sort": {
                        "type": "string"
                    },
                    "currency": {
                        "type": "string",
                        "example": "RUB"
                    }
                },
                "additionalProperties": true
            },
            "Error": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "example": "validation_error"
                    },
                    "message": {
                        "type": "string",
                        "example": "Проверьте поля запроса."
                    },
                    "details": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "field": {
                                    "type": "string",
                                    "example": "customer.phone"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "Укажите телефон полностью — 10 цифр."
                                }
                            }
                        }
                    }
                }
            },
            "ErrorResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": false
                    },
                    "error": {
                        "$ref": "#/components/schemas/Error"
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "ApiIndexResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "example": "Рыбсток API"
                            },
                            "version": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "base_url": {
                                "type": "string",
                                "example": "https://rybstock.ru/api/v1"
                            },
                            "docs_url": {
                                "type": "string",
                                "example": "https://rybstock.ru/api"
                            },
                            "openapi_url": {
                                "type": "string",
                                "example": "https://rybstock.ru/api/openapi"
                            },
                            "llms_url": {
                                "type": "string",
                                "example": "https://rybstock.ru/llms.txt"
                            },
                            "auth": {
                                "type": "string",
                                "example": "none"
                            },
                            "payment_on_delivery": {
                                "type": "boolean",
                                "example": true
                            },
                            "endpoints": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "order_flow": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "rate_limits": {
                                "type": "object",
                                "additionalProperties": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "HealthResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "string",
                                "example": "ok"
                            },
                            "database": {
                                "type": "string",
                                "example": "ok"
                            },
                            "time": {
                                "type": "string",
                                "format": "date-time"
                            }
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "SiteResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "$ref": "#/components/schemas/SiteInfo"
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "SiteInfo": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Рыбсток"
                    },
                    "description": {
                        "type": "string"
                    },
                    "region": {
                        "type": "string",
                        "example": "Москва и Московская область"
                    },
                    "language": {
                        "type": "string",
                        "example": "ru"
                    },
                    "currency": {
                        "type": "string",
                        "example": "RUB"
                    },
                    "phone": {
                        "type": "string",
                        "example": "+7-967-198-10-94"
                    },
                    "email": {
                        "type": "string",
                        "example": "zakaz@rybstock.ru"
                    },
                    "site_url": {
                        "type": "string",
                        "example": "https://rybstock.ru"
                    },
                    "pickup": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "delivery": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "payment": {
                        "type": "object",
                        "properties": {
                            "on_delivery_only": {
                                "type": "boolean",
                                "example": true
                            },
                            "prepayment": {
                                "type": "boolean",
                                "example": false
                            },
                            "methods": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "code": {
                                            "type": "string",
                                            "example": "cash"
                                        },
                                        "label": {
                                            "type": "string",
                                            "example": "Наличными при получении"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "links": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    }
                }
            },
            "CategoryRef": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 12
                    },
                    "name": {
                        "type": "string",
                        "example": "Рыба"
                    },
                    "slug": {
                        "type": "string",
                        "example": "fish"
                    },
                    "url": {
                        "type": "string",
                        "example": "https://rybstock.ru/katalog/fish"
                    }
                }
            },
            "CategoryNode": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CategoryRef"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "parent_id": {
                                "type": "integer",
                                "nullable": true
                            },
                            "product_count": {
                                "type": "integer",
                                "example": 42,
                                "description": "Товаров непосредственно в категории."
                            },
                            "product_count_total": {
                                "type": "integer",
                                "example": 120,
                                "description": "С учётом подкатегорий."
                            },
                            "children": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/CategoryNode"
                                }
                            }
                        }
                    }
                ]
            },
            "Breadcrumb": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Рыба"
                    },
                    "url": {
                        "type": "string",
                        "example": "https://rybstock.ru/katalog/fish"
                    }
                }
            },
            "CategoryDetail": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CategoryRef"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "parent_id": {
                                "type": "integer",
                                "nullable": true
                            },
                            "description": {
                                "type": "string"
                            },
                            "description_html": {
                                "type": "string"
                            },
                            "image": {
                                "type": "string"
                            },
                            "product_count": {
                                "type": "integer"
                            },
                            "product_count_total": {
                                "type": "integer"
                            },
                            "children": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/CategoryRef"
                                }
                            },
                            "breadcrumbs": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Breadcrumb"
                                }
                            }
                        }
                    }
                ]
            },
            "CategoriesResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/CategoryNode"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "CategoryResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "$ref": "#/components/schemas/CategoryDetail"
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "Variant": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 12345
                    },
                    "name": {
                        "type": "string",
                        "example": "Филе 1 кг"
                    },
                    "code": {
                        "type": "string",
                        "nullable": true
                    },
                    "article": {
                        "type": "string",
                        "nullable": true
                    },
                    "unit": {
                        "type": "string",
                        "example": "kg"
                    },
                    "unit_label": {
                        "type": "string",
                        "example": "кг"
                    },
                    "package_quantity": {
                        "type": "number",
                        "example": 1
                    },
                    "step_quantity": {
                        "type": "number",
                        "example": 1
                    },
                    "min_order_quantity": {
                        "type": "number",
                        "example": 1
                    },
                    "price_per_unit": {
                        "type": "number",
                        "nullable": true,
                        "example": 1290
                    },
                    "package_price": {
                        "type": "number",
                        "example": 1290
                    },
                    "old_package_price": {
                        "type": "number",
                        "nullable": true,
                        "example": 1390
                    },
                    "stock_quantity": {
                        "type": "number",
                        "nullable": true,
                        "description": "null — остаток не ведётся, товар доступен."
                    },
                    "in_stock": {
                        "type": "boolean",
                        "example": true
                    },
                    "is_default": {
                        "type": "boolean",
                        "example": true
                    }
                }
            },
            "PriceInfo": {
                "type": "object",
                "properties": {
                    "currency": {
                        "type": "string",
                        "example": "RUB"
                    },
                    "from": {
                        "type": "number",
                        "example": 990
                    },
                    "to": {
                        "type": "number",
                        "example": 2590
                    },
                    "unit": {
                        "type": "string",
                        "nullable": true,
                        "example": "kg"
                    },
                    "unit_label": {
                        "type": "string",
                        "nullable": true,
                        "example": "кг"
                    },
                    "package_price": {
                        "type": "number",
                        "example": 1290
                    },
                    "price_per_unit": {
                        "type": "number",
                        "nullable": true,
                        "example": 1290
                    },
                    "old_package_price": {
                        "type": "number",
                        "nullable": true,
                        "example": 1390
                    }
                }
            },
            "PriceTier": {
                "type": "object",
                "properties": {
                    "label": {
                        "type": "string",
                        "example": "Цена при сумме заказа от 20 000р. наличными"
                    },
                    "min_order_amount": {
                        "type": "number",
                        "example": 20000
                    },
                    "discount_percent": {
                        "type": "number",
                        "example": 5
                    },
                    "price": {
                        "type": "number",
                        "example": 1225
                    },
                    "note": {
                        "type": "string",
                        "example": "При оплате наличными"
                    }
                }
            },
            "ProductSummary": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 101
                    },
                    "name": {
                        "type": "string",
                        "example": "Форель филе"
                    },
                    "slug": {
                        "type": "string",
                        "example": "forel-file"
                    },
                    "url": {
                        "type": "string",
                        "example": "https://rybstock.ru/product/forel-file"
                    },
                    "sku": {
                        "type": "string",
                        "nullable": true
                    },
                    "image": {
                        "type": "string",
                        "example": "https://rybstock.ru/assets/uploads/products/forel.webp"
                    },
                    "category": {
                        "$ref": "#/components/schemas/CategoryRef"
                    },
                    "categories": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/CategoryRef"
                        }
                    },
                    "short_description": {
                        "type": "string"
                    },
                    "is_promo": {
                        "type": "boolean",
                        "example": false
                    },
                    "is_new": {
                        "type": "boolean",
                        "example": true
                    },
                    "badge": {
                        "type": "string",
                        "nullable": true,
                        "example": "Новинка"
                    },
                    "in_stock": {
                        "type": "boolean",
                        "example": true
                    },
                    "price": {
                        "$ref": "#/components/schemas/PriceInfo"
                    },
                    "variants": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Variant"
                        },
                        "description": "Для листинга — до 6 доступных фасовок."
                    }
                }
            },
            "ProductDetail": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/ProductSummary"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "images": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "url": {
                                            "type": "string"
                                        },
                                        "alt": {
                                            "type": "string"
                                        },
                                        "sort_order": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            },
                            "breadcrumbs": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Breadcrumb"
                                }
                            },
                            "description": {
                                "type": "string",
                                "description": "Описание обычным текстом."
                            },
                            "description_html": {
                                "type": "string",
                                "description": "Исходное описание в HTML."
                            },
                            "additional_info": {
                                "type": "string"
                            },
                            "additional_info_html": {
                                "type": "string"
                            },
                            "price_tiers": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/PriceTier"
                                }
                            },
                            "related": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/ProductSummary"
                                }
                            },
                            "updated_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        }
                    }
                ]
            },
            "ProductsResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ProductSummary"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "ProductResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "$ref": "#/components/schemas/ProductDetail"
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "FaqItem": {
                "type": "object",
                "properties": {
                    "slug": {
                        "type": "string",
                        "example": "forel-ili-semga"
                    },
                    "title": {
                        "type": "string",
                        "example": "Чем отличается форель от семги"
                    },
                    "answer": {
                        "type": "string"
                    },
                    "updated": {
                        "type": "string",
                        "example": "2026-11-13"
                    },
                    "url": {
                        "type": "string",
                        "example": "https://rybstock.ru/voprosy/forel-ili-semga"
                    },
                    "faq": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "q": {
                                    "type": "string"
                                },
                                "a": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "FaqListResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/FaqItem"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "FaqDetail": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/FaqItem"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "sections": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "title": {
                                            "type": "string"
                                        },
                                        "text": {
                                            "type": "string"
                                        },
                                        "html": {
                                            "type": "string"
                                        }
                                    }
                                }
                            },
                            "links": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "label": {
                                            "type": "string"
                                        },
                                        "url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                ]
            },
            "FaqDetailResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "$ref": "#/components/schemas/FaqDetail"
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "DeliveryQuoteRequest": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "description": "Товары для расчёта суммы. Можно не передавать, если указан subtotal.",
                        "items": {
                            "$ref": "#/components/schemas/OrderItemInput"
                        }
                    },
                    "subtotal": {
                        "type": "number",
                        "minimum": 0,
                        "description": "Сумма заказа, если товары не переданы."
                    },
                    "delivery": {
                        "$ref": "#/components/schemas/DeliveryInput"
                    },
                    "payment_method": {
                        "type": "string",
                        "enum": [
                            "cash",
                            "qr"
                        ],
                        "default": "cash"
                    }
                }
            },
            "DeliveryInput": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "courier",
                            "pickup",
                            "inside_mkad",
                            "outside_mkad"
                        ],
                        "default": "courier",
                        "description": "courier — сервер сам определит зону по адресу."
                    },
                    "address": {
                        "type": "string",
                        "example": "Москва, ул. Привольная, 13к1"
                    },
                    "lift": {
                        "type": "boolean",
                        "default": false,
                        "description": "Нужен подъём на этаж."
                    }
                }
            },
            "DeliveryQuote": {
                "type": "object",
                "properties": {
                    "subtotal": {
                        "type": "number",
                        "example": 5000
                    },
                    "currency": {
                        "type": "string",
                        "example": "RUB"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderItem"
                        }
                    },
                    "delivery": {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "example": "inside_mkad"
                            },
                            "label": {
                                "type": "string"
                            },
                            "requested_type": {
                                "type": "string"
                            },
                            "address": {
                                "type": "string",
                                "nullable": true
                            },
                            "zone": {
                                "type": "string",
                                "nullable": true
                            },
                            "distance_km": {
                                "type": "integer"
                            },
                            "store_distance_km": {
                                "type": "number",
                                "nullable": true
                            },
                            "amount": {
                                "type": "number"
                            },
                            "lift_amount": {
                                "type": "number"
                            },
                            "free_from": {
                                "type": "number"
                            },
                            "free_delivery_gap": {
                                "type": "number"
                            },
                            "address_recognized": {
                                "type": "boolean"
                            },
                            "manager_quote_required": {
                                "type": "boolean"
                            },
                            "status": {
                                "type": "string"
                            }
                        }
                    },
                    "payment": {
                        "$ref": "#/components/schemas/Payment"
                    },
                    "totals": {
                        "$ref": "#/components/schemas/Totals"
                    },
                    "address_recognized": {
                        "type": "boolean"
                    },
                    "manager_quote_required": {
                        "type": "boolean"
                    },
                    "note": {
                        "type": "string"
                    }
                }
            },
            "DeliveryQuoteResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "$ref": "#/components/schemas/DeliveryQuote"
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "Payment": {
                "type": "object",
                "properties": {
                    "method": {
                        "type": "string",
                        "nullable": true,
                        "example": "cash"
                    },
                    "label": {
                        "type": "string",
                        "example": "Наличными при получении"
                    },
                    "on_delivery": {
                        "type": "boolean",
                        "example": true
                    },
                    "cash_discount_percent": {
                        "type": "number",
                        "nullable": true
                    },
                    "discount_amount": {
                        "type": "number"
                    }
                }
            },
            "Totals": {
                "type": "object",
                "properties": {
                    "currency": {
                        "type": "string",
                        "example": "RUB"
                    },
                    "subtotal": {
                        "type": "number",
                        "example": 5000
                    },
                    "discount_amount": {
                        "type": "number",
                        "example": 0
                    },
                    "cash_discount_percent": {
                        "type": "number",
                        "nullable": true
                    },
                    "cash_discount_amount": {
                        "type": "number",
                        "example": 0
                    },
                    "delivery_amount": {
                        "type": "number",
                        "example": 599
                    },
                    "lift_amount": {
                        "type": "number",
                        "example": 0
                    },
                    "total": {
                        "type": "number",
                        "example": 5599
                    }
                }
            },
            "OrderItemInput": {
                "type": "object",
                "properties": {
                    "variant_id": {
                        "type": "integer",
                        "example": 12345,
                        "description": "ID фасовки из карточки товара."
                    },
                    "product_id": {
                        "type": "integer",
                        "description": "Альтернатива variant_id: возьмём фасовку по умолчанию."
                    },
                    "quantity": {
                        "type": "number",
                        "minimum": 1,
                        "maximum": 999,
                        "default": 1,
                        "description": "Количество упаковок."
                    }
                }
            },
            "OrderCreateRequest": {
                "type": "object",
                "required": [
                    "customer",
                    "items",
                    "delivery"
                ],
                "properties": {
                    "customer": {
                        "type": "object",
                        "required": [
                            "name",
                            "phone"
                        ],
                        "properties": {
                            "name": {
                                "type": "string",
                                "maxLength": 120,
                                "example": "Иван"
                            },
                            "phone": {
                                "type": "string",
                                "example": "+7 967 198-10-94"
                            },
                            "email": {
                                "type": "string",
                                "format": "email",
                                "nullable": true
                            }
                        }
                    },
                    "items": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 100,
                        "items": {
                            "$ref": "#/components/schemas/OrderItemInput"
                        }
                    },
                    "delivery": {
                        "$ref": "#/components/schemas/DeliveryInput"
                    },
                    "payment_method": {
                        "type": "string",
                        "enum": [
                            "cash",
                            "qr"
                        ],
                        "default": "cash"
                    },
                    "comment": {
                        "type": "string",
                        "maxLength": 2000
                    }
                }
            },
            "OrderValidateResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "valid": {
                                "type": "boolean",
                                "example": true
                            },
                            "would_create": {
                                "type": "boolean",
                                "example": true
                            },
                            "customer": {
                                "type": "object",
                                "additionalProperties": true
                            },
                            "items": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/OrderItem"
                                }
                            },
                            "subtotal": {
                                "type": "number"
                            },
                            "currency": {
                                "type": "string",
                                "example": "RUB"
                            },
                            "delivery": {
                                "type": "object",
                                "additionalProperties": true
                            },
                            "payment": {
                                "$ref": "#/components/schemas/Payment"
                            },
                            "totals": {
                                "$ref": "#/components/schemas/Totals"
                            },
                            "warnings": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "note": {
                                "type": "string"
                            }
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            },
            "OrderItem": {
                "type": "object",
                "properties": {
                    "product_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "variant_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "name": {
                        "type": "string",
                        "example": "Форель филе"
                    },
                    "variant_name": {
                        "type": "string",
                        "example": "Филе 1 кг"
                    },
                    "unit": {
                        "type": "string",
                        "example": "kg"
                    },
                    "unit_label": {
                        "type": "string",
                        "example": "кг"
                    },
                    "package_quantity": {
                        "type": "number",
                        "example": 1
                    },
                    "quantity": {
                        "type": "number",
                        "example": 1
                    },
                    "price_per_unit": {
                        "type": "number",
                        "nullable": true,
                        "example": 1290
                    },
                    "package_price": {
                        "type": "number",
                        "example": 1290
                    },
                    "line_total": {
                        "type": "number",
                        "example": 1290
                    },
                    "is_gift": {
                        "type": "boolean",
                        "example": false
                    },
                    "image": {
                        "type": "string",
                        "description": "Только в расчёте доставки."
                    }
                }
            },
            "OrderData": {
                "type": "object",
                "properties": {
                    "order_number": {
                        "type": "string",
                        "example": "00015376"
                    },
                    "status": {
                        "type": "string",
                        "example": "new"
                    },
                    "status_label": {
                        "type": "string",
                        "example": "Поступил"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "customer": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "delivery": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "payment": {
                        "$ref": "#/components/schemas/Payment"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderItem"
                        }
                    },
                    "totals": {
                        "$ref": "#/components/schemas/Totals"
                    },
                    "order_source": {
                        "type": "string",
                        "example": "api"
                    },
                    "confirmation_required": {
                        "type": "boolean",
                        "example": true
                    },
                    "payment_on_delivery": {
                        "type": "boolean",
                        "example": true
                    },
                    "message": {
                        "type": "string",
                        "example": "Заказ принят. Мы позвоним для подтверждения."
                    },
                    "support_phone": {
                        "type": "string",
                        "example": "+7-967-198-10-94"
                    }
                }
            },
            "OrderResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "$ref": "#/components/schemas/OrderData"
                    },
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    }
                }
            }
        }
    },
    "servers": [
        {
            "url": "https://rybstock.ru/api/v1",
            "description": "Публичный API Рыбсток"
        }
    ],
    "externalDocs": {
        "description": "Документация и Swagger UI",
        "url": "https://rybstock.ru/api"
    }
}