المصادقة
مفاتيح API للحساب: هيدر Bearer والصلاحيات وتقييد الأرقام وقائمة الـ IP والصلاحية وتغيير المفتاح ومفتاح الرقم القديم.
كل طلب لازم يكون معاه مفتاح الحساب في هيدر Authorization. المفاتيح بيانات دخول للأنظمة: استخدمها من السيرفر بتاعك بس.
Authorization: Bearer wsl_live_Ab12Cd34…إنشاء المفاتيح وحفظها
- اعمل المفاتيح من الإعدادات ← مفاتيح API. صاحب الحساب بس اللي يشوفها ويديرها؛ أعضاء الفريق لأ، ومينفعش تتعمل أثناء جلسة دعم.
- المفتاح عبارة عن
wsl_live_وبعدها 40 حرف عشوائي. بيظهر مرة واحدة. مرسلات بتخزن HMAC ليه بس بسر برا قاعدة البيانات، فالمفتاح الضايع مش بيرجع — غيّره. - لحد 20 مفتاح شغال لكل حساب. كل مفتاح بيعرض أوله وآخر 4 حروف وإمتى ومن أنهي IP اتستخدم آخر مرة.
- صلاحية اختيارية: من 1 لـ 730 يوم (بعدها
API_KEY_EXPIRED). - لازم باقتك تشمل الـ API (
403 API_ACCESS_NOT_IN_PLAN).
الصلاحيات
المفاتيح ممنوعة من كل حاجة إلا اللي تدّيه: الطلب محتاج الصلاحية المكتوبة في صفحة الـ endpoint، غير كده 403 SCOPE_REQUIRED (والرد بيقول الصلاحية الناقصة). ادّي كل نظام اللي محتاجه بس.
| الصلاحية | المعنى |
|---|---|
numbers:read | المعنىعرض الأرقام وحالتها وفحص الأرقام. |
numbers:write | المعنىإضافة وربط وتسمية وخروج ومسح الأرقام؛ الإيقاف والحدود. |
messages:send | المعنىإرسال رسايل وملفات، تفاعل، تعديل، مسح. |
messages:read | المعنىسجل حالة الرسايل (بيانات وصفية بس). |
campaigns:read | المعنىتقدم الحملات والمستلمين. |
campaigns:write | المعنىإنشاء وبدء وإيقاف واستكمال وإلغاء ومسح الحملات. |
autoreplies:read | المعنىقراءة قواعد الرد التلقائي وإعداداته؛ والتجربة من غير إرسال. |
autoreplies:write | المعنىإنشاء وتعديل ومسح قواعد الرد التلقائي. |
otp | المعنىإرسال والتحقق من أكواد OTP. |
groups:read | المعنىقراءة جروبات الرقم (الإرسال للجروبات مقفول). |
stats:read | المعنىالصحة والحدود والإحصائيات. |
webhooks:read | المعنىإعدادات الويب هوك وقائمة الأحداث وسجل التوصيل. |
webhooks:write | المعنىضبط/مسح الويب هوك وتغيير السر والاختبار وإعادة الإرسال. الويب هوك بيستقبل كل رسالة واردة — اديها بحذر. |
widgets:read | المعنىعرض أزرار الموقع وقراءة إحصائياتها. |
widgets:write | المعنىإنشاء وتعديل ومسح أزرار الموقع. |
links:read | المعنىعرض روابط واتساب المتتبَّعة وقراءة إحصائياتها. |
links:write | المعنىإنشاء وتعديل ومسح روابط واتساب المتتبَّعة. |
تقييد الأرقام
وانت بتعمل المفتاح بتختار كل الأرقام أو قائمة. المفتاح المقصور بيشوف أرقامه بس في كل القوايم، وبياخد 404 على الباقي (زي id مش موجود بالظبط)، ومش بيقدر يضيف أرقام أو يدير ويب هوك الحساب (KEY_NUMBER_RESTRICTED).
قائمة الـ IP المسموحة
اختياري: اكتب عناوين IPv4 / IPv6 أو نطاقات CIDR لسيرفراتك. الفحص بيحصل بعد التعرف على المفتاح على طول، قبل أي حاجة تانية (403 IP_NOT_ALLOWED). GET /v2/me بيرجع clientIp — العنوان اللي مرسلات شايفاه — عشان يساعدك تملاها.
تغيير المفتاح وإلغاؤه
- التغيير بيطلع مفتاح جديد (بيظهر مرة واحدة). القديم بيقف فورًا، أو بعد مهلة لحد 24 ساعة (
graceMinutes≤ 1440) عشان تنشر من غير توقف. - الإلغاء بيوقف المفتاح فورًا.
- كل إنشاء/تعديل/تغيير/إلغاء بيتسجل في سجل المراجعة — من غير المفتاح نفسه أبدًا.
مفتاح الرقم القديم (x-api-key)
مفتاح x-api-key الخاص بالرقم من v1 لسه شغال على v2 في endpoints الرسايل بتاعة رقمه بس (إرسال، رفع، حالة الرسالة، تفاعل، تعديل، مسح). في أي مكان تاني بيرد 401 ACCOUNT_KEY_REQUIRED. صفحات الـ endpoints بتكتب «مفتاح الرقم شغال» لما يكون مقبول.
حماية من التخمين
20 مفتاح غلط أو مش سليم من نفس الـ IP خلال 10 دقايق بيقفلوا الـ IP ده 15 دقيقة (429 AUTH_TOO_MANY_FAILURES)، حتى للمفاتيح الصح. المفاتيح الملغية أو المنتهية مش بتتحسب، عشان نسخة قديمة من نظامك متقفلش المفتاح الجديد.
عمرك ما تكشف المفتاح
متحطش المفاتيح في كود الواجهة أو تطبيقات الموبايل أو الروابط أو اللوجات. لو مفتاح اتسرب، ألغيه أو غيّره من الإعدادات ← مفاتيح API فورًا.