مفاتيح الـ API

تصادق مفاتيح الـ API تطبيقاتك مع واجهة TakeTheme البرمجية. ويشرح هذا الدليل كيفية إنشاء مفاتيحك وإدارتها وتأمينها.

توفّر الباقة

الوصول إلى الـ API متاح في باقتَي Pro وScale. وفي الباقات الأخرى لا يظهر قسم مفاتيح الـ API في لوحة التحكم وتُرفض الطلبات المُصادَقة بمفتاح.

إنشاء مفاتيح الـ API

من لوحة التحكم

1. سجّل الدخول إلى لوحة تحكم TakeTheme
2. انتقل إلى الإعدادات ← مفاتيح الـ API
3. اضغط إنشاء مفتاح جديد
4. اضبط المفتاح:
   • الاسم: اسم وصفي (مثل "خادم الإنتاج" أو "مزامنة المخزون")
   • البيئة: production أو staging أو development
   • الصلاحيات: أزواج المورد والإجراء المسموحة للمفتاح (راجع مرجع الصلاحيات)
   • قائمة عناوين IP المسموحة (اختياري): قصر الاستخدام على عناوين محددة
   • تاريخ الانتهاء / حد الاستخدام (اختياري): إنهاء المفتاح تلقائيًا في تاريخ معين، أو تحديد سقف لعدد طلباته
5. اضغط إنشاء المفتاح
6. انسخ مفتاحك فورًا — فلن يُعرض مرة أخرى

مهم

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

بنية المفتاح

tt_{64_character_hex_string}

الجزء	الوصف	الطول
tt_	بادئة TakeTheme	3
{64_character_hex_string}	سلسلة ست عشرية عشوائية تشفيريًا	64

مثال:

tt_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

وبعد الإنشاء، لا تُعرض سوى آخر 4 أحرف فقط.

إدارة المفاتيح

عرض المفاتيح

في لوحة التحكم ترى لكل مفتاح: الاسم والبيئة وتاريخ الإنشاء وآخر استخدام وإجمالي عدد الاستخدامات والصلاحيات وقيود عناوين IP — دون السر نفسه أبدًا.

تدوير المفاتيح

يُصدر التدوير سرًا جديدًا للمفتاح نفسه مع بقاء السر القديم صالحًا لـفترة سماح قصيرة، فتنقل تطبيقك دون أي انقطاع:

1. دوّر المفتاح (من لوحة التحكم أو عبر POST /api-key/{keyId}/rotate)
2. حدّث تطبيقك إلى السر الجديد
3. يتوقف السر القديم عن العمل بانتهاء فترة السماح (API_KEY_GRACE_PERIOD_EXPIRED)

إبطال المفاتيح

الإبطال يعطّل المفتاح (POST /api-key/{keyId}/revoke)، والحذف يزيله نهائيًا (DELETE /api-key/{keyId}). وتستقبل التطبيقات التي تستخدم مفتاحًا مُبطلًا الخطأ 401 API_KEY_REVOKED.

خطر

يسري الإبطال فورًا (مع مراعاة أي فترة سماح تُضبط وقت الإبطال). تأكد من عدم وجود عملية حرجة ما زالت تستخدم المفتاح.

الصلاحيات والأذونات

صلاحيات المفتاح مصفوفة من أزواج المورد والإجراءات:

{
  "scopes": [
    { "resource": "PRODUCTS", "actions": ["READ", "WRITE", "UPDATE"] },
    { "resource": "ORDERS", "actions": ["READ"] }
  ]
}

والإجراءات المتاحة هي READ وWRITE (إنشاء) وUPDATE وDELETE. والموارد المتاحة:

ANALYTICS، BILLING، BLOGS، CATEGORIES، COUPONS، CUSTOMERS، DISCOUNTS، DOMAINS، INTEGRATION، MARKETING، ORDERS، PRODUCTS، REVIEWS، SECRETS، SEGMENTS، STAFF، STORE_SETTINGS، SUPPORT، THEME، UPSELLS، API_KEYS

راجع مرجع الصلاحيات لمعرفة الصلاحية التي يتطلبها كل عنوان.

أفضل الممارسات

استخدم أسماء وصفية

✓ "Production Web Server"
✓ "Staging Environment"
✓ "Inventory Sync Service"

✗ "Key 1"
✗ "Test"

طبّق مبدأ أقل امتياز

امنح التكامل الصلاحيات التي يحتاجها فقط:

// ✓ Good: an inventory sync needs products only
{ "scopes": [{ "resource": "PRODUCTS", "actions": ["READ", "UPDATE"] }] }

// ✗ Bad: granting every resource with every action "just in case"

افصل المفاتيح حسب البيئة

البيئة	الاستخدام
development	التطوير والاختبار المحلي
staging	بيئة ما قبل الإنتاج
production	الإنتاج الحيّ ببيانات العملاء

احفظ المفاتيح بأمان

# ✓ Good: environment variable
export TAKETHEME_API_KEY=tt_xxx

# ✗ Bad: hardcoded in source code

راقب استخدام المفاتيح

يتتبع كل مفتاح lastUsedAt وإجمالي عدد الاستخدامات مجمّعًا يوميًا. راجعهما من لوحة التحكم أو عبر GET /api-key/stats، وانتبه للمفاتيح غير المستخدمة (مرشّحة للإبطال) أو المزدحمة بشكل غير متوقع.

إدارة المفاتيح برمجيًا

يمكن للمفاتيح إدارة المفاتيح — وتتطلب هذه العناوين صلاحية API_KEYS. لاحظ أن البادئة بصيغة المفرد /api-key:

الأسلوب	المسار	الإجراء المطلوب
GET	/api-key	READ
GET	/api-key/stats	READ
GET	/api-key/{keyId}	READ
POST	/api-key	WRITE
PATCH	/api-key/{keyId}	UPDATE
POST	/api-key/{keyId}/revoke	UPDATE
POST	/api-key/{keyId}/rotate	WRITE
DELETE	/api-key/{keyId}	DELETE

إنشاء مفتاح

curl -X POST "https://api.taketheme.com/api/v1/api-key" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "New Integration Key",
    "environment": "production",
    "scopes": [
      { "resource": "PRODUCTS", "actions": ["READ"] },
      { "resource": "ORDERS", "actions": ["READ"] }
    ]
  }'

عرض المفاتيح

curl -X GET "https://api.taketheme.com/api/v1/api-key" \
  -H "tt-api-key: tt_xxx"

إبطال مفتاح

curl -X POST "https://api.taketheme.com/api/v1/api-key/{keyId}/revoke" \
  -H "tt-api-key: tt_xxx"

اقرأ أيضًا

• دليل المصادقة
• مرجع الصلاحيات
• حدود المعدل
• معالجة الأخطاء