مرجع المطورين

صيغة الرد

باستخدام DomScan API، جميع الاستجابات بصيغة JSON. تحتوي نتيجة كل نطاق على هذه الحقول المشتركة:

صيغة الرد

جميع الاستجابات بصيغة JSON. تحتوي نتيجة كل نطاق على هذه الحقول المشتركة:

  • domain - اسم النطاق الكامل
  • available - حالة التوفر المنطقية
  • source - "rdap" or "cache"
  • checked_at - ISO 8601 timestamp
  • error - موجود عند حدوث خطأ

بيانات الاستجابة الوصفية

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

اختيار الحقول والاستجابات المضغوطة

أضف fields أو compact إلى سلسلة الاستعلام في أي طلب GET أو POST لتحصل على استجابة JSON أصغر. كلاهما اختياري. في طلبات POST يوضعان في سلسلة الاستعلام لا في جسم الطلب. لا يغيّر أي منهما تكلفة الأرصدة.

اختيار الحقول

يقبل fields مسارات منقوطة مفصولة بفواصل، مثل fields=domain,classification.status,records.data. عندما يعبر المسار قائمة، يُطبَّق على كل عنصر فيها. تحتفظ العناصر بمواضعها، ويتحول العنصر الذي لا يحتوي على أي حقل محدد إلى {}. وتبقى القيمة null الواقعة على المسار كما هي null.

أرسل ما يصل إلى 50 مساراً، لكل منها حتى 6 أجزاء، وكل جزء من 1 إلى 64 حرفاً أو رقماً أو شرطة سفلية. أي قيمة أخرى تعيد الخطأ 400 INVALID_PARAMETER قبل تنفيذ الطلب، ولذلك لا تُحتسب أي رسوم.

المسارات التي لا تطابق أي شيء في الاستجابة تُستبعد وتُدرج في ترويسة الاستجابة X-Fields-Ignored، بحد أقصى 20 مساراً.

الاستجابات المضغوطة

يزيل compact=true العناصر التالية فقط، وعلى المستوى الأعلى من الاستجابة فقط:

  • في الكائن meta: المفتاح served_by ومفاتيح الأزمنة duration_ms وquery_time_ms وtotal_ms وtotal_time_ms وlatency_ms وgeneration_ms وcheck_duration_ms. يُزال الكائن meta نفسه عندما لا يتبقى فيه شيء آخر.
  • warnings وcaveats وnotes وerrors عندما تكون قوائم فارغة.
  • request_id عندما يكرر قيمة الترويسة X-Request-Id.

لا تُزال أبداً حقول البيانات ولا classification ولا الكائنات المتداخلة ولا عناصر القوائم. عند إرسال المعاملين معاً يُنفَّذ compact أولاً ثم fields.

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

عند استخدام Idempotency-Key، يصبح fields وcompact جزءاً من الطلب. تعيد إعادة المحاولة بالقيم نفسها الاستجابة المخزنة المعاد صياغتها. أما إعادة استخدام المفتاح بقيم مختلفة فتعيد الخطأ 422 IDEMPOTENCY_KEY_REUSED.

تقبل أدوات MCP الوسيطين الاختياريين نفسيهما fields وcompact. تُدرج المسارات غير المطابقة في _meta.fields_ignored ضمن نتيجة الأداة.

مثال

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/dns?domain=google.com&type=TXT&fields=domain,status,records.data,records.ttl,owner&compact=true"

X-Fields-Ignored: owner

{
  "domain": "google.com",
  "records": [
    {
      "data": "v=spf1 include:_spf.google.com ~all",
      "ttl": 300
    },
    {
      "data": "google-site-verification=abc123",
      "ttl": 300
    }
  ],
  "status": "success"
}

مفاتيح snake_case (naming)

معظم مفاتيح الاستجابة مكتوبة بنمط snake_case بالفعل، لكن بعض نقاط النهاية تُرجع بعض المفاتيح بنمط camelCase، مثل registrarName في نتائج التسعير وtldTier في عوامل التقييم وeventDate في أحداث RDAP. أضف naming=snake إلى سلسلة الاستعلام، أو أرسل الترويسة DomScan-Naming: snake، لتحصل على كل هذه المفاتيح بنمط snake_case. وبدون ذلك تحتفظ الاستجابات بمفاتيحها الحالية.

لا يتغير المفتاح إلا إذا بدأ بحرف صغير، واحتوى على أحرف وأرقام فقط، وضم حرفًا كبيرًا واحدًا على الأقل. تُضاف شرطة سفلية قبل كل كلمة جديدة ويُحوَّل المفتاح كله إلى أحرف صغيرة. وتبقى الاختصارات متصلة، ومنها IPv4 وصيغ الجمع مثل IPs: يصبح registrarName هو registrar_name، ويصبح secureDNS هو secure_dns، ويصبح ipv4Address هو ipv4_address، ويصبح nameserverIPs هو nameserver_ips.

المفاتيح التي تمثل بيانات وليست أسماء حقول تحتفظ بكتابتها كما هي، مثل أنواع سجلات DNS (A وMX) والدرجات مثل A+ وأسماء النطاقات وأسماء الترويسات وأسماء التقنيات. لا تتغير القيم أبدًا، وتُحوَّل الكائنات والقوائم المتداخلة في كل مستوى.

إذا كان الكائن يحتوي بالفعل على الاسم بنمط snake_case، كأن يوجد fooBar وfoo_bar معًا، فيحتفظ foo_bar بقيمته ويحتفظ fooBar باسمه الأصلي، فلا يضيع شيء. ولا يتغير ترتيب المفاتيح.

تكون الأولوية لمعامل الاستعلام على الترويسة، لذا يتيح naming=default إيقاف الاشتراك المفعّل عبر الترويسة لطلب واحد. القيم المقبولة هي snake وdefault. أي قيمة أخرى تُرجع الخطأ 400 INVALID_PARAMETER قبل تنفيذ الطلب، فلا يتم خصم أي رصيد. وتتضمن الاستجابات الترويسة Vary: DomScan-Naming.

يُنفَّذ naming قبل compact وfields، لذا اكتب مسارات fields بنمط snake_case، مثل fields=factors.tld_tier. استجابات الأخطاء مكتوبة بنمط snake_case أصلًا ولا تتغير أبدًا، وتكلفة الاعتمادات هي نفسها.

عند استخدام Idempotency-Key، يُعدّ اختيار التسمية جزءًا من الطلب سواء جاء من المعامل أو من الترويسة، لذا تُرجع إعادة المحاولة المفاتيح نفسها.

تقبل أدوات MCP وسيطة naming الاختيارية نفسها. ولا تقرأ استدعاءات MCP الترويسة.

curl -H "X-API-Key: $DOMSCAN_API_KEY" -H "DomScan-Naming: snake" "https://domscan.net/v1/value?domain=example.com&fields=domain,factors.tld_tier,factors.has_hyphens"

{
  "domain": "example.com",
  "factors": {
    "tld_tier": "premium",
    "has_hyphens": false
  }
}

التحكم في حداثة البيانات (max_age)

تقبل نقاط النهاية التي يمكنها الرد من بيانات جرى فحصها حديثًا المعامل max_age، وهو عدد صحيح من الثواني بين 0 و2592000 (30 يومًا). تُفحص البيانات الأقدم من max_age مرة أخرى قبل إرجاعها، ويؤدي max_age=0 إلى فحص جديد دائمًا. وإذا لم تُرسل max_age، تحتفظ كل نقطة نهاية بسلوكها المعتاد.

تتضمن كل استجابة ناجحة من نقاط النهاية هذه الحقل cache_age_s في المستوى الأعلى: عمر البيانات المستخدمة بالثواني، أو 0 إذا جرى الفحص من جديد. وتُرسل القيمة نفسها في ترويسة الاستجابة X-Cache-Age. وعندما تحتوي الاستجابة على عدة عناصر، مثل فحص توفر عدة نطاقات، تكون القيمة عمر أقدم عنصر، وتحتفظ العناصر بقيمة cache_age_s الخاصة بها إن كانت تتضمنها أصلًا.

لا يغيّر max_age طريقة تصنيف النتيجة أبدًا. فالنتيجة التي تعذّر تأكيدها تبقى unknown مهما كانت حديثة، ولا تُعرض البيانات الحديثة على أنها موجودة أو غير موجودة ما لم يؤكد الفحص الأصلي ذلك.

لا يغيّر max_age تكلفة الطلب. الفحص الجديد والرد من بيانات حديثة يستهلكان الرصيد نفسه.

في /v1/status و/v1/status/bulk، تخضع عمليات الفحص الجديد الإجبارية (max_age=0) لحد لكل عميل لحماية سجلات النطاقات. وبعد بلوغ هذا الحد يُرد على الطلب كما لو لم يُرسل max_age، ويُظهر cache_age_s عمر ما استلمته. وإذا لم يكن max_age عددًا صحيحًا بين 0 و2592000، تُرجع الاستجابة 400 INVALID_PARAMETER قبل تنفيذ الطلب، فلا تُحتسب أي رسوم.

نقاط النهاية التي تقبل max_age: GET /v1/status, POST /v1/status/bulk, GET /v1/subdomains, GET /v1/certificates, GET /v1/tech, GET /v1/categorize, GET /v1/identity-assets, GET /v1/avatar, GET /v1/logo/:domain, GET /v1/brand, GET /v1/identity-resolution, GET /v1/url-intelligence, GET /v1/agent-readiness, GET /v1/robots, GET /v1/ssl/deep-scan

معاملات التخزين المؤقت القديمة

ما زالت هذه المعاملات تعمل، وأصبحت الآن أسماء بديلة مهجورة للمعامل max_age. وإذا أرسلت max_age معها، فإن max_age هو الذي يُعتمد.

المعاملنقاط النهايةيعادل
prefer_cache/v1/status, /v1/subdomainsmax_age=2592000
skip_cache/v1/status, /v1/tech, /v1/categorize, /v1/identity-assets, /v1/identity-resolution, /v1/url-intelligence, /v1/agent-readiness, /v1/robotsmax_age=0
cache_skip/v1/statusmax_age=0
cache-skip/v1/statusmax_age=0
options.prefer_cache (body)/v1/status/bulkmax_age=2592000
prefer_cache (body)/v1/status/bulkmax_age=2592000
options.skip_cache (body)/v1/status/bulkmax_age=0
options.cache_skip (body)/v1/status/bulkmax_age=0
options.cache-skip (body)/v1/status/bulkmax_age=0
refresh/v1/ssl/deep-scanmax_age=0

في /v1/subdomains، يحتفظ prefer_cache أيضًا بسلوك الاعتماد على التخزين المؤقت فقط: عندما لا توجد بيانات مخزنة بعد، يُرجع الطلب 202 دون أي رسوم ويبدأ البحث في الخلفية.

تقبل أدوات MCP الخاصة بنقاط النهاية هذه الوسيط الاختياري max_age نفسه، وتتضمن نتائجها cache_age_s.

ترقيم الصفحات (limit وcursor)

تقبل نقاط النهاية التي تُرجع قوائم طويلة المعاملين limit وcursor، وتتضمن كل استجابة has_more وnext_cursor. للحصول على الصفحة التالية، كرّر الطلب مع ضبط cursor على قيمة next_cursor. وفي الصفحة الأخيرة تكون قيمة has_more هي false وقيمة next_cursor هي null.

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

المؤشرات (cursor) غير شفافة وموقّعة. ولا يعمل المؤشر إلا للحساب الذي تسلّمه وللاستعلام نفسه، مثل النطاق والمرشحات نفسها. وأي مؤشر جرى تعديله أو يخص حسابًا آخر أو أُرسل مع مرشحات مختلفة يُرجع 400 INVALID_CURSOR.

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

كل صفحة طلب عادي وتكلّف الرصيد المعتاد لنقطة النهاية، تمامًا كما كان الطلب مع limit من قبل. وتبقى نقاط النهاية المجانية مجانية.

ما زالت المعاملات القديمة تعمل: offset في /v1/email/blacklist، وpagination.next_cursor الرقمي في /v1/certificates.

نقطة النهايةحجم الصفحة الافتراضيالحد الأقصى لـ limit
GET /v1/whois/history50100
GET /v1/dns/history1001000
GET /v1/subdomains5002000
GET /v1/certificates1001000
GET /v1/watchlistالقائمة كاملة100
GET /v1/watchlist/expiringالقائمة كاملة100
GET /v1/watchlist/availableالقائمة كاملة100
GET /v1/brand-monitorالقائمة كاملة100
GET /v1/email/blacklist100010000

مثال

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20"

{
  "domain": "example.com",
  "snapshots": [
    "..."
  ],
  "has_more": true,
  "next_cursor": "eyJvIjoi..."
}

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20&cursor=eyJvIjoi..."

حالة التصنيف

تضيف نقاط النهاية التي تفيد بوجود شيء ما (تسجيل النطاقات، حسابات وسائل التواصل الاجتماعي، سجلات DNS ومصادقة البريد، وsecurity.txt وrobots.txt وخرائط الموقع، ورؤوس الأمان، وركن النطاقات، وتسجيلات انتحال الأسماء typosquat، وشهادات SSL) كائنًا باسم classification بجانب حقولها الحالية. تحتفظ الحقول الحالية باسمها ومعناها.

  • status - إحدى القيم present (موجود) أو absent (غير موجود) أو unknown (غير معروف). لا تُعاد القيمتان present وabsent إلا عندما يقدّم الفحص دليلًا دقيقًا وموثوقًا.
  • reason - يُعاد فقط عندما تكون الحالة unknown. ويوضّح سبب تعذّر تقديم إجابة قاطعة.
  • evidence - مصدر الإجابة: source وmethod وobserved_at إضافةً إلى detail اختياري مثل http_404 أو nxdomain.
  • checked_at - وقت إنشاء DomScan للتصنيف. وفي النتائج المخزّنة مؤقتًا يكون evidence.observed_at أسبق.

أسباب القيمة unknown

  • blocked - رفضت الجهة المستهدفة الوصول، مثلًا برمز HTTP 401 أو 403 أو بتحدّي التحقق من الروبوتات.
  • rate_limited - طلبت منا الجهة المستهدفة أو السجل التمهّل، مثلًا برمز HTTP 429.
  • timeout - لم ينتهِ الفحص ضمن المهلة المحددة له.
  • ambiguous - وصلت استجابة لكنها لم تثبت الوجود ولا الغياب، مثل رمز حالة غير متوقع أو سجل مشوّه.
  • upstream_error - فشل مصدر البيانات، مثل عطل في خادم DNS أو استجابة HTTP 5xx.
  • unsupported - هذا الفحص غير متاح لهذا المُدخل، مثل نطاق TLD غير مدعوم أو منصة بلا أداة تحقق موثوقة.
{
  "classification": {
    "status": "unknown",
    "reason": "rate_limited",
    "evidence": {
      "source": "rdap",
      "method": "rdap_lookup",
      "observed_at": "2026-10-10T09:30:00.000Z",
      "detail": "http_429"
    },
    "checked_at": "2026-10-10T09:30:00.000Z"
  }
}
لا يُبلَّغ أبدًا عن فحص محظور أو محدود المعدل أو منتهي المهلة أو فاشل على أنه absent. تعامل مع القيمة unknown على أنها «حاول لاحقًا» وليس «غير موجود»، ولا تعتبر الغياب دليلًا على إمكانية المطالبة بالاسم.

الدرجات والتقديرات مع الفحوصات المجهولة

لا تحتسب الدرجات أبدًا الفحص المجهول على أنه مفقود. تستبعد درجة أمان DNS وتقدير مصادقة البريد الفحوصات المجهولة، وتبلّغ عنها في checks_unknown، وتضبط score_confidence على partial. وعندما تكون جميع الفحوصات مجهولة، تكون الدرجة والتقدير null. ويكون تقدير SSL ودرجته null مع ضبط grade_reason على certificate_not_retrieved عندما يتعذر قراءة أي شهادة، وتبلّغ درجة السمعة عن حالة الركن المجهولة بالقيمة null بدلًا من غير مركون.