{ "openapi": "3.1.0", "info": { "title": "Labeb Public API", "version": "1.0.0", "description": "واجهةُ لَبيب العامّة. كلُّ أداةٍ يراها المستشار وMCP متاحةٌ هنا بالمسار نفسه: `POST /api/v1/tools/{key}` بجسمٍ JSON يطابق مخطّط الأداة. الرمزُ نفسُه يخدم REST وMCP، ويُصدَر من «الإعدادات ← الربط الخارجيّ». التنفيذُ باسم موظّف الربط الخارجيّ وبأدواره وحدَها." }, "servers": [ { "url": "https://labeb.app" } ], "security": [ { "bearerToken": [] } ], "tags": [ { "name": "auth", "description": "الهويّة" }, { "name": "tools", "description": "فهرسُ الأدوات" }, { "name": "advisor", "description": "7 أداة" }, { "name": "general", "description": "7 أداة" }, { "name": "hr", "description": "18 أداة" }, { "name": "leads", "description": "17 أداة" }, { "name": "postsale", "description": "10 أداة" }, { "name": "product", "description": "19 أداة" }, { "name": "settings", "description": "13 أداة" }, { "name": "strategy", "description": "12 أداة" }, { "name": "tasks", "description": "7 أداة" }, { "name": "whatsapp", "description": "21 أداة" } ], "paths": { "/api/v1/me": { "get": { "tags": [ "auth" ], "operationId": "getMe", "summary": "هويّة الرمز: المستأجر والموظّف الذي يعمل باسمه ونطاقُه", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/tools": { "get": { "tags": [ "tools" ], "operationId": "listTools", "summary": "الأدواتُ المتاحة لهذا الرمز (نطاقُ الرمز ∩ صلاحيّاتُ موظّفه)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/tools/get_ai_agent": { "post": { "tags": [ "advisor" ], "operationId": "get_ai_agent", "summary": "قراءة برومبت وكيل", "description": "تفاصيل وكيل ذكاء واحد بما فيها البرومبت الكامل — للمراجعة أو التحسين.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentKey": { "type": "string" } }, "required": [ "agentKey" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "ai.prompt.manage" } }, "/api/v1/tools/get_business_profile": { "post": { "tags": [ "advisor" ], "operationId": "get_business_profile", "summary": "قراءة ملفّ الشركة", "description": "ملفّ الشركة (النشاط · المنتجات · الجمهور · النبرة · اللهجة · السياسات · الباقات · الأسئلة الشائعة …) مع **قائمة الحقول الناقصة** و**هل يصل الملفّ للبوت فعلاً** أم يحجبه برومبتٌ يدويّ. ابدأ بها قبل أي نصيحة عن ردود البوت: برومبتٌ ضعيف سببه غالباً ملفٌّ ناقص لا قالبٌ خاطئ.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "ai.prompt.manage" } }, "/api/v1/tools/list_ai_agents": { "post": { "tags": [ "advisor" ], "operationId": "list_ai_agents", "summary": "قائمة وكلاء الذكاء", "description": "وكلاء الذكاء القابلون للضبط في الشركة (المبيعات، ما بعد البيع...) مع النموذج والحالة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "ai.prompt.manage" } }, "/api/v1/tools/plan_mission": { "post": { "tags": [ "advisor" ], "operationId": "plan_mission", "summary": "تفكيك إلى مهمة", "description": "استدعِها حين يتطلّب الطلب عدة خطوات أو قراءة بيانات كثيرة (مراجعة محادثات، تدقيق جودة، تحليل شامل، تقرير مركّب). بدل محاولة إنجازه في هذه الدورة — فتتوقف ناقصاً — فكّكه إلى خطوات متسلسلة تعمل في الخلفية ويرى المستخدم تقدّمها. لا تضف خطوة تجميع نهائية؛ تُضاف تلقائياً. للطلب البسيط لا تستدعِها إطلاقاً — أجب مباشرة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "عنوان قصير للخطوة" }, "brief": { "type": "string", "description": "ماذا تقرأ هذه الخطوة بالضبط وماذا تُخرج" } }, "required": [ "title", "brief" ] } } }, "required": [ "steps" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "advisor.mission" } }, "/api/v1/tools/test_ai_agent_reply": { "post": { "tags": [ "advisor" ], "operationId": "test_ai_agent_reply", "summary": "اختبار برومبت", "description": "اختبار برومبت وكيل: أرسل رسالة عميل تجريبية واحصل على ردّ الوكيل الفعلي (يُخصم من رصيد الذكاء).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentKey": { "type": "string" }, "sampleMessage": { "type": "string" } }, "required": [ "agentKey", "sampleMessage" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "ai.prompt.manage" } }, "/api/v1/tools/update_ai_agent": { "post": { "tags": [ "advisor" ], "operationId": "update_ai_agent", "summary": "تعديل وكيل ذكاء", "description": "تعديل وكيل ذكاء: البرومبت أو النموذج أو الإعدادات أو التفعيل. يسري فوراً على ردود البوت.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentKey": { "type": "string" }, "systemPrompt": { "type": "string" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "maxTokens": { "type": "integer" }, "isEnabled": { "type": "boolean" } }, "required": [ "agentKey" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "ai.prompt.manage" } }, "/api/v1/tools/update_business_profile": { "post": { "tags": [ "advisor" ], "operationId": "update_business_profile", "summary": "تعديل ملفّ الشركة", "description": "تعديل جزئيّ لملفّ الشركة ثم **إعادة بناء برومبت الوكلاء المبنيّين منه تلقائياً**. مرّر الحقول التي تريد تغييرها فقط؛ الحقل غير المُمرَّر لا يُلمس، والقيمة الفارغة تفريغٌ صريح. الوكيل ذو البرومبت اليدويّ لا يتأثّر (تُعاد نتيجةُ الأداة بذلك صراحةً).", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyName": { "type": "string" }, "activity": { "type": "string" }, "products": { "type": "string" }, "audience": { "type": "string" }, "tone": { "type": "string" }, "dialect": { "type": "string" }, "cityCountry": { "type": "string" }, "differentiators": { "type": "string" }, "policies": { "type": "string" }, "notServed": { "type": "string" }, "escalationTarget": { "type": "string" }, "workingHours": { "type": "string" }, "valueLine": { "type": "string" }, "packages": { "type": "string" }, "competitors": { "type": "string" }, "officialLinks": { "type": "string" }, "faqs": { "type": "string" }, "objections": { "type": "string" }, "examples": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "ai.prompt.manage" } }, "/api/v1/tools/find_tools": { "post": { "tags": [ "general" ], "operationId": "find_tools", "summary": "بحث عن أدوات", "description": "ابحث عن أدوات إضافية في النظام بالعربية حين لا تجد بين أدواتك الحالية ما ينجز الطلب (ما بعد البيع، الرواتب، المنتجات، قواعد الأتمتة، الفرص، الأداء، الهيكل الإداري…). الأدوات المطابقة **تُتاح لك فوراً** فاستدعِها في ردّك التالي. لا تستدعِها إن كانت أدواتك الحالية تكفي.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "وصف ما تريد فعله بالعربية" } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tools/get_advisor_self_report": { "post": { "tags": [ "general" ], "operationId": "get_advisor_self_report", "summary": "مراجعة ذاتية", "description": "تقرير المستشار عن نفسه خلال فترة: عدد الطلبات وأزمنتها وتكلفتها، الأدوات التي فشلت ولماذا، حالات المهام، ونسبة الملاحظات التي وسمها المستخدم «غير دقيقة» (مقياس دقّتي الفعلي).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 90 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tools/get_ai_usage_report": { "post": { "tags": [ "general" ], "operationId": "get_ai_usage_report", "summary": "تقرير استهلاك الذكاء", "description": "تقرير استهلاك الذكاء الاصطناعي للشركة خلال فترة: الإجمالي وبحسب الوكيل. days الافتراضي 30.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 90 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tools/get_usage_summary": { "post": { "tags": [ "general" ], "operationId": "get_usage_summary", "summary": "استعمال الشاشات", "description": "أكثر شاشات النظام فتحاً في مؤسستي خلال فترة (الافتراضي 30 يوماً): المسار وعدد الفتحات وعدد المستخدمين المختلفين وآخر مرّة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "maximum": 90 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "admin.usage.read" } }, "/api/v1/tools/get_workspace_overview": { "post": { "tags": [ "general" ], "operationId": "get_workspace_overview", "summary": "نظرة عامة", "description": "نظرة عامة على وضع المستخدم الآن: عدّادات الأهداف السنوية والشهرية والمشاريع النشطة ومهامه المفتوحة، مع التاريخ الحالي.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tools/list_users": { "post": { "tags": [ "general" ], "operationId": "list_users", "summary": "قائمة الفريق", "description": "قائمة مستخدمي النظام (الفريق) بالمعرّف والاسم — استخدمها للحصول على userId قبل إسناد مهمة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tools/remember": { "post": { "tags": [ "general" ], "operationId": "remember", "summary": "حفظ في الذاكرة", "description": "احفظ حقيقة أو قراراً أو تفضيلاً **دائماً** عن المستخدم أو الشركة ذكره في المحادثة وسينفع في محادثات قادمة (مثل: «قرّرنا تأجيل كذا»، «أحمد يفضّل التقارير مختصرة»). لا تحفظ تفاصيل عابرة ولا أرقاماً متغيّرة ولا ما يمكن قراءته بالأدوات. جملة واحدة موجزة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "fact|decision|preference" }, "text": { "type": "string" } }, "required": [ "kind", "text" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tools/attendance_check_in": { "post": { "tags": [ "hr" ], "operationId": "attendance_check_in", "summary": "تسجيل حضور", "description": "تسجيل حضوري أنا الآن (يتطلب أن يكون لحسابك سجل موظف). اقتبس الوقت من checkInAt في النتيجة حرفياً — ولا تذكر وقتاً غيره.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.create.own" } }, "/api/v1/tools/attendance_check_out": { "post": { "tags": [ "hr" ], "operationId": "attendance_check_out", "summary": "تسجيل انصراف", "description": "تسجيل انصرافي أنا الآن. اقتبس الوقت من checkOutAt في النتيجة حرفياً — ولا تذكر وقتاً غيره.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.create.own" } }, "/api/v1/tools/decide_leave": { "post": { "tags": [ "hr" ], "operationId": "decide_leave", "summary": "قرار إجازة", "description": "الموافقة على طلب إجازة أو رفضه. استخدم get_leaves_report أولاً — يعيد id لكل طلب مع اسم صاحبه.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "leaveId": { "type": "string", "description": "معرّف طلب الإجازة أو اسم صاحبه" }, "approve": { "type": "boolean" } }, "required": [ "leaveId", "approve" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.leave.approve.direct" } }, "/api/v1/tools/get_attendance_report": { "post": { "tags": [ "hr" ], "operationId": "get_attendance_report", "summary": "تقرير الحضور", "description": "تقرير الحضور لفترة (الافتراضي 14 يوماً): حضور/غياب/تأخير لكل موظف.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "maximum": 92 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.read.all" } }, "/api/v1/tools/get_employee_attendance": { "post": { "tags": [ "hr" ], "operationId": "get_employee_attendance", "summary": "حضور موظف", "description": "تقرير حضور موظف واحد بالاسم أو المعرّف خلال فترة (الافتراضي 30 يوماً): ملخص (حضور، تأخير، غياب، عن بعد، دقائق التأخير، ساعات العمل، نسبة الالتزام) + الإجازات + كل يوم بوقت الدخول والخروج بتوقيت الشركة. من يملك قراءة حضور الجميع يرى أي موظف، وغيره يرى نفسه ومن تحته فقط.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee": { "type": "string", "description": "اسم الموظف أو جزء منه، أو معرّف الموظف أو المستخدم" }, "days": { "type": "integer", "minimum": 1, "maximum": 92 } }, "required": [ "employee" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.read.team" } }, "/api/v1/tools/get_employee_team_attendance": { "post": { "tags": [ "hr" ], "operationId": "get_employee_team_attendance", "summary": "حضور فريق موظف", "description": "تقرير حضور فريق موظف (من تحته في الخط الإداري) خلال فترة (الافتراضي 30 يوماً): ملخص الفريق + لكل عضو ملخصه وحالته اليوم + من لم يسجّل دخوله اليوم. بلا employee يعيد فريقك أنت. من يملك قراءة حضور الجميع يرى فريق أي مدير، وغيره يرى فريقه أو فريق مدير تحته فقط.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee": { "type": "string", "description": "اسم المدير أو معرّفه — اختياري" }, "days": { "type": "integer", "minimum": 1, "maximum": 92 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.read.team" } }, "/api/v1/tools/get_leaves_report": { "post": { "tags": [ "hr" ], "operationId": "get_leaves_report", "summary": "تقرير الإجازات", "description": "طلبات الإجازات (معلقة وموافَقة) ضمن فترة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "maximum": 92 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.leave.read.all" } }, "/api/v1/tools/get_my_attendance": { "post": { "tags": [ "hr" ], "operationId": "get_my_attendance", "summary": "سجل حضوري", "description": "سجل حضوري خلال فترة (الافتراضي 14 يوماً).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "maximum": 62 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.read.own" } }, "/api/v1/tools/get_my_team": { "post": { "tags": [ "hr" ], "operationId": "get_my_team", "summary": "فريقي", "description": "مَن في فريقي: الموظفون الذين أديرهم مباشرةً أو عبر الخطّ الإداري، بأسمائهم ومناصبهم.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.employee.read.team" } }, "/api/v1/tools/get_org_chart": { "post": { "tags": [ "hr" ], "operationId": "get_org_chart", "summary": "الهيكل الإداري", "description": "الهيكل الإداري: المناصب وشجرتها + الموظفون ومناصبهم ومدراؤهم المباشرون.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.employee.read.all" } }, "/api/v1/tools/get_team_attendance": { "post": { "tags": [ "hr" ], "operationId": "get_team_attendance", "summary": "حضور فريقي", "description": "حضور فريقي خلال فترة (الافتراضي 14 يوماً): حضور وغياب وتأخير لكل فرد أديره.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "maximum": 92 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.read.team" } }, "/api/v1/tools/get_team_member_profile": { "post": { "tags": [ "hr" ], "operationId": "get_team_member_profile", "summary": "بطاقة موظف في فريقي", "description": "البطاقة الوظيفية لموظف في فريقي بالاسم: المنصب والقسم وتاريخ التوظيف والمدير المباشر.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.profile.read.team" } }, "/api/v1/tools/list_coaching_notes": { "post": { "tags": [ "hr" ], "operationId": "list_coaching_notes", "summary": "ملاحظات التدريب", "description": "ملاحظات التدريب (الكوتشينغ) للموظفين: العنوان والأولوية والحالة والمُسنَد إليه.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "new|seen|started|submitted|resolved" }, "limit": { "type": "integer", "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "coaching.notes.view" } }, "/api/v1/tools/list_employees": { "post": { "tags": [ "hr" ], "operationId": "list_employees", "summary": "قراءة الموظفين", "description": "قائمة الموظفين: id (معرّف الموظف)، userId (معرّف المستخدم — هذا ما تطلبه أدوات الإسناد)، الاسم، المنصب، القسم، الحالة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.employee.read.all" } }, "/api/v1/tools/list_payroll_grievances": { "post": { "tags": [ "hr" ], "operationId": "list_payroll_grievances", "summary": "تظلّمات الرواتب", "description": "تظلّمات الرواتب: الموضوع والحالة ومن فتحها ومتى روجعت.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "limit": { "type": "integer", "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "payroll.grievance.review" } }, "/api/v1/tools/list_payroll_runs": { "post": { "tags": [ "hr" ], "operationId": "list_payroll_runs", "summary": "دورات الرواتب", "description": "دورات الرواتب: الفترة والحالة واعتمادات المدير والموارد البشرية وحاجة إعادة الاحتساب.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "payroll.run.read" } }, "/api/v1/tools/mark_employee_attendance": { "post": { "tags": [ "hr" ], "operationId": "mark_employee_attendance", "summary": "تسجيل حضور موظف", "description": "تسجيل حضور موظف آخر بالنيابة عنه اليوم (للمدير أو الموارد البشرية): action واحدة من present حاضر · late متأخر · absent غائب · remote عن بعد · check_out انصراف الآن. employee بالاسم أو المعرّف.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee": { "type": "string" }, "action": { "type": "string", "enum": [ "present", "late", "absent", "remote", "check_out" ] }, "notes": { "type": "string" }, "workLocation": { "type": "string" } }, "required": [ "employee", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.attendance.update.all" } }, "/api/v1/tools/request_leave": { "post": { "tags": [ "hr" ], "operationId": "request_leave", "summary": "طلب إجازة", "description": "تقديم طلب إجازة لي: النوع (annual|sick|unpaid|other) وتاريخا البداية والنهاية.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "leaveType": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "leaveType", "startDate", "endDate" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "hr.leave.request.own" } }, "/api/v1/tools/add_lead_note": { "post": { "tags": [ "leads" ], "operationId": "add_lead_note", "summary": "إضافة ملاحظة عميل", "description": "إضافة ملاحظة مؤرخة على بطاقة عميل محتمل.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "معرّف العميل أو اسمه أو رقمه" }, "note": { "type": "string" } }, "required": [ "customerId", "note" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/assign_follow_up_template": { "post": { "tags": [ "leads" ], "operationId": "assign_follow_up_template", "summary": "إسناد قالب متابعة", "description": "إسناد قالب متابعة لعميل: **يلغي كل متابعاته المعلّقة أولاً** ثم ينشئ تسلسل خطوات القالب من الآن. استخدم list_follow_up_templates لمعرفة القوالب ومراحلها.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "معرّف العميل أو اسمه أو هاتفه" }, "templateId": { "type": "string", "description": "معرّف قالب المتابعة أو اسمه" } }, "required": [ "customerId", "templateId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/cancel_lead_follow_ups": { "post": { "tags": [ "leads" ], "operationId": "cancel_lead_follow_ups", "summary": "إيقاف متابعات عميل", "description": "إيقاف كل المتابعات المعلّقة لعميل دفعةً واحدة (مثلاً حين يردّ العميل أو يُغلق ملفه). لا يمسّ المُرسَلة.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "معرّف العميل أو اسمه أو هاتفه" } }, "required": [ "customerId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/complete_follow_up": { "post": { "tags": [ "leads" ], "operationId": "complete_follow_up", "summary": "إقفال متابعة", "description": "إقفال تذكير متابعة بـ«تمّت المتابعة» بعد أن تواصل الموظف فعلاً. للتذكيرات الداخلية لا لرسائل القناة.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "followUpId": { "type": "string", "description": "معرّف المتابعة (GUID من قائمة المتابعات)" } }, "required": [ "followUpId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/get_campaign_funnel": { "post": { "tags": [ "leads" ], "operationId": "get_campaign_funnel", "summary": "قمع الحملة", "description": "قمعُ حملةٍ واحدة: كم عميلاً جلبت وماذا حدث لهم (interested · engaged · trial · won · lost)، مع نسبة التحويل وأسباب الخسارة وتكلفة العميل وتكلفة الصفقة من إنفاق الحملة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "string", "description": "معرّف الحملة أو معرّفها في ميتا أو اسمها كاملاً أو جزءاً منه" }, "period": { "type": "string", "description": "today|yesterday|last24h|last7d|last30d|all — الافتراضي all" }, "fromDate": { "type": "string" }, "toDate": { "type": "string" } }, "required": [ "campaign" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/get_crm_report": { "post": { "tags": [ "leads" ], "operationId": "get_crm_report", "summary": "تقرير العملاء", "description": "تقرير العملاء المحتملين: توزيعهم على المراحل + الجدد خلال فترة + آخر العملاء. days الافتراضي 30.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 365 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/get_follow_ups_report": { "post": { "tags": [ "leads" ], "operationId": "get_follow_ups_report", "summary": "تقرير المتابعات", "description": "تقرير المتابعات: التوزيع على الحالات والأنواع خلال فترة + المتابعات القادمة غير المرسلة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 180 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/get_lead_details": { "post": { "tags": [ "leads" ], "operationId": "get_lead_details", "summary": "تفاصيل عميل", "description": "بطاقة عميل محتمل كاملة بالبحث بالهاتف أو الاسم: البيانات، المرحلة، الملاحظات، ملخص الرحلة إن وجد.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/get_lead_settings": { "post": { "tags": [ "leads" ], "operationId": "get_lead_settings", "summary": "إعدادات العملاء", "description": "إعدادات العملاء المحتملين: مصادر العملاء المعرّفة وأسباب الخسارة — مفيدة قبل تحليل المصادر أو الخسارة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/get_lead_source_report": { "post": { "tags": [ "leads" ], "operationId": "get_lead_source_report", "summary": "مصادر العملاء", "description": "مصادرُ العملاء خلال فترة، ولكلّ مصدرٍ اسمٌ مقروء (label) وتوزيعُ حملاته — ومجموعُ التفصيل يطابق الإجمالي دائماً لأنّ ما بلا حملةٍ يظهر سطراً صريحاً «بلا حملة». المصادر: meta_ctwa = إعلانات ميتا (يشمل من نقر الإعلان ثم كتب نصّاً من عنده) · whatsapp = تواصل مباشر بلا إعلان · tenant_data = بيانات مستوردة · manual = إدخال يدوي. ومعه توزيعٌ حسب القناة (واتساب · ماسنجر · الموقع) والبلد ومسار الإسناد (ctwa_click = نقرة إعلان مؤكّدة · opener = عبارة افتتاحية). الفترة تقويميّة بتوقيت حساب المستأجر.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "description": "today|yesterday|last24h|last7d|last30d|all — الافتراضي last24h" }, "fromDate": { "type": "string", "description": "YYYY-MM-DD بتوقيت حساب المستأجر" }, "toDate": { "type": "string", "description": "YYYY-MM-DD شاملاً" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/get_leads_by_campaign": { "post": { "tags": [ "leads" ], "operationId": "get_leads_by_campaign", "summary": "عملاء حملة", "description": "عملاءُ حملةٍ واحدة: العددُ أوّلاً ثمّ القائمةُ ثمّ الملخّص. تقبل معرّف الحملة أو معرّفها في ميتا أو اسمها كاملاً أو جزءاً منه (تُطابَق بعد تجاهل علامات اتّجاه النصّ وفروق المسافات). ولكلّ عميل: الاسمُ والهاتفُ ووقتُ الدخول والمصدرُ والمرحلةُ والمسؤولُ وسببُ الخسارة والبلدُ ومسارُ الإسناد (نقرة إعلان أم عبارة افتتاحية).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "string", "description": "معرّف الحملة أو معرّفها في ميتا أو اسمها كاملاً أو جزءاً منه" }, "period": { "type": "string", "description": "today|yesterday|last24h|last7d|last30d|all — الافتراضي all" }, "fromDate": { "type": "string", "description": "YYYY-MM-DD بتوقيت حساب المستأجر" }, "toDate": { "type": "string", "description": "YYYY-MM-DD شاملاً" }, "source": { "type": "string" }, "stage": { "type": "string" }, "limit": { "type": "integer", "maximum": 200 } }, "required": [ "campaign" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/list_follow_up_templates": { "post": { "tags": [ "leads" ], "operationId": "list_follow_up_templates", "summary": "قوالب المتابعة", "description": "قوالب متابعة العملاء المحتملين: المرحلة التي تنطبق عليها، مفعّلة أم لا، عدد خطواتها، ونمط التشغيل.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "followup.manage" } }, "/api/v1/tools/list_follow_ups": { "post": { "tags": [ "leads" ], "operationId": "list_follow_ups", "summary": "المتابعات", "description": "المتابعات المجدولة والمرسلة (الافتراضي القادمة والمعلقة).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "maximum": 40 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/list_sales_opportunities": { "post": { "tags": [ "leads" ], "operationId": "list_sales_opportunities", "summary": "الفرص البيعية", "description": "الفرص البيعية: التوزيع على المراحل مع مجموع القيمة + آخر الفرص وأسباب الخسارة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.view" } }, "/api/v1/tools/reschedule_follow_up": { "post": { "tags": [ "leads" ], "operationId": "reschedule_follow_up", "summary": "تعديل متابعة", "description": "تعديل متابعة معلّقة: تأجيلها أو تغيير نصها أو تخطيها أو إلغاؤها. followUpId من list_follow_ups أو get_follow_ups_report. status: pending|skipped|cancelled. المتابعات المُرسَلة تاريخٌ لا يُعدَّل.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "followUpId": { "type": "string", "description": "معرّف المتابعة (GUID من قائمة المتابعات)" }, "scheduledAt": { "type": "string", "description": "الموعد الجديد بصيغة ISO — في المستقبل" }, "messageText": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "description": "pending|skipped|cancelled" } }, "required": [ "followUpId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/schedule_follow_up": { "post": { "tags": [ "leads" ], "operationId": "schedule_follow_up", "summary": "جدولة متابعة", "description": "جدولة متابعة لعميل محتمل في موعد مستقبلي. kind: channel (تُرسل للعميل عبر واتساب تلقائياً) | reminder (تذكير داخلي للموظف لا يصل العميل). الافتراضي channel — فاختر reminder صراحةً إن كان المقصود تذكير الفريق لا مراسلة العميل.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "معرّف العميل أو اسمه أو هاتفه" }, "messageText": { "type": "string", "description": "نص الرسالة أو التذكير" }, "scheduledAt": { "type": "string", "description": "الموعد بصيغة ISO مثل 2026-08-05T09:00:00Z — يجب أن يكون في المستقبل" }, "title": { "type": "string" }, "kind": { "type": "string", "description": "channel|reminder" } }, "required": [ "customerId", "messageText", "scheduledAt" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/update_lead_stage": { "post": { "tags": [ "leads" ], "operationId": "update_lead_stage", "summary": "نقل مرحلة عميل", "description": "نقل عميل محتمل إلى مرحلة: interested|trial|engaged. «نجاح» عبر ترقية ما بعد البيع، و«خسارة» من الواجهة مع سبب.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "معرّف العميل أو اسمه أو رقمه" }, "stage": { "type": "string" } }, "required": [ "customerId", "stage" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "leads.manage" } }, "/api/v1/tools/assign_ticket": { "post": { "tags": [ "postsale" ], "operationId": "assign_ticket", "summary": "إسناد تذكرة", "description": "إسناد تذكرة لموظف (استخدم list_users للمعرّف).", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketId": { "type": "string", "description": "معرّف التذكرة أو رقمها أو عنوانها" }, "userId": { "type": "string", "description": "معرّف المستخدم أو اسمه" } }, "required": [ "ticketId", "userId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "quality.ticket.assign" } }, "/api/v1/tools/create_kb_article": { "post": { "tags": [ "postsale" ], "operationId": "create_kb_article", "summary": "إضافة مقال معرفة", "description": "إضافة مقال جديد لقاعدة المعرفة (يتفهرس فوراً لبوت الدعم).", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "category": { "type": "string" }, "isPublished": { "type": "boolean" } }, "required": [ "title", "content" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "postsale.kb.manage" } }, "/api/v1/tools/create_ticket": { "post": { "tags": [ "postsale" ], "operationId": "create_ticket", "summary": "فتح تذكرة", "description": "فتح تذكرة دعم جديدة (تحسب SLA تلقائياً).", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string", "description": "low|normal|high|critical" }, "assignedToUserId": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "quality.ticket.create" } }, "/api/v1/tools/get_postsale_customer": { "post": { "tags": [ "postsale" ], "operationId": "get_postsale_customer", "summary": "تفاصيل عميل ما بعد البيع", "description": "تفاصيل عميل ما بعد البيع (بالهاتف أو الاسم): الحالة وخطوات الإعداد ودرجة الصحة وسبب النجاح وسرعة التحويل + آخر الملاحظات الداخلية.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "postsale.read" } }, "/api/v1/tools/get_tickets_report": { "post": { "tags": [ "postsale" ], "operationId": "get_tickets_report", "summary": "تقرير التذاكر", "description": "تقرير تذاكر الدعم: توزيع الحالات + أحدث التذاكر المفتوحة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tickets.read" } }, "/api/v1/tools/list_kb_articles": { "post": { "tags": [ "postsale" ], "operationId": "list_kb_articles", "summary": "قائمة المقالات", "description": "قائمة مقالات قاعدة المعرفة (منشورة ومسودات) مع التصنيف.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string" }, "limit": { "type": "integer", "maximum": 30 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "postsale.read" } }, "/api/v1/tools/list_postsale_customers": { "post": { "tags": [ "postsale" ], "operationId": "list_postsale_customers", "summary": "عملاء ما بعد البيع", "description": "عملاء ما بعد البيع: التوزيع على الحالات + قائمة بالاسم والهاتف ودرجة الصحة والفئة والمسؤول.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "pending|active|churned… (اختياري)" }, "limit": { "type": "integer", "maximum": 60 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "postsale.read" } }, "/api/v1/tools/search_knowledge_base": { "post": { "tags": [ "postsale" ], "operationId": "search_knowledge_base", "summary": "بحث قاعدة المعرفة", "description": "بحث دلالي في قاعدة المعرفة — نفس البحث الذي يستخدمه بوت الدعم.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "topK": { "type": "integer", "maximum": 10 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "postsale.read" } }, "/api/v1/tools/update_kb_article": { "post": { "tags": [ "postsale" ], "operationId": "update_kb_article", "summary": "تعديل مقال معرفة", "description": "تعديل مقال معرفة قائم (عنوان/محتوى/تصنيف/نشر).", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "articleId": { "type": "string", "description": "معرّف المقال أو عنوانه" }, "title": { "type": "string" }, "content": { "type": "string" }, "category": { "type": "string" }, "isPublished": { "type": "boolean" } }, "required": [ "articleId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "postsale.kb.manage" } }, "/api/v1/tools/update_ticket_status": { "post": { "tags": [ "postsale" ], "operationId": "update_ticket_status", "summary": "تغيير حالة تذكرة", "description": "تغيير حالة تذكرة: in_progress | waiting_customer | testing | resolved | cancelled.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketId": { "type": "string" }, "status": { "type": "string" }, "resolutionText": { "type": "string" } }, "required": [ "ticketId", "status" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "quality.ticket.update.all" } }, "/api/v1/tools/get_product_card": { "post": { "tags": [ "product" ], "operationId": "get_product_card", "summary": "تفاصيل بطاقة تقنية", "description": "تفاصيل بطاقة تقنية بعنوانها: الوصف والحالة والأولوية والنظام وعدد الطالبين + آخر التعليقات.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.view" } }, "/api/v1/tools/get_product_report": { "post": { "tags": [ "product" ], "operationId": "get_product_report", "summary": "تقرير إدارة المنتج", "description": "تقرير إدارة المنتج: توزّع البطاقات على الحالات والأولويّات والأنواع، وأقدمُ البطاقات العالقة، وحِمل كلّ مسؤول، وحال الإصدارات.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.view" } }, "/api/v1/tools/list_product_card_triggers": { "post": { "tags": [ "product" ], "operationId": "list_product_card_triggers", "summary": "محفّزات البطاقات", "description": "محفّزات البطاقات التقنية: رسالة تُرسل عند تحوّل حالة البطاقة أو عند إطلاق إصدار.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.view" } }, "/api/v1/tools/list_product_cards": { "post": { "tags": [ "product" ], "operationId": "list_product_cards", "summary": "بطاقات المنتج", "description": "بطاقات المنتج (ميزات/أخطاء) مع الحالة والأولوية وعدد الطالبين — لتحليل أولويات التطوير.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "cardType": { "type": "string", "description": "feature|bug" }, "limit": { "type": "integer", "maximum": 40 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.view" } }, "/api/v1/tools/list_release_cards": { "post": { "tags": [ "product" ], "operationId": "list_release_cards", "summary": "بطاقات الإصدار", "description": "بطاقات إصدار منتجٍ واحد، لكلٍّ عمودُها على اللوحة، مع قصٍّ مُعلَن (totalRows/shownRows).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "releaseId": { "type": "string", "description": "معرّف إصدار المنتج أو نسخته أو عنوانه" }, "status": { "type": "string" }, "limit": { "type": "integer", "maximum": 200 } }, "required": [ "releaseId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.view" } }, "/api/v1/tools/list_releases": { "post": { "tags": [ "product" ], "operationId": "list_releases", "summary": "الإصدارات", "description": "آخر إصدارات النظام (ما الجديد) وبنودها.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "maximum": 15 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.releases.view" } }, "/api/v1/tools/pm_add_comment": { "post": { "tags": [ "product" ], "operationId": "pm_add_comment", "summary": "تعليق على بطاقة", "description": "تعليق داخلي على بطاقة منتج (نقاش الفريق — لا يصل العميل).", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" }, "text": { "type": "string" } }, "required": [ "cardId", "text" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.manage" } }, "/api/v1/tools/pm_assign_card": { "post": { "tags": [ "product" ], "operationId": "pm_assign_card", "summary": "إسناد بطاقة منتج", "description": "إسناد بطاقة منتج لعضو فريق (أو إلغاء الإسناد بترك userId فارغاً). يُشعر المُسنَد إليه.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" }, "userId": { "type": "string", "description": "معرّف المستخدم أو اسمه — اتركه فارغاً لإلغاء الإسناد" } }, "required": [ "cardId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.manage" } }, "/api/v1/tools/pm_assign_to_release": { "post": { "tags": [ "product" ], "operationId": "pm_assign_to_release", "summary": "ضمّ بطاقة لإصدار", "description": "ضمّ بطاقة منتج إلى إصدار.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" }, "releaseId": { "type": "string", "description": "معرّف الإصدار أو رقمه" } }, "required": [ "cardId", "releaseId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.manage" } }, "/api/v1/tools/pm_create_card": { "post": { "tags": [ "product" ], "operationId": "pm_create_card", "summary": "إنشاء بطاقة منتج", "description": "إنشاء بطاقة منتج (ميزة/خطأ/تحسين/اقتراح) بمصدر داخلي. استخدمها حين يطلب المستخدم تسجيل طلب تطوير أو خطأ. cardType: bug|feature|improvement|suggestion · priority: low|normal|high|critical.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "cardType": { "type": "string", "description": "bug|feature|improvement|suggestion" }, "priority": { "type": "string", "description": "low|normal|high|critical" }, "system": { "type": "string", "description": "اسم النظام (اختياري)" } }, "required": [ "title", "cardType" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.create" } }, "/api/v1/tools/pm_delete_card": { "post": { "tags": [ "product" ], "operationId": "pm_delete_card", "summary": "حذف بطاقة منتج", "description": "حذف بطاقة منتج. **حذف ناعم**: تختفي من القوائم ويبقى أثرها وسجلّها للتدقيق، ولا تُفقد أوقاتُها المسجَّلة.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" } }, "required": [ "cardId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.delete" } }, "/api/v1/tools/pm_list_time_entries": { "post": { "tags": [ "product" ], "operationId": "pm_list_time_entries", "summary": "سجلّ أوقات العمل", "description": "سجلّ أوقات العمل على البطاقات بين تاريخين: الموظف والبطاقة والإصدار ونوع العمل والبداية والنهاية والمدة والملاحظة ومصدر الإدخال (يدويّ/مُعدَّل/أُغلق آلياً). from/to بصيغة ISO (اليوم كاملاً). employeeId/releaseId/categoryId فلاترٌ اختيارية.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "ISO date" }, "to": { "type": "string", "description": "ISO date" }, "employeeId": { "type": "string", "description": "معرّف الموظف أو اسمه" }, "releaseId": { "type": "string", "description": "معرّف الإصدار أو رقمه" }, "categoryId": { "type": "string" }, "limit": { "type": "integer", "maximum": 200 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.time.report.team" } }, "/api/v1/tools/pm_remove_from_release": { "post": { "tags": [ "product" ], "operationId": "pm_remove_from_release", "summary": "إخراج بطاقة من إصدار", "description": "إخراج بطاقة من إصدارها. تعود البطاقة إلى مرحلتها قبل الضمّ (أو «مقبولة» إن لم يُعرف).", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" } }, "required": [ "cardId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.manage" } }, "/api/v1/tools/pm_start_timer": { "post": { "tags": [ "product" ], "operationId": "pm_start_timer", "summary": "بدء عدّاد بطاقة", "description": "بدء عدّاد الوقت على بطاقة منتج للمستخدم الحالي — يوقف عدّاده الجاري (إن وُجد) تلقائياً.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" } }, "required": [ "cardId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.manage" } }, "/api/v1/tools/pm_stop_timer": { "post": { "tags": [ "product" ], "operationId": "pm_stop_timer", "summary": "إيقاف عدّاد بطاقة", "description": "إيقاف عدّاد وقت المستخدم الحالي أياً كانت بطاقته، مع بيان ما أُنجز (اختياري).", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "بيان ما أُنجز" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.manage" } }, "/api/v1/tools/pm_time_summary": { "post": { "tags": [ "product" ], "operationId": "pm_time_summary", "summary": "تجميع أوقات العمل", "description": "تجميعُ أوقات العمل بين تاريخين: إجماليٌّ عامّ + حسب الإصدار + حسب الموظف. يُحسب على **كلّ** صفوف الفترة بلا قصّ. يميّز الدقائقَ المُدخلة يدوياً (تقديرٌ لا قياس).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "ISO date" }, "to": { "type": "string", "description": "ISO date" }, "employeeId": { "type": "string", "description": "معرّف الموظف أو اسمه" }, "releaseId": { "type": "string", "description": "معرّف الإصدار أو رقمه" }, "categoryId": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.time.report.team" } }, "/api/v1/tools/pm_update_card": { "post": { "tags": [ "product" ], "operationId": "pm_update_card", "summary": "تعديل بطاقة منتج", "description": "تعديل بطاقة منتج قائمة: العنوان/الوصف/النوع/الأولوية/النظام. الحقول غير المذكورة تبقى كما هي. cardType: bug|feature|improvement|suggestion · priority: low|normal|high|critical.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" }, "title": { "type": "string" }, "description": { "type": "string" }, "cardType": { "type": "string" }, "priority": { "type": "string" }, "system": { "type": "string" } }, "required": [ "cardId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.update" } }, "/api/v1/tools/pm_update_card_status": { "post": { "tags": [ "product" ], "operationId": "pm_update_card_status", "summary": "نقل مرحلة بطاقة", "description": "نقل بطاقة منتج إلى مرحلة جديدة. **يُطلق رسالة التريغر للعملاء الطالبين** إن كان لتلك المرحلة تريغر فعّال. status: new|reviewing|accepted|rejected|in_release|in_progress|testing|done · reason إلزامي عند rejected.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "معرّف البطاقة أو عنوانها" }, "status": { "type": "string" }, "reason": { "type": "string", "description": "سبب الرفض — إلزامي عند rejected" } }, "required": [ "cardId", "status" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.manage" } }, "/api/v1/tools/release_status_summary": { "post": { "tags": [ "product" ], "operationId": "release_status_summary", "summary": "حالة الإصدار", "description": "عدّادات إصدار منتجٍ واحد على أعمدة اللوحة كما يراها المستأجر (أعمدة لوحة المطوّر بأسمائها عنده)، مع فصل «تمّ التطوير» عن «تمّت ورُفعت للإصدار». مرّر نسخة الإصدار أو عنوانه في releaseId.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "releaseId": { "type": "string", "description": "معرّف إصدار المنتج أو نسخته أو عنوانه — إصدارات المنتج لا نشرات النظام" } }, "required": [ "releaseId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "product.cards.view" } }, "/api/v1/tools/apply_labeeb_prompt_simulation": { "post": { "tags": [ "settings" ], "operationId": "apply_labeeb_prompt_simulation", "summary": "اعتماد مسودة المحاكاة", "description": "يعتمد مسودة محاكاة مكتملة برومبتا محفوظا للموظف لبيب عبر مسار الحفظ الرسمي (نسخة احتياطية + سجل نسخ). لا تستعملها إلا بعد أن يرى المستخدم النتيجة ويوافق صراحة.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.manage" } }, "/api/v1/tools/estimate_labeeb_prompt_simulation": { "post": { "tags": [ "settings" ], "operationId": "estimate_labeeb_prompt_simulation", "summary": "تقدير محاكاة البرومبت", "description": "تقدير محاكاة برومبت لبيب قبل بدئها: كم دورا حقيقيا في النطاق (range: today اليوم · yesterday أمس · 7d آخر 7 أيام · 24h · 48h · custom مع fromDate/toDate بساعة الحساب) أو في محادثات بعينها (threadKeys من list_labeeb_prompt_simulation_conversations) سيعاد، كم نداء ذكاء، وكم ستكلف من رصيد الذكاء الاصطناعي للحساب وهل الرصيد يكفي. اقرأ البرومبت الحالي أولا بـ get_ai_agent (sales) واكتب المسودة كاملة في draftPrompt. لا تكلف شيئا.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "draftPrompt": { "type": "string" }, "range": { "type": "string", "enum": [ "today", "yesterday", "7d", "24h", "48h", "custom" ] }, "fromDate": { "type": "string", "description": "YYYY-MM-DD بساعة الحساب — مع custom" }, "toDate": { "type": "string" }, "threadKeys": { "type": "array", "items": { "type": "string" } }, "maxTurns": { "type": "integer", "minimum": 5, "maximum": 60 } }, "required": [ "draftPrompt" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.manage" } }, "/api/v1/tools/get_labeeb_prompt_simulation": { "post": { "tags": [ "settings" ], "operationId": "get_labeeb_prompt_simulation", "summary": "نتيجة محاكاة البرومبت", "description": "نتيجة محاكاة برومبت لبيب: الحالة والتقدم، عدد الردود التي تحسنت أو ساءت أو بقيت، متوسط درجة الرد القديم مقابل الجديد، التكلفة الفعلية، ولكل دور رسالة العميل والرد القديم (before) والرد الجديد (after) ودرجتاهما وسبب المحكم. بلا id تعيد آخر المحاكاات.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "includeItems": { "type": "boolean" }, "take": { "type": "integer" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.manage" } }, "/api/v1/tools/get_labeeb_report": { "post": { "tags": [ "settings" ], "operationId": "get_labeeb_report", "summary": "تقرير لبيب", "description": "تقرير لبيب لفترة (days الافتراضي 1 = اليوم، حتى 31): عدد المحادثات والردود والتحويلات للموظفين والمتابعات والمواعيد، التوزيع اليومي، ما يحتاج انتباهاً، المحادثات المنتظرة، الأسئلة التي لم يعرف جوابها، وزمن الاستجابة. channel اختياري: whatsapp · messenger · website.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 31 }, "channel": { "type": "string", "enum": [ "all", "whatsapp", "messenger", "website" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.usage.view" } }, "/api/v1/tools/get_labeeb_settings": { "post": { "tags": [ "settings" ], "operationId": "get_labeeb_settings", "summary": "إعدادات لبيب", "description": "إعدادات الموظف لبيب كاملة: persona هويته (الاسم والنبرة واللهجة وطول الرد والإفصاح والإيموجي) · selling أسلوب البيع · limits حدود المتابعة · handoff قواعد التحويل للبشر · powers قدراته المفعلة · trial إعدادات التجربة · model نموذج الذكاء المستعمل · branches الفروع · rules قواعد رحلة العميل. بلا section تعيد الأقسام القياسية، والفروع والقواعد تقرأ بقسمها صراحة لأنها قد تكون مئات الصفوف. وترد مع كل حقل قيمه المسموحة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "persona", "selling", "limits", "handoff", "powers", "trial", "model", "branches", "rules" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.usage.view" } }, "/api/v1/tools/get_quality_report": { "post": { "tags": [ "settings" ], "operationId": "get_quality_report", "summary": "تقرير الجودة", "description": "تقرير جودة المحادثات (تدقيق البوت): درجات المحادثات، النتائج، مستوى الإحباط، الأسئلة المكررة، أبطأ استجابة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "maximum": 30 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.usage.view" } }, "/api/v1/tools/get_working_hours": { "post": { "tags": [ "settings" ], "operationId": "get_working_hours", "summary": "ساعات العمل", "description": "ساعات عمل الشركة والمنطقة الزمنية وإعدادات المواعيد — مرجع لأي تحليل عن زمن الاستجابة.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.settings.view" } }, "/api/v1/tools/list_automation_rules": { "post": { "tags": [ "settings" ], "operationId": "list_automation_rules", "summary": "قواعد الأتمتة", "description": "قواعد الأتمتة/التحويل المفعّلة: الاسم والنطاق والحالة والأولوية ومنطق المطابقة — لفهم «لماذا تصرّف النظام هكذا».", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.rules.view" } }, "/api/v1/tools/list_labeeb_prompt_simulation_conversations": { "post": { "tags": [ "settings" ], "operationId": "list_labeeb_prompt_simulation_conversations", "summary": "محادثات لمحاكاة البرومبت", "description": "المحادثات التي رد عليها لبيب في نطاق زمني (range: today · yesterday · 7d · 24h · 48h · custom مع fromDate/toDate) مع اسم العميل إن عُرف وعدد الأدوار وآخر رسالة — لتختار منها محادثة أو أكثر تمررها في threadKeys لمحاكاة البرومبت عليها بعينها. query للبحث بالاسم أو الرقم.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "today", "yesterday", "7d", "24h", "48h", "custom" ] }, "fromDate": { "type": "string", "description": "YYYY-MM-DD بساعة الحساب — مع custom" }, "toDate": { "type": "string" }, "query": { "type": "string" }, "take": { "type": "integer" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.manage" } }, "/api/v1/tools/list_report_subscriptions": { "post": { "tags": [ "settings" ], "operationId": "list_report_subscriptions", "summary": "اشتراكات التقارير", "description": "اشتراكات التقرير الأسبوعي: من يستلم أي نطاق وهل اشتراكه مفعّل.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "reports.weekly.subscribe" } }, "/api/v1/tools/list_weekly_reports": { "post": { "tags": [ "settings" ], "operationId": "list_weekly_reports", "summary": "التقارير الأسبوعية", "description": "التقارير الأسبوعية المولَّدة: النطاق والأسبوع ومتى قُرئت.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "description": "personal|department|company" }, "limit": { "type": "integer", "maximum": 20 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "reports.weekly.read.own" } }, "/api/v1/tools/simulate_labeeb_prompt": { "post": { "tags": [ "settings" ], "operationId": "simulate_labeeb_prompt", "summary": "بدء محاكاة البرومبت", "description": "يبدأ محاكاة حقيقية لمسودة برومبت لبيب: يعيد توليد رد لبيب على محادثات العملاء الحقيقية في النطاق (range اليوم/أمس/7d/24h/48h/custom) أو في محادثات بعينها (threadKeys) بالمسودة عبر نفس مسار الإنتاج، ويقارن كل رد جديد بالرد الذي وصل العميل فعلا بمحكم أعمى. **تكلف من رصيد الذكاء الاصطناعي للحساب** — قدرها أولا بـ estimate_labeeb_prompt_simulation وأخبر المستخدم بالتكلفة قبل البدء. لا تحفظ المسودة ولا ترسل شيئا للعملاء. تعمل في الخلفية دقائق؛ اقرأ النتيجة بـ get_labeeb_prompt_simulation.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "draftPrompt": { "type": "string" }, "range": { "type": "string", "enum": [ "today", "yesterday", "7d", "24h", "48h", "custom" ] }, "fromDate": { "type": "string", "description": "YYYY-MM-DD بساعة الحساب — مع custom" }, "toDate": { "type": "string" }, "threadKeys": { "type": "array", "items": { "type": "string" } }, "maxTurns": { "type": "integer", "minimum": 5, "maximum": 60 } }, "required": [ "draftPrompt" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.manage" } }, "/api/v1/tools/update_labeeb_settings": { "post": { "tags": [ "settings" ], "operationId": "update_labeeb_settings", "summary": "تعديل إعدادات لبيب", "description": "تعديل إعدادات لبيب: مرر section وvalues بالحقول المراد تغييرها فقط — وما لا ترسله لا يمس. persona: displayName tone dialect replyLength disclosure emojiLevel. selling: priceTiming questionDensity. limits: fuMaxPerLead fuQuietStartHour fuQuietEndHour fuRespectOptOut fuSkipWhenAssigned. handoff: يلزمه situation ثم isEnabled assignConversation assigneeUserIds assigneeUserIdsPostSale sendReassurance reassuranceText cooldownMinutes dailyCap slaMinutes slaEscalateToUserIds. powers: يلزمه toolKey وisEnabled. trial: replyTriggerEnabled replyTriggerMsgCount successStage successAssign successAssigneeIds. model: modelKey من الكتالوج. branches: بلا id ينشئ فرعا ومعه id يعدله، وحقوله name city phone address workingHours mapsUrl isActive sortOrder notes، والحذف بتمرير id مع delete صواب. rules: بلا id ينشئ قاعدة وتولد بوضع مراقبة ما لم تمرر mode بقيمة active، وحقولها name outcome targetStage fromStage detectDescription examplePhrases counterExamplePhrases priority isActive stopFollowUps sendFarewell successAssign successAssigneeIds، والحذف بتمرير id مع delete صواب. اقرأ الإعدادات أولا لترى القيم المسموحة.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "persona", "selling", "limits", "handoff", "powers", "trial", "model", "branches", "rules" ] }, "values": { "type": "object" } }, "required": [ "section", "values" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tenant.ai.manage" } }, "/api/v1/tools/create_monthly_goal": { "post": { "tags": [ "strategy" ], "operationId": "create_monthly_goal", "summary": "إنشاء هدف شهري", "description": "إنشاء هدف شهري مرتبط بهدف سنوي (استخدم list_annual_goals للحصول على annualObjectiveId).", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "annualObjectiveId": { "type": "string", "description": "معرّف الهدف السنوي أو عنوانه" }, "year": { "type": "integer" }, "month": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "kpiName": { "type": "string" }, "kpiTarget": { "type": "number" }, "kpiUnit": { "type": "string" } }, "required": [ "annualObjectiveId", "year", "month", "title" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.monthly.manage" } }, "/api/v1/tools/create_project": { "post": { "tags": [ "strategy" ], "operationId": "create_project", "summary": "إنشاء مشروع", "description": "إنشاء مشروع جديد، مع ربط اختياري بأهداف سنوية/شهرية.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string", "description": "low|medium|high" }, "dueDate": { "type": "string" }, "objectiveIds": { "type": "array", "items": { "type": "string" } }, "goalIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.projects.manage" } }, "/api/v1/tools/delete_monthly_goal": { "post": { "tags": [ "strategy" ], "operationId": "delete_monthly_goal", "summary": "حذف هدف شهري", "description": "حذف هدف شهري.", "x-write": true, "x-operation": "delete", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "goalId": { "type": "string", "description": "معرّف الهدف الشهري أو عنوانه" } }, "required": [ "goalId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.monthly.manage" } }, "/api/v1/tools/delete_project": { "post": { "tags": [ "strategy" ], "operationId": "delete_project", "summary": "حذف مشروع", "description": "حذف مشروع.", "x-write": true, "x-operation": "delete", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "معرّف المشروع أو عنوانه" } }, "required": [ "projectId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.projects.manage" } }, "/api/v1/tools/list_annual_goals": { "post": { "tags": [ "strategy" ], "operationId": "list_annual_goals", "summary": "قراءة الأهداف السنوية", "description": "الأهداف السنوية (الاستراتيجية) مع حالتها وتقدمها.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.objectives.view" } }, "/api/v1/tools/list_goal_comments": { "post": { "tags": [ "strategy" ], "operationId": "list_goal_comments", "summary": "تعليقات الأهداف", "description": "تعليقات الأهداف (سنوية/شهرية) — للاطلاع على نقاش الفريق حول هدف.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityId": { "type": "string", "description": "معرّف الهدف" }, "limit": { "type": "integer", "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.comments.manage" } }, "/api/v1/tools/list_monthly_goals": { "post": { "tags": [ "strategy" ], "operationId": "list_monthly_goals", "summary": "قراءة الأهداف الشهرية", "description": "الأهداف الشهرية (التشغيلية) لشهر محدد مع KPI والتقدم. الافتراضي الشهر الحالي.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.monthly.view" } }, "/api/v1/tools/list_projects": { "post": { "tags": [ "strategy" ], "operationId": "list_projects", "summary": "قراءة المشاريع", "description": "المشاريع مع الحالة والتقدم والصحة وعدد المهام.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "planning|active|on_hold|done|cancelled (اختياري)" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.projects.view" } }, "/api/v1/tools/list_strategic_pillars": { "post": { "tags": [ "strategy" ], "operationId": "list_strategic_pillars", "summary": "الركائز الاستراتيجية", "description": "الركائز الاستراتيجية للشركة — الإطار الذي تُنسب إليه الأهداف والمخاطر.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.pillars.view" } }, "/api/v1/tools/list_strategic_risks": { "post": { "tags": [ "strategy" ], "operationId": "list_strategic_risks", "summary": "المخاطر الاستراتيجية", "description": "سجلّ المخاطر الاستراتيجية مرتّباً بدرجة الخطورة: الاحتمال والأثر والحالة وخطة التخفيف.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "limit": { "type": "integer", "maximum": 60 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.risks.view" } }, "/api/v1/tools/update_monthly_goal": { "post": { "tags": [ "strategy" ], "operationId": "update_monthly_goal", "summary": "تعديل هدف شهري", "description": "تعديل هدف شهري (عنوان/وصف/حالة/KPI). الحقول غير المذكورة تبقى كما هي.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "goalId": { "type": "string", "description": "معرّف الهدف الشهري أو عنوانه" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "description": "new|in_progress|done|cancelled" }, "kpiTarget": { "type": "number" }, "kpiCurrent": { "type": "number" } }, "required": [ "goalId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.monthly.manage" } }, "/api/v1/tools/update_project": { "post": { "tags": [ "strategy" ], "operationId": "update_project", "summary": "تعديل مشروع", "description": "تعديل مشروع (عنوان/وصف/حالة/أولوية/استحقاق). الحقول غير المذكورة تبقى.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "معرّف المشروع أو عنوانه" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "description": "planning|active|on_hold|done|cancelled" }, "priority": { "type": "string" }, "dueDate": { "type": "string" } }, "required": [ "projectId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "strategy.projects.manage" } }, "/api/v1/tools/create_task": { "post": { "tags": [ "tasks" ], "operationId": "create_task", "summary": "إنشاء مهمة", "description": "إنشاء مهمة جديدة. استخدم list_users للحصول على assignedToUserId عند الإسناد.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "assignedToUserId": { "type": "string" }, "priority": { "type": "string", "description": "low|normal|high|urgent" }, "dueDate": { "type": "string", "description": "ISO date" }, "projectId": { "type": "string" }, "monthlyGoalId": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tasks.task.create" } }, "/api/v1/tools/delete_task": { "post": { "tags": [ "tasks" ], "operationId": "delete_task", "summary": "حذف مهمة", "description": "حذف مهمة (حذف ناعم).", "x-write": true, "x-operation": "delete", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "معرّف المهمة أو عنوانها" } }, "required": [ "taskId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tasks.task.delete.all" } }, "/api/v1/tools/get_performance_metrics": { "post": { "tags": [ "tasks" ], "operationId": "get_performance_metrics", "summary": "مؤشرات الأداء", "description": "مؤشرات أداء الفريق لشهر: المهام المُسندة والمنجزة في وقتها والمتأخرة والمرفوضة ومتوسط زمن الإنجاز، باسم كل موظف.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tasks.task.read.all" } }, "/api/v1/tools/list_task_dependencies": { "post": { "tags": [ "tasks" ], "operationId": "list_task_dependencies", "summary": "اعتماديات المهام", "description": "روابط اعتماد المهام (من يحجب من) — لكشف سلاسل التعطيل.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "معرّف المهمة أو عنوانها" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tasks.task.read.own" } }, "/api/v1/tools/list_tasks": { "post": { "tags": [ "tasks" ], "operationId": "list_tasks", "summary": "قراءة المهام", "description": "قائمة المهام مع فلاتر اختيارية. إن لم تملك صلاحية قراءة الكل تُعاد مهامك فقط.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "open|in_progress|submitted|approved|rejected|cancelled|draft" }, "onlyMine": { "type": "boolean" }, "projectId": { "type": "string" }, "monthlyGoalId": { "type": "string" }, "limit": { "type": "integer", "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tasks.task.read.own" } }, "/api/v1/tools/set_task_status": { "post": { "tags": [ "tasks" ], "operationId": "set_task_status", "summary": "تغيير حالة مهمة", "description": "نقل مهمة إلى حالة: open | in_progress | submitted | approved | rejected | cancelled.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "معرّف المهمة أو عنوانها" }, "status": { "type": "string" } }, "required": [ "taskId", "status" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tasks.task.update.own" } }, "/api/v1/tools/update_task": { "post": { "tags": [ "tasks" ], "operationId": "update_task", "summary": "تعديل مهمة", "description": "تعديل مهمة قائمة (العنوان/الوصف/الأولوية/الاستحقاق/الإسناد/الروابط).", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "معرّف المهمة أو عنوانها" }, "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string" }, "dueDate": { "type": "string" }, "assignedToUserId": { "type": "string" }, "projectId": { "type": "string" }, "monthlyGoalId": { "type": "string" } }, "required": [ "taskId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "tasks.task.update.own" } }, "/api/v1/tools/cancel_appointment": { "post": { "tags": [ "whatsapp" ], "operationId": "cancel_appointment", "summary": "إلغاء موعد", "description": "إلغاء موعد مع إشعار العميل بالإلغاء. خذ appointmentId من list_appointments، وreason اختياري.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "appointmentId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "appointmentId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "appointments.manage" } }, "/api/v1/tools/create_appointment": { "post": { "tags": [ "whatsapp" ], "operationId": "create_appointment", "summary": "حجز موعد", "description": "حجز موعد يدوي لعميل برقمه في وقت محدد بتوقيت الشركة (scheduledAt بصيغة 2026-09-21T15:30). يتحقق من التعارض ويربطه ببطاقة العميل إن وجدت. لا يرسل رسالة للعميل.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "customerName": { "type": "string" }, "scheduledAt": { "type": "string" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "assignedToUserId": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "phone", "scheduledAt" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "appointments.manage" } }, "/api/v1/tools/create_whatsapp_template": { "post": { "tags": [ "whatsapp" ], "operationId": "create_whatsapp_template", "summary": "إنشاء قالب واتساب", "description": "إنشاء قالب واتساب رسمي وإرساله لمراجعة ميتا. name بحروف إنجليزية صغيرة وشرطات سفلية، body نص القالب والمتغيرات بصيغة {{1}} {{2}} مع مثال لكل متغير في examples، category واحدة من UTILITY (خدمي) أو MARKETING (تسويقي) أو AUTHENTICATION (رمز تحقق)، language مثل ar أو en، footer اختياري، buttons اختيارية: QUICK_REPLY حتى 10، URL حتى 2 مع url، PHONE_NUMBER واحد مع phoneNumber. instanceId مطلوب فقط إن كان في الحساب أكثر من قناة رسمية. القالب لا يرسل قبل اعتماده — تابع حالته بـ get_whatsapp_template_status.", "x-write": true, "x-operation": "create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "body": { "type": "string" }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "language": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "QUICK_REPLY", "URL", "PHONE_NUMBER" ] }, "text": { "type": "string" }, "url": { "type": "string" }, "phoneNumber": { "type": "string" } }, "required": [ "type", "text" ] } }, "instanceId": { "type": "string" } }, "required": [ "name", "body", "category" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.instance.manage" } }, "/api/v1/tools/delete_whatsapp_template": { "post": { "tags": [ "whatsapp" ], "operationId": "delete_whatsapp_template", "summary": "حذف قالب واتساب", "description": "حذف قالب واتساب رسمي من ميتا ومن القائمة — لا رجعة فيه، ولا يمكن إعادة استعمال اسمه فوراً عند ميتا. مرر templateId (المعرّف أو الاسم). القالب الذي تديره خدمة رمز التحقق لا يحذف من هنا.", "x-write": true, "x-operation": "delete", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string", "description": "معرّف القالب أو اسمه" } }, "required": [ "templateId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.instance.manage" } }, "/api/v1/tools/get_appointment_settings": { "post": { "tags": [ "whatsapp" ], "operationId": "get_appointment_settings", "summary": "إعدادات المواعيد", "description": "إعدادات وكيل المواعيد: التفعيل، المدة، القوالب، كلمات الكشف.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "appointments.manage" } }, "/api/v1/tools/get_conversation_summaries": { "post": { "tags": [ "whatsapp" ], "operationId": "get_conversation_summaries", "summary": "ملخصات المحادثات", "description": "الملخصات المحفوظة لمحادثات العملاء (ذاكرة المحادثات الطويلة).", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "limit": { "type": "integer", "maximum": 20 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.read.all" } }, "/api/v1/tools/get_whatsapp_conversation": { "post": { "tags": [ "whatsapp" ], "operationId": "get_whatsapp_conversation", "summary": "قراءة محادثة", "description": "رسائل محادثة واتساب لرقم محدد أو لمجموعة (الأحدث أولاً) — للتحليل العميق للمحادثة: الاتجاه والنص والوقت. للمجموعة مرّر معرّفها الكامل (…@g.us من list_whatsapp_groups) في phone، فتعيد لكلّ رسالة من أرسلها: لَبيب أو موظّف أو رقم المشارك.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "رقم العميل، أو معرّف مجموعة كامل بلاحقة @g.us" }, "isGroup": { "type": "boolean", "description": "اختياري: الوجهة مجموعة. يُستنتج من لاحقة @g.us" }, "limit": { "type": "integer", "maximum": 60 } }, "required": [ "phone" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.read.all" } }, "/api/v1/tools/get_whatsapp_routing": { "post": { "tags": [ "whatsapp" ], "operationId": "get_whatsapp_routing", "summary": "توجيه الواتساب", "description": "إعداد توجيه محادثات الواتساب لكل رقم: ذكاء أم موظف واحد أم تناوب.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.routing.manage" } }, "/api/v1/tools/get_whatsapp_send_window": { "post": { "tags": [ "whatsapp" ], "operationId": "get_whatsapp_send_window", "summary": "نافذة الإرسال", "description": "هل نافذة 24 ساعة مفتوحة لهذا الرقم على القناة الرسمية. اسأل قبل إرسال ملف أو نص حر: خارج النافذة لا تقبل ميتا إلا قالبا معتمدا. القنوات غير الرسمية لا تخضع لهذا الحد.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" } }, "required": [ "phone" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.send" } }, "/api/v1/tools/get_whatsapp_template_status": { "post": { "tags": [ "whatsapp" ], "operationId": "get_whatsapp_template_status", "summary": "حالة قالب واتساب", "description": "حالة قالب واتساب الآن: يسحب الحالة من ميتا أولاً ثم يعيد status (approved معتمد، pending قيد المراجعة، rejected مرفوض، paused موقوف) مع معناها وسبب الرفض إن وجد والنص وعدد المتغيرات. مرر templateId (المعرّف أو الاسم)، وrefresh=false للقراءة المخزنة بلا سحب.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string", "description": "معرّف القالب أو اسمه" }, "refresh": { "type": "boolean" } }, "required": [ "templateId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.instance.manage" } }, "/api/v1/tools/list_appointments": { "post": { "tags": [ "whatsapp" ], "operationId": "list_appointments", "summary": "قائمة المواعيد", "description": "المواعيد ضمن فترة (الافتراضي القادمة 14 يوماً) مع الحالة والعميل.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "daysAhead": { "type": "integer", "maximum": 90 }, "status": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "appointments.read" } }, "/api/v1/tools/list_whatsapp_conversations": { "post": { "tags": [ "whatsapp" ], "operationId": "list_whatsapp_conversations", "summary": "قراءة المحادثات", "description": "محادثات واتساب الخاصة مع فلاتر: نافذة زمنية بتوقيت الحساب (period أو fromDate/toDate)، ومرحلة العميل (stage)، والقناة باسمها أو رقمها (channel)، وunanswered للمحادثات التي آخر رسالة فيها من العميل ولم يُردّ عليها. لكل محادثة: الرقم والاسم والمرحلة والقناة وعدد الرسائل في النافذة وآخر رسالة ومن أرسلها وهل تنتظر ردّاً، مع العدد الكلي المطابق. نقطة البداية لتحليل المحادثات.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "description": "today|yesterday|last24h|last7d|last30d|all — الافتراضي last30d" }, "fromDate": { "type": "string", "description": "YYYY-MM-DD بتوقيت الحساب" }, "toDate": { "type": "string", "description": "YYYY-MM-DD شاملاً" }, "stage": { "type": "string", "description": "interested|engaged|trial|won|lost" }, "channel": { "type": "string", "description": "اسم القناة أو رقمها" }, "unanswered": { "type": "boolean", "description": "فقط المحادثات التي تنتظر ردّنا" }, "limit": { "type": "integer", "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.read.all" } }, "/api/v1/tools/list_whatsapp_groups": { "post": { "tags": [ "whatsapp" ], "operationId": "list_whatsapp_groups", "summary": "قراءة المجموعات", "description": "مجموعات واتساب التي يشارك بها حسابك: المعرف الكامل بصيغة أرقام تليها @g.us والاسم وعدد الرسائل وآخر نشاط، مرتبة بالأحدث نشاطاً. هذا المعرف هو ما يوضع في حقل phone عند send_whatsapp_message أو send_whatsapp_media للإرسال إلى مجموعة. الحساب قد يكون في مئات المجموعات، فمرر query بجزء من اسم المجموعة للبحث عنها بالاسم بدل تصفح الأحدث. ومع period أو fromDate/toDate تعيد فقط المجموعات التي تحرّكت في تلك الفترة مع عدد رسائلها فيها وآخر رسالة ومن أرسلها (لَبيب · موظّف · رقم المشارك) — لسؤال «أيّ مجموعات تحرّكت اليوم». ولقراءة رسائل مجموعة مرّر معرّفها إلى get_whatsapp_conversation. limit الافتراضي 20 وأقصاه 50.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "اختياري: جزء من اسم المجموعة للبحث — بلا حساسية لحالة الأحرف" }, "period": { "type": "string", "description": "اختياري: today|yesterday|last24h|last7d|last30d" }, "fromDate": { "type": "string", "description": "YYYY-MM-DD بتوقيت الحساب" }, "toDate": { "type": "string", "description": "YYYY-MM-DD شاملاً" }, "limit": { "type": "integer", "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.read.all" } }, "/api/v1/tools/list_whatsapp_official_templates": { "post": { "tags": [ "whatsapp" ], "operationId": "list_whatsapp_official_templates", "summary": "قوالب واتساب الرسمية", "description": "قوالب واتساب الرسمية المعتمدة: الاسم واللغة والحالة وعدد المتغيّرات ونصّها.", "x-write": false, "x-operation": "read", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.instance.manage" } }, "/api/v1/tools/reschedule_appointment": { "post": { "tags": [ "whatsapp" ], "operationId": "reschedule_appointment", "summary": "إعادة جدولة موعد", "description": "تغيير وقت موعد قائم (scheduledAt بتوقيت الشركة) مع إشعار العميل بالوقت الجديد. خذ appointmentId من list_appointments.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "appointmentId": { "type": "string" }, "scheduledAt": { "type": "string" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "assignedToUserId": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "appointmentId", "scheduledAt" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "appointments.manage" } }, "/api/v1/tools/send_whatsapp_media": { "post": { "tags": [ "whatsapp" ], "operationId": "send_whatsapp_media", "summary": "إرسال مرفق واتساب", "description": "إرسال ملف أو صورة أو مستند عبر واتساب إلى رقم أو إلى مجموعة — وللمجموعة مرر معرفها الكامل بصيغة @g.us في حقل phone، وتُقرأ المعرفات بـ list_whatsapp_groups. مرر fileId لملف رفعته سابقا بـ upload_file وهو الأفضل عند الإرسال لأكثر من رقم لأنه لا يعيد الحمولة، أو url للملف، أو base64 لمحتواه — مصدر واحد فقط لا أكثر. مع fileName وcaption اختياريا. تصل للعميل فعلا. السقف 16 ميغابايت، والصور والفيديو سقفها 16 من واتساب نفسه. الصوت غير مدعوم بعد. يخضع لحدود الإرسال: فاصل زمني بين رسالتين لنفس الرقم، وسقف ساعي للحساب، وسقف لعدد الأرقام المختلفة في الساعة.", "x-write": true, "x-operation": "send", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "رقم بصيغة دولية بأرقام فقط بلا + ولا مسافات، أو معرف مجموعة كامل بلاحقة @g.us" }, "fileId": { "type": "string", "description": "معرف ملف مرفوع مسبقا بـ upload_file — الأفضل للإرسال المتكرر" }, "url": { "type": "string" }, "base64": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "caption": { "type": "string" }, "isGroup": { "type": "boolean", "description": "اختياري: الوجهة مجموعة. يُستنتج تلقائياً من لاحقة @g.us" }, "channel": { "type": "string", "description": "اختياري: اسم القناة أو رقمها التي تخرج منها الرسالة — لازم إذا عند الحساب أكثر من قناة والرقم ما تواصل قبل" } }, "required": [ "phone" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.send" } }, "/api/v1/tools/send_whatsapp_message": { "post": { "tags": [ "whatsapp" ], "operationId": "send_whatsapp_message", "summary": "إرسال رسالة واتساب", "description": "إرسال رسالة واتساب نصية إلى رقم أو إلى مجموعة. للرقم: أرقام فقط مع رمز الدولة بلا + ولا مسافات. وللمجموعة: مرر معرفها الكامل في نفس حقل phone بصيغة أرقام تليها @g.us — والمعرفات تُقرأ بـ list_whatsapp_groups. ويمكن تمرير isGroup صريحاً ومعه يُقبل المعرف كما هو. تصل فعلياً — استخدمها بحذر وبنص نهائي جاهز. وإذا عند الحساب أكثر من قناة مرّر channel باسم القناة، وإلا ترجع لك الأداة أسماء القنوات لتسأل المستخدم.", "x-write": true, "x-operation": "send", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "رقم بصيغة دولية بأرقام فقط بلا + ولا مسافات، أو معرف مجموعة كامل بلاحقة @g.us" }, "text": { "type": "string" }, "isGroup": { "type": "boolean", "description": "اختياري: الوجهة مجموعة. يُستنتج تلقائياً من لاحقة @g.us، ويُصرَّح به عند الحاجة" }, "channel": { "type": "string", "description": "اختياري: اسم القناة أو رقمها التي تخرج منها الرسالة — لازم إذا عند الحساب أكثر من قناة والرقم ما تواصل قبل" } }, "required": [ "phone", "text" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.send" } }, "/api/v1/tools/send_whatsapp_template": { "post": { "tags": [ "whatsapp" ], "operationId": "send_whatsapp_template", "summary": "إرسال قالب واتساب", "description": "إرسال قالب واتساب معتمد إلى رقم — وهو الطريق الوحيد لفتح محادثة بعد انتهاء نافذة 24 ساعة على القناة الرسمية، لأن الوسائط والنص الحر لا يقبلان خارجها. اقرأ القوالب أولا بـ list_whatsapp_official_templates وخذ منها المعرف وعدد المتغيرات. يخضع لنفس حدود الإرسال.", "x-write": true, "x-operation": "send", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "templateId": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "channel": { "type": "string", "description": "اختياري: اسم القناة أو رقمها الرسمية التي يخرج منها القالب — لازم إذا عند الحساب أكثر من قناة والرقم ما تواصل قبل" } }, "required": [ "phone", "templateId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.send" } }, "/api/v1/tools/send_whatsapp_template_bulk": { "post": { "tags": [ "whatsapp" ], "operationId": "send_whatsapp_template_bulk", "summary": "إرسال قالب لمجموعة", "description": "إرسال قالب واتساب معتمد لمجموعة عملاء دفعة واحدة (حتى 25 رقماً): مرر phones قائمة أرقام، أو stage مرحلة البطاقات (interested · trial · engaged · won) فيؤخذ أحدث 25 بلا الخاسرين والمؤجّلين. params قيم المتغيرات، وfirstParamIsCustomerName=true يضع الاسم الأول لكل عميل في المتغير الأول. كل رقم يمر بسياسة ميتا (لا قالب خلال 24 ساعة من سابقه ولا بعد رفض حديث) فيتخطى المحمي ويذكر السبب.", "x-write": true, "x-operation": "send", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string" }, "phones": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "stage": { "type": "string", "enum": [ "interested", "trial", "engaged", "won" ] }, "params": { "type": "array", "items": { "type": "string" } }, "firstParamIsCustomerName": { "type": "boolean" } }, "required": [ "templateId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.send" } }, "/api/v1/tools/update_appointment_settings": { "post": { "tags": [ "whatsapp" ], "operationId": "update_appointment_settings", "summary": "تعديل إعدادات المواعيد", "description": "تعديل إعدادات المواعيد: تفعيل/مدة/أقصى أيام/قوالب الرسائل.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "isEnabled": { "type": "boolean" }, "durationMinutes": { "type": "integer" }, "maxDaysAhead": { "type": "integer" }, "askTimeMessage": { "type": "string" }, "confirmationTemplate": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "appointments.manage" } }, "/api/v1/tools/upload_file": { "post": { "tags": [ "whatsapp" ], "operationId": "upload_file", "summary": "رفع ملف", "description": "رفع ملف مرة واحدة إلى النظام وأخذ معرف قصير له، ثم إرساله لأي عدد من الأرقام بـ send_whatsapp_media ومعه fileId — بلا إعادة الحمولة في كل مرة وبلا خطر حرف فاسد يفسد الملف. مرر base64 لمحتوى الملف أو url لجلبه، مع fileName وmimeType. المعرف صالح سبعة أيام ولا يصلح إلا داخل حسابك.", "x-write": true, "x-operation": "update", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "base64": { "type": "string" }, "url": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResult" }, "400": { "$ref": "#/components/responses/ToolError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-permission": "whatsapp.message.send" } } }, "x-webhooks": { "signatureHeader": "X-Labeb-Signature", "eventHeader": "X-Labeb-Event", "deliveryHeader": "X-Labeb-Delivery", "signature": "t=,v1=hex(HMAC-SHA256(secret, \".\")) — ارفض ما مضى عليه أكثر من 300 ثانية", "retrySchedule": [ 1, 5, 30, 120, 480 ], "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "format": "uuid" }, "data": { "type": "object" } } }, "events": [ { "key": "lead.created", "title": "عميلٌ محتمل جديد", "description": "بطاقةُ عميلٍ أُنشئت (من واتساب أو يدويّاً أو عبر API).", "sample": { "leadId": "…", "phone": "9665…", "fullName": "…", "stage": "interested", "source": "whatsapp", "assignedTo": null } }, { "key": "lead.stage_changed", "title": "تغيّرت مرحلةُ عميل", "description": "انتقلت بطاقةٌ من مرحلةٍ إلى أخرى (interested → engaged → won/lost…).", "sample": { "leadId": "…", "phone": "9665…", "fromStage": "interested", "toStage": "engaged" } }, { "key": "lead.assigned", "title": "أُسند عميلٌ لموظّف", "description": "تغيّر المسؤولُ عن بطاقة عميل.", "sample": { "leadId": "…", "phone": "9665…", "fromAssignedTo": null, "toAssignedTo": "…" } }, { "key": "ticket.created", "title": "تذكرةٌ جديدة", "description": "فُتحت تذكرةُ دعمٍ (من الموظّف أو من لَبيب أو عبر API).", "sample": { "ticketId": "…", "ticketNumber": 2031, "title": "…", "status": "new", "priority": "high", "customerId": "…", "sourcePhone": "9665…" } }, { "key": "ticket.status_changed", "title": "تغيّرت حالةُ تذكرة", "description": "new → in_progress → resolved / cancelled / converted.", "sample": { "ticketId": "…", "ticketNumber": 2031, "fromStatus": "new", "toStatus": "resolved", "resolvedAt": "2026-09-11T08:00:00Z" } }, { "key": "ticket.assigned", "title": "أُسندت تذكرة", "description": "تغيّر المسؤولُ عن تذكرة.", "sample": { "ticketId": "…", "ticketNumber": 2031, "fromAssignedTo": null, "toAssignedTo": "…" } }, { "key": "appointment.created", "title": "موعدٌ جديد", "description": "أُنشئ موعدٌ (بانتظار وقتٍ أو مجدولٌ).", "sample": { "appointmentId": "…", "customerPhone": "9665…", "customerName": "…", "status": "scheduled", "scheduledAt": "2026-09-12T10:00:00Z", "assignedTo": "…", "leadId": "…" } }, { "key": "appointment.status_changed", "title": "تغيّر موعد", "description": "تغيّرت حالةُ موعدٍ أو وقتُه (scheduled / completed / cancelled / no_show…).", "sample": { "appointmentId": "…", "customerPhone": "9665…", "fromStatus": "scheduled", "toStatus": "completed", "scheduledAt": "2026-09-12T10:00:00Z" } }, { "key": "message.received", "title": "رسالةُ واتساب واردة", "description": "وصلت رسالةٌ من عميلٍ على أحد أرقامك (نصٌّ أو وسائط).", "sample": { "threadKey": "9665…@s.whatsapp.net", "fromPhone": "9665…", "instanceId": "…", "messageId": "…", "text": "…", "hasMedia": false, "isGroup": false } }, { "key": "conversation.assigned", "title": "أُسندت محادثة", "description": "تحوّلت محادثةٌ إلى موظّفٍ أو إلى لَبيب.", "sample": { "threadKey": "…", "assignedType": "human", "assignedUserId": "…", "reason": "…" } }, { "key": "conversation.resolved", "title": "أُغلقت محادثة", "description": "أُقفلت محادثةٌ مُسندة.", "sample": { "threadKey": "…", "resolvedBy": "…" } }, { "key": "conversation.handoff", "title": "طلبُ تدخّلٍ بشريّ", "description": "لَبيب طلب تدخّل إنسان في محادثة.", "sample": { "threadKey": "…", "reason": "…" } } ] }, "components": { "securitySchemes": { "bearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "wkm_… (رمزُ ربطٍ خارجيّ)" } }, "schemas": { "Me": { "type": "object", "properties": { "tenantId": { "type": "string", "format": "uuid" }, "tokenId": { "type": "string", "format": "uuid" }, "tokenName": { "type": "string" }, "actorUserId": { "type": "string", "format": "uuid" }, "writeAllowed": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "Tool": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "module": { "type": "string" }, "write": { "type": "boolean" }, "path": { "type": "string" }, "inputSchema": { "type": "object" } } }, "ToolList": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } }, "ToolResult": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "description": "ناتجُ الأداة كما تعيده (JSON)" } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "out_of_scope", "unknown_tool", "write_not_allowed", "tool_failed", "bad_request" ] } } } }, "responses": { "ToolResult": { "description": "نجاح", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResult" } } } }, "ToolError": { "description": "الأداةُ رفضت الوسائط أو أخفقت", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "رمزٌ غائب أو منتهٍ أو ملغى", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "خارج نطاق الرمز، أو لا صلاحيّة لموظّف الربط، أو كتابةٌ والوصولُ قراءةٌ فقط", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }