المصادقة
- Authorization: ApiKey
- يُرسل مفتاح API حصريًا في ترويسة Authorization لطلب POST /api/v1/auth/token. لا تضعه في JSON أو عنوان URL أو معاملات الاستعلام.
- Authorization: Bearer
- استخدم الرمز المعاد لطلبات الموارد، وجدده وفق expires_at؛ تُعبّر expires_in عن المدة بالثواني.
لماذا نحصل على رمز وصول أولًا؟
يُستخدم مفتاح API للحصول على رمز وصول. يكون الرمز صالحًا لمدة 15 دقيقة ويمكن استخدامه لطلبات متعددة. أرسل الرمز فقط إلى الموارد في الترويسة Authorization: Bearer.
لا تحتوي الطلبات العادية على مفتاح API. إذا تسرّب الرمز وحده، فلا يتيح الوصول بعد انتهاء صلاحيته. أما سرقة مفتاح API فقد تظل تسمح بالحصول على رموز جديدة.
ما مدة صلاحية الرمز؟
- expires_in
- 900 ثانية، أي 15 دقيقة من وقت الإصدار. إرسال الطلبات لا يمدد الصلاحية.
- expires_at
- وقت انتهاء الصلاحية بتوقيت UTC. قد تمنع قيود الوصول الحالية استخدام الرمز قبل ذلك.
متى تحصل على رمز جديد؟
أعد استخدام الرمز نفسه لطلبات متعددة واحصل على رمز جديد قبل expires_at. لا تطلب رمزًا قبل كل عملية. استخدم مفتاح API للحصول على الرمز الجديد.
رفض الوصول وإعادة المحاولة
- 401
- لا يعني 401 دائمًا انتهاء صلاحية الرمز. إذا انتهت صلاحيته، احصل على رمز جديد وأعد طلب القراءة مرة واحدة كحد أقصى. إذا أعاد طلب الرمز 401، فتحقق من المفتاح وأوقف المحاولات التلقائية.
- 403
- عند ظهور 403، تحقق من الصلاحيات وقيود IP والخطة. الحصول على رمز جديد لا يعيد الوصول الذي تم إلغاؤه.
قيود IP
- لا يتجاوز رمز الوصول التحقق من صلاحيات المفتاح الحالية أو استحقاقات المتجر أو إلغاء المفتاح أو قيود IP.
- قيّد المفتاح بعناوين مصدر التكامل عند الحاجة.
- يمكن للمسؤول تعديل هذه القائمة؛ والحد الأقصى المقبول هو 32 عنوانًا.
إدارة المفاتيح
- إدارة مفاتيح API مستقلة عن صلاحيات التكامل على الموارد.
- وحده owner يستطيع منح المجموعات الصلاحيات الإدارية لعرض المفاتيح أو إنشائها أو تعديلها أو حذفها؛ ولا يستطيع عضو المجموعة المخوّل إلا تنفيذ الإجراءات الممنوحة لمجموعته.
حدود معدل الطلبات
Engine ≥ 4.143.0. تتضمن كل استجابة للرمز data.rate_limits من سياسة المتجر وقت إصداره. تتشارك جميع المفاتيح هذه الحدود؛ إصدار رمز جديد لا يعيد ضبطها. قد يسري تغيير الخطة قبل انتهاء صلاحية الرمز.
- read_per_minute
- طلبات القراءة في الدقيقة.
- write_per_minute
- طلبات الكتابة في الدقيقة؛ لا تمنح هذه القيمة صلاحيات الكتابة.
- auth_per_minute
- طلبات الرمز في الدقيقة، بما فيها محاولات المصادقة الفاشلة.