{
    "openapi": "3.0.3",
    "info": {
        "title": "Kitobchi Client API",
        "version": "v1",
        "description": "Hamkor servislar, tashqi kataloglar va marketplace integratsiyalari uchun read-only Client API.",
        "contact": {
            "name": "Kitobchi Developers",
            "url": "https://kitobchi.com/developers/api"
        }
    },
    "servers": [
        {
            "url": "https://kitobchi.com/api/v1/client",
            "description": "Production"
        }
    ],
    "security": [
        {
            "AppId": [],
            "AppSecret": []
        }
    ],
    "components": {
        "securitySchemes": {
            "AppId": {
                "type": "apiKey",
                "in": "header",
                "name": "X-App-ID"
            },
            "AppSecret": {
                "type": "apiKey",
                "in": "header",
                "name": "X-App-Secret"
            }
        }
    },
    "paths": {
        "/products/{col}": {
            "get": {
                "operationId": "products_list",
                "summary": "Mahsulotlar ro‘yxati",
                "description": "Katalogdagi mahsulotlarni turi bo‘yicha sahifalab qaytaradi.",
                "tags": [
                    "Products"
                ],
                "parameters": [
                    {
                        "name": "col",
                        "in": "path",
                        "required": true,
                        "description": "Mahsulot turi: books yoki stationery.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "books"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Sahifa raqami (1 dan boshlanadi).",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Nom bo‘yicha filtr.",
                        "schema": {
                            "type": "string"
                        },
                        "example": null
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "description": "Tartiblash: popular, new, price_asc, price_desc.",
                        "schema": {
                            "type": "string"
                        },
                        "example": null
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 128,
                                            "name": "Atomic Habits",
                                            "price": 89000,
                                            "old_price": 99000,
                                            "image": "https://kitobchi.com/storage/books/128.jpg",
                                            "type": "book",
                                            "in_stock": true,
                                            "seller_id": 12
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "per_page": 20,
                                        "total": 342
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/products/recommendation/{col}": {
            "get": {
                "operationId": "products_recommendation",
                "summary": "Tavsiya qilingan mahsulotlar",
                "description": "Vitrina va “sizga mos” bloklari uchun tavsiya ro‘yxati.",
                "tags": [
                    "Products"
                ],
                "parameters": [
                    {
                        "name": "col",
                        "in": "path",
                        "required": true,
                        "description": "Mahsulot turi: books yoki stationery.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "books"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 305,
                                            "name": "Deep Work",
                                            "price": 76000,
                                            "image": "https://kitobchi.com/storage/books/305.jpg",
                                            "type": "book",
                                            "in_stock": true
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/products/sellers/list": {
            "get": {
                "operationId": "products_sellers_list",
                "summary": "Sellerlar va oxirgi mahsulotlari",
                "description": "Do‘konlar ro‘yxati va har biri uchun eng so‘nggi mahsulotlar.",
                "tags": [
                    "Products"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Sahifa raqami.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 12,
                                            "name": "Asaxiy Books",
                                            "logo": "https://kitobchi.com/storage/sellers/12.png",
                                            "rating": 4.8,
                                            "latest_products": []
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/products/sellers/by-qr/{token}": {
            "get": {
                "operationId": "products_seller_by_qr",
                "summary": "QR orqali seller",
                "description": "QR token orqali do‘kon ma’lumotini olish.",
                "tags": [
                    "Products"
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "path",
                        "required": true,
                        "description": "Seller QR tokeni.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "qr_9f3c1a"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "id": 12,
                                        "name": "Asaxiy Books",
                                        "rating": 4.8
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/products/sellers/profile/{id}/{page}": {
            "get": {
                "operationId": "products_seller_profile",
                "summary": "Seller profili",
                "description": "Do‘kon profili va uning sahifalangan mahsulotlari.",
                "tags": [
                    "Products"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Seller ID.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 12
                    },
                    {
                        "name": "page",
                        "in": "path",
                        "required": true,
                        "description": "Mahsulotlar sahifasi.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "id": 12,
                                        "name": "Asaxiy Books",
                                        "products": [],
                                        "meta": {
                                            "page": 1,
                                            "total": 240
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/products/sellers/{sellerId}/code/{code}": {
            "get": {
                "operationId": "products_seller_code",
                "summary": "Shtrix-kod / ISBN bo‘yicha mahsulot",
                "description": "Do‘kon ichidan shtrix-kod yoki ISBN orqali bitta mahsulotni topadi. `/isbn/{isbn}` alias ham mavjud.",
                "tags": [
                    "Products"
                ],
                "parameters": [
                    {
                        "name": "sellerId",
                        "in": "path",
                        "required": true,
                        "description": "Seller ID.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 12
                    },
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "description": "Shtrix-kod yoki ISBN.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "9781847941831"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "id": 128,
                                        "name": "Atomic Habits",
                                        "price": 89000,
                                        "in_stock": true,
                                        "seller_id": 12
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/search": {
            "get": {
                "operationId": "search_global",
                "summary": "Global qidiruv",
                "description": "Nom, muallif, kategoriya va turga qarab natija qaytaradi.",
                "tags": [
                    "Search"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Qidiruv matni.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "python"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Sahifa raqami.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 128,
                                            "name": "Python bilan dasturlash",
                                            "type": "book",
                                            "price": 120000,
                                            "image": "https://kitobchi.com/storage/books/128.jpg"
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "total": 37
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/search/suggestions": {
            "get": {
                "operationId": "search_suggestions",
                "summary": "Autocomplete takliflari",
                "description": "Qidiruv maydoni uchun tezkor takliflar (nom, muallif, teg).",
                "tags": [
                    "Search"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Qidiruv boshlanmasi.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "pyth"
                    },
                    {
                        "name": "seller_id",
                        "in": "query",
                        "required": false,
                        "description": "Bitta do‘kon ichida cheklash.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": null
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        "Python",
                                        "Python bilan dasturlash",
                                        "Pythonic"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/search/trending": {
            "get": {
                "operationId": "search_trending",
                "summary": "Trend so‘rovlar",
                "description": "Oxirgi 7 kunda eng ko‘p qidirilgan so‘rovlar.",
                "tags": [
                    "Search"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "text": "atomic habits",
                                            "result_name": "Atomic Habits",
                                            "total_count": 512
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/search/categories": {
            "get": {
                "operationId": "search_categories",
                "summary": "Kategoriyalar",
                "description": "Katalog menyusi va filtr paneli uchun kategoriyalar ro‘yxati.",
                "tags": [
                    "Search"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 3,
                                            "name": "Biznes",
                                            "type": "book",
                                            "children": []
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/search/category/{cat_id}/{type}": {
            "get": {
                "operationId": "search_category",
                "summary": "Kategoriya mahsulotlari",
                "description": "Bitta kategoriya ichidagi mahsulotlarni turi bo‘yicha qaytaradi.",
                "tags": [
                    "Search"
                ],
                "parameters": [
                    {
                        "name": "cat_id",
                        "in": "path",
                        "required": true,
                        "description": "Kategoriya ID.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 3
                    },
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "description": "Mahsulot turi: book yoki stationery.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "book"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Sahifa raqami.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [],
                                    "meta": {
                                        "page": 1,
                                        "total": 96
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        },
        "/products/stock/by-code": {
            "post": {
                "operationId": "seller_stock_update",
                "summary": "Zaxirani kod bo‘yicha yangilash",
                "description": "Do‘konga bog‘langan kalit orqali ISBN (kitob) yoki shtrix-kod (kanselyariya) bo‘yicha zaxirani o‘rnatadi (`stock`) yoki o‘zgartiradi (`delta`). `stock:write` ability va seller-scoped kalit talab qilinadi.",
                "tags": [
                    "Seller"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "success": true,
                                    "type": "book",
                                    "id": 128,
                                    "name": "Atomic Habits",
                                    "stock": 25,
                                    "in_stock": true
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "code": "9781847941831",
                                "stock": 25
                            }
                        }
                    }
                }
            }
        },
        "/products/mine": {
            "get": {
                "operationId": "seller_my_products",
                "summary": "Mening mahsulotlarim",
                "description": "Kalitga bog‘langan do‘konning mahsulotlari va zaxirasi (sahifalangan).",
                "tags": [
                    "Seller"
                ],
                "parameters": [
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "description": "book (default) yoki stationery.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "book"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Sahifadagi soni (1–100).",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 50
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Sahifa raqami.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli javob",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 128,
                                            "type": "book",
                                            "name": "Atomic Habits",
                                            "code": "9781847941831",
                                            "price": 89000,
                                            "stock": 25,
                                            "in_stock": true
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "per_page": 50,
                                        "total": 240
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credential headerlari yuborilmagan"
                    },
                    "403": {
                        "description": "Noto‘g‘ri yoki nofaol credential / ability yetarli emas"
                    },
                    "429": {
                        "description": "Rate limit oshib ketdi"
                    }
                }
            }
        }
    }
}