مصادقة API

تستخدم وقتي مصادقة قائمة على الرموز المميزة (tokens) لجميع طلبات API. يشرح هذا الدليل كيفية المصادقة وإدارة رموز API.

نظرة عامة

تتطلب جميع نقاط نهاية API المصادقة باستخدام Bearer token. ترتبط الرموز بالمستأجر (tenant) الخاص بك ويمكن إنشاؤها وإدارتها وإلغاؤها من لوحة الإعدادات.

الحصول على رمز API

عبر واجهة الإعدادات

1. انتقل إلى الإعدادات ← إعدادات API
2. انقر إنشاء رمز جديد
3. أدخل اسمًا وصفيًا للرمز (مثل «تكامل ERP»)
4. اختر الصلاحيات/النطاقات المناسبة
5. انقر إنشاء
6. مهم: انسخ الرمز فورًا. يُعرض مرة واحدة فقط.

عبر API (إذا كان لديك رمز قائم)

POST /api/v1/tokens
Authorization: Bearer {existing_token}
Content-Type: application/json

{
  "name": "New Token Name",
  "abilities": ["read", "write"]
}

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

أدرج الرمز في ترويسة Authorization لكل طلب:

curl -X GET "https://acme.waqti.sa/api/v1/purchase-orders" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

نطاقات الرمز / الصلاحيات (Abilities)

يمكن إنشاء الرموز بصلاحيات محدودة:

الصلاحية	الوصف
read	وصول للقراءة فقط لجميع الموارد
write	إنشاء الموارد وتحديثها
delete	حذف الموارد
approve	الموافقة على العناصر أو رفضها
admin	وصول إداري كامل

مثال: رمز للقراءة فقط

{
  "name": "Reporting Integration",
  "abilities": ["read"]
}

مثال: رمز بوصول كامل

{
  "name": "ERP Sync",
  "abilities": ["read", "write", "delete"]
}

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

تنبيه أمني

تمنح رموز API وصولًا إلى بيانات المشتريات. التزم بما يلي:

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

إلغاء الرموز

عبر واجهة الإعدادات

1. انتقل إلى الإعدادات ← إعدادات API
2. اعثر على الرمز في القائمة
3. انقر إلغاء
4. أكّد الإجراء

عبر API

DELETE /api/v1/tokens/{token_id}
Authorization: Bearer {admin_token}

تحديد معدل الطلبات (Rate Limiting)

تُقيّد طلبات API حسب خطة الاشتراك:

الخطة	طلبات/دقيقة	طلبات/يوم
Professional	60	10,000
Enterprise	120	50,000
Ultimate	300	غير محدود

عند تجاوز الحد، تتلقى استجابة 429 Too Many Requests مع ترويسات توضح متى يمكن إعادة المحاولة:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000

استجابات الأخطاء

401 Unauthorized

رمز مفقود أو غير صالح:

{
  "message": "Unauthenticated.",
  "errors": {
    "token": ["Invalid or expired token"]
  }
}

403 Forbidden

الرمز لا يملك الصلاحية المطلوبة:

{
  "message": "This action is unauthorized.",
  "errors": {
    "ability": ["Token does not have 'write' ability"]
  }
}

انتهاء صلاحية الرمز

بشكل افتراضي، لا تنتهي صلاحية الرموز. ومع ذلك، يمكنك تعيين تاريخ انتهاء عند الإنشاء:

{
  "name": "Temporary Access",
  "abilities": ["read"],
  "expires_at": "2025-03-01T00:00:00Z"
}

اختبار الرمز

استخدم نقطة النهاية التالية للتحقق من صلاحية الرمز:

curl -X GET "https://acme.waqti.sa/api/v1/me" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

الاستجابة المتوقعة:

{
  "data": {
    "tenant_id": "acme-corp",
    "tenant_name": "ACME Corporation",
    "token_name": "ERP Integration",
    "abilities": ["read", "write"],
    "last_used_at": "2025-01-15T10:30:00Z"
  }
}