رموز واجهة البرمجة (API Tokens)¶

نظرة عامة¶

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

الغرض¶

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

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

انتقل إلى: إدارة المستخدمين > رموز API من الشريط الجانبي

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

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

عرض القائمة¶

قائمة رموز API

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

أعمدة الجدول¶

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

الترتيب الافتراضي¶

تُرتب الرموز حسب تاريخ الإنشاء ترتيبًا تنازليًا بحيث تظهر الأحدث أولًا.

وظيفة البحث¶

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

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

الفلاتر¶

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

تصفية حسب المستخدم¶

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

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

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

لم تُستخدم مطلقًا¶

تبديل لعرض الرموز التي لم تُستخدم قط
يعتمد على أن last_used_at فارغ
مفيد لتحديد الرموز غير المستخدمة أو المنسية

إجراءات الصف¶

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

إبطال¶

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

عرض¶

الوظيفة: فتح نافذة منبثقة تعرض تفاصيل الرمز
الاستخدام: مراجعة إعدادات الرمز دون تعديلات

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

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

إبطال المحدد¶

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

إنشاء رموز API¶

إنشاء رمز API

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

تفاصيل الرمز¶

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

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

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

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

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

أفضل ممارسة: استخدم أسماء واضحة تشير إلى غرض التكامل وبيئته مثل "Shopify Sync - Production" مقابل "Shopify Sync - Staging".

القدرات / الأذونات مطلوب¶

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

الأذونات المتاحة:

وصول كامل¶

⭐ وصول كامل (كل الأذونات) (*)
يمنح وصولًا كاملًا إلى جميع نقاط نهاية 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)
✅ ملفات إعدادات مُشفرة
❌ عدم رفع الرموز إلى أنظمة التحكم بالإصدارات
❌ عدم حفظها في ملفات نصية عادية
❌ عدم مشاركتها عبر البريد أو الدردشة

التعامل مع اختراق رمز¶

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

أبطِل الرمز المخترق فورًا
أنشئ رمزًا جديدًا ببيانات مختلفة
حدّث التكامل لاستخدام الرمز الجديد
راجع سجلات الوصول للبحث عن استخدام غير مصرح
فكّر في إبطال جميع رموز المستخدم المتأثر إذا لزم الأمر

كيفية عمل رموز API¶

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

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

نموذج الأذونات¶

تستخدم الرموز نظام أذونات قائمًا على القدرات:

الوايلدكارد (*): يمنح كل الأذونات
مساحات أسماء: تُجمع الأذونات حسب المورد (التصنيفات والعناصر والطلبات)
أنواع العمليات:
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 Mobile App - Production"
المستخدم: حساب خدمة التطبيق
القدرات:
items:read (تصفح المنتجات)
categories:read (تصفح التصنيفات)
orders:write (إنشاء الطلبات)
orders:read (عرض السجل)
الغرض: تمكين تطبيق الجوال من عرض المنتجات وإنشاء الطلبات

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

اسم الرمز: "Warehouse Management System - Sync"
المستخدم: حساب مدير المخزون
القدرات:
items:read (التحقق من المخزون الحالي)
items:write (تحديث مستويات المخزون)
الغرض: إبقاء المخزون متزامنًا بين الأنظمة

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

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

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

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

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

اسم الرمز: "Development Environment - Testing"
المستخدم: حساب المطوّر
القدرات: * (وصول كامل لأغراض الاختبار)
الغرض: اختبار وظائف API أثناء التطوير
ملاحظة: يُنصح بإبطال الرمز بعد انتهاء الاختبارات

المستخدمون - مالكو رموز API
الأدوار - إدارة الأذونات