التوثيق

تستخدم الواجهة البرمجية العامة لمجيب مفاتيح API، وليس JWT. كل مفتاح هو وثيقة اعتماد طويلة الأمد بين الخوادم، تُصدَر من لوحة التحكم وتنتمي إلى منظمتك. أرسل المفتاح كـ Bearer token عبر HTTPS.

كيف أُرسل مفتاح API؟

مرّر المفتاح في رأس Authorization القياسي:

Authorization: Bearer mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5

HTTPS فقط. طلبات HTTP العادية تُرفض من قبل موازن الحمل قبل الوصول إلى الواجهة.

كيف تبدو صيغة المفتاح؟

mk_live_<22 chars>_<10 char checksum>

Example: mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5

• mk_ — بادئة مجيب؛ قابلة للبحث في السجلات
• live_ — علامة البيئة (test_ محجوزة لبيئة اختبار مستقبلية)
• جسم 22 حرفاً يحمل 130 بت من العشوائية
• 10 حروف checksum حتى ترفض الواجهة المفاتيح المشوّهة محلياً قبل أي استعلام قاعدة بيانات

الـchecksum يحميك من الأخطاء الإملائية: خطأ بحرف واحد يفشل محلياً، بسرعة.

من أين أحصل على مفتاح؟

1. سجّل دخولك إلى لوحة تحكم مجيب. تحتاج منظمتك إلى باقة Starter أو Professional. يلزم أن تكون المالك، أو مديراً لديه صلاحية على كل الوكلاء.
2. افتح صفحة مفاتيح API من الشريط الجانبي
3. اضغط إنشاء مفتاح، اعطه اسماً، وأكّد
4. انسخ السر فوراً — يُعرض مرة واحدة فقط ولا يُسترجع أبداً

إذا فقدت مفتاحاً، ألغِه من لوحة التحكم وأنشئ واحداً جديداً. لا توجد طريقة لاسترجاع السر الأصلي.

تعمل المفاتيح نفسها مع خادم MCP من مجيب، الذي يتيح لمساعدي الذكاء الاصطناعي مثل Claude أو Cursor استدعاء هذه الواجهة. أعطِ كل مساعد مفتاحاً خاصاً به، مقيّداً بالوكلاء الذين يحتاج إليهم.

ما النطاقات (scopes)؟

النطاقات تُسمّي ما يستطيع المفتاح فعله، بصيغة resource:action. حالياً يُصدَر كل مفتاح بصلاحية كاملة، أي النطاق *: يمكنه استدعاء كل نقاط النهاية التي تقدّمها الواجهة على كل وكلاء منظمته.

النطاق	يسمح بـ
*	كل نقاط النهاية الحالية والمستقبلية. وهو ما يحمله كل مفتاح اليوم.
whatsapp:send	إرسال رسائل واتساب نصية وقوالب، وقراءة حالة رسالة مُرسَلة (GET /v1/whatsapp/messages/{id}). المفاتيح الصادرة قبل 11 أكتوبر 2026 كانت تحمل هذا النطاق وحده، وهي تحمل الآن *.

كل صفحة في مرجع الواجهة تعرض مسبقاً النطاق الذي ستطلبه نقطة النهاية (x-scope)، بحيث يمكن لاحقاً حصر مفتاح في القراءة فقط أو في نوع واحد من البيانات:

النطاق	نقاط النهاية
whatsapp:read	قوالب رقم واتساب
contacts:read / contacts:write	جهات الاتصال
notes:read / notes:write	ملاحظات جهة الاتصال
leads:read / leads:write	العملاء المحتملون، ومن ذلك إسنادهم وتثبيتهم وحذفهم؛ وحقول العملاء المحتملين للوكيل؛ وتعليمات حفظ العملاء للذكاء الاصطناعي
knowledge:read / knowledge:write	قواعد المعرفة
connections:read / connections:write	القنوات المتصلة وإعدادات رد الذكاء الاصطناعي فيها؛ ويقرأ connections:read أيضاً أداة الموقع وكود تضمينها
agents:read / agents:write	الوكلاء (عرضهم وقراءتهم) وإعداداتهم: الاسم والوصف والتعليمات الرئيسية والمنطقة الزمنية وإيقاف الذكاء الاصطناعي بعد رد فريقك ومدته والإخفاء التلقائي للتعليقات والمتابعات
team:read	فريقك: الأعضاء وأدوارهم وبريدهم الإلكتروني والوكلاء الذين يستطيع كلٌّ منهم فتحهم
usage:read	باقتك واستخدامها من الرسائل والوكلاء، الآن ولكل فترة فوترة
analytics:read	تحليلات الوكيل اليومية
custom_api:read / custom_api:write	أدوات ربط نظامك للوكيل وسجل تشغيلها؛ ويختبرها custom_api:write أيضاً ويغيّر تسجيل دخول مواقعها
conversations:read / conversations:write	محادثات الوكيل ورسائلها؛ ويغيّر conversations:write أيضاً حالتها والمُسنَد إليه ويرد على العملاء
comments:read / comments:write	تعليقات فيسبوك وإنستجرام الخاصة بالوكيل مع ردودها وحالة إشرافها؛ ويُخفيها comments:write أيضاً ويُظهرها

هذه النطاقات لا تُصدَر بعد. وعند إصدارها تستمر المفاتيح الحاملة لـ * في العمل دون تغيير. وليس لـ team:read وusage:read وanalytics:read نطاق كتابة: تقرأ الواجهة فريقك وباقتك واستخدامك وتحليلاتك، ولا تغيّرها أبداً. ولا يحتاج GET /v1/me إلى أي نطاق: يستطيع أي مفتاح صالح أن يصف نفسه، وتعرض صفحته في المرجع x-scope: none.

طلب بدون النطاق المطلوب يُعيد 403 insufficient_scope مع حقل required_scope يُخبرك بالضبط بما كان مفقوداً.

هل يمكنني تقييد المفتاح بوكلاء معيّنين؟

ليس من لوحة التحكم بعد. كل مفتاح تنشئه هناك يعمل على كل وكلاء منظمتك، ومنهم الوكلاء الذين تضيفهم لاحقاً، وتعرضه صفحة مفاتيح API بعبارة جميع الوكلاء. أما المفتاح الذي يحمل قائمة وكلاء فلا يعمل إلا عليهم: طلب لوكيل آخر من منظمتك يُعيد 403 agent_not_authorized، ووكيل منظمة أخرى يُعيد 404 agent_not_found. أما على نقطتي إرسال واتساب، اللتين تأخذان agent_id في جسم الطلب، فأي وكيل خارج قائمة المفتاح يُعيد 403 agent_not_authorized أياً كانت منظمته. وحالة الرسالة تتبع القائمة أيضاً: GET /v1/whatsapp/messages/{id} لرسالة أُرسلت عبر وكيل خارجها يُعيد 404 message_not_found، تماماً كالمعرّف غير الموجود.

يُظهر GET /v1/me قائمة وكلاء المفتاح في agent_ids (والقيمة null تعني كل الوكلاء)، ويعرض GET /v1/agents الوكلاء الذين يستطيع العمل عليهم الآن. راجع مفتاحك ووكلاؤه.

وإلى أن تتيح لوحة التحكم هذا الخيار، استخدم مفتاحاً لكل تكامل حتى تلغي أحدها دون أن تمس البقية.

والمفتاح الذي يحمل قائمة وكلاء مقيّد بها أيضاً فيما يتشاركه الوكلاء. قد تخدم قاعدة معرفة واحدة عدة وكلاء، لذلك لا يغيّرها هذا المفتاح إلا إذا كان يستطيع العمل على كل وكيل يستخدمها (وإلا 403 shared_with_other_agents). والأمر نفسه في تسجيل دخول موقع أداة ربط نظامك، الذي قد تستخدمه أدوات عدة وكلاء: لا يضيف هذا المفتاح أداة إليه ولا يغيّره إلا إذا كان يستطيع العمل على كل وكيل تستخدمه أدواته (وإلا 403 shared_with_other_agents).

وبعض القراءات تشمل منظمتك كلها أياً كانت قائمة وكلاء المفتاح: باقتك واستخدامك، وفريقك. فالمفتاح الذي يحمل قائمة وكلاء يرى كل أعضاء الفريق، لكن agent_ids لكل عضو لا تُظهر إلا الوكلاء الموجودين في قائمة المفتاح.

ماذا يستطيع المفتاح أن يفعل؟

يعمل المفتاح باسم منظمتك بصلاحيات مدير الوكيل على وكلائه. يقرأ ويغيّر معظم ما يستطيعه مدير الوكيل في لوحة التحكم، من إعدادات الوكيل إلى عملائه المحتملين ومعرفته وقنواته، ويقرأ فريقك وباقتك واستخدامك. لا ينشئ وكلاء ولا يحذفهم أبداً، ولا يدير أبداً فريقك أو الفوترة أو مفاتيح API.

• الوكلاء: عرضهم وقراءتهم، وتغيير اسم الوكيل ووصفه وتعليماته الرئيسية ومنطقته الزمنية وإيقاف الذكاء الاصطناعي بعد رد فريقك ومدته والإخفاء التلقائي للتعليقات. لا حالته ولا نموذج الذكاء الاصطناعي ولا مزوّده ولا صورته ولا لغته (422 field_not_writable).
• واتساب: إرسال الرسائل والقوالب، وعرض قوالب رقم، والاستعلام عن حالة رسالة.
• جهات الاتصال والملاحظات: قراءة جهات الاتصال وتحديثها؛ وقراءة الملاحظات وإضافتها، وتعديل أو حذف ما كتبه منشئ المفتاح منها.
• العملاء المحتملون: قراءتهم وإنشاؤهم وتحديثهم وإسنادهم وتثبيتهم وحذفهم؛ وإضافة حقول العملاء المحتملين المخصّصة للوكيل وتغييرها وحذفها؛ وتغيير تعليمات حفظ العملاء للذكاء الاصطناعي.
• المعرفة: قراءة قواعد المعرفة وإضافتها وتعديلها وحذفها.
• المحادثات: عرضها وقراءة رسائلها، والرد على العملاء باسم فريقك، وفتح المحادثة أو إغلاقها أو أرشفتها وتعليمها مقروءة أو غير مقروءة، وإيقاف الذكاء الاصطناعي فيها أو إنهاء إيقافه المؤقت، وتعليمها عاجلة أو محلولة، وإسنادها. لا البحث داخل سجل الرسائل.
• التعليقات: قراءة تعليقات فيسبوك وإنستجرام الخاصة بالوكيل مع ردودها وحالة إشرافها، وإخفاؤها وإظهارها.
• القنوات والمتابعات: عرض قنوات الوكيل المتصلة وتشغيل الذكاء الاصطناعي أو إيقافه في كل منها، وقراءة إعدادات المتابعة وتغييرها، وجلب أداة الموقع وكود تضمينها.
• أدوات ربط نظامك: إضافة أدوات الوكيل وتغييرها واختبارها وتشغيلها وإيقافها وحذفها، وتغيير تسجيل دخول مواقعها، وقراءة سجل تشغيلها (الباقات المدفوعة).
• التقارير: قراءة تحليلات الوكيل اليومية، وباقة منظمتك واستخدامها.
• الفريق: عرض أعضاء فريقك بأسمائهم وأدوارهم وبريدهم الإلكتروني، ومن يستطيع فتح كل وكيل.

حذف العميل المحتمل نهائي ولا يمكن التراجع عنه. ولا يحذف المفتاح أبداً جهات الاتصال أو المحادثات، ولا يربط القنوات أو يفصلها، ولا يغيّر أداة الموقع أو قوالب واتساب.

حين يسجّل مجيب شخصاً، مثل كاتب ملاحظة أو من غيّر حالة عميل محتمل أو من أسنده، يسجّل الشخص الذي أنشأ المفتاح. وبخلاف تعديل أحد أعضاء الفريق، لا يُسند التعديل عبر الواجهة عميلاً محتملاً غير مُسنَد إلى أي أحد؛ وحدهما نقطتا الإسناد تفعلان ذلك: POST /v1/agents/{agentId}/leads/{leadId}/assign، وPOST /v1/agents/{agentId}/conversations/{conversationId}/assign التي تُسند معها العميل المحتمل للمحادثة. ولا يُسند الرد عبر الواجهة المحادثة لأحد كذلك.

ماذا يحدث عند فشل التوثيق؟

كل فشل توثيق يُعيد HTTP 401 مع ظرف الخطأ القياسي. رمز واحد (invalid_api_key) يغطي كل الحالات الفرعية — حقل message يُميّز للمتعاملين البشر. استثناء واحد: حين يتعذّر على مجيب فحص المفتاح أصلاً، يحمل الـ401 القيمتين type: internal_error وcode: internal_server_error؛ أعد المحاولة بتراجع متصاعد ولا تُدوّر المفتاح.

الحالة الفرعية	message
رأس Authorization مفقود	Missing Authorization header. Send 'Authorization: Bearer mk_live_...'.
نظام خاطئ (مثل Basic)	Authorization header must use the Bearer scheme.
مفتاح مشوّه أو غير معروف أو ملغى أو منتهي	The API key is invalid, malformed, or revoked.

مثال على الاستجابة:

{
  "error": {
    "type":           "authentication_error",
    "code":           "invalid_api_key",
    "message":        "The API key is invalid, malformed, or revoked.",
    "correlation_id": "req_01KQER73VQBSZK5RPVZCPW221V"
  }
}

أسئلة شائعة

هل يجب أن أُدوّر المفاتيح بانتظام؟

نعم. تعامل مع مفاتيح API كاعتمادات قاعدة بيانات — دوّرها كل 90 يوماً، دوّرها فوراً إذا تسرّب مفتاح، واستخدم مفاتيح منفصلة لبيئات وتكاملات مختلفة لتقليل نطاق التأثير عند الإلغاء.

هل يستطيع المفتاح قراءة البريد الإلكتروني لأعضاء فريقي؟

نعم. يُعيد GET /v1/organization/members وGET /v1/agents/{agentId}/members اسم كل عضو ودوره وبريده الإلكتروني، ولا يُعيدان رقم هاتفه أبداً، لأي مفتاح يحمل team:read، وهو ما يحمله كل مفتاح اليوم. أبقِ المفاتيح على خوادمك، وألغِ أي مفتاح ربما تسرّب.

هل يمكنني استخدام المفتاح ذاته من خوادم متعدّدة؟

نعم. المفتاح ليس مرتبطاً بـIP. حد المعدّل (60 طلب/دقيقة افتراضياً) لكل مفتاح، فالخوادم المتعدّدة التي تتشارك مفتاحاً واحداً تتشارك الميزانية. لميزانيات معدّل مستقلة، أصدر مفاتيح منفصلة.

هل يوجد بيئة اختبار/sandbox؟

ليس بعد. علامة البيئة test_ محجوزة في صيغة المفتاح لكنها لا تُصدَر حالياً. طوِّر على وكيل اختبار في منظمتك في الوقت الحالي، واستخدم مفاتيح الإعادة الآمنة مع إرسال واتساب حتى لا تتضاعف الرسائل عند إعادة المحاولة أثناء التطوير.

ما الفرق بين توثيق مفتاح API و JWT لوحة التحكم؟

تُوثّق لوحة التحكم المستخدمين عبر JWT يُصدَر عند تسجيل الدخول. تُوثّق الواجهة العامة الخوادم عبر مفاتيح API طويلة الأمد. داخلياً، كلاهما يُنتج نفس سياق الصلاحيات — تُطبَّق نفس فحوصات الإذن لكل وكيل — لكن لا يمكن استخدام مفاتيح API في متصفح لوحة التحكم، ولا يمكن استخدام JWTs مع نقاط /v1/.