وثائق المطورين
واجهة برمجة منصة الوكلاء
امنح وكيل ذكاء اصطناعي وصولاً محدود الصلاحيات عبر مفتاح Bearer إلى خدمات المنشأة، وأوقاتها المتاحة، وحجوزاتها، وعملائها، وإدارة علاقات العملاء — عبر REST أو MCP.
ما هي هذه المنصة
تتيح منصة الوكلاء في موعدي لوكيل ذكاء اصطناعي خارجي — مساعد صوتي، أو مساعد محادثة، أو وكيل برمجي للتنسيق، أو أي جهة أخرى قادرة على إرسال طلبات HTTPS — قراءة وإدارة بيانات منشأة واحدة نيابة عنها. كل طلب يُصادَق عليه بمفتاح Bearer يُصدر من لوحة تحكم المنشأة. لا توجد صلاحية جلسة أو ملفات تعريف ارتباط على هذه الواجهة، ولا تُصدَر أي ترويسات CORS على الإطلاق — فالمفتاح ترويسة لا يرسلها المتصفح من تلقاء نفسه.
المصادقة
كل طلب عبر REST أو MCP يحمل مفتاح Bearer نفسه. المفتاح المفقود أو غير الصحيح أو غير المعروف أو الملغى أو المنتهي يحصل جميعها على استجابة 401 واحدة متطابقة، بحيث لا تكشف الاستجابة وحدها للمتصل أياً من هذه الحالات وقعت.
- الترويسة
Authorization: Bearer mwd_live_<key>- الرابط الأساسي
https://mawidi.com/api/agent/v1- التطوير المحلي
http://localhost:9000/api/agent/v1
الحصول على مفتاح
تُصدر المفاتيح من لوحة التحكم، وليس من هذه الواجهة. سجّل الدخول بصفتك مالك المنشأة أو مسؤولاً فيها، وأنشئ عميل وكيل مسمّى، واختر صلاحياته، وأصدر مفتاحاً له. يُعرض المفتاح كاملاً مرة واحدة فقط عند إنشائه — وبعدها لا يُعرض إلا جزء منه.
افتح إعدادات وصول الوكلاء ←الصلاحيات
تُحدَّد صلاحيات المفتاح عند إصداره، ولا يمكن بعد ذلك إلا تضييقها أو إلغاؤها، لا توسيعها. اختر أضيق مجموعة صلاحيات يحتاجها العميل فعلاً؛ فالمفتاح الذي تنقصه صلاحية مطلوبة يحصل على 403 insufficient_scope.
| الصلاحية | تُستخدم في |
|---|---|
| audit.read | GET /audit/receipts |
| availability.read | GET /availability |
| bookings.read | GET /bookings, GET /bookings/{id}, GET /bookings/changes |
| bookings.read.org | GET /bookings, GET /bookings/{id}, GET /bookings/changes |
| bookings.write | POST /bookings, PATCH /bookings/{id} |
| business_hours.read | GET /config/business-hours |
| business_hours.write | POST /config/business-hours |
| conversations.read | GET /conversations |
| customers.read | GET /customers/list |
| customers.write | POST /customers |
| knowledge.read | GET /config/knowledge |
| knowledge.write | POST /config/knowledge |
| leads.delete | DELETE /leads/{id} |
| leads.read | GET /leads, GET /leads/{id}, GET /leads/{id}/activities |
| leads.write | POST /leads, POST /leads/{id}/notes, POST /leads/{id}/stage, POST /leads/{id}/status |
| messages.send | POST /conversations/{id}/replies |
| orders.read | GET /orders |
| org_settings.read | GET /config/settings |
| org_settings.write | POST /config/settings |
| payments.link | POST /payments/links |
| payments.refund | POST /payments/refunds |
| pipeline.read | GET /pipeline/stages |
| real_estate.read | GET /properties |
| service_jobs.read | GET /service-jobs |
| services.read | GET /config/services, GET /services |
| services.write | POST /config/services |
| voice_agent.read | GET /config/voice-agent |
العمليات
جميع عمليات REST، مجمّعة حسب المورد. العقد الكامل القابل للقراءة الآلية، بما في ذلك مخططات الطلب والاستجابة، هو ملف OpenAPI المرتبط أدناه.
+ = تتطلب جميع, / = تتطلب أي واحدة من
الخدمات
كتالوج الخدمات القابلة للحجز الخاص بالمنشأة.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /services | عرض الخدمات القابلة للحجز | services.read |
التوفر
حساب الأوقات المتاحة، باستخدام نفس الشبكة الزمنية التي يفرضها مسار الكتابة.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /availability | جلب الأوقات المتاحة لخدمة واحدة | availability.read |
الحجوزات
إنشاء الحجوزات وقراءتها وعرضها وإعادة جدولتها وإلغاؤها، ومتابعة تغذية تغييراتها.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /bookings | عرض الحجوزات ضمن نطاق تواريخ | bookings.read / bookings.read.org |
| POST | /bookings | إنشاء حجز | bookings.write |
| GET | /bookings/{id} | جلب حجز واحد | bookings.read / bookings.read.org |
| PATCH | /bookings/{id} | إعادة جدولة حجز أو إلغاؤه | bookings.write |
| GET | /bookings/changes | جلب تغذية تغييرات الحجوزات | bookings.read / bookings.read.org |
العملاء
بحث آمن من التعداد للبحث عن عميل أو إنشائه عبر رقم الهاتف، وسجل عملاء مُخفى الهوية جزئياً.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| POST | /customers | البحث عن عميل برقم الهاتف أو إنشاؤه | customers.write |
| GET | /customers/list | عرض سجل العملاء | customers.read |
الطلبات
حالة الطلب وحالة الدفع والتنفيذ. لا يشمل أبداً بيانات Stripe الخاصة بالمنشأة.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /orders | عرض الطلبات | orders.read |
طلبات الخدمة الميدانية
طلبات الخدمة الميدانية، حرفتها ونافذتها الزمنية المجدولة. لا يشمل أبداً عنوان الخدمة.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /service-jobs | عرض طلبات الخدمة الميدانية | service_jobs.read |
العقارات
قوائم العقارات باللغتين. لا يشمل أبداً الملاحظات أو الإحداثيات.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /properties | عرض قوائم العقارات | real_estate.read |
المحادثات
عناوين مواضيع المحادثات. لا يشمل أبداً نصوص الرسائل.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /conversations | عرض مواضيع المحادثات | conversations.read |
العملاء المحتملون
العملاء المحتملون لدى المنشأة وسجل أنشطتهم في CRM. بيانات التواصل مُخفاة، دون نص حر أو بريد إلكتروني.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /leads | عرض العملاء المحتملين | leads.read |
| POST | /leads | إنشاء عميل محتمل | leads.write |
| DELETE | /leads/{id} | اقتراح حذف عميل محتمل نهائياً (يتطلب موافقة المالك) | leads.delete |
| GET | /leads/{id} | جلب عميل محتمل واحد | leads.read |
| GET | /leads/{id}/activities | عرض عناوين أنشطة عميل محتمل واحد | leads.read |
| POST | /leads/{id}/notes | إضافة ملاحظة إلى عميل محتمل | leads.write |
| POST | /leads/{id}/stage | نقل عميل محتمل إلى مرحلة في خط الأنابيب | leads.write |
| POST | /leads/{id}/status | تحديد حالة عميل محتمل | leads.write |
خط الأنابيب
إعدادات مراحل خط الأنابيب — لا توجد بيانات عملاء يلزم إخفاؤها.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /pipeline/stages | عرض إعدادات مراحل خط الأنابيب | pipeline.read |
الإعدادات
إعدادات المنشأة: إدارة كتالوج الخدمات، وساعات العمل، وإعدادات المنشأة، وقاعدة معرفة واتساب الذكية، وملخص مُشتق للوكيل الصوتي. يُستثنى كل حقل متعلق بالاعتماد أو الفوترة أو المصادقة أو الاحتفاظ بالبيانات؛ ولا حذف.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /config/business-hours | عرض ساعات العمل | business_hours.read |
| POST | /config/business-hours | تحديد ساعات عمل يوم واحد من أيام الأسبوع | business_hours.write |
| GET | /config/knowledge | عرض مدخلات قاعدة المعرفة | knowledge.read |
| POST | /config/knowledge | إنشاء مدخل في قاعدة المعرفة أو تحديثه | knowledge.write |
| GET | /config/services | عرض إعدادات الخدمات (عرض إداري) | services.read |
| POST | /config/services | إنشاء خدمة أو تحديثها | services.write |
| GET | /config/settings | جلب إعدادات المنشأة | org_settings.read |
| POST | /config/settings | تحديث إعدادات المنشأة | org_settings.write |
| GET | /config/voice-agent | جلب إعدادات الوكيل الصوتي | voice_agent.read |
التدقيق
إيصالات الاستخدام الخاصة بعميل الواجهة البرمجية هذا نفسه لكل قدرة على حدة، لأغراض المطابقة والتصدير الرقابي. لا تشمل أبداً بيانات عميل آخر، ولا تكون على مستوى المنشأة بالكامل أبداً. لا يوجد تقرير عن اتفاقية مستوى الخدمة (SLA) أو وقت التشغيل على هذه الواجهة.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| GET | /audit/receipts | عرض إيصالات الاستخدام الخاصة بعميل الواجهة البرمجية هذا | audit.read |
الرسائل
ردود على العملاء يقترحها الوكيل ولا يُرسل أي منها إلا بعد موافقة مالك النشاط عليه. عبر واتساب فقط، ضمن نافذة الـ 24 ساعة للعميل، ولا تُرسل أبداً إلى عميل ألغى اشتراكه.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| POST | /conversations/{id}/replies | اقتراح رد عبر واتساب (لا يُرسل إلا بعد موافقة المالك) | messages.send |
المدفوعات
عمليات الاسترداد وروابط الدفع لحجز ما، على حساب Stripe الخاص بالمنشأة. ينتظر كل طلب موافقة المالك بعد التحقق من هويته، ولا يتحرك أي مبلغ قبل ذلك.
| الطريقة | المسار | الوصف | الصلاحية المطلوبة |
|---|---|---|---|
| POST | /payments/links | طلب رابط دفع لحجز (يتطلب موافقة المالك) | payments.link |
| POST | /payments/refunds | طلب استرداد دفعة حجز أو طلب (يتطلب موافقة المالك) | payments.refund |
نقطة نهاية MCP
العمليات نفسها متاحة أيضاً كأدوات MCP عبر نقطة نهاية واحدة من نوع JSON-RPC 2.0، مصادَق عليها بمفتاح Bearer نفسه. يعيد tools/list الأدوات التي تغطيها صلاحيات المفتاح فعلاً فقط.
- نقطة النهاية
/api/agent/mcp