وثائق واجهة API للمطورين لأحكام الأصالة ومؤشرات الدرجة

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

لا تعمل مفاتيح المطورين الخارجية على /api/v1 (واجهة API الخاصة بحسابات المستخدمين المدفوعة)، ولا تُرجع سجل النطاقات المتابَعة، ولا التقارير بعد تسجيل الدخول، ولا معرّفات ملكية الفحوصات، ولا حزم الأدلة المدفوعة.

يُجري MyDomainRisk فحوصات بمستويين مختلفين من العمق، وتمنحك هذه الواجهة المستوى الأقل عمقًا. والفرق ليس حدًّا لعدد الفحوصات التي يمكنك إجراؤها — بل هو فرق في حجم التحليل المُنجَز ومقدار التفاصيل المُرجَعة.

ما لا يفعله الفحص السريع

• لا يشرح النتيجة. تحصل على عنوان ودرجة خطورة، لا على التحليل الذي تستند إليه، ولا على خطوات المعالجة، ولا على المصادر التي أسهمت فيها.
• قد تكون درجته أعلى من درجة الفحص الكامل، ولا تكون أدنى منها أبدًا. فهو يقرأ مؤشر انكشاف أخف، لذا لا يمكن لأربعة فحوصات أعمق أن تخفضها. وعندما ينطبق ذلك، coverage_note يذكر ذلك في الاستجابة — فلا تعرض الرقم من دونه. وعندما يتعذّر جمع الأدلة الأساسية لا توجد درجة على الإطلاق (score قيمتها null، وليست صفرًا أبدًا) و score_note يوضح السبب.
• قد يُرجع حكمًا مؤقتًا بشأن الأصالة. عندما تكون قيمة enrichment_status هي pending، فهذا يعني أن مؤشرين أبطأ لا يزالان قيد التشغيل وقد يتغيّر الحكم. لا يُرسَل إليك أي شيء عند انتهائهما. اطلب النطاق نفسه مجددًا بعد قليل وستحصل على الإجابة المكتملة، التي تُظهر القيمة completed. أما الحكم ذو القيمة not_applicable فلم يحتج إلى أي مؤشر بطيء، ولن يتغيّر مهما تكرر الطلب. وهذا بالضبط سلوك الموقع — فالزائر لا يُبلَّغ أيضًا.
• ربما لم يقرأ الصفحة الرئيسية. homepage.reviewed يخبرك ما إذا كان قد قرأها، و homepage.blocked_by يسمّي ما منعه. «لم يُعثر على شيء» و«تعذّر جلب الصفحة» إجابتان مختلفتان، ويجب ألا تُعرضا بالطريقة نفسها.
• تُخزَّن النتائج مؤقتًا لمدة تصل إلى ٢٠ دقيقة ولا يوجد خيار لفرض التحديث. وقد لا يظهر بعدُ تغيير طرأ على النطاق خلال الدقائق القليلة الماضية.

لأنه الفحص نفسه الذي يمكن للزائر إجراؤه، فإنه يخضع للحصة نفسها: خمس مرات في الساعة. وهو لا يستهلك حصة الفحوصات اليومية للحساب، المخصصة للفحوصات الكاملة.

هذه إجابات على مستوى النتيجة لأغراض التقييم والفرز. ولا تغني عن فحص كامل لنطاق أنت مسؤول عنه.

يُنشر عقد API الكامل كمستند بصيغة OpenAPI 3.1 . تحقّق من صحة الاستجابات في CI لديك أو أنشئ منه عملاء برمجيين محددي الأنواع (typed clients) بدلًا من نسخ الجداول أدناه.

curl -sS https://mydomainrisk.com/openapi.json

يمكن الوصول إلى المستند نفسه من مضيف API، الذي يعيد التوجيه إلى العنوان أعلاه:

curl -sSL https://api.mydomainrisk.com/api/developer/v1/openapi.json

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

هناك واجهتان، وتجيبان عن سؤالين مختلفين. فواجهة API الفحص السريع (peek) للمطورين تجيب عن سؤال حول نطاق تسمّيه — مدى حمايته، أو ما إذا كان هو ما يدّعيه فعلًا — وتُرجع النتيجة نفسها التي يحصل عليها الزائر على الموقع. أما واجهة API الحساب فتقرأ حسابك أنت: النطاقات التي تتابعها، وسجل فحوصاتها وتقاريرها، لأغراض الأتمتة التي تديرها بنفسك.

كلتاهما متاحة في كل الخطط، بما فيها المجانية. الفرق ليس في الباب بل في الغرفة: كل مفتاح محكوم بحدود الخطة التي يتبع لها، و GET /me يُرجع تلك الحدود لتقرأها بدلًا من أن تخمّنها.

يحمل المفتاح أحد الدورين فقط ولا يمكن استخدامه للدور الآخر. يُرفض مفتاح المطوّر إذا أُرسل إلى نقطة نهاية خاصة بالحساب، ويُرفض العكس أيضًا.

مفاتيح واجهة API للمطورين متاحة في كل الخطط، بما فيها المجانية. يرتبط المفتاح بحساب مالكه ويستطيع فعل ما يستطيعه ذلك الحساب — لا أكثر. أنشئ مفتاحًا من نوع Developer API - authenticity and score advisory من قسم الحساب وأرسله كرمز Bearer.

Authorization: Bearer mdr_live_<id>_<secret>

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

تحقّق من صلاحية المفتاح قبل البناء عليه:

GET https://api.mydomainrisk.com/api/developer/v1/me
Authorization: Bearer mdr_live_<id>_<secret>

{
  "api": "developer",
  "version": "v1",
  "scope": "developer_peek",
  "tier": "pro",
  "capabilities": [
    { "operation_id": "getDeveloperCapabilities", "method": "GET", "path": "/me" },
    { "operation_id": "checkDomainSecurity", "method": "GET", "path": "/peek/security" },
    { "operation_id": "checkDomainAuthenticity", "method": "GET", "path": "/peek/authenticity" }
  ],
  "limits": {
    "requests_per_minute_per_key": 120,
    "requests_per_minute_per_ip": 60,
    "requests_per_hour_per_subnet": 150,
    "cache_max_age_seconds": 1200
  },
  "entitlements": {
    "security_score_advisory": true,
    "authenticity_verdict": true,
    "account_data": false,
    "force_refresh": false,
    "consumes_account_daily_allowance": false
  }
}

لا تتضمن استجابة الإمكانات عمدًا البريد الإلكتروني للحساب ولا أي بيانات للعملاء.

إذا كنت تحتاج إلى الوصول إلى API وليس لديك حساب، أو تريد مناقشة ترتيب شراكة، فتواصل مع support@mydomainrisk.com.

GET https://api.mydomainrisk.com/api/developer/v1/peek/security?domain=example.com
Authorization: Bearer mdr_live_<id>_<secret>

مثال على الاستجابة:

{
  "domain": "example.com",
  "checked_at": "2026-08-17T12:00:00Z",
  "score": 82,
  "grade": "B",
  "score_summary": {
    "bucket": "goodWithGaps",
    "label": "GOOD — GAPS REMAIN"
  },
  "score_basis": "point",
  "score_note": null,
  "findings": [
    {
      "title": "DMARC policy could be stronger",
      "severity": "medium"
    }
  ],
  "total_findings": 1,
  "cache": { "hit": false, "max_age_seconds": 1200 },
  "scan_time_ms": 842
}

GET https://api.mydomainrisk.com/api/developer/v1/peek/authenticity?domain=example.com
Authorization: Bearer mdr_live_<id>_<secret>

يمكنك إضافة سياق اختياري عن العلامة التجارية عندما يكون اسم الجهة المتوقعة معروفًا:

GET https://api.mydomainrisk.com/api/developer/v1/peek/authenticity?domain=example.com&expected_brand=Example%20Ltd
Authorization: Bearer mdr_live_<id>_<secret>

مثال على الاستجابة:

{
  "domain": "example.com",
  "checked_at": "2026-08-17T12:00:00Z",
  "verdict": "genuine",
  "findings": [],
  "total_findings": 0,
  "factual": {
    "resolves": true,
    "registrar": "Example Registrar Ltd",
    "age_days": 10950,
    "has_tls": true
  },
  "cache": { "hit": false, "max_age_seconds": 1200 },
  "scan_time_ms": 936
}

الأصالة verdict — القيم الممكنة:

في عمليات التكامل البسيطة بنظام إشارات المرور، اربط genuine و probablyLegit بالنجاح، uncertain و suspicious بالمراجعة، و malicious بالإخفاق.

حقول مؤشر درجة الأمان

ابنِ منطقك على score_summary.bucket بدلًا من مقارنة score بعتباتك الخاصة. الفئة (bucket) جزء من العقد؛ أما العتبة التي تختارها بنفسك فليست كذلك، وستنحرف عن عتباتنا دون أي خطأ ينبّهك.

حقول حكم الأصالة

تُخزَّن النتائج مؤقتًا لمدة تصل إلى ٢٠ دقيقة. لا يوجد في واجهة API للمطورين خيار لفرض التحديث؛ اعرض النتائج كمؤشر حديث لا كقرار دائم بالنسبة إلى النطاقات التي ربما تغيّرت للتو.

طلبات واجهة API للمطورين محدودة بـ ١٢٠ طلبًا في الدقيقة لكل مفتاح، و٦٠ في الدقيقة لكل عنوان IP، و١٥٠ في الساعة لكل شبكة فرعية.

الحصة التي تقيّد الفحص فعليًا هي خمس مرات في الساعة لكل عنوان IP — وهي الحصة نفسها التي يحصل عليها الزائر عند إجراء الفحص نفسه على موقعنا. أما الأرقام بالدقيقة أعلاه فهي ضوابط للدفعات المفاجئة تُضاف فوقها. /me يعرضها باسم peeks_per_hour_per_ip، وقراءة /me لا تُحتسب منها.

هذه الفحوصات لا تستهلك حصة الفحوصات اليومية للحساب. فتلك الحصة مخصصة للفحوصات الكاملة، وهي أعمق وأمر مختلف تمامًا.

يُرجع كل إخفاق بنية JSON نفسها، على كل مسار وبكل رمز حالة. ابنِ منطقك على error.code، لا على نص الرسالة:

{ "error": { "code": "rate_limited", "message": "...", "retry_after_seconds": 30 } }

تعامل مع هذه القائمة على أنها الرموز التي تستحق المعالجة كلٌّ على حدة، لا على أنها مجموعة مغلقة: تعرّف على هذه الرموز واعتمد على رمز حالة HTTP في كل ما عداها، حتى لا يعطّل أي رمز جديد عملية التكامل لديك.

تتضمن الاستجابة ٤٢٩ ترويسة Retry-After إضافة إلى الحقل أعلاه. انتظر وفقًا لقيمتها بدلًا من فاصل زمني ثابت.

واجهة API مخصصة لإجراءات العمل المشروعة في الأعمال والأمن ومكافحة الاحتيال وحماية العملاء والامتثال. ولا يُجري MyDomainRisk إلا تحليلًا خارجيًا غير تدخّلي.

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

قد تُخزَّن نتائج واجهة API للمطورين مؤقتًا وتُحتسب ضمن إحصاءات استخدام مجمّعة، وفق نموذج التشغيل نفسه لفحوصات النطاقات العامة وسياسة الخصوصية لدى MyDomainRisk. للاستفسارات المتعلقة بالخصوصية، تواصل مع support@mydomainrisk.com.