> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/ar/docs/response-format

# صيغة الرد

باستخدام 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` ضمن نتيجة الأداة.

#### مثال

```bash
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 الترويسة.

```bash
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/subdomains` | `max_age=2592000` |
| `skip_cache` | `/v1/status`, `/v1/tech`, `/v1/categorize`, `/v1/identity-assets`, `/v1/identity-resolution`, `/v1/url-intelligence`, `/v1/agent-readiness`, `/v1/robots` | `max_age=0` |
| `cache_skip` | `/v1/status` | `max_age=0` |
| `cache-skip` | `/v1/status` | `max_age=0` |
| `options.prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` |
| `prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` |
| `options.skip_cache (body)` | `/v1/status/bulk` | `max_age=0` |
| `options.cache_skip (body)` | `/v1/status/bulk` | `max_age=0` |
| `options.cache-skip (body)` | `/v1/status/bulk` | `max_age=0` |
| `refresh` | `/v1/ssl/deep-scan` | `max_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/history` | 50 | 100 |
| `GET /v1/dns/history` | 100 | 1000 |
| `GET /v1/subdomains` | 500 | 2000 |
| `GET /v1/certificates` | 100 | 1000 |
| `GET /v1/watchlist` | القائمة كاملة | 100 |
| `GET /v1/watchlist/expiring` | القائمة كاملة | 100 |
| `GET /v1/watchlist/available` | القائمة كاملة | 100 |
| `GET /v1/brand-monitor` | القائمة كاملة | 100 |
| `GET /v1/email/blacklist` | 1000 | 10000 |

#### مثال

```bash
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 غير مدعوم أو منصة بلا أداة تحقق موثوقة.

```json
{
  "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` بدلًا من غير مركون.
