{
    "openapi": "3.1.0",
    "info": {
        "title": "تلفن ابری همکاران — AI Agent API",
        "description": "تلفن ابری همکاران، پلتفرم مرکز تماس ابری (Cloud PBX) برای کسب‌وکارها؛ شامل تلفن گویا، صف تماس، داخلی سازمانی، ضبط مکالمات، گزارش تماس، فکس اینترنتی، صندوق صوتی، اتصال به CRM، وب‌هوک و API.\n\nاین API عمومی برای دستیارهای هوش مصنوعی طراحی شده و فقط اطلاعات عمومی ارائه می‌دهد و سرنخ فروش می‌پذیرد. هیچ دسترسی به داده‌های خصوصی مشتری وجود ندارد.",
        "version": "1.0.0",
        "contact": {
            "name": "تلفن ابری همکاران",
            "email": "info@hamkaran.cloud",
            "url": "https://hamkaran.cloud"
        },
        "license": {
            "name": "Public",
            "url": "https://hamkaran.cloud/openapi.json"
        }
    },
    "servers": [
        {
            "url": "https://hamkaran.cloud/wp-json/hamkaran-ai/v1/",
            "description": "WordPress REST API"
        }
    ],
    "externalDocs": {
        "description": "Portal توسعه‌دهنده",
        "url": "https://developers.hamkaran.cloud"
    },
    "tags": [
        {
            "name": "services",
            "description": "خدمات و قابلیت‌ها"
        },
        {
            "name": "pricing",
            "description": "پلن‌ها و محاسبه هزینه"
        },
        {
            "name": "content",
            "description": "مقالات، مستندات، FAQ"
        },
        {
            "name": "business",
            "description": "معرفی کسب‌وکار و تماس"
        },
        {
            "name": "leads",
            "description": "ثبت سرنخ (demo/consultation/sales)"
        }
    ],
    "paths": {
        "/manifest": {
            "get": {
                "tags": [
                    "manifest"
                ],
                "summary": "دریافت فهرست کامل ابزارها و متادیتای API.",
                "operationId": "manifest",
                "description": "دریافت فهرست کامل ابزارها و متادیتای API.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/services": {
            "get": {
                "tags": [
                    "services"
                ],
                "summary": "فهرست خدمات اصلی.",
                "operationId": "services",
                "description": "فهرست خدمات اصلی.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/services/{slug}": {
            "get": {
                "tags": [
                    "services"
                ],
                "summary": "جزئیات یک خدمت.",
                "operationId": "service_detail",
                "description": "جزئیات یک خدمت.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                },
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "شناسه خدمت."
                    }
                ]
            }
        },
        "/features": {
            "get": {
                "tags": [
                    "services"
                ],
                "summary": "فهرست قابلیت‌ها.",
                "operationId": "features",
                "description": "فهرست قابلیت‌ها.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/plans": {
            "get": {
                "tags": [
                    "pricing"
                ],
                "summary": "فهرست پلن‌ها با قیمت زنده.",
                "operationId": "plans",
                "description": "فهرست پلن‌ها با قیمت زنده.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PlansResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/plans/compare": {
            "get": {
                "tags": [
                    "pricing"
                ],
                "summary": "ماتریس مقایسه پلن‌ها.",
                "operationId": "plans_compare",
                "description": "ماتریس مقایسه پلن‌ها.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/pricing/calculate": {
            "get": {
                "tags": [
                    "pricing"
                ],
                "summary": "محاسبه برآورد هزینه.",
                "operationId": "pricing_calculate",
                "description": "محاسبه برآورد هزینه.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PricingCalculation"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                },
                "parameters": [
                    {
                        "name": "plan",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "کد پلن (مثلاً starter، growth، Professional، Business، Enterprise).",
                        "example": "starter"
                    },
                    {
                        "name": "extensions",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "تعداد داخلی.",
                        "example": 2
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "monthly",
                                "quarterly",
                                "semiannual",
                                "annual"
                            ]
                        },
                        "example": "monthly"
                    },
                    {
                        "name": "addons",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                ]
            }
        },
        "/articles/search": {
            "get": {
                "tags": [
                    "content"
                ],
                "summary": "جست‌وجوی مقالات/مستندات.",
                "operationId": "articles_search",
                "description": "جست‌وجوی مقالات/مستندات.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                },
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 2
                        },
                        "description": "عبارت جست‌وجو.",
                        "example": "ضبط مکالمات"
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "post",
                                "page"
                            ]
                        },
                        "description": "نوع محتوا (پیش‌فرض post).",
                        "example": "post"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    }
                ]
            }
        },
        "/docs": {
            "get": {
                "tags": [
                    "content"
                ],
                "summary": "فهرست مستندات فنی.",
                "operationId": "docs",
                "description": "فهرست مستندات فنی.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/faq": {
            "get": {
                "tags": [
                    "content"
                ],
                "summary": "سؤالات متداول.",
                "operationId": "faq",
                "description": "سؤالات متداول.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/api-info": {
            "get": {
                "tags": [
                    "content"
                ],
                "summary": "اطلاعات API و Webhook.",
                "operationId": "api_info",
                "description": "اطلاعات API و Webhook.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/contact": {
            "get": {
                "tags": [
                    "business"
                ],
                "summary": "اطلاعات تماس.",
                "operationId": "contact",
                "description": "اطلاعات تماس.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/business": {
            "get": {
                "tags": [
                    "business"
                ],
                "summary": "معرفی کامل کسب‌وکار.",
                "operationId": "business",
                "description": "معرفی کامل کسب‌وکار.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/phone-numbers": {
            "get": {
                "tags": [
                    "services"
                ],
                "summary": "فهرست اپراتورهای ارائه‌دهنده خطوط PSTN و معرفی صفحه انتخاب شماره.",
                "operationId": "phone_operators",
                "description": "فهرست اپراتورهای ارائه‌دهنده خطوط PSTN و معرفی صفحه انتخاب شماره.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                }
            }
        },
        "/leads/demo": {
            "post": {
                "tags": [
                    "leads"
                ],
                "summary": "ثبت درخواست demo. شامل rate limit، honeypot و اعتبارسنجی موبایل.",
                "operationId": "lead_demo",
                "description": "ثبت درخواست demo. شامل rate limit، honeypot و اعتبارسنجی موبایل.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "mobile"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 100,
                                        "example": "سارا حسینی"
                                    },
                                    "mobile": {
                                        "type": "string",
                                        "pattern": "^09[0-9]{9}$",
                                        "description": "موبایل ایرانی به‌فرمت 09XXXXXXXXX.",
                                        "example": "09120000000"
                                    },
                                    "company": {
                                        "type": "string",
                                        "maxLength": 200,
                                        "example": "شرکت نمونه"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "maxLength": 1000
                                    },
                                    "use_case": {
                                        "type": "string",
                                        "maxLength": 300
                                    },
                                    "source": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "hp": {
                                        "type": "string",
                                        "description": "honeypot — باید خالی باشد."
                                    }
                                }
                            },
                            "examples": {
                                "valid": {
                                    "summary": "درخواست معتبر",
                                    "value": {
                                        "name": "سارا حسینی",
                                        "mobile": "09120000000",
                                        "company": "شرکت نمونه",
                                        "notes": "درخواست دمو برای تیم فروش ۳ نفره",
                                        "source": "ai-agent/claude"
                                    }
                                }
                            }
                        }
                    }
                },
                "x-side-effect": true,
                "x-requires-confirm": true
            }
        },
        "/leads/consultation": {
            "post": {
                "tags": [
                    "leads"
                ],
                "summary": "ثبت درخواست consultation. شامل rate limit، honeypot و اعتبارسنجی موبایل.",
                "operationId": "lead_consultation",
                "description": "ثبت درخواست consultation. شامل rate limit، honeypot و اعتبارسنجی موبایل.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "mobile"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 100,
                                        "example": "سارا حسینی"
                                    },
                                    "mobile": {
                                        "type": "string",
                                        "pattern": "^09[0-9]{9}$",
                                        "description": "موبایل ایرانی به‌فرمت 09XXXXXXXXX.",
                                        "example": "09120000000"
                                    },
                                    "company": {
                                        "type": "string",
                                        "maxLength": 200,
                                        "example": "شرکت نمونه"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "maxLength": 1000
                                    },
                                    "use_case": {
                                        "type": "string",
                                        "maxLength": 300
                                    },
                                    "source": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "hp": {
                                        "type": "string",
                                        "description": "honeypot — باید خالی باشد."
                                    }
                                }
                            },
                            "examples": {
                                "valid": {
                                    "summary": "درخواست معتبر",
                                    "value": {
                                        "name": "سارا حسینی",
                                        "mobile": "09120000000",
                                        "company": "شرکت نمونه",
                                        "notes": "درخواست دمو برای تیم فروش ۳ نفره",
                                        "source": "ai-agent/claude"
                                    }
                                }
                            }
                        }
                    }
                },
                "x-side-effect": true,
                "x-requires-confirm": true
            }
        },
        "/leads/sales": {
            "post": {
                "tags": [
                    "leads"
                ],
                "summary": "ثبت درخواست sales. شامل rate limit، honeypot و اعتبارسنجی موبایل.",
                "operationId": "lead_sales",
                "description": "ثبت درخواست sales. شامل rate limit، honeypot و اعتبارسنجی موبایل.",
                "responses": {
                    "200": {
                        "description": "پاسخ موفق.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Error",
                        "description": "پارامتر نامعتبر."
                    },
                    "404": {
                        "$ref": "#/components/responses/Error",
                        "description": "یافت نشد."
                    },
                    "429": {
                        "$ref": "#/components/responses/Error",
                        "description": "محدودیت نرخ (rate limit)."
                    },
                    "500": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای داخلی."
                    },
                    "502": {
                        "$ref": "#/components/responses/Error",
                        "description": "خطای سرویس خارجی (مثلاً کاتالوگ قیمت)."
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "mobile"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 100,
                                        "example": "سارا حسینی"
                                    },
                                    "mobile": {
                                        "type": "string",
                                        "pattern": "^09[0-9]{9}$",
                                        "description": "موبایل ایرانی به‌فرمت 09XXXXXXXXX.",
                                        "example": "09120000000"
                                    },
                                    "company": {
                                        "type": "string",
                                        "maxLength": 200,
                                        "example": "شرکت نمونه"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "maxLength": 1000
                                    },
                                    "use_case": {
                                        "type": "string",
                                        "maxLength": 300
                                    },
                                    "source": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "hp": {
                                        "type": "string",
                                        "description": "honeypot — باید خالی باشد."
                                    }
                                }
                            },
                            "examples": {
                                "valid": {
                                    "summary": "درخواست معتبر",
                                    "value": {
                                        "name": "سارا حسینی",
                                        "mobile": "09120000000",
                                        "company": "شرکت نمونه",
                                        "notes": "درخواست دمو برای تیم فروش ۳ نفره",
                                        "source": "ai-agent/claude"
                                    }
                                }
                            }
                        }
                    }
                },
                "x-side-effect": true,
                "x-requires-confirm": true
            }
        }
    },
    "components": {
        "securitySchemes": {},
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "code",
                    "message"
                ],
                "properties": {
                    "code": {
                        "type": "string",
                        "description": "کد خطای ماشین‌خوانا (مثل hcai_plan_not_found).",
                        "example": "hcai_invalid_input"
                    },
                    "message": {
                        "type": "string",
                        "description": "پیام خطای قابل‌فهم.",
                        "example": "پارامتر plan الزامی است."
                    },
                    "data": {
                        "type": "object",
                        "description": "داده‌های تکمیلی خطا (اختیاری).",
                        "properties": {
                            "status": {
                                "type": "integer",
                                "description": "HTTP status code تکراری."
                            }
                        }
                    }
                }
            },
            "Plan": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "code": {
                        "type": "string",
                        "example": "starter"
                    },
                    "name": {
                        "type": "string",
                        "example": "استارتر"
                    },
                    "description": {
                        "type": "string"
                    },
                    "included_extensions": {
                        "type": "integer",
                        "example": 2
                    },
                    "min_extensions": {
                        "type": "integer",
                        "example": 2
                    },
                    "monthly_price_per_extension": {
                        "type": "integer",
                        "description": "قیمت هر داخلی به‌ریال در ماه.",
                        "example": 1900000
                    },
                    "image_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "sort": {
                        "type": "integer"
                    }
                }
            },
            "PlansResponse": {
                "type": "object",
                "properties": {
                    "plans": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Plan"
                        }
                    },
                    "setup_fee": {
                        "type": "object",
                        "nullable": true
                    },
                    "tax": {
                        "type": "object",
                        "nullable": true
                    },
                    "addons": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "currency": {
                        "type": "string",
                        "example": "IRR"
                    },
                    "source": {
                        "type": "string"
                    },
                    "retrieved_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "PricingCalculation": {
                "type": "object",
                "properties": {
                    "plan": {
                        "type": "object"
                    },
                    "extensions": {
                        "type": "integer",
                        "example": 2
                    },
                    "period": {
                        "type": "string",
                        "example": "monthly"
                    },
                    "months": {
                        "type": "integer",
                        "example": 1
                    },
                    "subscription_total": {
                        "type": "integer",
                        "example": 3800000
                    },
                    "setup_fee": {
                        "type": "object"
                    },
                    "addons": {
                        "type": "object"
                    },
                    "vat": {
                        "type": "object"
                    },
                    "net_total": {
                        "type": "integer"
                    },
                    "grand_total": {
                        "type": "integer"
                    },
                    "currency": {
                        "type": "string",
                        "example": "IRR"
                    },
                    "warning": {
                        "type": "string"
                    },
                    "source": {
                        "type": "string"
                    },
                    "retrieved_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            }
        },
        "responses": {
            "Error": {
                "description": "خطای ساختاریافته.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        },
                        "examples": {
                            "ValidationError": {
                                "summary": "خطای اعتبارسنجی",
                                "value": {
                                    "code": "hcai_invalid_input",
                                    "message": "پارامتر extensions باید عدد صحیح بزرگ‌تر از صفر باشد.",
                                    "data": {
                                        "status": 400
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}