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

أضف فحص المواقع إلى سير عملك.

ابدأ فحصًا، وتابع تقدّمه، واعرض نتائجه في تطبيقك. ستجد هنا الطلب والاستجابة والخطوة التالية بوضوح.

تطبيقك، وفحص الموقع، وتقرير يساعدك على التحسين.

طلبك البرمجي الأول

استخدم عنوان خادم فحص مع المسار الأساسي أدناه. تُرسل الطلبات والاستجابات بصيغة JSON، باستثناء تنزيل تقارير PDF.

المسار الأساسي: /api/v1
عنوان التطوير المحلي: http://localhost:8000

اضبط FAHS_API_URL على عنوان خادمك دون شرطة مائلة في النهاية. عنوان localhost مخصّص للتطوير المحلي؛ استخدم عنوان خادمك الفعلي عند النشر.

احصل على رمز وصول
سجّل الدخول ببريد حسابك وكلمة المرور، واحتفظ برمز الوصول لاستخدامه في الطلبات التي تتطلب المصادقة.
ابدأ فحص موقع
أرسل رابط الموقع. تعيد الواجهة معرّف الفحص بينما تُجرى الفحوصات في الخلفية.
تابع التقدّم، ثم اقرأ النتائج
استعلم عن الحالة كل بضع ثوانٍ. توقّف عند complete أو failed أو blocked، واجلب تفاصيل الفحص عند اكتماله.

المصادقة

سجّل الدخول بالبريد وكلمة المرور، ثم أرسل رمز الوصول في ترويسة Authorization. لا يتطلب تسجيل الدخول أو تجديد الجلسة رمز وصول مسبقًا.

استخدم رمز الوصول في هذه الترويسة، وليس رمز التجديد:

Authorization: Bearer YOUR_ACCESS_TOKEN

POST/api/v1/auth/token

أرسل email وpassword في جسم الطلب بصيغة JSON. يعيد الطلب الناجح الحالة HTTP 200 مع access_token وrefresh_token وtoken_type وuser.

تسجيل الدخول: مثال الطلبcURL

curl --request POST \
  "$FAHS_API_URL/api/v1/auth/token" \
  --header "Content-Type: application/json" \
  --data '{"email":"[email protected]","password":"YOUR_PASSWORD"}'

تسجيل الدخول: مثال الاستجابةJSON

{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer",
  "user": {
    "id": "83740a2d-fbd3-4b2e-8c93-d8e3a4d372d0",
    "email": "[email protected]",
    "is_active": true,
    "tier": "free",
    "created_at": "2026-10-15T09:00:00"
  }
}

تجديد الجلسة

POST/api/v1/auth/refresh

أرسل refresh_token في جسم الطلب بصيغة JSON لتحصل على رمزين جديدين وبيانات المستخدم. استخدم access_token الجديد في الطلبات التالية.

تجديد الجلسة: مثال الطلبcURL

curl --request POST \
  "$FAHS_API_URL/api/v1/auth/refresh" \
  --header "Content-Type: application/json" \
  --data '{"refresh_token":"YOUR_REFRESH_TOKEN"}'

تجديد الجلسة: مثال الاستجابةJSON

{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer",
  "user": {
    "id": "83740a2d-fbd3-4b2e-8c93-d8e3a4d372d0",
    "email": "[email protected]",
    "is_active": true,
    "tier": "free",
    "created_at": "2026-10-15T09:00:00"
  }
}

نعرض حقولًا مختارة من الاستجابة. الرموز وبيانات الحساب هنا أمثلة توضيحية.

تنتهي صلاحية رمز الوصول حاليًا بعد ٣٠ يومًا، ورمز التجديد بعد ٩٠ يومًا. عند تلقي HTTP 401، جدّد الجلسة أو سجّل الدخول مجددًا.

ابدأ فحصًا

اختر مثالًا واستبدل رمز الوصول التوضيحي. يُرسل الطلب فحصًا فعليًا عند تشغيله في بيئتك؛ لا تُنفّذ هذه الصفحة أي طلب فحص.

تستخدم أمثلة cURL صياغة Bash ومتغيرات البيئة. يعمل مثال JavaScript كوحدة ES في Node.js مع دعم fetch، ويحتاج مثال Python إلى حزمة requests. اضبط عنوان الخادم ورمز الوصول نفسيهما لكل مثال.

cURL

ابدأ فحصًاcURL

export FAHS_API_URL="http://localhost:8000"
export FAHS_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl --request POST \
  "$FAHS_API_URL/api/v1/audits" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com"}'

JavaScript

ابدأ فحصًاJavaScript

const baseUrl = process.env.FAHS_API_URL;
const token = process.env.FAHS_ACCESS_TOKEN;

if (!baseUrl || !token) {
  throw new Error("Set FAHS_API_URL and FAHS_ACCESS_TOKEN");
}

const response = await fetch(baseUrl + "/api/v1/audits", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const audit = await response.json();
console.log(audit.id, audit.status);

Python

ابدأ فحصًاPython

import os
import requests

response = requests.post(
    os.environ["FAHS_API_URL"] + "/api/v1/audits",
    headers={
        "Authorization": "Bearer " + os.environ["FAHS_ACCESS_TOKEN"],
    },
    json={"url": "https://example.com"},
    timeout=30,
)
response.raise_for_status()
audit = response.json()
print(audit["id"], audit["status"])

الفحوصات

5 نقاط نهاية

أنشئ فحصًا، وتابع تقدّمه، واسترجع نتائج المواقع المرتبطة بحسابك.

حالات الفحص هي pending وrunning وcomplete وfailed وblocked. قد تصل التوصيات بعد الاكتمال. يحتوي scores على درجات الفئات دون حقل مستقل للدرجة الإجمالية.

POST/api/v1/audits

إنشاء فحص

أضف فحص الموقع إلى قائمة التنفيذ واحصل على بياناته. احتفظ بقيمة id لمتابعة التقدّم واسترجاع النتيجة.

رمز وصولHTTP 201

المعاملات والأمثلة

جسم الطلب بصيغة JSON

urlstring (URI)مطلوب: رابط موقع كامل يبدأ ببروتوكول HTTP أو HTTPS.
target_countriesstring[] | nullاختياري: رموز البلدان المستهدفة للفحوصات الإقليمية، وهي اختيارية.
answersobject | nullاختياري: إجابات ما قبل الفحص، بمفاتيح وقيم نصية، مثل audience وsite_type وpriority وdepth.

الحقل url وحده مطلوب. لا تقبل هذه النقطة اختيار categories أو locale. يُحتسب إنشاء الفحص ضمن حصة خطتك.

إنشاء فحص: مثال الطلبcURL

curl --request POST \
  "$FAHS_API_URL/api/v1/audits" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com"}'

إنشاء فحص: مثال الاستجابةJSON

{
  "id": "c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41",
  "url": "https://example.com/",
  "status": "pending",
  "progress": 0,
  "scores": null,
  "results": null,
  "recommendations": null,
  "answers": null,
  "created_at": "2026-10-15T09:00:00",
  "updated_at": "2026-10-15T09:00:00"
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

GET/api/v1/audits/{audit_id}/status

متابعة تقدّم الفحص

اقرأ حالة فحص يملكه حسابك ونسبة تقدّمه الرقمية.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

audit_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء الفحص.

استعلم كل بضع ثوانٍ، وتوقّف عند complete أو failed أو blocked. يعود HTTP 404 إذا لم يوجد الفحص أو كان مملوكًا لحساب آخر.

متابعة تقدّم الفحص: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/audits/c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41/status" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

متابعة تقدّم الفحص: مثال الاستجابةJSON

{
  "id": "c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41",
  "status": "running",
  "progress": 55
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

GET/api/v1/audits/{audit_id}

استرجاع نتائج الفحص

اجلب بيانات الفحص، بما فيها درجات الفئات والنتائج والتوصيات المتاحة.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

audit_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء الفحص.

اختُصر الكائن results في هذا المثال. تكون scores وresults بقيمة null قبل توفرها، وقد تبقى recommendations بقيمة null بعد الاكتمال.

استرجاع نتائج الفحص: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/audits/c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

استرجاع نتائج الفحص: مثال الاستجابةJSON

{
  "id": "c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41",
  "url": "https://example.com/",
  "status": "complete",
  "progress": 100,
  "scores": {
    "seo": 82,
    "arabic_seo": 65,
    "performance": 71,
    "accessibility": 68,
    "security": 88,
    "mobile": 75,
    "geo": 56,
    "mena_compliance": 34
  },
  "results": {},
  "recommendations": null,
  "answers": null,
  "created_at": "2026-10-15T09:00:00",
  "updated_at": "2026-10-15T09:01:20"
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

GET/api/v1/audits

عرض فحوصاتك

اجلب فحوصات حسابك من الأحدث إلى الأقدم، مع العدد الإجمالي.

رمز وصولHTTP 200

المعاملات والأمثلة

لا يتطلب جسم طلب أو معاملات استعلام.

يعيد هذا المسار القائمة كاملة حاليًا، ولا يقبل المعاملين page وlimit. يوضّح المثال حسابًا بلا فحوصات.

عرض فحوصاتك: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/audits" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

عرض فحوصاتك: مثال الاستجابةJSON

{
  "audits": [],
  "total": 0
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

DELETE/api/v1/audits/{audit_id}

حذف فحص

احذف فحصًا يملكه حسابك حذفًا نهائيًا.

رمز وصولHTTP 204

المعاملات والأمثلة

معاملات المسار

audit_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء الفحص.

يعيد الحذف الناجح HTTP 204 دون جسم استجابة. إذا كان الفحص لحساب آخر، تعود الحالة HTTP 404.

حذف فحص: مثال الطلبcURL

curl --request DELETE \
  "$FAHS_API_URL/api/v1/audits/c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

حذف فحص: مثال الاستجابةHTTP

HTTP/1.1 204 No Content

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

المراقبة

7 نقاط نهاية

جدوِل فحوصات متكررة وراجع سجل فحوصات الموقع الذي تراقبه.

يتطلب إنشاء مراقبة خطة برو أو الوكالات. تتيح برو ٥ مراقبات، ولا تضع خطة الوكالات حدًا لعددها. تُوضّح الإعدادات المحفوظة أدناه، وتتبع الجدولة قيمة frequency.

POST/api/v1/monitors

إنشاء مراقبة

احفظ الموقع وتكرار فحصه. تتضمن الاستجابة موعد التشغيل التالي.

رمز وصولHTTP 201

المعاملات والأمثلة

جسم الطلب بصيغة JSON

urlstring (URI)مطلوب: رابط HTTP أو HTTPS متاح للعامة. تُرفض العناوين الخاصة والداخلية.
frequencystringمطلوب: إحدى القيم hourly أو daily أو weekly أو monthly. تستخدم الجدولة الشهرية فترة من ٣٠ يومًا.
score_thresholdintegerاختياري: حدّ الدرجة المحفوظ. القيمة الافتراضية ٧٠.
email_notificationsbooleanاختياري: إرسال إشعارات المراقبة بالبريد. القيمة الافتراضية true.
webhook_urlstring | nullاختياري: عنوان عام يستقبل طلب POST بالدرجة ورابط التقرير عند انتهاء كل فحص مجدول.
alert_categoriesobject | nullاختياري: اختيارات الفئات المحفوظة، بقيم منطقية لكل مفتاح فئة.
scheduled_daysinteger[] | nullاختياري: اختيارات أيام الأسبوع المحفوظة. يتبع المجدوِل حاليًا frequency وليس هذه الاختيارات.

الحقلان url وfrequency مطلوبان فقط. تبدأ trend فارغة؛ وتحسب طلبات القائمة والتفاصيل اتجاهًا من سبع نقاط وفق الفحوصات المكتملة.

إنشاء مراقبة: مثال الطلبcURL

curl --request POST \
  "$FAHS_API_URL/api/v1/monitors" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com","frequency":"weekly"}'

إنشاء مراقبة: مثال الاستجابةJSON

{
  "id": "4f9a8b24-865e-45b9-b23c-663dadca115e",
  "user_id": "83740a2d-fbd3-4b2e-8c93-d8e3a4d372d0",
  "url": "https://example.com/",
  "frequency": "weekly",
  "is_active": true,
  "score_threshold": 70,
  "email_notifications": true,
  "webhook_url": null,
  "alert_categories": null,
  "scheduled_days": null,
  "last_audit_id": null,
  "last_run_at": null,
  "next_run_at": "2026-10-22T09:00:00",
  "created_at": "2026-10-15T09:00:00",
  "updated_at": "2026-10-15T09:00:00",
  "trend": []
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

GET/api/v1/monitors

عرض مراقباتك

اجلب مراقبات حسابك من الأحدث إلى الأقدم، مع العدد الإجمالي واتجاهات الدرجات الأخيرة.

رمز وصولHTTP 200

المعاملات والأمثلة

لا يتطلب جسم طلب أو معاملات استعلام.

تتكون trend من سبع قيم، وتُستكمل الفترات التي لا تملك سجلًا بأصفار في البداية. يوضّح المثال حسابًا بلا مراقبات.

عرض مراقباتك: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/monitors" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

عرض مراقباتك: مثال الاستجابةJSON

{
  "monitors": [],
  "total": 0
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

GET/api/v1/monitors/{monitor_id}

استرجاع مراقبة

اقرأ بيانات مراقبة وإعداداتها المحفوظة واتجاه درجاتها من سبع نقاط.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

monitor_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء المراقبة.

تعود الحالة HTTP 403 لمراقبة يملكها حساب آخر، وHTTP 404 إذا لم توجد المراقبة.

استرجاع مراقبة: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/monitors/4f9a8b24-865e-45b9-b23c-663dadca115e" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

استرجاع مراقبة: مثال الاستجابةJSON

{
  "id": "4f9a8b24-865e-45b9-b23c-663dadca115e",
  "user_id": "83740a2d-fbd3-4b2e-8c93-d8e3a4d372d0",
  "url": "https://example.com/",
  "frequency": "weekly",
  "is_active": true,
  "score_threshold": 70,
  "email_notifications": true,
  "webhook_url": null,
  "alert_categories": null,
  "scheduled_days": null,
  "last_audit_id": null,
  "last_run_at": null,
  "next_run_at": "2026-10-22T09:00:00",
  "created_at": "2026-10-15T09:00:00",
  "updated_at": "2026-10-15T09:00:00",
  "trend": [
    0,
    0,
    0,
    0,
    0,
    0,
    0
  ]
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

PATCH/api/v1/monitors/{monitor_id}

تعديل إعدادات المراقبة

عدّل الحقول التي ترسلها فقط. عند تغيير frequency، يُحسب موعد التشغيل التالي من وقت التعديل.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

monitor_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء المراقبة.

جسم الطلب بصيغة JSON

urlstring (URI)اختياري: رابط HTTP أو HTTPS متاح للعامة. تُرفض العناوين الخاصة والداخلية.
frequencystringاختياري: إحدى القيم hourly أو daily أو weekly أو monthly. تستخدم الجدولة الشهرية فترة من ٣٠ يومًا.
score_thresholdintegerاختياري: حدّ الدرجة المحفوظ. القيمة الافتراضية ٧٠.
email_notificationsbooleanاختياري: إرسال إشعارات المراقبة بالبريد. القيمة الافتراضية true.
webhook_urlstring | nullاختياري: عنوان عام يستقبل طلب POST بالدرجة ورابط التقرير عند انتهاء كل فحص مجدول.
alert_categoriesobject | nullاختياري: اختيارات الفئات المحفوظة، بقيم منطقية لكل مفتاح فئة.
scheduled_daysinteger[] | nullاختياري: اختيارات أيام الأسبوع المحفوظة. يتبع المجدوِل حاليًا frequency وليس هذه الاختيارات.

حقول الجسم اختيارية، وتُتجاهل قيم null. لمسح رابط استدعاء محفوظ، أرسل سلسلة نصية فارغة في webhook_url.

تعديل إعدادات المراقبة: مثال الطلبcURL

curl --request PATCH \
  "$FAHS_API_URL/api/v1/monitors/4f9a8b24-865e-45b9-b23c-663dadca115e" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"frequency":"daily"}'

تعديل إعدادات المراقبة: مثال الاستجابةJSON

{
  "id": "4f9a8b24-865e-45b9-b23c-663dadca115e",
  "user_id": "83740a2d-fbd3-4b2e-8c93-d8e3a4d372d0",
  "url": "https://example.com/",
  "frequency": "daily",
  "is_active": true,
  "score_threshold": 70,
  "email_notifications": true,
  "webhook_url": null,
  "alert_categories": null,
  "scheduled_days": null,
  "last_audit_id": null,
  "last_run_at": null,
  "next_run_at": "2026-10-16T09:00:00",
  "created_at": "2026-10-15T09:00:00",
  "updated_at": "2026-10-15T09:00:00",
  "trend": [
    0,
    0,
    0,
    0,
    0,
    0,
    0
  ]
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

PATCH/api/v1/monitors/{monitor_id}/toggle

إيقاف المراقبة أو استئنافها

اعكس قيمة is_active واحصل على بيانات المراقبة المحدّثة.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

monitor_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء المراقبة.

يعكس الطلب القيمة الحالية، ويعكسها تكراره مرة أخرى. لا تُعد المحاولة تلقائيًا قبل التحقق من الحالة الحالية.

إيقاف المراقبة أو استئنافها: مثال الطلبcURL

curl --request PATCH \
  "$FAHS_API_URL/api/v1/monitors/4f9a8b24-865e-45b9-b23c-663dadca115e/toggle" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

إيقاف المراقبة أو استئنافها: مثال الاستجابةJSON

{
  "id": "4f9a8b24-865e-45b9-b23c-663dadca115e",
  "user_id": "83740a2d-fbd3-4b2e-8c93-d8e3a4d372d0",
  "url": "https://example.com/",
  "frequency": "weekly",
  "is_active": false,
  "score_threshold": 70,
  "email_notifications": true,
  "webhook_url": null,
  "alert_categories": null,
  "scheduled_days": null,
  "last_audit_id": null,
  "last_run_at": null,
  "next_run_at": "2026-10-22T09:00:00",
  "created_at": "2026-10-15T09:00:00",
  "updated_at": "2026-10-15T09:00:00",
  "trend": []
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

GET/api/v1/monitors/{monitor_id}/history

قراءة سجل المراقبة

اجلب درجات مؤرخة لآخر ١٢ فحصًا مكتملًا بحد أقصى للموقع المراقب، من الأقدم إلى الأحدث.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

monitor_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء المراقبة.

تحتوي كل نقطة على audit_id وcreated_at وscore. يعيد الحساب الذي لا يملك فحوصات مكتملة مصفوفة points فارغة.

قراءة سجل المراقبة: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/monitors/4f9a8b24-865e-45b9-b23c-663dadca115e/history" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

قراءة سجل المراقبة: مثال الاستجابةJSON

{
  "points": [
    {
      "audit_id": "c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41",
      "created_at": "2026-10-15T09:00:00",
      "score": 71
    }
  ]
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

DELETE/api/v1/monitors/{monitor_id}

حذف مراقبة

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

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

monitor_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء المراقبة.

يعيد الطلب الناجح HTTP 200 مع رسالة. تبقى الفحوصات السابقة محفوظة.

حذف مراقبة: مثال الطلبcURL

curl --request DELETE \
  "$FAHS_API_URL/api/v1/monitors/4f9a8b24-865e-45b9-b23c-663dadca115e" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

حذف مراقبة: مثال الاستجابةJSON

{
  "message": "Monitor deleted"
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

تقارير PDF

نقطتا نهاية

نزّل تقرير PDF لفحص مكتمل يملكه حسابك.

يتطلب تنزيل التقارير خطة برو أو الوكالات، وتخصيص الألوان والنصوص ورابط الوكالة والشعار يتطلب خطة الوكالات. الاستجابة ملف PDF مباشرة، وليست مهمة JSON أو رابط تنزيل.

GET/api/v1/reports/{audit_id}

تنزيل تقرير PDF

أنشئ تقرير PDF لفحص مكتمل ونزّله. اضبط lang على en أو ar.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

audit_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء الفحص.

معاملات الاستعلام

langstringاختياري: لغة التقرير: en أو ar. الافتراضية en، وتُستبدل القيم غير المدعومة بها.
primary_colorstringاختياري: لون التقرير المخصّص. يتطلب خطة الوكالات.
header_textstringاختياري: نص الترويسة المخصّص. يتطلب خطة الوكالات.
footer_textstringاختياري: نص التذييل المخصّص. يتطلب خطة الوكالات.
agency_urlstringاختياري: رابط موقع وكالتك. يتطلب خطة الوكالات.

تتطلب معاملات تخصيص الهوية الاختيارية خطة الوكالات. احفظ الاستجابة كملف؛ وتعني HTTP 400 أن الفحص لم يكتمل بعد.

تنزيل تقرير PDF: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/reports/c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41?lang=en" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN" \
  --output fahs-report.pdf

تنزيل تقرير PDF: مثال الاستجابةHTTP

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=fahs-audit-c7bb55c0.pdf

<PDF bytes>

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

POST/api/v1/reports/{audit_id}

إنشاء تقرير بهويتك

أرسل خيارات التقرير بصيغة JSON. يقبل هذا المسار أيضًا صورة الشعار بصيغة رابط بيانات في جسم الطلب.

رمز وصولHTTP 200

المعاملات والأمثلة

معاملات المسار

audit_idstringمطلوب: قيمة id التي أُعيدت عند إنشاء الفحص.

جسم الطلب بصيغة JSON

langstringاختياري: لغة التقرير: en أو ar. الافتراضية en، وتُستبدل القيم غير المدعومة بها.
primary_colorstringاختياري: لون التقرير المخصّص. يتطلب خطة الوكالات.
header_textstringاختياري: نص الترويسة المخصّص. يتطلب خطة الوكالات.
footer_textstringاختياري: نص التذييل المخصّص. يتطلب خطة الوكالات.
agency_urlstringاختياري: رابط موقع وكالتك. يتطلب خطة الوكالات.
logo_data_uristring | nullاختياري: صورة الشعار بصيغة رابط بيانات. متاحة في طلب POST وتتطلب خطة الوكالات.

يتطلب تخصيص الهوية خطة الوكالات. يمكن لبرو استخدام المسار لخيارات اللغة فقط. تُستكمل قيم الهوية غير المرسلة من إعدادات حساب الوكالة المحفوظة.

إنشاء تقرير بهويتك: مثال الطلبcURL

curl --request POST \
  "$FAHS_API_URL/api/v1/reports/c7bb55c0-a3c1-4fa7-9a64-ff370d00ec41" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"lang":"ar","primary_color":"#2456d6","header_text":"Your agency"}' \
  --output fahs-report.pdf

إنشاء تقرير بهويتك: مثال الاستجابةHTTP

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=fahs-audit-c7bb55c0.pdf

<PDF bytes>

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

استخدام الحساب

نقطة نهاية واحدة

اطّلع على حصة الفحوصات والاستخدام الحالي لحسابك.

تعني قيمة null في limit عدم وجود حد. تكون period إما day أو month أو null. تمثّل seats_used حاليًا مالك الحساب فقط، ولا تشمل الواجهة قائمة للفواتير.

GET/api/v1/billing/usage

استرجاع استخدام الحساب

اقرأ الخطة الحالية وحصة الفحوصات والمتبقي وموعد التجديد وعدد المراقبات.

رمز وصولHTTP 200

المعاملات والأمثلة

لا يتطلب جسم طلب أو معاملات استعلام.

تتجدد الحصص اليومية والشهرية عند منتصف الليل بتوقيت UTC. قد تشير 429 إلى حصة الفحوصات أو حد المراقبات أو تقييد الطلبات؛ اقرأ detail لمعرفة السبب.

استرجاع استخدام الحساب: مثال الطلبcURL

curl --request GET \
  "$FAHS_API_URL/api/v1/billing/usage" \
  --header "Authorization: Bearer $FAHS_ACCESS_TOKEN"

استرجاع استخدام الحساب: مثال الاستجابةJSON

{
  "tier": "pro",
  "limit": 50,
  "period": "month",
  "used": 42,
  "remaining": 8,
  "resets_at": "2026-11-01T00:00:00",
  "monitors_used": 2,
  "seats_used": 1
}

القيم توضيحية. راجع ملاحظات النقطة لمعرفة الحقول المختصرة والبيانات التي تتغير حسب الحالة.

الحصص وحدود الطلبات

تختلف حصة الخطة عن حدود الطلبات المتتابعة. راجع استخدام الحساب قبل إضافة مجموعة من الفحوصات.

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

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

حد بدء الفحوصات

يُسمح ببدء ١٢ فحصًا في الدقيقة و٦٠ في الساعة لكل عنوان IP، عبر جميع الخطط، عند استخدام المصادقة. يعيد بلوغ الحصة أو حد الطلبات الحالة HTTP 429. وزّع الطلبات زمنيًا واقرأ تفاصيل الخطأ قبل إعادة المحاولة.

راجع استجابة الاستخدام

تعامل مع الأخطاء بوضوح

تحقق من حالة HTTP قبل قراءة استجابة النجاح. تحتوي معظم الأخطاء على الحقل detail؛ وتعيد أخطاء التحقق مصفوفة detail توضّح الحقل غير الصالح والسبب.

400

لا يمكن إكمال الطلب في الحالة الحالية.

عند طلب PDF، انتظر اكتمال الفحص.

401

بيانات الدخول أو رمز الوصول غير صالح أو منتهي الصلاحية.

جدّد الجلسة أو سجّل الدخول مجددًا.

403

لا يملك الحساب أو الخطة صلاحية الوصول.

تحقق من الملكية وحالة الحساب ومتطلبات الخطة.

404

لم يُعثر على المورد المطلوب.

تحقق من المعرّف. تعيد مسارات الفحص أيضًا 404 لفحص يملكه حساب آخر.

422

قيمة في الجسم أو المسار أو الاستعلام غير صالحة.

اقرأ تفاصيل التحقق وصحّح الطلب.

429

بُلغت الحصة أو أحد حدود الطلبات.

اقرأ detail، ثم انتظر تجدد الحصة المناسبة أو خفّض معدل الطلبات.

خطأ في المصادقة · HTTP 401JSON

{
  "detail": "Invalid credentials"
}

نطاق الربط المتاح

يغطي المرجع أعلاه الفحوصات والمراقبة والتقارير والاستخدام المطبّقة حاليًا.

اشتراكات إشعارات الأحداث

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

الفواتير

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

تحتاج مساعدة في الربط؟

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

توثيق المنتج تواصل مع فريقنا