REST API v1

توثيق واجهة البرمجة

ادمج قدرات فحص فحص مباشرةً في تطبيقاتك.

البدء

واجهة برمجة فحص من نوع RESTful تُرجع استجابات JSON. جميع النقاط تتطلب مصادقة عبر رموز JWT حاملة. الرابط الأساسي:

https://api.fahs.com

المصادقة

احصل على رمز مصادقة بتبادل مفتاح واجهة البرمجة الخاص بك في نقطة المصادقة. أضف الرمز في ترويسة Authorization مع كل طلب.

مسار المصادقة

1١. احصل على مفتاح واجهة البرمجة من لوحة التحكم ← الإعدادات ← مفاتيح واجهة البرمجة
2٢. استبدل مفتاح واجهة البرمجة برمز مصادقة عبر POST /auth/token
3٣. أضف رمز المصادقة كـ Authorization: Bearer YOUR_TOKEN في كل طلب
4٤. تنتهي صلاحية الرموز بعد ٢٤ ساعة — جدّدها عند الحاجة

HTTP

POST /api/v1/auth/token
Content-Type: application/json

{ "api_key": "fk_live_xxxxxxxxxxxxxxxx" }

→ { "token": "eyJhbG...", "expires_in": 86400 }

حدود الطلبات

تختلف الحدود حسب الخطة. تجاوز الحدود يُرجع HTTP 429 Too Many Requests.

الخطة	طلب/دقيقة	فحوصات يومية
مجاني	٣٠ / دقيقة	٣ / يومياً
احترافي	٦٠٠ / دقيقة	٣٠٠ / شهرياً
وكالات	٢٬٠٠٠ / دقيقة	غير محدود

أمثلة على الكود

أمثلة سريعة للبدء مع واجهة برمجة فحص.

curl -X POST https://api.fahs.com/api/v1/audits \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "categories": ["seo", "arabic", "geo"]}'

الفحوصات

POST/api/v1/auditsيتطلب مصادقة

إنشاء فحص جديد للموقع. يُرجع معرّف الفحص للاستعلام عن النتائج.

المعاملات

الاسم	النوع	إلزامي	الوصف
`url`	`string`	إلزامي	رابط الموقع المراد فحصه
`categories`	`string[]`	اختياري	فئات الفحص: seo, performance, accessibility, security, arabic, geo, content
`locale`	`string`	اختياري	تلميح لغة المحتوى (ar, en)

الاستجابة

JSON

{
  "id": "aud_abc123",
  "status": "processing",
  "url": "https://example.com",
  "created_at": "2025-03-15T10:30:00Z"
}

GET/api/v1/audits/:idيتطلب مصادقة

استرجاع نتائج الفحص بالمعرّف. يُرجع الدرجات والمشاكل عند الاكتمال.

المعاملات

الاسم	النوع	إلزامي	الوصف
`id`	`string`	إلزامي	معرّف الفحص (معامل مسار)

الاستجابة

JSON

{
  "id": "aud_abc123",
  "status": "complete",
  "url": "https://example.com",
  "scores": {
    "overall": 78,
    "seo": 82,
    "performance": 71,
    "accessibility": 90,
    "security": 85,
    "arabic": 65,
    "geo": 72
  },
  "issues_count": 47,
  "created_at": "2025-03-15T10:30:00Z"
}

GET/api/v1/auditsيتطلب مصادقة

عرض جميع فحوصات المستخدم المُصادَق. يدعم التصفّح.

المعاملات

الاسم	النوع	إلزامي	الوصف
`page`	`number`	اختياري	رقم الصفحة (الافتراضي: 1)
`limit`	`number`	اختياري	عدد العناصر لكل صفحة (الافتراضي: 20، الأقصى: 100)

الاستجابة

JSON

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156
  }
}

المراقبة

POST/api/v1/monitorsيتطلب مصادقة

إنشاء مراقب جديد للموقع. يُجري فحوصات وفق جدول زمني.

المعاملات

الاسم	النوع	إلزامي	الوصف
`url`	`string`	إلزامي	رابط الموقع المراد مراقبته
`frequency`	`string`	إلزامي	الجدول: daily, weekly, monthly
`notify_email`	`string`	اختياري	البريد الإلكتروني لإشعارات التنبيه

الاستجابة

JSON

{
  "id": "mon_xyz789",
  "url": "https://example.com",
  "frequency": "weekly",
  "status": "active",
  "next_run": "2025-03-22T00:00:00Z"
}

GET/api/v1/monitorsيتطلب مصادقة

عرض جميع المراقبات النشطة.

الاستجابة

JSON

{
  "data": [
    {
      "id": "mon_xyz789",
      "url": "https://example.com",
      "frequency": "weekly",
      "status": "active",
      "last_score": 78
    }
  ]
}

DELETE/api/v1/monitors/:idيتطلب مصادقة

حذف مراقب وإيقاف الفحوصات المجدولة.

المعاملات

الاسم	النوع	إلزامي	الوصف
`id`	`string`	إلزامي	معرّف المراقب (معامل مسار)

الاستجابة

JSON

{ "deleted": true }

التقارير

POST/api/v1/reportsيتطلب مصادقة

إنشاء تقرير PDF أو HTML من نتائج فحص.

المعاملات

الاسم	النوع	إلزامي	الوصف
`audit_id`	`string`	إلزامي	معرّف الفحص المصدر
`format`	`string`	إلزامي	صيغة التقرير: pdf, html
`branding`	`object`	اختياري	خيارات العلامة البيضاء

الاستجابة

JSON

{
  "id": "rpt_def456",
  "audit_id": "aud_abc123",
  "format": "pdf",
  "status": "generating",
  "download_url": null
}

GET/api/v1/reports/:idيتطلب مصادقة

الاستعلام عن حالة التقرير ورابط التحميل.

المعاملات

الاسم	النوع	إلزامي	الوصف
`id`	`string`	إلزامي	معرّف التقرير (معامل مسار)

الاستجابة

JSON

{
  "id": "rpt_def456",
  "status": "ready",
  "download_url": "https://api.fahs.com/reports/rpt_def456.pdf",
  "expires_at": "2025-03-22T10:30:00Z"
}

الفواتير

GET/api/v1/billing/usageيتطلب مصادقة

عرض استخدام فترة الفوترة الحالية والحدود.

الاستجابة

JSON

{
  "plan": "pro",
  "period": { "start": "2025-03-01", "end": "2025-03-31" },
  "audits": { "used": 42, "limit": -1 },
  "api_calls": { "used": 1250, "limit": 10000 }
}

GET/api/v1/billing/invoicesيتطلب مصادقة

عرض فواتير الحساب.

الاستجابة

JSON

{
  "data": [
    {
      "id": "inv_001",
      "amount": 49.00,
      "currency": "USD",
      "status": "paid",
      "date": "2025-03-01"
    }
  ]
}

الإشعارات التلقائية

POST/api/v1/webhooksيتطلب مصادقة

تسجيل نقطة webhook. استقبال إشعارات POST عند اكتمال الفحص أو تنبيهات المراقبة.

المعاملات

الاسم	النوع	إلزامي	الوصف
`url`	`string`	إلزامي	رابط callback الخاص بالـ webhook
`events`	`string[]`	إلزامي	الأحداث للاشتراك: audit.complete, monitor.alert, report.ready
`secret`	`string`	اختياري	مفتاح التوقيع للتحقق من الحمولة

الاستجابة

JSON

{
  "id": "wh_ghi012",
  "url": "https://your-app.com/webhooks/fahs",
  "events": ["audit.complete", "monitor.alert"],
  "status": "active"
}

DELETE/api/v1/webhooks/:idيتطلب مصادقة

إزالة اشتراك webhook.

المعاملات

الاسم	النوع	إلزامي	الوصف
`id`	`string`	إلزامي	معرّف الـ webhook (معامل مسار)

الاستجابة

JSON

{ "deleted": true }