المصادقة والمفاتيح
كل طلب يحمل مفتاح API سريًّا في ترويسة Authorization:
curl https://api.saei.automize.sa/v1/me -H "Authorization: Bearer sk_live_..."وتعمل أيضًا الترويسة X-Api-Key: sk_live_... للأدوات التي لا تستطيع ضبط Authorization. الطلبات عبر HTTPS فقط.
مفاتيح التشغيل والاختبار#
| المفتاح | يبدأ بـ | ماذا يفعل |
|---|---|---|
| اختبار | sk_test_ | كل شيء محاكاة: لا تصل الرسائل إلى واتساب، ولا شيء يُحتسب في الفوترة، ولا تستقبل الأحداث إلا نقاط الاستقبال الخاصة بوضع الاختبار. |
| تشغيل | sk_live_ | رسائل حقيقية إلى عملاء حقيقيين عبر أرقامك المربوطة. |
الوضع مرتبط بالمفتاح لا بالطلب، لذا يعمل الكود نفسه في الوضعين: بدّل المفتاح لتنتقل للتشغيل. ولا تنتقل العناصر بين الوضعين: مفتاح الاختبار لا يقرأ رسالة حقيقية، ومفتاح التشغيل لا يقرأ رسالة اختبار.
الصلاحيات#
لا يستطيع المفتاح إلا ما تسمح به صلاحياته. كل نقطة في المرجع تذكر الصلاحية التي تحتاجها، وبدونها تُرجع الواجهة 403 insufficient_scope وتذكر الصلاحية الناقصة في required_scope.
| الصلاحية | تسمح بـ |
|---|---|
messages:send | إرسال الرسائل واستخدام أدوات وضع الاختبار |
messages:read | قراءة الرسائل وحالتها |
webhooks:read / webhooks:write | عرض وإدارة نقاط الاستقبال وعمليات الإرسال |
templates:read | قراءة القوالب (قريبًا) |
contacts:read / contacts:write | قراءة وإدارة جهات الاتصال (قريبًا) |
عند إنشاء المفتاح يمكنك اختيار مجموعة جاهزة (وصول كامل، المراسلة، قراءة فقط) أو اختيار الصلاحيات واحدة واحدة. امنح كل تكامل أقل ما يحتاجه.
حماية المفاتيح#
- يظهر المفتاح كاملًا مرة واحدة عند إنشائه، ونحن لا نخزّن إلا بصمته.
- احفظ المفاتيح في متغيرات البيئة أو مدير الأسرار، ولا تضعها أبدًا في كود المتصفح أو تطبيق جوال أو مستودع كود.
- أنشئ مفتاحًا لكل تكامل، لتلغي أحدها دون أن يتعطل الباقي.
- ألغِ المفتاح فور الشك في تسرّبه: المطورون ← مفاتيح API ← إلغاء. يتوقف فورًا (
api_key_revoked). - لا تُنشأ المفاتيح إلا من البوابة، ولا يمكن إنشاؤها عبر الواجهة، لذا لا يستطيع مفتاح مسرّب إنشاء مفاتيح أخرى.
الباقات#
مفاتيح الاختبار تعمل في كل الباقات. أما الوصول الحي للواجهة فجزء من الباقات التي تشمله، وإن لم تشمله باقتك تُرجع الطلبات الحية api_access_not_in_plan.