مرجع API

واجهة برمجة تطبيقات (REST API) صغيرة ومستقرة لإدارة المراقبين والقنوات وجلب التغييرات. نفس المساحة السطحية للوحة التحكم.

الرابط الأساسي (Base URL)

الإنتاج: https://api.pagedeltas.com. جميع نقاط النهاية (Endpoints) تبدأ بـ /api. الاستجابات الناجحة تكون بتنسيق JSON.

المصادقة

قم بإنشاء مفتاح من الإعدادات ← مفاتيح API (يتطلب دور محرر أو مسؤول). يُعرض المفتاح مرة واحدة عند إنشائه — انسخه على الفور. لإبطال مفتاح، احذفه من نفس الصفحة.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

تقتصر المفاتيح على المؤسسة التي أنشأتها وتعمل بصلاحيات مستوى المسؤول داخل تلك المؤسسة، بشكل مستقل عن أي مستخدم. لا ترتبط بعضو، لذلك إزالة زميل فريق لا تبطل مفاتيح المؤسسة — احذف المفتاح نفسه لقطع الوصول.

الأخطاء

ترجع الأخطاء حالة غير 2xx. تعود أخطاء المصادقة والصلاحيات كرسالة نصية عادية قصيرة (مثل unauthorized، forbidden)؛ بينما ترجع أخطاء الحصة وحد المعدل جسم JSON صغيراً مع رسالة والأرقام ذات الصلة. لا تحلل حزمة خطأ ثابتة — تفرع بناءً على رمز حالة HTTP:

400 — طلب غير صالح (JSON سيء، رابط غير صالح، حقل مفقود).
401 — بيانات اعتماد مفقودة أو غير صالحة.
403 — مصادق عليه ولكن دورك يفتقر إلى صلاحية هذا الإجراء.
404 — المورد مفقود أو ليس في مؤسستك.
409 — تعارض (مثل إيقاف المراقب مؤقتاً بسبب الكتل المتكررة).
422 — سيتم تجاوز الحصة (مثل حد المراقبين في خطتك). يتضمن جسم JSON current و limit.
429 — تجاوز حد المعدل (للفحوصات اليدوية). تراجع وأعد المحاولة بعد التأخير في Retry-After.

مثال على خطأ الحصة (422):

{
  "error": "plan_url_limit exceeded",
  "current": 100,
  "limit": 100,
  "message": "Creating this monitor would exceed your plan's monitor limit (100)."
}

مرجع نقاط النهاية

الطريقة والمسار	الوصف
`GET /api/monitors`	سرد المراقبين في مؤسستك.
`POST /api/monitors`	إنشاء مراقب واحد.
`GET /api/monitors/{id}`	الحصول على مراقب واحد.
`PATCH /api/monitors/{id}`	تحديث `url`، `nl_description`، `filter_prompt`، `css_selector`، `xpath_selector`، `status`.
`DELETE /api/monitors/{id}`	حذف مراقب وتاريخه.
`POST /api/monitors/{id}/check-now`	إدراج فحص فوري في قائمة الانتظار، متجاوزاً الجدول الزمني (مقيد بالمعدل، انظر أدناه).
`GET /api/monitors/{id}/changes`	سرد التغييرات المكتشفة لمراقب (يدعم `?limit=`، بحد أقصى 100).
`POST /api/monitors/import`	الاستيراد الجماعي عبر رفع CSV متعدد الأجزاء (حقل `file`).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	تطبيق إجراء على قائمة معرفات المراقبين.
`GET\|PUT /api/monitors/{id}/alert-channels`	قراءة أو استبدال تجاوزات قناة المراقب.
`GET /api/alert-channels`	سرد قنوات الإشعارات.
`POST /api/alert-channels`	إنشاء قناة.
`PATCH\|DELETE /api/alert-channels/{id}`	تحديث أو حذف قناة.
`POST /api/alert-channels/{id}/test`	إرسال حمولة اختبار للتحقق من التسليم.
`GET\|POST /api/sitemap-monitors`	سرد أو إنشاء مراقبي خريطة الموقع.
`POST /api/sitemap-monitors/import`	إنشاء مراقبي خريطة الموقع جماعياً عبر رفع CSV متعدد الأجزاء (حقل `file`).
`GET\|POST\|DELETE /api/tokens`	سرد وإنشاء وحذف مفاتيح API.
`GET /api/billing/plan`	الخطة والحدود الحالية لمؤسستك.
`GET /api/plans`	عام — سرد الخطط المتاحة (لا يتطلب مصادقة).

مثال — إنشاء مراقب

curl -X POST https://api.pagedeltas.com/api/monitors \
  -H "Authorization: Bearer $PAGEDELTAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "nl_description": "Competitor pricing; alert on plan or price changes",
    "filter_prompt": "Alert on plan or price changes; ignore copy tweaks",
    "channel_ids": []
  }'

الحقول الاختيارية: filter_prompt، css_selector، xpath_selector، is_pdf، و channel_ids (تجاوزات القناة لكل مراقب؛ تجاوز لاستخدام الإعدادات الافتراضية للمؤسسة). لا يوجد frequency — الجدولة تكيفية.

مثال — جلب التغييرات

GET /api/monitors/01HW2X.../changes?limit=50
Authorization: Bearer $PAGEDELTAS_TOKEN

يرجع التغييرات الأحدث أولاً (الافتراضي 50، بحد أقصى 100). لا يوجد مؤشر (cursor) — قم بترحيل الصفحات عن طريق ضبط limit وتتبع أحدث detected_at رأيته بالفعل.

{
  "changes": [
    {
      "id": "01HW3...",
      "detected_at": "2026-06-01T08:42:00Z",
      "summary": "Pro plan increased from $29 to $39/month."
    }
  ]
}

حدود المعدل

لا توجد حالياً حدود معدل لكل مفتاح على نقاط نهاية القراءة والكتابة. الاستثناء الوحيد هو الفحوصات اليدوية:

تحقق الآن: طلب 1 / دقيقة / مراقب.

عندما تصل إلى هذا الحد، تكون الاستجابة 429 مع رأس Retry-After بالثواني. يرجى الاستمرار في تقييم نفسك بحكمة على نقاط النهاية الأخرى.

إصدارات API

نهدف إلى إبقاء هذه المساحة السطحية مستقرة. قد يتم إضافة حقول ونقاط نهاية جديدة دون إشعار، لذا اكتب عملاء يتجاهلون حقول JSON غير المعروفة.