المفاتيح والأمان
كل طلب للـ API يحمل مفتاحاً في الهيدر Authorization. نوع المفتاح يحدد ما يستطيع فعله، فاختر أقل صلاحية تكفيك.
إرسال المفتاح
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json
لا ترسل المفتاح في رابط الطلب (?token=) ولا في جسم الطلب، فقط في الهيدر.
أنواع المفاتيح
عند إنشاء المفتاح من أدوات المطوّرين تختار صلاحيته:
| الصلاحية | ماذا يستطيع | أين تضعه | مثال استخدام |
|---|---|---|---|
| كل الصلاحيات | كل الـ API: الرسائل وجهات الاتصال والمجموعات والحملات والقوالب وموتشي | سيرفرك فقط | تكامل كامل مع نظام CRM |
| إرسال الرسائل فقط | POST /api/send و /api/send/template و /api/send/media، و GET /api/messages/{id} و GET /api/templates و GET /api/verify |
سيرفرك فقط | متجر يرسل إشعارات الطلبات |
| قراءة فقط | أي طلب GET (ما عدا موتشي)، ولا يرسل ولا يعدّل شيئاً |
سيرفرك أو أداة تقارير | لوحة تقارير داخلية |
| موتشي فقط (للسيرفر) | محادثات موتشي فقط، وسيرفرك هو من يحدد هوية المستخدم (user.id) |
سيرفرك فقط | تطبيق له سيرفر خاص |
| مفتاح موتشي العام (داخل التطبيقات) | فتح محادثات موتشي فقط، بحدود صارمة لكل جهاز. يبدأ بـ pk_ |
مسموح داخل تطبيق الموبايل أو كود الموقع | تطبيق موبايل بدون سيرفر |
المفاتيح التي أنشئت قبل إضافة الصلاحيات تعمل بـ كل الصلاحيات كما كانت، فلا يتوقف أي تكامل قديم.
لو استخدمت مفتاحاً في طلب خارج صلاحيته يرجع:
{
"statusCode": 403,
"code": "api_key_scope_denied",
"message": "This API key is not allowed to use this endpoint.",
"request_id": "74159c04-8fc8-473a-aa26-d2e0d34484a0"
}
لماذا لا تضع المفتاح السري في تطبيق الموبايل؟
أي شخص يستطيع فك ملف التطبيق (APK أو IPA) وقراءة النصوص بداخله في دقائق. لو وضعت مفتاحاً سرياً هناك، سيستطيع أي أحد أن يرسل رسائل واتساب من رقمك ويقرأ جهات اتصالك ويستهلك باقتك.
لذلك عندك طريقتان آمنتان:
- الأفضل: تطبيقك يكلّم سيرفرك، وسيرفرك هو من يكلّم بوتزو بالمفتاح السري. هكذا تتحكم أنت في من يرسل ماذا.
- بدون سيرفر: استخدم مفتاح موتشي العام
pk_. هو مصمم ليُكشف: لا يستطيع إلا فتح محادثات مع موتشي، وكل جهاز يأخذ محادثته الخاصة بتوكن لا يعرفه غيره، ومحدود بعدد المحادثات والرسائل لكل جهاز. لا يرسل واتساب ولا يقرأ أي بيانات.
دورة حياة المفتاح
| العملية | من أين | ماذا يحدث |
|---|---|---|
| إنشاء | أدوات المطوّرين ← إنشاء مفتاح | يظهر المفتاح مرة واحدة. نحن نحفظ نسخة مشفّرة منه (HMAC) فقط ولا نستطيع إظهاره مرة أخرى |
| تدوير (Rotate) | زر التدوير بجانب المفتاح | يصدر مفتاح جديد بنفس الصلاحية، والقديم يتوقف فوراً |
| إلغاء | زر الإلغاء | يتوقف المفتاح فوراً ولا يمكن استرجاعه |
في البطاقة ترى آخر 4 حروف من المفتاح وآخر وقت استُخدم فيه، لتعرف أي مفتاح يعمل في أي مكان.
إذا تسرّب مفتاح: دوّره فوراً من لوحة التحكم، ثم ضع المفتاح الجديد في سيرفرك. المفتاح القديم يتوقف في نفس اللحظة.
أخطاء المصادقة
| الحالة | code |
السبب والحل |
|---|---|---|
| 401 | bearer_token_missing |
لم ترسل الهيدر Authorization. تأكد من الصيغة Bearer <key> |
| 401 | bearer_token_invalid |
المفتاح غير صحيح أو أُلغي أو دُوّر. انسخ المفتاح من جديد |
| 403 | api_key_scope_denied |
المفتاح صحيح لكن صلاحيته لا تسمح بهذا الطلب. استخدم مفتاحاً بالصلاحية المناسبة |
| 403 | subscription_inactive |
اشتراك المؤسسة منتهٍ. جدّد الاشتراك من لوحة التحكم |
نصائح أمان
- ضع المفتاح في متغيرات البيئة أو مدير الأسرار، وليس داخل الكود أو Git.
- استخدم مفتاحاً منفصلاً لكل نظام (المتجر، الـ CRM، التطبيق) مع اسم واضح، حتى تستطيع إلغاء واحد دون التأثير على الباقي.
- اختر أقل صلاحية تكفي. متجر يرسل إشعارات فقط يكفيه «إرسال الرسائل فقط».
- تحقق دائماً من توقيع الـ Webhooks قبل الوثوق بها: الـ Webhooks.