مفاتيح الـ API مفقودة أو غير صالحة أو منتهية

ماذا يعني ذلك#

يُفحص كل استدعاء لواجهة التاجر (/api/v1) أو واجهة الشركة (/api/company/v1) بترتيب ثابت: المفتاح أولاً، ثم الحساب، ثم الباقة. وأول فحص يفشل يوقف الاستدعاء ويعيد رد الخطأ بالصيغة المعتادة ومعه error.code. ولا يُنشأ شيء ولا يُخصم شيء. تربط هذه الصفحة كل رد بسببه وحلّه.

من المتأثر#

التجار الذين يستخدمون مفتاح واجهة التاجر، ومديرو الشركات الذين يستخدمون مفتاح واجهة الشركة. وليس لمفاتيح الـ API تاريخ انتهاء، لذلك فإن «انتهاء المفتاح» يعني في الواقع أن المفتاح جُدّد أو أُلغي، أو أن الباقة أو الاشتراك انتهى.

الأسباب المحتملة#

الرسائل التالية هي الرسائل الافتراضية بالعربية. وأضف الترويسة Accept-Language: en للحصول على النص الإنجليزي.

الرد 429 مع rate_limited هو حد باقة وليس مشكلة اعتماد، فراجع مقالة حدود الطلبات. وهناك خطأ شائع: المفتاح الذي فيه علامة اقتباس زائدة أو مسافة داخلية أو نقاط التقنيع هو مفتاح مختلف تماماً، فيعطي invalid_key. أما المسافات في بدايته أو نهايته فتُهمَل.

كيف تشخّص المشكلة#

استدعِ نقطة الحساب واقرأ رمز HTTP وerror.code:

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

واستخدم /api/company/v1/me لمفتاح الشركة. بعد ذلك قارن مع اللوحة:

• التاجر: افتح «الويب هوك والـ API» تحت «الربط». يعرض الصف الأول «API للمطورين» المفتاح مقنَّعاً بأول 7 أحرف وآخر 4 أحرف، وزر العين يُظهره كاملاً. وعبارة «ما في مفتاح» تعني أنه لا يوجد مفتاح.
• مدير الشركة: افتح «الربط والـ API». تعرض بطاقة «مفتاح الـ API» المفتاح (بأول 8 أحرف وآخر 4 أحرف عند التقنيع). وتعرض بطاقة «باقة الشركة» الباقة وتاريخ انتهائها والميزات المشمولة، وتظهر فوق المفتاح رسالة تحذير إذا لم تتضمن الباقة الـ API.
• البادئة: مفاتيح التجار تبدأ بـ sk_ ومفاتيح الشركات بـ ck_.

خطوات الحل#

1. أصلح المفتاح المفقود أو غير الصحيح

   أرسل Authorization: Bearer YOUR_API_KEY تماماً بهذا الشكل، وبالمفتاح الصحيح للواجهة الصحيحة. قارن المفتاح المخزَّن لديك بما في اللوحة. وإذا اختلف، أو لم تكن متأكداً، فجدّده.

2. جدّد المفتاح أو ولّده

   يضغط التاجر «توليد»، أو «تجديد» إذا كان المفتاح موجوداً، في صف «API للمطورين». ويضغط مدير الشركة «ولّد مفتاح API»، أو «تجديد». ويطلب التجديد تأكيداً، ثم تعرض الصفحة المفتاح الجديد كاملاً. ويتوقف المفتاح القديم فوراً، فحدّث كل نظام يستخدمه. وتوليد المفاتيح محدود بـ 20 طلباً في الدقيقة للتجار و10 للشركات، فإذا تجاوزت الحد فانتظر دقيقة ثم أعد المحاولة.

3. عالج ردود الحساب والباقة

   عند plan_feature يفتح التاجر «الباقة والاشتراك» ليجدد أو يرقّي، ويجدد مدير الشركة اشتراك الشركة (subscription_expired) أو يطلب من المنصة إضافة ميزة الـ API إلى الباقة. وعند api_not_allowed لا يستطيع التاجر التابع لشركة توصيل استخدام واجهة التاجر: طروده تمر عبر الشركة، وللشركة أن تستخدم واجهة الشركة لتجارها. وعند account_inactive يجب أن يعيد تفعيل الحساب من يديره.

4. جرّب من جديد

   استدعِ GET /me مرة أخرى. الرد 200 مع "success": true يؤكد سلامة المفتاح والباقة، ويعمل المفتاح نفسه من جديد بعد إصلاح الباقة المنتهية.

1234

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

أخطاء شائعة#

• استخدام نوع مفتاح خاطئ: مفتاح ck_ على /api/v1، أو مفتاح ستور سيريا أو ووكومرس أو سلة أو منصة مخصصة، يعطي invalid_key.
• نسيان تحديث نظامك بعد «تجديد».
• نسخ النص المقنَّع من الجدول. فالنقاط جزء منه.
• توقّع الرسالة Invalid Api Key. هذه رسالة HTTP 400 تخص واجهة تطبيقات الجوال وترويسة apiKey فيها، ولا تستخدمها هاتان الواجهتان.

متى تتواصل مع الدعم#

• عند account_inactive وأنت تعتقد أن الحساب فعّال: اسأل شركة التوصيل أو المنصة.
• عندما تقول صفحة الشركة «ما في أدمن مالك للشركة — تواصل مع الدعم.» أثناء توليد مفتاح.
• عند 500 مع server_error: اذكر قيمة reference (تبدأ بالحرف E).