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

قائمة مراقبة النطاق

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

قائمة مراقبة النطاق

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

يعتمد عدد النطاقات التي يمكنك مراقبتها على خطتك. يمكن للحسابات المجانية مراقبة 5 نطاقات. يمكن للحسابات المدفوعة مراقبة نطاق واحد مقابل كل 30 رصيداً من رصيد الخطة الشهرية، وهو يكفي لفحص يومي لكل نطاق، بحد أدنى 100 وحد أقصى 1000. يمكن للحسابات المدفوعة بدون خطة شهرية مراقبة 100 نطاق. يعيد GET /v1/watchlist حدك الحالي في الحقل max_domains. تُرفض الإضافة التي تتجاوز الحد، أو المكررة، أو المدخلات غير الصالحة، ولا تكلّف أي رصيد.

المراقبة

سجّل الدخول باستخدام Google للوصول إلى قائمة مراقبة نطاقاتك الشخصية مع تنبيهات البريد الإلكتروني وwebhooks وغير ذلك.

تلقي الإشعارات عبر البريد الإلكتروني أو Telegram أو Slack أو Discord أو Webhook.

GET /v1/watchlist

احصل على جميع النطاقات في قائمة المراقبة الخاصة بك.

يدعم ترقيم الصفحات: أرسل limit (من 1 إلى 100) ومرّر next_cursor مرة أخرى بوصفه cursor. تتضمن الاستجابات has_more وnext_cursor. وإذا لم تُرسل limit تُرجع القائمة كاملة. راجع ترقيم الصفحات.

مثال الرد

{
                "watchlist": [
                {
                "domain": "startup.com",
                "added_at": "2024-01-15T10:30:00Z",
                "status": "registered",
                "expiry_date": "2025-01-15T00:00:00Z",
                "days_until_expiry": 287,
                "last_checked": "2024-03-01T12:00:00Z",
                "notify_email": "[email protected]",
                "check_count": 4
                }
                ],
                "total": 1,
                "max_domains": 333,
                "limit_basis": "monthly_credits",
                "updated_at": "2024-03-01T12:00:00Z"
                }

حقول الرد

الحقل النوع
has_more boolean
next_cursor string | null
watchlist[] object[]
watchlist[] object
watchlist[].domain string
watchlist[].added_at string
watchlist[].status string
watchlist[].last_checked string
watchlist[].expiry_date string
watchlist[].days_until_expiry integer
watchlist[].notify_email string
watchlist[].check_count integer
total integer
max_domains integer
limit_basis string
updated_at string
POST /v1/watchlist

أضف نطاقاً إلى قائمة المراقبة الخاصة بك.

نص الطلب

{
                "domain": "mydomain.com",
                "notify_email": "[email protected]"
                }

حقول الرد

الحقل النوع
success boolean
message string
watchlist[] object[]
watchlist[] object
watchlist[].domain string
watchlist[].added_at string
watchlist[].status string
watchlist[].last_checked string
watchlist[].expiry_date string
watchlist[].days_until_expiry integer
watchlist[].notify_email string
watchlist[].check_count integer
total integer
max_domains integer
limit_basis string

مثال الرد

{
  "success": true,
  "message": "Added example.org to watchlist",
  "watchlist": [
    {
      "domain": "example.com",
      "added_at": "2026-06-02T09:12:00.000Z",
      "last_checked": "2026-10-09T03:00:12.000Z",
      "status": "expiring_soon",
      "expiry_date": "2026-12-18T14:22:08Z",
      "days_until_expiry": 70,
      "notify_email": "[email protected]"
    },
    {
      "domain": "example.org",
      "added_at": "2026-10-09T10:15:30.000Z",
      "status": "unknown",
      "notify_email": "[email protected]"
    }
  ],
  "total": 2,
  "max_domains": 333,
  "limit_basis": "monthly_credits"
}
PATCH /v1/watchlist/:domain

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

نص الطلب

{
                "notify_email": "[email protected]"
                }
curl -X PATCH -H "X-API-Key: your-api-key" -H "Content-Type: application/json"                 -d '{"notify_email":"[email protected]"}' "https://domscan.net/v1/watchlist/mydomain.com"

حقول الرد

الحقل النوع
success boolean
message string
domain object
domain.domain string
domain.added_at string
domain.status string
domain.last_checked string
domain.expiry_date string
domain.days_until_expiry integer
domain.notify_email string
domain.check_count integer

مثال الرد

{
  "success": true,
  "message": "Updated example.com in your watchlist",
  "domain": {
    "domain": "example.com",
    "added_at": "2026-06-02T09:12:00.000Z",
    "status": "registered",
    "notify_email": "[email protected]",
    "check_count": 12
  }
}
DELETE /v1/watchlist?domain=mydomain.com

إزالة من قائمة المراقبة

curl -X DELETE -H "X-API-Key: your-api-key" "https://domscan.net/v1/watchlist?domain=mydomain.com"

حقول الرد

الحقل النوع
success boolean
message string
domain string
watchlist[] object[]
watchlist[] object
watchlist[].domain string
watchlist[].added_at string
watchlist[].status string
watchlist[].last_checked string
watchlist[].expiry_date string
watchlist[].days_until_expiry integer
watchlist[].notify_email string
watchlist[].check_count integer
total integer

مثال الرد

{
  "success": true,
  "message": "Request completed",
  "domain": "example.com",
  "watchlist": [
    {
      "domain": "example.com",
      "added_at": "2026-08-27T12:00:00Z",
      "status": "registered",
      "last_checked": "2026-08-27T12:00:00Z",
      "expiry_date": "2026-08-27T12:00:00Z",
      "days_until_expiry": 1,
      "notify_email": "[email protected]",
      "check_count": 1
    }
  ],
  "total": 1
}
GET /v1/watchlist/expiring?days=30

تنتهي قريباً

يدعم ترقيم الصفحات: أرسل limit (من 1 إلى 100) ومرّر next_cursor مرة أخرى بوصفه cursor. تتضمن الاستجابات has_more وnext_cursor. وإذا لم تُرسل limit تُرجع القائمة كاملة. راجع ترقيم الصفحات.

مثال الرد

{
                "expiring_domains": [
                {
                "domain": "renewal-window.com",
                "status": "expiring_soon",
                "expiry_date": "2026-05-12T00:00:00Z",
                "days_until_expiry": 28,
                "check_count": 11
                }
                ],
                "total": 1,
                "threshold_days": 30
                }

حقول الرد

الحقل النوع
has_more boolean
next_cursor string | null
expiring_domains[] object[]
expiring_domains[] object
expiring_domains[].domain string
expiring_domains[].added_at string
expiring_domains[].status string
expiring_domains[].last_checked string
expiring_domains[].expiry_date string
expiring_domains[].days_until_expiry integer
expiring_domains[].notify_email string
expiring_domains[].check_count integer
total integer
threshold_days integer
GET /v1/watchlist/available

متاح

يدعم ترقيم الصفحات: أرسل limit (من 1 إلى 100) ومرّر next_cursor مرة أخرى بوصفه cursor. تتضمن الاستجابات has_more وnext_cursor. وإذا لم تُرسل limit تُرجع القائمة كاملة. راجع ترقيم الصفحات.

مثال الرد

{
                "available_domains": [
                {
                "domain": "startupdrop.ai",
                "status": "available",
                "last_checked": "2026-04-14T08:30:00Z",
                "check_count": 18
                }
                ],
                "total": 1,
                "message": "هذه النطاقات من قائمة المراقبة الخاصة بك متاحة الآن للتسجيل!"
                }

حقول الرد

الحقل النوع
has_more boolean
next_cursor string | null
available_domains[] object[]
available_domains[] object
available_domains[].domain string
available_domains[].added_at string
available_domains[].status string
available_domains[].last_checked string
available_domains[].expiry_date string
available_domains[].days_until_expiry integer
available_domains[].notify_email string
available_domains[].check_count integer
total integer
message string

خطافات ويب التنبيهات

استقبل تنبيهات المراقبة على شكل طلبات POST موقّعة بصيغة JSON إلى نقاط نهاية HTTPS الخاصة بك. أدر نقاط النهاية بمفتاح API، أو من إعدادات المراقبة أثناء تسجيل الدخول.

أنواع الأحداث

المراقبةالأحداث
توفر عناصر قائمة المراقبة وانتهاؤها وحالتهاdomain.available domain.expiring_30 domain.expiring_14 domain.expiring_7 domain.expiring_1 domain.status_change
مراقبة تغيّر النطاقاتdomain.dns_changed domain.certificate_changed domain.registration_changed domain.hosting_changed domain.technology_changed domain.email_security_changed
مراقبة العلامة التجارية (تسجيلات جديدة لنطاقات مشابهة)brand.threat_detected
اشتراكات تنبيهات قائمة المراقبة (الشهادات والأسعار وسجلات DNS والنطاقات المشابهة)ssl.expiring ssl.expired ssl.changed price.dropped dns.changed typosquat.detected
تنبيهات تغيير العلامة التجارية (الشعارات والألوان والاسم والحسابات الاجتماعية)brand.updated
المهام غير المتزامنة (مجانية، فقط للمهام المنشأة مع notify_webhook)job.completed job.failed job.cancelled
حدث اختبار (مجاني)webhook.test

اقرأ دليل واجهة API لتنبيهات خطاف الويب

الأسعار

يكلّف كل تنبيه يُسلَّم إلى نقطة نهاية برد 2xx ما مقداره 2 رصيد. تُحجز الأرصدة قبل المحاولة الأولى مباشرة، وتُسترد إذا فشل التسليم أو أُلغي أو حُذفت نقطة النهاية. أحداث الاختبار مجانية. وعندما يكون الرصيد غير كافٍ يُتخطى التنبيه ولا يُخصم شيء.

POST /v1/webhooks

سجّل نقطة نهاية HTTPS. يجب أن يُحل العنوان إلى عنوان عام. احذف events أو مرّر ["*"] لاستقبال كل أنواع الأحداث. لا يُعاد سر التوقيع إلا في هذا الرد.

طلب مثال

curl -X POST "https://domscan.net/v1/webhooks" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/domscan",
    "events": ["domain.expiring_30", "domain.available", "domain.dns_changed"]
  }'

مثال الرد

{
  "endpoint": {
    "id": "whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3",
    "url": "https://hooks.example.com/domscan",
    "events": ["domain.available", "domain.expiring_30", "domain.dns_changed"],
    "status": "active",
    "secret_hint": "9c2e"
  },
  "secret": "whsec_..."
}

حقول الرد

الحقل النوع
endpoint object
endpoint.id string
endpoint.url string
endpoint.description string | null
endpoint.events[] string[]
endpoint.status string
endpoint.disabled_reason string | null
endpoint.consecutive_failures integer
endpoint.secret_hint string
endpoint.previous_secret_expires_at string | null
endpoint.secret_rotated_at string | null
endpoint.last_success_at string | null
endpoint.last_failure_at string | null
endpoint.last_error string | null
endpoint.created_at string
endpoint.updated_at string
endpoint.disabled_at string | null
secret string
GET /v1/webhooks

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

حقول الرد

الحقل النوع
endpoints[] object[]
endpoints[] object
endpoints[].id string
endpoints[].url string
endpoints[].description string | null
endpoints[].events[] string[]
endpoints[].status string
endpoints[].disabled_reason string | null
endpoints[].consecutive_failures integer
endpoints[].secret_hint string
endpoints[].previous_secret_expires_at string | null
endpoints[].secret_rotated_at string | null
endpoints[].last_success_at string | null
endpoints[].last_failure_at string | null
endpoints[].last_error string | null
endpoints[].created_at string
endpoints[].updated_at string
endpoints[].disabled_at string | null
available_events[] string[]
all_events string
test_event string
policy object
policy.secret_rotation_grace_seconds integer
policy.secret_rotation_credits integer
policy.credits_per_delivered_alert integer
policy.test_event_credits integer
policy.job_event_credits integer
policy.failed_deliveries_charged boolean
policy.max_endpoints integer
policy.max_attempts integer
policy.disable_after_consecutive_failures integer
policy.signature_tolerance_seconds integer

مثال الرد

{
  "endpoints": [
    {
      "id": "example-id",
      "url": "https://example.com",
      "events": [
        "example"
      ],
      "status": "active",
      "secret_hint": "example",
      "created_at": "2026-08-27T12:00:00Z",
      "description": "example",
      "disabled_reason": "customer",
      "consecutive_failures": 1,
      "previous_secret_expires_at": "2026-08-27T12:00:00Z",
      "secret_rotated_at": "2026-08-27T12:00:00Z",
      "last_success_at": "2026-08-27T12:00:00Z",
      "last_failure_at": "2026-08-27T12:00:00Z",
      "last_error": "example",
      "updated_at": "2026-08-27T12:00:00Z",
      "disabled_at": "2026-08-27T12:00:00Z"
    }
  ],
  "available_events": [
    "domain.available"
  ],
  "policy": {
    "credits_per_delivered_alert": 2,
    "test_event_credits": 0,
    "failed_deliveries_charged": false,
    "max_endpoints": 1,
    "max_attempts": 1,
    "disable_after_consecutive_failures": 1,
    "signature_tolerance_seconds": 1,
    "secret_rotation_grace_seconds": 86400,
    "secret_rotation_credits": 0,
    "job_event_credits": 0
  },
  "all_events": "*",
  "test_event": "webhook.test"
}
PATCH /v1/webhooks/:webhook_id

أوقف نقطة نهاية مؤقتًا أو فعّلها، أو غيّر أحداثها أو عدّل وصفها. يؤدي تفعيل نقطة النهاية إلى تصفير عدد الإخفاقات.

{ "enabled": true, "events": ["*"] }

حقول الرد

الحقل النوع
endpoint object
endpoint.id string
endpoint.url string
endpoint.description string | null
endpoint.events[] string[]
endpoint.status string
endpoint.disabled_reason string | null
endpoint.consecutive_failures integer
endpoint.secret_hint string
endpoint.previous_secret_expires_at string | null
endpoint.secret_rotated_at string | null
endpoint.last_success_at string | null
endpoint.last_failure_at string | null
endpoint.last_error string | null
endpoint.created_at string
endpoint.updated_at string
endpoint.disabled_at string | null

مثال الرد

{
  "endpoint": {
    "id": "example-id",
    "url": "https://example.com",
    "events": [
      "example"
    ],
    "status": "active",
    "secret_hint": "example",
    "created_at": "2026-08-27T12:00:00Z",
    "description": "example",
    "disabled_reason": "customer",
    "consecutive_failures": 1,
    "previous_secret_expires_at": "2026-08-27T12:00:00Z",
    "secret_rotated_at": "2026-08-27T12:00:00Z",
    "last_success_at": "2026-08-27T12:00:00Z",
    "last_failure_at": "2026-08-27T12:00:00Z",
    "last_error": "example",
    "updated_at": "2026-08-27T12:00:00Z",
    "disabled_at": "2026-08-27T12:00:00Z"
  }
}
DELETE /v1/webhooks/:webhook_id

احذف نقطة نهاية. تُلغى عمليات التسليم المعلقة وتُسترد أي أرصدة محجوزة.

حقول الرد

الحقل النوع
id string
deleted boolean

مثال الرد

{
  "id": "example-id",
  "deleted": true
}
POST /v1/webhooks/:webhook_id/test

أرسل حدث webhook.test واحدًا مجانًا وأعد النتيجة. لا تُعاد محاولة أحداث الاختبار ولا تُحتسب ضمن الإيقاف المؤقت التلقائي.

حقول الرد

الحقل النوع
delivery object
delivery.id string
delivery.endpoint_id string
delivery.event_id string
delivery.event_type string
delivery.status string
delivery.attempts integer
delivery.next_attempt_at string | null
delivery.last_attempt_at string | null
delivery.response_status integer | null
delivery.last_error string | null
delivery.credits_charged integer
delivery.refunded boolean
delivery.created_at string
delivery.delivered_at string | null
delivered boolean

مثال الرد

{
  "delivery": {
    "id": "example-id",
    "endpoint_id": "example",
    "event_id": "example",
    "event_type": "domain",
    "status": "pending",
    "attempts": 1,
    "next_attempt_at": "2026-08-27T12:00:00Z",
    "last_attempt_at": "2026-08-27T12:00:00Z",
    "response_status": 1,
    "last_error": "example",
    "credits_charged": 1,
    "refunded": false,
    "created_at": "2026-08-27T12:00:00Z",
    "delivered_at": "2026-08-27T12:00:00Z"
  },
  "delivered": false
}
POST /v1/webhooks/:webhook_id/rotate-secret

استبدل سر التوقيع لنقطة نهاية، بما في ذلك نقطة نهاية موقوفة مؤقتًا. يُعاد السر الجديد في هذه الاستجابة فقط. خلال الـ 24 ساعة التالية يُوقَّع كل تسليم بالسر الجديد والسر السابق معًا. التدوير مجاني.

طلب مثال

curl -X POST "https://domscan.net/v1/webhooks/whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3/rotate-secret" \
  -H "X-API-Key: $DOMSCAN_API_KEY"

مثال الرد

{
  "endpoint": {
    "id": "whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3",
    "status": "active",
    "secret_hint": "4b7a",
    "previous_secret_expires_at": "2026-10-11T12:00:00.000Z"
  },
  "secret": "whsec_...",
  "previous_secret_expires_at": "2026-10-11T12:00:00.000Z",
  "grace_period_seconds": 86400
}

حقول الرد

الحقل النوع
endpoint object
endpoint.id string
endpoint.url string
endpoint.description string | null
endpoint.events[] string[]
endpoint.status string
endpoint.disabled_reason string | null
endpoint.consecutive_failures integer
endpoint.secret_hint string
endpoint.previous_secret_expires_at string | null
endpoint.secret_rotated_at string | null
endpoint.last_success_at string | null
endpoint.last_failure_at string | null
endpoint.last_error string | null
endpoint.created_at string
endpoint.updated_at string
endpoint.disabled_at string | null
secret string
previous_secret_expires_at string
grace_period_seconds integer
GET /v1/webhooks/:webhook_id/deliveries

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

المعاملالنوعDescription
limit integer عدد عمليات التسليم المراد إعادتها، من 1 إلى 100. القيمة الافتراضية 50.

اعرض عمليات التسليم الأخيرة مع حالتها وعدد المحاولات ورد HTTP والأرصدة المخصومة والمبالغ المستردة. تُحفظ سجلات التسليم لمدة 30 يومًا.

حقول الرد

الحقل النوع
endpoint_id string
deliveries[] object[]
deliveries[] object
deliveries[].id string
deliveries[].endpoint_id string
deliveries[].event_id string
deliveries[].event_type string
deliveries[].status string
deliveries[].attempts integer
deliveries[].next_attempt_at string | null
deliveries[].last_attempt_at string | null
deliveries[].response_status integer | null
deliveries[].last_error string | null
deliveries[].credits_charged integer
deliveries[].refunded boolean
deliveries[].created_at string
deliveries[].delivered_at string | null

مثال الرد

{
  "endpoint_id": "example",
  "deliveries": [
    {
      "id": "example-id",
      "endpoint_id": "example",
      "event_id": "example",
      "event_type": "domain",
      "status": "pending",
      "attempts": 1,
      "next_attempt_at": "2026-08-27T12:00:00Z",
      "last_attempt_at": "2026-08-27T12:00:00Z",
      "response_status": 1,
      "last_error": "example",
      "credits_charged": 1,
      "refunded": false,
      "created_at": "2026-08-27T12:00:00Z",
      "delivered_at": "2026-08-27T12:00:00Z"
    }
  ]
}

تنسيق الطلب

كل تنبيه هو طلب POST بنص JSON. يبقى الحقل id ثابتًا للحدث الواحد ويتكرر في X-DomScan-Event-Id، فيمكنك تجاهل المحاولات المعادة التي عالجتها سابقًا.

POST /domscan HTTP/1.1
Content-Type: application/json
X-DomScan-Event: domain.expiring_30
X-DomScan-Event-Id: evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9
X-DomScan-Timestamp: 1791633600
X-DomScan-Signature: sha256=...

{
  "id": "evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9",
  "type": "domain.expiring_30",
  "created": "2026-10-10T12:00:00.000Z",
  "data": {
    "domain": "acme.io",
    "previous_status": "registered",
    "current_status": "expiring_soon",
    "expiry_date": "2026-11-09T00:00:00Z",
    "days_until_expiry": 30,
    "checked_at": "2026-10-10T12:00:00.000Z"
  }
}

التحقق من التوقيعات

احسب HMAC-SHA256 لقيمة X-DomScan-Timestamp متبوعة بنقطة ثم نص الطلب الخام، مستخدمًا سر نقطة النهاية. قارن النتيجة بالقيمة في X-DomScan-Signature بمقارنة ثابتة الزمن، وارفض الطلبات التي يزيد عمر طابعها الزمني على 5 دقيقة.

يتحقق المثال أدناه من كل توقيع في الترويسة، لذا يستمر عمله أثناء تدوير السر.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before JSON parsing.
function verifyDomScanWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-domscan-timestamp'];
  const header = headers['x-domscan-signature'] || '';
  if (!/^\d{10}$/.test(timestamp || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = Buffer.from('sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex'));
  // One entry normally; two during a secret rotation (new secret first).
  return header.split(',').some((entry) => {
    const candidate = Buffer.from(entry.trim());
    return candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected);
  });
}

تدوير سر التوقيع

خلال فترة السماح البالغة 24 ساعة بعد التدوير، يحتوي X-DomScan-Signature على توقيعين مفصولين بفاصلة، ويأتي توقيع السر الجديد أولًا كما يظهر أدناه. اقبل الطلب إذا طابق أي توقيع سرًا تثق به، ثم انشر السر الجديد وبعدها أوقف الوثوق بالسر القديم. إذا دوّرت مرة أخرى خلال فترة السماح، يُلغى السر السابق الأقدم فورًا.

X-DomScan-Signature: sha256=<new>,sha256=<previous>

إعادة المحاولة والإيقاف المؤقت التلقائي

أعد أي حالة 2xx خلال 8 ثوانٍ لتأكيد استلام التنبيه. تُعاد محاولة عمليات إعادة التوجيه وحالات الرد الأخرى وانتهاء المهلة بتراجع أسي (1 و4 و16 و64 و256 دقيقة)، بحد أقصى 6 محاولة إجمالًا. بعد 15 محاولة فاشلة متتالية تُوقَف نقطة النهاية مؤقتًا؛ فعّلها من جديد باستخدام PATCH أو من إعدادات المراقبة.

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

اشتراكات تنبيهات قائمة المراقبة

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

النوعالأحداثمتى يُطلق
sslssl.expiring ssl.expired ssl.changedيُطلق ssl.expiring عندما تنتهي صلاحية الشهادة التي يقدمها اسم المضيف خلال ssl_expiring_days (30 أو 14 أو 7 أو 1، والافتراضي 14)، مرة واحدة لكل شهادة وكل حد. يُطلق ssl.expired مرة واحدة لكل شهادة منتهية الصلاحية. يُطلق ssl.changed عند رصد بصمة شهادة جديدة في فحصين متتاليين، وتوضح الحمولة ما إذا كانت الجهة المُصدِرة قد تغيّرت.
priceprice.droppedعندما ينخفض سعر التسجيل أو التجديد لـ TLD، لدى مسجّل محدد أو لدى الأرخص، بما لا يقل عن drop_percent عن أعلى سعر منذ آخر تنبيه، أو يصل إلى target_price أو أقل. تأتي الأسعار من لقطة التسعير اليومية، وتُقيَّم كل لقطة مرة واحدة.
dnsdns.changedعندما يعيد نوع سجل مراقَب (A أو AAAA أو MX أو NS أو TXT أو CNAME) لأي اسم مضيف الإجابة الجديدة نفسها في عمليتي بحث متتاليتين مؤكدتين.
typosquattyposquat.detectedعندما يُسجَّل نطاق مشابه لنطاق العلامة التجارية حديثًا ويتأكد ذلك عبر بحث تسجيل موثوق. المسح الكامل الأول للنطاقات المشابهة يحدد خط الأساس ولا يرسل تنبيهًا.
brandbrand.updatedعندما يتغير الشعار المربع أو الشعار العريض أو الألوان أو الاسم أو الحسابات الاجتماعية المعلنة لنطاق علامة تجارية، ويظهر التغيير مجددًا في الفحص التالي. اختر ما تريد مراقبته عبر attributes (logo وwide_logo وcolors وname وsocials؛ الكل افتراضيًا). يحدد الفحص الأول خط الأساس ولا يُرسل تنبيهًا، وتبقى أي سمة تعذّر فحصها دون تغيير.

الأدلة الدقيقة وحدها تطلق حدثًا. فشل مصافحة TLS، وبحث DNS الذي يفشل أو تنتهي مهلته، والسعر المفقود، والبحث المحظور أو المحدود المعدل كلها حالات غير معروفة: لا تغيّر شيئًا ولا تُرسل تنبيهًا ولا تُحتسب أي رسوم. أول فحص مؤكد للاشتراك يحدد خط الأساس الخاص به.

تعمل الفحوصات تلقائيًا: الشهادات كل 12 ساعة، وسجلات DNS كل ساعة (مع فحص تأكيدي بعد 15 دقيقة من رصد التغيير أول مرة)، والأسعار كل ساعتين بالمقارنة مع اللقطة اليومية، والنطاقات المشابهة على دفعات من 30 مع مسح كامل كل يوم. بعد فحص غير معروف يأتي المحاولة التالية أبكر. تُفحص اشتراكات العلامات التجارية مرة واحدة يوميًا، مع فحص تأكيدي بعد 90 دقيقة من رصد التغيير لأول مرة.

إنشاء الاشتراكات وتشغيل الفحوصات مجاني. كل تنبيه يُسلَّم إلى نقطة Webhook باستجابة 2xx يكلّف 2 رصيدًا، مثل أي تنبيه مراقبة آخر. تُسترد رسوم عمليات التسليم الفاشلة، ويمكن أن يضم الحساب ما يصل إلى 100 اشتراك، منها 20 للنطاقات المشابهة.

POST /v1/watchlist/alerts

أنشئ اشتراكًا. يحدد type الحقول المطبّقة: domain لـ ssl وdns وtyposquat، وtld وregistrar وprice_type وdrop_percent وtarget_price لـ price. تُرفض الحقول التي لا تنطبق على النوع.

نص الطلب

المعاملالنوعDescription
typestringssl أو price أو dns أو typosquat. مطلوب.
domainstringاسم المضيف المراد مراقبته لـ ssl وdns، أو نطاق العلامة التجارية لـ typosquat.
tldstringالـ TLD المراد مراقبته لـ price، مثل com.
registrarstringمعرّف المسجّل لـ price. احذفه لمراقبة أرخص مسجّل.
eventsstring[]الأحداث المراد استلامها. الافتراضي هو كل أحداث النوع.
ssl_expiring_daysintegerعدد الأيام قبل الانتهاء لـ ssl.expiring: 30 أو 14 أو 7 أو 1. الافتراضي 14.
price_typestringregistration (الافتراضي) أو renewal.
drop_percentnumberأرسل تنبيهًا عند انخفاض لا تقل نسبته عن هذه النسبة المئوية، من 1 إلى 95.
target_pricenumberأرسل تنبيهًا عندما يصل السعر بالدولار الأمريكي إلى هذا المبلغ أو أقل. يتطلب اشتراك السعر drop_percent أو target_price أو كليهما.
record_typesstring[]أنواع السجلات المراد مراقبتها لـ dns. الافتراضي A وAAAA وMX وNS وTXT وCNAME.
notify_emailstringاختياري. يرسل أيضاً كل تنبيه من هذا الاشتراك بالبريد الإلكتروني إلى هذا العنوان (3 أرصدة لكل بريد مرسل). لا يتغير التسليم عبر Webhook. غيّره لاحقاً باستخدام PATCH، أو أرسل null لإيقاف الرسائل.

طلب مثال

curl -X POST "https://domscan.net/v1/watchlist/alerts" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "price",
    "tld": "com",
    "registrar": "porkbun",
    "price_type": "renewal",
    "drop_percent": 10,
    "target_price": 9.5
  }'

مثال الرد

{
  "subscription": {
    "id": "mas_8c1f0e2d3b4a59687766554433221100",
    "type": "price",
    "target": "com",
    "registrar": "porkbun",
    "events": ["price.dropped"],
    "status": "active",
    "price_type": "renewal",
    "drop_percent": 10,
    "target_price": 9.5,
    "currency": "USD",
    "observed": null,
    "last_check_status": null,
    "next_check_at": "2026-10-10T12:00:00.000Z"
  }
}

حقول الرد

الحقل النوع
subscription object
subscription.id string
subscription.type string
subscription.target string
subscription.registrar string | null
subscription.events[] string[]
subscription.status string
subscription.ssl_expiring_days integer | null
subscription.price_type string | null
subscription.drop_percent number | null
subscription.target_price number | null
subscription.currency string | null
subscription.record_types[] string[]
subscription.attributes[] string[]
subscription.notify_email string | null
subscription.observed object | null
subscription.last_check_at string | null
subscription.last_check_status string | null
subscription.last_error string | null
subscription.next_check_at string | null
subscription.created_at string
subscription.updated_at string
GET /v1/watchlist/alerts

اعرض اشتراكاتك مع أحدث دليل مؤكد وحالة الفحص، والأحداث التي يدعمها كل نوع، وجدول الفحص، وسعر التنبيه.

حقول الرد

الحقل النوع
subscriptions[] object[]
subscriptions[] object
subscriptions[].id string
subscriptions[].type string
subscriptions[].target string
subscriptions[].registrar string | null
subscriptions[].events[] string[]
subscriptions[].status string
subscriptions[].ssl_expiring_days integer | null
subscriptions[].price_type string | null
subscriptions[].drop_percent number | null
subscriptions[].target_price number | null
subscriptions[].currency string | null
subscriptions[].record_types[] string[]
subscriptions[].attributes[] string[]
subscriptions[].notify_email string | null
subscriptions[].observed object | null
subscriptions[].last_check_at string | null
subscriptions[].last_check_status string | null
subscriptions[].last_error string | null
subscriptions[].next_check_at string | null
subscriptions[].created_at string
subscriptions[].updated_at string
total integer
available_types object
available_types.ssl[] string[]
available_types.price[] string[]
available_types.dns[] string[]
available_types.typosquat[] string[]
available_types.brand[] string[]
policy object
policy.credits_per_delivered_alert integer
policy.check_credits integer
policy.unknown_checks_charged boolean
policy.max_subscriptions integer
policy.max_typosquat_subscriptions integer
policy.max_brand_subscriptions integer
policy.brand_attributes[] string[]
policy.ssl_expiring_days[] integer[]
policy.default_ssl_expiring_days integer
policy.record_types[] string[]
policy.price_types[] string[]
policy.check_interval_minutes object
policy.confirmation_checks object

مثال الرد

{
  "subscriptions": [
    {
      "id": "example-id",
      "type": "ssl",
      "target": "example",
      "registrar": "example",
      "events": [
        "ssl.expiring"
      ],
      "status": "active",
      "ssl_expiring_days": 30,
      "price_type": "registration",
      "drop_percent": 0.5,
      "target_price": 0.5,
      "currency": "USD",
      "record_types": [
        "A"
      ],
      "attributes": [
        "logo"
      ],
      "notify_email": "[email protected]",
      "observed": {},
      "last_check_at": "2026-08-27T12:00:00Z",
      "last_check_status": "baseline",
      "last_error": "example",
      "next_check_at": "2026-08-27T12:00:00Z",
      "created_at": "2026-08-27T12:00:00Z",
      "updated_at": "2026-08-27T12:00:00Z"
    }
  ],
  "total": 1,
  "available_types": {
    "ssl": [
      "ssl.expiring"
    ],
    "price": [
      "price.dropped"
    ],
    "dns": [
      "dns.changed"
    ],
    "typosquat": [
      "typosquat.detected"
    ],
    "brand": [
      "brand.updated"
    ]
  },
  "policy": {
    "credits_per_delivered_alert": 2,
    "check_credits": 0,
    "unknown_checks_charged": false,
    "max_subscriptions": 1,
    "check_interval_minutes": {},
    "max_typosquat_subscriptions": 1,
    "max_brand_subscriptions": 1,
    "brand_attributes": [
      "logo"
    ],
    "ssl_expiring_days": [
      1
    ],
    "default_ssl_expiring_days": 1,
    "record_types": [
      "A"
    ],
    "price_types": [
      "registration"
    ],
    "confirmation_checks": {}
  }
}
GET /v1/watchlist/alerts/:subscription_id

اجلب اشتراكًا واحدًا مع أحدث دليل مؤكد له وآخر 20 حدثًا.

حقول الرد

الحقل النوع
subscription object
subscription.id string
subscription.type string
subscription.target string
subscription.registrar string | null
subscription.events[] string[]
subscription.status string
subscription.ssl_expiring_days integer | null
subscription.price_type string | null
subscription.drop_percent number | null
subscription.target_price number | null
subscription.currency string | null
subscription.record_types[] string[]
subscription.attributes[] string[]
subscription.notify_email string | null
subscription.observed object | null
subscription.last_check_at string | null
subscription.last_check_status string | null
subscription.last_error string | null
subscription.next_check_at string | null
subscription.created_at string
subscription.updated_at string
events[] object[]
events[] object
events[].id string
events[].event_type string
events[].detected_at string
events[].published_at string | null
events[].data object

مثال الرد

{
  "subscription": {
    "id": "example-id",
    "type": "ssl",
    "target": "example",
    "registrar": "example",
    "events": [
      "ssl.expiring"
    ],
    "status": "active",
    "ssl_expiring_days": 30,
    "price_type": "registration",
    "drop_percent": 0.5,
    "target_price": 0.5,
    "currency": "USD",
    "record_types": [
      "A"
    ],
    "attributes": [
      "logo"
    ],
    "notify_email": "[email protected]",
    "observed": {},
    "last_check_at": "2026-08-27T12:00:00Z",
    "last_check_status": "baseline",
    "last_error": "example",
    "next_check_at": "2026-08-27T12:00:00Z",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z"
  },
  "events": [
    {
      "id": "example-id",
      "event_type": "ssl.expiring",
      "detected_at": "2026-08-27T12:00:00Z",
      "published_at": "2026-08-27T12:00:00Z",
      "data": {}
    }
  ]
}
PATCH /v1/watchlist/alerts/:subscription_id

أوقف اشتراكًا مؤقتًا أو استأنفه عبر enabled، أو غيّر events أو ssl_expiring_days أو drop_percent أو target_price أو record_types. لا يرسل السعر المستهدف الجديد تنبيهًا إلا عند حدوث تغيّر لاحق في السعر.

{ "enabled": false }
{ "notify_email": "[email protected]" }

حقول الرد

الحقل النوع
subscription object
subscription.id string
subscription.type string
subscription.target string
subscription.registrar string | null
subscription.events[] string[]
subscription.status string
subscription.ssl_expiring_days integer | null
subscription.price_type string | null
subscription.drop_percent number | null
subscription.target_price number | null
subscription.currency string | null
subscription.record_types[] string[]
subscription.attributes[] string[]
subscription.notify_email string | null
subscription.observed object | null
subscription.last_check_at string | null
subscription.last_check_status string | null
subscription.last_error string | null
subscription.next_check_at string | null
subscription.created_at string
subscription.updated_at string

مثال الرد

{
  "subscription": {
    "id": "example-id",
    "type": "ssl",
    "target": "example",
    "registrar": "example",
    "events": [
      "ssl.expiring"
    ],
    "status": "active",
    "ssl_expiring_days": 30,
    "price_type": "registration",
    "drop_percent": 0.5,
    "target_price": 0.5,
    "currency": "USD",
    "record_types": [
      "A"
    ],
    "attributes": [
      "logo"
    ],
    "notify_email": "[email protected]",
    "observed": {},
    "last_check_at": "2026-08-27T12:00:00Z",
    "last_check_status": "baseline",
    "last_error": "example",
    "next_check_at": "2026-08-27T12:00:00Z",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z"
  }
}
DELETE /v1/watchlist/alerts/:subscription_id

احذف اشتراكًا. تُسقَط الأحداث التي لم تُرسل بعد ولا تُحتسب عليها أي رسوم.

حقول الرد

الحقل النوع
id string
deleted boolean

مثال الرد

{
  "id": "example-id",
  "deleted": true
}

مثال على حدث dns.changed

{
  "id": "evt_2b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e",
  "type": "dns.changed",
  "created": "2026-10-10T12:15:00.000Z",
  "data": {
    "domain": "partner-shop.example",
    "changes": [
      {
        "record_type": "MX",
        "before": ["10 mx1.mail.example"],
        "after": ["10 mx.other-mail.example"],
        "added": ["10 mx.other-mail.example"],
        "removed": ["10 mx1.mail.example"],
        "first_seen_at": "2026-10-10T12:00:00.000Z"
      }
    ],
    "confirmed_checks": 2,
    "confirmed_at": "2026-10-10T12:15:00.000Z",
    "subscription_id": "mas_8c1f0e2d3b4a59687766554433221100"
  }
}