المصادقة

تصادق واجهة TakeTheme البرمجية الطلبات باستخدام مفاتيح API. ويجب أن يحمل كل طلب مفتاحك بإحدى طريقتين:

tt-api-key: tt_YOUR_API_KEY

أو كرمز Bearer قياسي:

Authorization: Bearer tt_YOUR_API_KEY

والطريقتان متكافئتان، ويُفضَّل tt-api-key لأنه لا يتعارض مع أنظمة تفويض أخرى.

صيغة المفتاح

تبدو المفاتيح على شكل tt_ متبوعًا بسلسلة ست عشرية من 64 حرفًا. وإذا لم يبدأ مفتاحك بـ tt_، ترفضه الواجهة بالخطأ INVALID_API_KEY_FORMAT قبل أي عملية بحث.

OAuth لخادم MCP وحده

يقبل خادم MCP إضافةً إلى ذلك رموز وصول OAuth 2.1، فيستطيع مساعد ذكي الاتصال بمتجر دون أن يتداول أحد مفتاحًا — راجع OAuth. وهذه الرموز مقيّدة بجمهور /mcp؛ وتقديم أحدها لأي مسار REST في هذه الصفحة يُرجع 403 ACCESS_DENIED. أما الـ REST API فبمفاتيح API فقط.

إرسال طلبات مُصادَقة

cURL

curl -X GET "https://api.taketheme.com/api/v1/product" \
  -H "tt-api-key: $TAKETHEME_API_KEY" \
  -H "Content-Type: application/json"

JavaScript (Axios)

import axios from "axios";

const client = axios.create({
  baseURL: "https://api.taketheme.com/api/v1",
  headers: {
    "tt-api-key": process.env.TAKETHEME_API_KEY,
    "Content-Type": "application/json",
  },
});

const response = await client.get("/product");
const data = response.data;

Python

import requests
import os

headers = {
    'tt-api-key': os.environ.get('TAKETHEME_API_KEY'),
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.taketheme.com/api/v1/product',
    headers=headers
)

data = response.json()

‏.NET

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.BaseAddress = new Uri("https://api.taketheme.com/api/v1/");
client.DefaultRequestHeaders.Add("tt-api-key", Environment.GetEnvironmentVariable("TAKETHEME_API_KEY"));

var response = await client.GetAsync("product");
var data = await response.Content.ReadAsStringAsync();

الصلاحيات

يحمل كل مفتاح API قائمة صلاحيات — أزواجًا من مورد والإجراءات المسموحة عليه:

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

وتقابل الإجراءات دلالات HTTP: READ (GET) وWRITE (POST) وUPDATE (PATCH/PUT) وDELETE (DELETE). ويعلن كل عنوان عن زوج (مورد، إجراء) واحد مطلوب؛ فإن لم يملكه مفتاحك فشل الطلب بالخطأ 403 INSUFFICIENT_SCOPE.

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

أقل امتياز ممكن

امنح التكامل الصلاحيات التي يحتاجها فقط. فمزامنة التجهيز تحتاج ORDERS:READ وORDERS:UPDATE — لا PRODUCTS:DELETE.

البيئات

يُنشأ كل مفتاح لبيئة واحدة: production أو staging أو development. استخدم مفاتيح منفصلة لكل بيئة حتى لا يمسّ مفتاح تطوير مسرَّب بيانات الإنتاج أبدًا.

قائمة عناوين IP المسموحة

يمكنك تقييد المفتاح بعناوين IP محددة. وعند ضبط قائمة مسموحة، تُرفض الطلبات من أي عنوان آخر بالخطأ 403 IP_NOT_WHITELISTED.

1. اذهب إلى لوحة التحكم ← الإعدادات ← مفاتيح الـ API
2. افتح المفتاح الذي تريد تقييده
3. أضف عناوين IP المسموحة (بمطابقة تامة) أو نطاقات بصيغة CIDR
4. احفظ

أخطاء المصادقة

تستخدم الأخطاء الغلاف القياسي — راجع معالجة الأخطاء:

{
  "status": 401,
  "message": "API key not found or has been revoked"
}

الرمز	الشيفرة	المعنى
401	API_KEY_REQUIRED	لا يوجد مفتاح في ترويسة tt-api-key أو Authorization
401	INVALID_API_KEY_FORMAT	المفتاح لا يبدأ بـ tt_ أو أقصر من اللازم
401	INVALID_API_KEY	المفتاح غير موجود أو فشل التحقق من بصمته
401	API_KEY_REVOKED	أُبطل المفتاح (وانتهت أي فترة سماح)
401	API_KEY_INACTIVE	المفتاح مُعطَّل
401	API_KEY_EXPIRED	تجاوز المفتاح تاريخ expiresAt
401	API_KEY_GRACE_PERIOD_EXPIRED	استُخدم مفتاح مدوَّر أو مُبطل بعد انتهاء نافذة السماح
402	STORE_SUSPENDED	المتجر الذي يتبعه المفتاح موقوف
403	INSUFFICIENT_SCOPE	المفتاح لا يملك صلاحية (مورد، إجراء) التي يتطلبها العنوان
403	IP_NOT_WHITELISTED	الطلب من عنوان IP خارج قائمة المفتاح المسموحة
429	API_KEY_USAGE_LIMIT_REACHED	استُنفدت حصة الاستخدام الإجمالية للمفتاح

أفضل الممارسات الأمنية

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

# .env file
TAKETHEME_API_KEY=tt_abc123...

الخطوات التالية

• إنشاء مفاتيح الـ API وإدارتها
• OAuth لعملاء MCP
• مرجع الصلاحيات
• فهم حدود المعدل
• التعامل مع الأخطاء بسلاسة