رموز API

نظرة عامة

توفر رموز API مصادقة آمنة للتطبيقات والتكاملات الخارجية للوصول إلى واجهة برمجة التطبيقات الخاصة بمتجر Trinavo. تتيح لك هذه الميزة إنشاء وإدارة وإلغاء رموز API مع تحكم دقيق في الصلاحيات.

الغرض

• مصادقة API: مصادقة آمنة للتطبيقات والخدمات الخارجية
• دعم التكامل: تمكين تكاملات الطرف الثالث مع متجرك
• صلاحيات دقيقة: التحكم في ما يمكن لكل رمز الوصول إليه من خلال صلاحيات قائمة على القدرات
• رموز خاصة بالمستخدم: ربط الرموز بمستخدمين محددين للمساءلة
• إدارة الرموز: إنشاء وعرض وإلغاء الرموز حسب الحاجة
• التحكم الأمني: مراقبة استخدام الرموز وإلغاء الرموز المخترقة فورًا

الوصول إلى رموز API

انقر على الأقسام ← إدارة المستخدمين ← رموز API

شارة التنقل

يعرض عنصر قائمة رموز API شارة تُظهر إجمالي عدد الرموز النشطة في النظام. يشير لون الشارة إلى الحالة:

• أخضر: يوجد رمز واحد أو أكثر
• رمادي: لا توجد رموز

عرض القائمة

يعرض عرض القائمة جميع رموز API في النظام. إذا لم توجد رموز، سترى رسالة "لا توجد رموز API".

أعمدة الجدول

• المستخدم: حساب المستخدم الذي ينتمي إليه هذا الرمز (قابل للبحث، قابل للفرز، يعرض البريد الإلكتروني كوصف)
• اسم الرمز: اسم وصفي للرمز (قابل للبحث، قابل للفرز، يُعرض بخط عريض)
• الرمز: قيمة الرمز الفعلية (تُعرض دائمًا كـ •••••••••••••••• للأمان)
• مهم: قيمة الرمز مرئية مرة واحدة فقط عند الإنشاء لأول مرة
• لا يمكن نسخها من عرض القائمة
• إذا فُقدت، يجب إلغاء الرمز وإنشاء رمز جديد
• الصلاحيات: الأذونات الممنوحة لهذا الرمز (تُعرض كشارات خضراء، مفصولة بفواصل)
• آخر استخدام: متى تم استخدام الرمز آخر مرة للوصول إلى API (تاريخ ووقت مع وقت نسبي مثل "منذ ساعتين"، قابل للفرز)
• يُظهر "أبدًا" إذا لم يُستخدم الرمز مطلقًا
• تاريخ الإنشاء: متى تم إنشاء الرمز (تاريخ ووقت مع وقت نسبي، قابل للفرز، مرئي دائمًا)
• ينتهي: تاريخ انتهاء صلاحية الرمز (تاريخ ووقت، مخفي افتراضيًا، يمكن تبديل الرؤية)
• يُظهر "أبدًا" إذا لم يتم تعيين تاريخ انتهاء
• حاليًا، لا تنتهي صلاحية الرموز افتراضيًا

الفرز الافتراضي

يتم فرز الرموز حسب تاريخ الإنشاء بترتيب تنازلي (الرموز الأحدث أولاً).

وظيفة البحث

استخدم مربع البحث للعثور على الرموز حسب:

• اسم المستخدم
• بريد المستخدم الإلكتروني
• اسم الرمز

الفلاتر

انقر على زر تصفية للوصول إلى خيارات التصفية هذه:

فلتر المستخدم

• تصفية الرموز حسب مستخدم محدد
• قائمة منسدلة قابلة للبحث تعرض ما يصل إلى 100 مستخدم
• يعرض فقط الرموز التي تنتمي للمستخدم المحدد

الرموز المستخدمة فقط

• تبديل لعرض الرموز التي تم استخدامها مرة واحدة على الأقل فقط
• يُصفي حسب الرموز حيث last_used_at ليس null
• مفيد لتدقيق التكاملات النشطة

لم تُستخدم أبدًا

• تبديل لعرض الرموز التي لم تُستخدم أبدًا فقط
• يُصفي حسب الرموز حيث last_used_at هو null
• مفيد لتحديد الرموز غير المستخدمة/المنسية

إجراءات الصف

يحتوي كل صف رمز على أزرار الإجراءات التالية:

إلغاء

• الوظيفة: يحذف الرمز بشكل دائم
• تحذير: هذا الإجراء لا يمكن التراجع عنه
• التأثير: يصبح الرمز غير صالح فورًا ولا يمكن استخدامه لطلبات API
• حالة الاستخدام: إلغاء الرموز المخترقة، إزالة الوصول للتكاملات المنتهية

عرض

• الوظيفة: يفتح نافذة مشروطة مع معلومات مفصلة عن الرمز
• حالة الاستخدام: مراجعة إعداد الرمز دون تحرير

الإجراءات الجماعية

حدد رموز متعددة باستخدام مربعات الاختيار، ثم اختر من:

إلغاء المحدد

• العنوان: "إلغاء المحدد"
• الوظيفة: حذف رموز متعددة دفعة واحدة
• تحذير: هذا الإجراء لا يمكن التراجع عنه
• التأكيد: يعرض مربع حوار تأكيد قبل الحذف
• حالة الاستخدام: تنظيف رموز متعددة غير مستخدمة، إلغاء الوصول لتكاملات متعددة

إنشاء رموز API

أنشئ رموز API جديدة لتمكين التطبيقات والخدمات الخارجية من الوصول إلى API متجرك.

تفاصيل الرمز

المستخدم مطلوب

• النوع: قائمة منسدلة قابلة للبحث
• الوظيفة: اختيار حساب المستخدم الذي ينتمي إليه هذا الرمز
• البحث: البحث حسب اسم المستخدم أو البريد الإلكتروني
• صيغة العرض: "اسم المستخدم (email@example.com)"
• الحد: يعرض ما يصل إلى 50 نتيجة لكل بحث
• التحقق: حقل مطلوب
• الغرض: ربط الرمز بمستخدم للمساءلة والصلاحيات

مهم: سيرث الرمز أي قيود على مستوى المستخدم. اختر حساب المستخدم المناسب بناءً على ما يحتاج التكامل للوصول إليه.

اسم الرمز مطلوب

• النوع: إدخال نص
• الوظيفة: اسم وصفي لتحديد هذا الرمز
• التحقق: مطلوب، بحد أقصى 255 حرفًا
• العنصر النائب: "رمز API الخاص بي"
• نص المساعدة: "اسم وصفي لهذا الرمز"
• أمثلة:
• "تكامل تطبيق الجوال"
• "مزامنة Shopify"
• "لوحة التحليلات"
• "نظام إدارة المستودعات"
• "أداة أتمتة التسويق"

أفضل الممارسات: استخدم أسماء واضحة ووصفية تشير إلى غرض التكامل والبيئة (مثل "مزامنة Shopify - الإنتاج" مقابل "مزامنة Shopify - التجريب").

الصلاحيات / الأذونات مطلوب

• النوع: قائمة منسدلة متعددة الاختيار
• الوظيفة: تحديد العمليات التي يمكن لهذا الرمز تنفيذها
• التحقق: مطلوب، يجب تحديد صلاحية واحدة على الأقل
• الافتراضي: وصول كامل (*)
• نص المساعدة: "اختر ما يمكن لهذا الرمز فعله. '⭐ وصول كامل' يعني الوصول الكامل لجميع نقاط النهاية."
• تلميح: "حدد إذنًا واحدًا أو أكثر"

الصلاحيات المتاحة:

الوصول الكامل

• ⭐ وصول كامل (جميع الصلاحيات) (*)
• يمنح وصولاً كاملاً لجميع نقاط نهاية API
• يشمل جميع عمليات القراءة والكتابة والحذف
• استخدم بحذر - فقط للتكاملات الموثوقة
• لا يمكن دمجه مع صلاحيات أخرى (اختيار هذا يتجاوز جميع الصلاحيات الأخرى)

صلاحيات التصنيفات

• 📁 التصنيفات: قراءة فقط (GET) (categories:read)
• عرض قوائم التصنيفات وتفاصيلها
• لا يمكن إنشاء أو تحديث أو حذف التصنيفات

• آمن لأدوات التحليلات والتقارير

• 📝 التصنيفات: إنشاء وتحديث (POST, PUT, PATCH) (categories:write)

• إنشاء تصنيفات جديدة
• تحديث التصنيفات الموجودة
• لا يشمل إذن الحذف

• يتطلب categories:read لمعظم حالات الاستخدام العملية

• 🗑️ التصنيفات: حذف (DELETE) (categories:delete)

• حذف التصنيفات
• صلاحية عالية المخاطر - استخدم بحذر
• ضع في الاعتبار التأثير على المنتجات في التصنيفات المحذوفة

صلاحيات المنتجات

• 👁️ المنتجات: قراءة فقط (GET) (items:read)
• عرض قوائم المنتجات وتفاصيلها
• الوصول إلى معلومات المخزون

• آمن لتكاملات العرض (تطبيقات الجوال، أنظمة نقاط البيع)

• ✏️ المنتجات: إنشاء وتحديث (POST, PUT, PATCH) (items:write)

• إنشاء منتجات جديدة
• تحديث تفاصيل المنتج والأسعار والمخزون
• لا يشمل إذن الحذف

• شائع لتكاملات إدارة المخزون

• 🗑️ المنتجات: حذف (DELETE) (items:delete)

• حذف المنتجات
• صلاحية عالية المخاطر
• قد يؤثر على الطلبات والمراجع الأخرى

صلاحيات الطلبات

• 📋 الطلبات: قراءة فقط (GET) (orders:read)
• عرض قوائم الطلبات وتفاصيلها
• الوصول إلى سجل طلبات العملاء

• شائع لتكاملات التقارير والتحليلات

• 📝 الطلبات: إنشاء (POST) (orders:write)

• إنشاء طلبات جديدة
• مفيد لأنظمة نقاط البيع وقنوات المبيعات الخارجية
• ملاحظة: عادة لا يمكن تحديث أو حذف الطلبات لأسباب أمنية/تدقيق

إجراءات النموذج

إنشاء

• ينشئ الرمز ويعرض قيمة الرمز مرة واحدة فقط
• يُظهر إشعار نجاح مع الرمز المُنشأ
• حرج: انسخ واحفظ الرمز فورًا - لا يمكن استرجاعه مرة أخرى
• يعود إلى عرض القائمة
• يصبح الرمز نشطًا فورًا

إلغاء

• يتجاهل النموذج ويعود إلى عرض القائمة
• لا يتم إنشاء أي رمز

ملاحظات أمنية مهمة

أمان قيمة الرمز

تُعرض قيمة الرمز مرة واحدة فقط عند الإنشاء لأول مرة.

• بعد الإنشاء، سترى إشعارًا أو نافذة مشروطة مع قيمة الرمز الكاملة
• انسخها واحفظها فورًا - لا يمكنك استرجاعها مرة أخرى
• إذا فُقدت، يجب إلغاء الرمز وإنشاء رمز جديد
• في عرض القائمة، تُقنّع الرموز دائمًا كـ ••••••••••••••••
• هذه ميزة أمنية حرجة لمنع سرقة الرموز

أفضل ممارسات تخزين الرموز

أين تخزن الرموز:

• ✅ متغيرات البيئة في تطبيقك (ملف .env)
• ✅ أنظمة إدارة الأسرار الآمنة (AWS Secrets Manager, HashiCorp Vault)
• ✅ ملفات التكوين المشفرة
• ❌ لا تقم أبدًا بإضافة الرموز إلى التحكم في الإصدار
• ❌ لا تقم أبدًا بالتخزين في ملفات نصية عادية
• ❌ لا تقم أبدًا بالمشاركة عبر البريد الإلكتروني أو الدردشة

الاستجابة لاختراق الرمز

إذا تم اختراق رمز:

1. ألغِ فورًا الرمز المخترق
2. أنشئ رمزًا جديدًا ببيانات اعتماد مختلفة
3. حدّث تكاملك بالرمز الجديد
4. راجع سجلات وصول API للاستخدام غير المصرح به
5. فكر في إلغاء جميع رموز المستخدم المتأثر إذا لم تكن متأكدًا

كيف تعمل رموز API

تدفق المصادقة

1. إنشاء الرمز: إنشاء رمز بصلاحيات محددة
2. التخزين الآمن: حفظ الرمز في التخزين الآمن لتطبيقك
3. طلب API: تضمين الرمز في ترويسة الطلب: Authorization: Bearer {your-token}
4. فحص الصلاحية: يتحقق API من صحة الرمز ويتحقق مما إذا كان الإجراء المطلوب مسموحًا به
5. الاستجابة: يعالج API الطلب ويُرجع الاستجابة

نموذج الصلاحيات

تستخدم الرموز نظام صلاحيات قائم على القدرات:

• حرف البدل (*): يمنح جميع الصلاحيات
• صلاحيات مساحة الاسم: يتم تجميع الصلاحيات حسب المورد (التصنيفات، المنتجات، الطلبات)
• أنواع العمليات:
• read: طلبات GET (عرض البيانات)
• write: طلبات POST, PUT, PATCH (إنشاء/تحديث البيانات)
• delete: طلبات DELETE (إزالة البيانات)
• تراكمي: يمكن تحديد صلاحيات متعددة للوصول المختلط
• يُفحص في كل طلب: كل طلب API يتحقق من قدرات الرمز

أمثلة على مجموعات الصلاحيات:

• تكامل للقراءة فقط (لوحة التحليلات):
• categories:read
• items:read

• orders:read

• إدارة المخزون:

• items:read

• items:write

• إدارة المنتجات الكاملة:

• items:read
• items:write
• items:delete
• categories:read
• categories:write

تتبع استخدام الرمز

يتتبع النظام متى يُستخدم كل رمز:

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

حالات الاستخدام

مثال 1: تكامل تطبيق الجوال

• اسم الرمز: "تطبيق iOS للجوال - الإنتاج"
• المستخدم: حساب خدمة التطبيق
• الصلاحيات:
• items:read (تصفح المنتجات)
• categories:read (تصفح التصنيفات)
• orders:write (إنشاء الطلبات)
• orders:read (عرض سجل الطلبات)
• الغرض: السماح لتطبيق الجوال بعرض المنتجات وتقديم الطلبات

مثال 2: نظام مزامنة المخزون

• اسم الرمز: "نظام إدارة المستودعات - المزامنة"
• المستخدم: حساب مدير المخزون
• الصلاحيات:
• items:read (التحقق من المخزون الحالي)
• items:write (تحديث مستويات المخزون)
• الغرض: الحفاظ على مزامنة المخزون بين الأنظمة

مثال 3: منصة التحليلات

• اسم الرمز: "لوحة ذكاء الأعمال"
• المستخدم: حساب خدمة التحليلات
• الصلاحيات:
• orders:read (تحليل بيانات المبيعات)
• items:read (أداء المنتج)
• categories:read (تحليل التصنيفات)
• الغرض: وصول للقراءة فقط للتقارير والتحليلات

مثال 4: قناة مبيعات خارجية

• اسم الرمز: "تكامل Shopify"
• المستخدم: حساب خدمة التكامل
• الصلاحيات:
• ⭐ وصول كامل (*) أو مجموعة فرعية محددة بناءً على مستوى الثقة
• الغرض: مزامنة المنتجات والطلبات والمخزون بين المنصات

مثال 5: التطوير/الاختبار

• اسم الرمز: "بيئة التطوير - الاختبار"
• المستخدم: حساب المطور
• الصلاحيات: * (وصول كامل للاختبار)
• الغرض: اختبار وظائف API أثناء التطوير
• ملاحظة: ألغِ بعد اكتمال التطوير

الأقسام ذات الصلة

• المستخدمون - مالكو رموز API
• الأدوار - إدارة الصلاحيات