التوثيق

كل طلب يحمل المفتاح في ترويسة Authorization:

curl https://k-message.kerneltics.com/v1/me \
  -H "Authorization: Bearer km_live_a1b2c3d4e5f6..."

الترويسة X-API-Key: km_live_... مقبولة كبديل. Bearer هي الموثّقة لأنها الافتراضية في أغلب الأدوات.

ما فيه خطوة تسجيل دخول، ولا رمز تجدّده، ولا انتهاء صلاحية إلا إذا حددت واحد.

إنشاء مفتاح

الإعدادات ← مفاتيح الواجهة ← إنشاء مفتاح من لوحة التحكم.

تختار الاسم، والصلاحيات، واختياريًا تاريخ انتهاء وحد للطلبات وقائمة عناوين IP مسموح لها.

المفتاح كامل يظهر مرة وحدة، في رد الإنشاء، وما يمكن استرجاعه بعدها. نحن نحفظ بصمة SHA-256 فقط، فحتى لو طلبت منا ما نقدر نعطيك إياه مرة ثانية. إذا ضاع منك، أنشئ غيره وألغِ القديم.

الصلاحيات

المفتاح ما يسوي إلا اللي اخترته وقت الإنشاء. الصلاحيات دقيقة: ما فيه تدرّج ولا رمز شامل، وcontacts:write ما تعني contacts:read. هذا مقصود، لأن الصلاحيات الضمنية هي المكان اللي تتسرّب منه أنظمة الصلاحيات، واختيار المربعين ما يكلفك شيء.

الصلاحية	تسمح بـ
account:read	قراءة بيانات المنشأة وأرقام واتساب
messages:send	إرسال رسائل نصية وقوالب ووسائط
messages:read	قراءة المحادثات والسجل وحالة التسليم والوسائط
contacts:read	عرض جهات الاتصال والبحث فيها
contacts:write	إضافة وتعديل جهات الاتصال ووسومها
contacts:delete	حذف جهات الاتصال وسجل محادثاتها
templates:read	عرض القوالب ومتغيراتها
templates:write	إرسال القوالب للاعتماد وتحديث حالتها
campaigns:read	قراءة الحملات وتقدّمها
campaigns:write	إنشاء الحملات وإضافة المستقبلين وتشغيلها
webhooks:read	قراءة الويب هوك وسجل الإرسال
webhooks:write	إنشاء وتعديل وحذف واختبار الويب هوك

استدعاء نقطة نهاية بدون صلاحيتها يرجّع 403 ويسمّي الصلاحية الناقصة، فما تحتاج ترجع لهذا الجدول:

{
  "error": {
    "type": "permission_error",
    "code": "missing_scope",
    "message": "This API key is missing the 'messages:send' scope."
  }
}

المفتاح ليس شخصًا

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

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

حماية المفتاح

على السيرفر فقط. المفتاح في متصفح أو تطبيق جوال يقدر أي أحد يقرأه.

في متغيرات البيئة، مو في المستودع. المفتاح المرفوع في git يظل في السجل حتى بعد حذفه.

مفتاح لكل نظام. مفاتيح منفصلة للمتجر ولـ ERP وللأدوات الداخلية تعني إنك تقدر تلغي واحد بدون ما توقف الباقي.

قيّد مصدر الاستخدام. إذا تكاملك ينادي من عناوين ثابتة، ضفها لقائمة المفتاح. المفتاح المسرّب يصير عديم الفائدة من أي مكان ثاني.

حط تاريخ انتهاء لأي شيء مؤقت. المفتاح اللي أنشأته لعملية ترحيل أو لوكالة لازم يتوقف لحاله.

إيقاف المفتاح

شيئين مختلفين، بقصد:

التعطيل يوقف المفتاح ويرجّعه. استخدمه عشان تختبر إذا كان فيه شيء لا يزال يعتمد عليه قبل ما تحذفه.

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

المفاتيح القديمة

المفاتيح اللي تبدأ بـ whm_ أُنشئت قبل نظام الصلاحيات. لا تزال تشتغل مع واجهة لوحة التحكم لكنها مرفوضة على /v1، برمز key_wrong_surface، لأنها ما تحمل صلاحيات وما فيه طريقة آمنة نخمّن بها وش المفروض تسمح فيه.

أنشئ مفتاح جديد. ما فيه مسار ترحيل، وهذا هو المقصود: نفس السبب اللي خلاها مرفوضة هو السبب اللي يخليك تبدّلها.