مرجع API
Enterpriseادمج بيانات منظمتك مع أدوات خارجية، ومنصات تحليلات، وتطبيقات مخصصة باستخدام REST API الخاص بـ Enkelt.ai.
عنوان URL الأساسي
https://enkelt.ai/api/public/v1يجب إرسال جميع طلبات API إلى عنوان URL الأساسي هذا. HTTPS مطلوب.
نظرة عامة سريعة
توفر واجهة برمجة تطبيقات Enkelt.ai وصولاً برمجيًا إلى بيانات منظمتك. استخدمها لبناء تكاملات مخصصة، أو مزامنة البيانات مع أنظمة خارجية، أو إنشاء سير عمل آلي.
مصادقة Bearer
صادق باستخدام مفاتيح API عبر ترويسة Authorization.
معدّل محدود
الطلبات محدودة المعدل حسب الخطة. Enterprise يحصل على 1,000 طلب/دقيقة.
تنسيق JSON
تستخدم جميع الطلبات والاستجابات تنسيق JSON. ترميز UTF-8 مطلوب.
المصادقة
تتطلب جميع طلبات API مصادقة باستخدام رمز Bearer. أنشئ مفاتيح API من قسم الامتثال > مفاتيح API في لوحة التحكم الخاصة بك.
ترويسة Authorization
Authorization: Bearer sk_live_your_api_key_hereمثال على الطلب
curl -X GET "https://enkelt.ai/api/public/v1/players" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json"حافظ على أمان مفتاح API الخاص بك
تحديد المعدل
طلبات API محدودة المعدل لضمان الاستخدام العادل واستقرار النظام. تُطبَّق الحدود لكل مفتاح API وتُعاد ضبطها على أساس نافذة متجددة.
ترويسات حد المعدل
تتضمن كل استجابة ترويسات تُظهر حالة حد المعدل الحالية لديك:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1703275200نقاط النهاية المتاحة
توفر API وصولاً إلى الموارد التالية. تتطلب جميع نقاط النهاية مصادقة وتحترم الصلاحيات المخصصة لمفتاح API الخاص بك.
اللاعبون
/api/public/v1/playersعرض قائمة بجميع اللاعبين في منظمتك/api/public/v1/playersplayers:read/api/public/v1/players/{id}الحصول على لاعب معين حسب المعرّف/api/public/v1/players/{id}players:read/api/public/v1/playersإنشاء لاعب جديد/api/public/v1/playersplayers:write/api/public/v1/players/{id}تحديث لاعب موجود/api/public/v1/players/{id}players:writeالتحقق من الدور
يجب أن يكون حقل الدور دورًا صالحًا للعبة الفريق. إذا لم يتم تعيين فريق، يتم التحقق من الأدوار مقابل أدوار لعبة "أخرى".
الفرق والجدول
/api/public/v1/teamsعرض قائمة بجميع الفرق في منظمتك/api/public/v1/teamsteams:read/api/public/v1/rosterالحصول على معلومات قائمة الفريق/api/public/v1/rosterroster:read/api/public/v1/scheduleالحصول على الجدول والمباريات القادمة/api/public/v1/scheduleschedule:readالمواهب
/api/public/v1/prospectsعرض قائمة بجميع المواهب في مسارك/api/public/v1/prospectsprospects:read/api/public/v1/prospects/{id}الحصول على موهبة معينة/api/public/v1/prospects/{id}prospects:read/api/public/v1/prospectsإضافة موهبة جديدة/api/public/v1/prospectsprospects:write/api/public/v1/prospects/{id}تحديث تفاصيل الموهبة/api/public/v1/prospects/{id}prospects:writeالعقود
/api/public/v1/contractsعرض قائمة بجميع العقود/api/public/v1/contractscontracts:read/api/public/v1/contracts/{id}الحصول على تفاصيل العقد/api/public/v1/contracts/{id}contracts:read/api/public/v1/contracts/expiringالحصول على العقود التي توشك على الانتهاء/api/public/v1/contracts/expiringcontracts:readتنسيق الاستجابة
تتبع جميع استجابات API بنية JSON متسقة. تتضمن الاستجابات الناجحة البيانات والبيانات الوصفية، بينما تتضمن الأخطاء رموز الأخطاء والرسائل.
استجابة ناجحة
{
"success": true,
"data": {
"id": "player_abc123",
"ign": "TenZ",
"realName": "Tyson Ngo",
"role": "Duelist",
"teamId": "team_xyz789",
"contractStatus": "active",
"joinDate": 1705314600000
},
"meta": {
"count": 1,
"requestId": "req_xyz789",
"timestamp": "2024-01-15T10:30:00Z"
}
}استجابة خطأ
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded",
"status": 429
},
"meta": {
"requestId": "req_xyz789",
"timestamp": "2024-01-15T10:30:00Z"
}
}رموز الأخطاء
عند حدوث خطأ، تُرجع API رمز حالة HTTP مناسبًا وجسم JSON بتفاصيل الخطأ.
INVALID_API_KEY401مفتاح API مفقود أو غير صالح التنسيق
KEY_REVOKED403تم إلغاء مفتاح API
KEY_EXPIRED403انتهت صلاحية مفتاح API
INSUFFICIENT_PERMISSIONS403يفتقر مفتاح API إلى الصلاحيات المطلوبة لهذه النقطة
VALIDATION_ERROR400جسم الطلب يفتقد حقولاً مطلوبة أو يحتوي على قيم غير صالحة
INVALID_PARAMETER400معامل استعلام يحتوي على قيمة غير صالحة
INVALID_ROLE400الدور غير صالح للعبة الفريق. راجع الأدوار الصالحة لكل لعبة
RATE_LIMIT_EXCEEDED429عدد كبير جدًا من الطلبات. انتظر وأعد المحاولة
NOT_FOUND404المورد المطلوب غير موجود
INTERNAL_ERROR500حدث خطأ غير متوقع في الخادم
الصلاحيات والنطاقات
يمكن تعيين صلاحيات محددة لمفاتيح API للحد مما يمكنها الوصول إليه من بيانات. استخدم دائمًا الحد الأدنى من الصلاحيات المطلوبة لتكاملك.
players:readعرض ملفات اللاعبين وإحصاءاتهم ومعلوماتهم الأساسية
players:writeإنشاء ملفات اللاعبين وتحديثها
prospects:readعرض المواهب في مسار مواهبك
prospects:writeإضافة المواهب وتحديثها
contracts:readعرض تفاصيل العقود وتواريخ انتهائها
teams:readعرض الفرق وتفاصيلها
roster:readعرض معلومات قائمة الفريق وتعيينات اللاعبين
schedule:readعرض الجدول القادم والمباريات والأحداث
أمثلة الكود
فيما يلي أمثلة على كيفية استخدام API بلغات البرمجة الشائعة.
JavaScript / Node.js
const response = await fetch('https://enkelt.ai/api/public/v1/players', {
headers: {
'Authorization': 'Bearer sk_live_your_api_key',
'Content-Type': 'application/json'
}
});
const { data } = await response.json();
console.log(data); // Array of playersPython
import requests
response = requests.get(
'https://enkelt.ai/api/public/v1/players',
headers={
'Authorization': 'Bearer sk_live_your_api_key',
'Content-Type': 'application/json'
}
)
data = response.json()
print(data['data']) # List of playersأفضل الممارسات
- استخدم متغيرات البيئة لتخزين مفتاح API الخاص بك، ولا تكتبه مباشرة في الكود أبدًا
- طبّق التراجع الأسي (exponential backoff) عند تلقي أخطاء حد المعدل (429)
- خزّن الاستجابات مؤقتًا عند الإمكان لتقليل طلبات API
- استخدم الحد الأدنى من الصلاحيات المطلوبة لمفتاح API الخاص بك
- دوّر مفاتيح API بشكل دوري لأمان أفضل
- راقب استخدام API الخاص بك في لوحة التحكم لتجنب الوصول إلى الحدود
بحاجة إلى مساعدة؟