إنتقل إلى المحتوى الرئيسي

التوثيق

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

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

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

Authorization: Bearer mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5

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

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

mk_live_<22 حرفاً>_<10 حروف checksum>

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

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

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

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

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

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

النطاقات تُقيّد ما يستطيع المفتاح فعله، بصيغة resource:action. النطاق الافتراضي والأكثر شيوعاً:

النطاقيسمح بـ
whatsapp:sendإرسال رسائل واتساب نصية وقوالب
whatsapp:read(محجوز) قراءة حالة وسجل رسائل واتساب
messenger:send(محجوز) إرسال رسائل Facebook Messenger
instagram:send(محجوز) إرسال رسائل Instagram المباشرة
*بطاقة بدل — كل النطاقات الحالية والمستقبلية (استخدمه باقتصاد)

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

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

نعم. عند إنشاء مفتاح، اختر اختيارياً وكيلاً واحداً أو أكثر. سيستطيع المفتاح العمل على هؤلاء فقط — أي طلب لـ agent_id آخر يُعيد 403 agent_not_authorized.

اترك قائمة الوكلاء فارغة لمفتاح غير مقيّد يعمل عبر كل وكلاء المنظمة. استخدم المفاتيح المقيّدة عند تكامل منتج أو سير عمل وحيد ينبغي ألا يلامس سوى وكيل بعينه (يُنصح به لتطبيق مبدأ أقل صلاحية).

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

كل فشل توثيق يُعيد HTTP 401 مع ظرف الخطأ القياسي. رمز واحد (invalid_api_key) يغطي كل الحالات الفرعية حتى يحتاج عميلك فرعاً واحداً فقط — حقل message يُميّز للمتعاملين البشر:

الحالة الفرعية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 يوماً، دوّرها فوراً إذا تسرّب مفتاح، واستخدم مفاتيح منفصلة لبيئات وتكاملات مختلفة لتقليل نطاق التأثير عند الإلغاء.

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

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

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

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

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

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