المصادقة ومفاتيح الـ API

الغرض#

يجب أن يحمل كل استدعاء لواجهة التاجر أو واجهة الشركة مفتاح API. يحدّد المفتاح حسابك، فكل ما يفعله الاستدعاء (كإنشاء الطرود) يُنفَّذ باسمك. توضّح هذه الصفحة من أين تحصل على المفتاح، وكيف ترسله، وماذا يردّ به الـ API عند حدوث مشكلة.

من يستطيع الحصول على مفتاح؟#

• التجّار: تجّار المنصة فقط. التاجر التابع لشركة توصيل يظهر له تنبيه بأن الميزة لحسابات تجّار المنصة، ويُعاد إلى لوحة التحكم.
• شركات التوصيل: أدمن الشركة فقط. يظهر بند «الربط والـ API» في قائمة الشركة للأدمن.

ما الذي تحتاجه؟#

• حساب فعّال، وللشركة اشتراك فعّال أيضاً. وتُستثنى من الاشتراك الشركات التابعة للمنصة والمملوكة لتاجر.
• باقة تتضمن ميزة الـ API. يحدّدها السوبر أدمن لكل باقة: تبدأ باقة التاجر الجديدة وميزة الـ API غير مفعّلة، وتبدأ باقة الشركة الجديدة وهي مفعّلة. ولا تُطبَّق ميزات باقة التاجر إلا ما دامت في المنصة باقة تجّار فعّالة واحدة على الأقل، ولا تحتاج الشركات التابعة للمنصة والمملوكة لتاجر إلى باقة. وإذا خلت الباقة من الميزة لا يمكن توليد مفتاح: يحصل التاجر على تحذير يذكر السبب، وتعرض صفحة الشركة تنبيهاً وتعطّل الأزرار.

الحصول على مفتاح التاجر#

1. افتح «الويب هوك والـ API»

   من قائمة التاجر، تحت «الربط»، اضغط «الويب هوك والـ API».

2. ولّد مفتاح المطوّر

   في جدول «مفاتيح الويب هوك» ابحث عن الصف الأول. يظهر اسمه «API للمطورين» حتى في الواجهة الإنجليزية، ووصفه: «للربط مع أي نظام أو منصة غير الموجودة (ERP، تطبيقك، متجر خاص)». إذا كان عمود «المفتاح» يعرض «ما في مفتاح» فاضغط «توليد».

3. انسخ المفتاح

   تُحمَّل الصفحة من جديد ويظهر فيها المفتاح كاملاً. اضغط «نسخ». وفي الزيارات اللاحقة يظهر المفتاح مخفياً جزئياً (أول 7 أحرف وآخر 4 أحرف)؛ اضغط «إظهار / إخفاء» لإظهاره من جديد.

4. احفظه على خادمك

   خزّنه في متغيّر بيئة أو مخزن أسرار، ولا تضعه أبداً في تطبيق جوال أو كود متصفح.

1234

1. مفاتيح الـ API الحالية (تُعرض مخفية)
2. اسم المنصة أو النظام الذي ستربطه
3. أنشئ مفتاحاً جديداً
4. افتح توثيق الـ API

الحصول على مفتاح الشركة#

1. افتح «الربط والـ API»

   سجّل الدخول بحساب أدمن الشركة وافتح «الربط والـ API» من قائمة الشركة.

2. راجع بطاقة الباقة

   تعرض بطاقة «باقة الشركة» باقتك وتاريخ انتهائها وميزاتها واستهلاك اليوم («طلبات الـ API اليوم»).

3. ولّد المفتاح

   في بطاقة «مفتاح الـ API» اضغط «ولّد مفتاح API».

4. انسخ المفتاح وعنوان Base URL

   يظهر المفتاح كاملاً بعد التوليد مباشرة، ثم يظهر مخفياً جزئياً (أول 8 أحرف وآخر 4 أحرف) مع زر عين لإظهاره وزر نسخ. ويُعرض عنوان Base URL في أسفل بطاقة «مفتاح الـ API».

إرسال المفتاح#

ضع المفتاح في ترويسة Authorization بصيغة Bearer.

curl https://YOUR_DOMAIN/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

• تُقرأ هذه الترويسة فقط. المفتاح في الرابط أو في جسم الطلب يُهمَل.
• لواجهة الشركة مفتاحها ومسارها الأساسي /api/company/v1 (مثلاً /api/company/v1/me).
• أضف Accept-Language: en لتصلك رسائل الأخطاء بالإنجليزية.
• ليس للمفاتيح تاريخ انتهاء: يعمل المفتاح حتى تجدّده أو تلغيه.

النتيجة المتوقعة#

يعيد الاستدعاء 200 مع {"success": true, "data": ...}: في واجهة التاجر بيانات حسابك وباقتك وأرصدتك، وفي واجهة الشركة بيانات شركتك وباقتها واستهلاكها. وهذا يثبت أن المفتاح يعمل. وأي ردّ آخر يوضّحه قسم «ماذا يحدث عند مفتاح ناقص أو خاطئ؟».

ماذا تعني البادئات؟#

ماذا يحدث عند مفتاح ناقص أو خاطئ؟#

يجري الـ API هذه الفحوصات بالترتيب ويتوقف عند أول فحص يفشل. وكل ردّ يأتي بغلاف الخطأ الموحّد.

{ "success": false, "error": { "code": "invalid_key", "message": "The key is invalid or revoked. Generate a new key from the merchant dashboard." } }

تجديد المفتاح وإلغاؤه وحمايته#

• التجديد ينشئ مفتاحاً جديداً ويتوقف القديم فوراً. حدّث كل نظام يستخدمه.
• الإلغاء (زر «إلغاء»، وأيقونة سلة المهملات في جدول التاجر) يحذف المفتاح ويتوقف كل نظام يستخدمه.
• من يملك المفتاح يتصرّف باسم حسابك، فجدّده فوراً إن تسرّب. يستطيع مفتاح التاجر إنشاء طرود على حساب ذلك التاجر وتُخصم الأجور من رصيد الشحن لديه. ويستطيع مفتاح الشركة قراءة تجّار الشركة ومناديبها وطرودها، وإنشاء طرود لتجّارها، وتعيين المناديب، وتغيير حالات الطرود؛ ولا تُخصم الأجرة من رصيد التاجر لدى الشركة إلا إذا كان دفع الأجرة عنده «من رصيده مسبقاً».
• يستطيع المالك، بعد تسجيل دخوله إلى اللوحة، إظهار المفتاح كاملاً في أي وقت، فاحمِ الدخول إلى اللوحة أيضاً.

أخطاء شائعة#

• نسيان تحديث نظامك بعد الضغط على «تجديد».
• وضع المفتاح في الرابط (?key=...) أو في جسم الطلب: 401 والكود unauthenticated.
• الحصول على 403 والكود plan_feature مع مفتاح وُلّد سابقاً: انتهت باقة التاجر أو فقدت ميزة الـ API، أو باقة الشركة لا تتضمنها (والشركة التي انتهى اشتراكها تحصل على 402 والكود subscription_expired). جدّد الاشتراك أو اطلب تفعيل ميزة الـ API في الباقة فيعمل المفتاح نفسه من جديد.

الحدود والصلاحيات#

• الشركة: يُخزَّن المفتاح على حساب أدمن الشركة المالك. يرى كل أدمن في الشركة المفتاح نفسه ويجدّده، وإذا أُوقف حساب المالك يردّ الـ API بالكود account_inactive.
• توليد المفاتيح محدود بعدد الطلبات: 20 في الدقيقة للتاجر و10 للشركة.