account/monitors – التوثيق

التكاليف والحدود

التكاليف والحدود
ماذا	الأرصدة
مراقب يُفحص كل يوم، لمدة 30 يومًا	50
مراقب يُفحص كل 3 أيام، لمدة 30 يومًا	40
مراقب يُفحص كل 7 أيام، لمدة 30 يومًا	20
مراقب يُفحص كل 30 أيام، لمدة 30 يومًا	10
كل فحص ناجح إضافي خلال الفترة	+2

الحد: 30 طلب في الدقيقة. الإنشاء والتعديل والحذف: 10 في الدقيقة.

إنشاء المراقب والخط الأساسي الأول مجانيان. وتُحتسب دورة من 30 يومًا بمجرد أن يصبح المراقب نشطًا. يتوقف السعر على فاصل الفحص ويغطي جميع الفحوص التي يجدولها الفاصل ضمن دورة واحدة.

الفاصل الواقع بين درجتين يكلّف بقدر الدرجة الأكثر تكرارًا التالية: كل أربعة أيام يكلّف بقدر كل ثلاثة أيام.

تحدث الفحوص الإضافية أساسًا عندما تقصّر الفاصل في منتصف دورة. ويكلّف كل فحص إضافي ناجح المبلغ المذكور في الجدول.

بعد 30 يومًا تتجدد الدورة تلقائيًا بالسعر الساري حينها. والفحوص الفاشلة لا تكلّف شيئًا. وعند الإيقاف المؤقت أو الأرشفة أو تغيير الفاصل لا نردّ شيئًا.

يمكن أن يكون لكل حساب حتى 50 مراقب في الوقت نفسه، واحد لكل شركة. وخلال 24 ساعة يمكنك إنشاء حتى 50 مراقب؛ وتُحتسب المؤرشفة أيضًا.

تحصل على سعر فاصل ما مجانًا عبر GET /v1/account/monitoring/pricing، هنا لفحص كل سبعة أيام:

curl -G "https://handelsregister.ai/api/v1/account/monitoring/pricing" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'poll_interval_days=7'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitoring/pricing",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "poll_interval_days": "7",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/account/monitoring/pricing");
url.searchParams.append("poll_interval_days", "7");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

1{2  "pricing": {3    "policy_version": "2026-08.v2",4    "credits_per_run": 2,5    "cycle_minimum_credits": 20,6    "included_runs": 5,7    "cycle_days": 30,8    "estimated_runs": 5,9    "estimated_credits": 2010  },11  "entitled": true,12  "meta": {13    "request_credit_cost": 0,14    "credits_remaining": 14515  }16}

200 · مثال على استجابة: السعر لمراقب بفحص كل 7 أيام

كيف يعمل المراقب

الإنشاء. تحدد الشركة وفاصل الفحص ونقطة نهاية webhook موثّقة واحدة على الأقل. يبدأ المراقب بالحالة initializing.
الخط الأساسي. نسجّل إشارات الأيام القليلة الأخيرة كمعروفة. ولا تُسلَّم، لذا تحصل فقط على ما هو جديد بعد ذلك.
التفعيل. نحتسب الدورة، ويصبح المراقب active ويفحص للمرة الأولى فورًا.
الفحص. بعد ذلك يفحص بالفاصل المختار. وتطلق كل إشارة جديدة رسالة واحدة لكل مراقب إلى نقاط نهاية webhook الخاصة بك.
التجديد. بعد كل دورة تُحتسب الدورة التالية تلقائيًا، ما دام رصيدك يغطيها.

فاصل الفحص بين 1 و30 يومًا. وقد يتفاوت الوقت الدقيق للفحص ضمن ساعة. وينظر كل فحص بضعة أيام إلى الوراء، لكي تصل حتى القيود المنشورة متأخرة.

يسلّم المراقب مواضيع Signals الخاصة بخطتك: خمسة في كل حساب، و«حالات الإعسار» مع Pro، و«التحويلات والاندماج والاستحواذ» مع Max. ويحمل الـ webhook الإشارة نفسها في الحقل data.signal كما تفعل signals.

الحالة
الحالة	المعنى
initializing	أُنشئ؛ والخط الأساسي والتفعيل قيد التنفيذ.
active	يفحص بالفاصل المختار.
paused_user	أوقفته أنت مؤقتًا.
paused_configuration	لم تعد هناك نقطة نهاية webhook نشطة وموثّقة متصلة.
paused_billing	رصيدك لا يغطي الدورة أو فحصًا إضافيًا. أو تغيّر السعر وينتظر موافقتك.
error	فشلت عدة فحوص متتالية.
archived	انتهى نهائيًا. لا يزال بإمكانك قراءة المراقب بمعرّفه، لكنه لم يعد يظهر في القائمة.

للمراقبات الموقوفة مؤقتًا وللأخطاء يشرح status_reason السبب، مثل no_verified_endpoint أو insufficient_cycle_floor.

نقاط النهاية

جميع المسارات تحت /v1/account. تقرأ وتكتب بمفتاح API الخاص بك في الـ Header ‏x-api-key.

الطريقة
الطريقة	المسار	الغرض
GET	`/v1/account/monitors`	جميع المراقبات، الأحدث أولًا، دون المؤرشفة.
POST	`/v1/account/monitors`	إنشاء مراقب.
GET	`/v1/account/monitors/{id}`	مراقب واحد مع دورته وأحدث فحوصه.
PATCH	`/v1/account/monitors/{id}`	تغيير فاصل الفحص.
POST	`/v1/account/monitors/{id}/pause`	إيقاف مؤقت.
POST	`/v1/account/monitors/{id}/resume`	استئناف.
DELETE	`/v1/account/monitors/{id}`	أرشفة.
GET	`/v1/account/monitoring/pricing`	سعر فاصل.

Idempotency-Key

يحتاج كل طلب كتابة إلى الـ Header ‏Idempotency-Key، قيمة فريدة لكل عملية، ويُفضَّل UUID. ودونه تجيب الـ API بـ 428.

إذا كررت طلبًا بالمفتاح نفسه والبيانات نفسها خلال 24 ساعة، تحصل على الاستجابة المخزنة. وهي تحمل الـ Header ‏Idempotency-Status: replayed. وبذلك لا يُنشئ خطأ في الشبكة مراقبًا ثانيًا.

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

يُسمح بما يصل إلى 128 حرفًا: حروف وأرقام و. _ : -. الحرف الأول حرف أو رقم. والمفتاح بأي صيغة أخرى يُرجع 400.

إنشاء مراقب

تحتاج إلى entity_id الخاص بالشركة ونقطة نهاية webhook موثّقة واحدة على الأقل، انظر account/webhook-endpoints.

curl -X POST "https://handelsregister.ai/api/v1/account/monitors" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "94eb910fef13f94585c48c263fa446d4",
    "label": "Hetzner Online GmbH",
    "poll_interval_days": 7,
    "endpoint_ids": [
        "wep_01m6b3j1g0cdz98hw8zdefbf52"
    ]
}'

import uuid
import requests

response = requests.post(
    "https://handelsregister.ai/api/v1/account/monitors",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "entity_id": "94eb910fef13f94585c48c263fa446d4",
        "label": "Hetzner Online GmbH",
        "poll_interval_days": 7,
        "endpoint_ids": [
            "wep_01m6b3j1g0cdz98hw8zdefbf52"
        ]
    },
)
data = response.json()

const response = await fetch("https://handelsregister.ai/api/v1/account/monitors", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "entity_id": "94eb910fef13f94585c48c263fa446d4",
      "label": "Hetzner Online GmbH",
      "poll_interval_days": 7,
      "endpoint_ids": [
          "wep_01m6b3j1g0cdz98hw8zdefbf52"
      ]
  }),
});
const data = await response.json();

المعاملات
الاسم	النوع	الوصف	مثال
Idempotency-KeyHeader	نص (string)إلزامي	قيمة فريدة لكل عملية، ويُفضَّل UUID. انظر Idempotency-Key.الحدود: من 1 إلى 128 حرفًا	`req-20260802-01`
entity_idBody	نص (string)إلزامي	`entity_id` الخاص بالشركة من fetch-organization أو search-organizations.الحدود: من 1 إلى 128 حرفًا	`94eb910fef13f94585c48c263fa446d4`
labelBody	نص (string)اختياري	اسم للمراقب.الحدود: 200 حرفًا على الأكثر	`Hetzner Online GmbH`
poll_interval_daysBody	عدد صحيح (integer)إلزامي	فاصل الفحص بالأيام.الحدود: من 1 إلى 30	`7`
endpoint_idsBody	قائمة من stringإلزامي	معرّفات نقاط نهاية webhook الخاصة بك (`wep_…`). ويجب أن تكون كلٌّ منها نشطة وموثّقة.الحدود: من 1 إلى 10 عنصرًا	`["wep_01m6b3j1g0cdz98hw8zdefbf52"]`

تجيب الـ API بـ 202: أُنشئ المراقب، والخط الأساسي والتفعيل يجريان في الخلفية. ويُظهر meta.billing.charged_credits أنه لم يُحتسب شيء مقابل ذلك.

1{2  "monitor": {3    "id": "mon_01m6b3m7945dn7cyvexzv41kjz",4    "type": "organization.signals",5    "entity_id": "94eb910fef13f94585c48c263fa446d4",6    "label": "Hetzner Online GmbH",7    "poll_interval_days": 7,8    "status": "initializing",9    "status_reason": null,10    "pricing_policy_version": "2026-08.v2",11    "baseline_completed_at": null,12    "activated_at": null,13    "last_succeeded_at": null,14    "next_poll_at": null,15    "created_at": "2026-11-01T08:29:13+00:00"16  },17  "meta": {18    "message": "Monitor created; the free baseline is queued and this request charged 0 credits. The cycle price is charged only when activation succeeds.",19    "baseline_queued": true,20    "billing": {21      "charged_credits": 0,22      "new_cycle": false,23      "floor_transaction_id": null24    },25    "request_credit_cost": 0,26    "credits_remaining": 14527  }28}

202 · مثال على استجابة: مراقب جديد، في مثالنا لـ Hetzner Online GmbH، Ansbach HRB 6089

عبر الـ API تحدد نقاط نهاية webhook عند إنشاء المراقب. وتربط نقطة نهاية webhook أخرى تحت الحساب › المراقبة عبر «ربط وجهة»، دون تكلفة إضافية.

عرض المراقبات وتعديلها

يُرجع GET /v1/account/monitors حتى 100 مراقب تحت monitors، مع total. والمؤرشفة ليست في القائمة.

يُظهر GET /v1/account/monitors/{id} أيضًا الدورة الحالية في billing_cycle وأحدث الفحوص في recent_runs.

curl -G "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec" \
  -H "x-api-key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

1{2  "monitor": {3    "id": "mon_01m65pn3vm11sjjp1j076cbvec",4    "type": "organization.signals",5    "entity_id": "94eb910fef13f94585c48c263fa446d4",6    "label": "Hetzner Online GmbH",7    "poll_interval_days": 1,8    "status": "active",9    "status_reason": null,10    "pricing_policy_version": "2026-08.v2",11    "baseline_completed_at": "2026-10-30T06:06:28+00:00",12    "activated_at": "2026-10-30T06:06:28+00:00",13    "last_succeeded_at": "2026-10-30T06:06:53+00:00",14    "next_poll_at": "2026-10-31T06:19:12+00:00",15    "created_at": "2026-10-30T06:06:18+00:00"16  },17  "billing_cycle": {18    "starts_at": "2026-10-30T06:06:28+00:00",19    "ends_at": "2026-11-29T06:06:28+00:00",20    "floor_credits": 50,21    "credits_per_run": 2,22    "included_runs": 30,23    "successful_runs": 1,24    "extra_credits_settled": 0,25    "pricing_policy_version": "2026-08.v2"26  },27  "recent_runs": [28    {29      "due_slot_at": "2026-10-30T06:06:28+00:00",30      "kind": "activation_catchup",31      "status": "succeeded",32      "charge_state": "covered",33      "charge_credits": 0,34      "events_new": 0,35      "finished_at": "2026-10-30T06:06:55+00:00"36    }37  ],38  "meta": {39    "request_credit_cost": 0,40    "credits_remaining": 14541  }42}

200 · مثال على استجابة: مراقب نشط بفحص يومي، مرة أخرى لـ Hetzner Online GmbH

حقول المراقب
الحقل	المعنى
id	معرّف المراقب، يبدأ بـ `mon_`.
entity_id	الشركة المراقَبة.
poll_interval_days	فاصل الفحص بالأيام.
status, status_reason	الحالة، انظر أعلاه. ويذكر `status_reason` السبب.
baseline_completed_at, activated_at, last_succeeded_at	أوقات الخط الأساسي والتفعيل وآخر فحص ناجح.
next_poll_at	الفحص المجدول التالي، للمراقبات النشطة فقط.
billing_cycle	الدورة الحالية: البداية والنهاية والسعر والفحوص المشمولة والفحوص المنجزة حتى الآن.
recent_runs	أحدث الفحوص مع النتيجة والاحتساب وعدد الإشارات الجديدة في `events_new`.

يغيّر PATCH /v1/account/monitors/{id} فاصل الفحص. ويلي الفحص التالي حينها بالفاصل الجديد، محسوبًا من وقت التغيير.

تحتفظ الدورة الحالية بسعرها وفحوصها المشمولة. ويسري السعر الجديد بدءًا من الدورة التالية. وقد يطلق الفاصل الأقصر فحوصًا إضافية في الدورة الحالية.

curl -X PATCH "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "poll_interval_days": 30
}'

import uuid
import requests

response = requests.patch(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "poll_interval_days": 30
    },
)
data = response.json()

const response = await fetch("https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz", {
  method: "PATCH",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "poll_interval_days": 30
  }),
});
const data = await response.json();

1{2  "monitor": {3    "id": "mon_01m6b3m7945dn7cyvexzv41kjz",4    "type": "organization.signals",5    "entity_id": "94eb910fef13f94585c48c263fa446d4",6    "label": "Hetzner Online GmbH",7    "poll_interval_days": 30,8    "status": "initializing",9    "status_reason": null,10    "pricing_policy_version": "2026-08.v2",11    "baseline_completed_at": null,12    "activated_at": null,13    "last_succeeded_at": null,14    "next_poll_at": null,15    "created_at": "2026-11-01T08:29:13+00:00"16  },17  "meta": {18    "request_credit_cost": 0,19    "credits_remaining": 14520  }21}

200 · مثال على استجابة: تغيير الفاصل إلى 30 يومًا

الإيقاف المؤقت والاستئناف والأرشفة

يوقف POST …/{id}/pause مراقبًا نشطًا. وتستمر الدورة المدفوعة حتى نهايتها، ولا يُردّ شيء.

يستأنف POST …/{id}/resume مراقبًا موقوفًا مؤقتًا أو مراقبًا به خطأ. ونتحقق مجددًا من نقاط نهاية webhook والرصيد والسعر.

ضمن الدورة المدفوعة الحالية لا يكلّف الاستئناف شيئًا. وإذا انتهت الدورة، تبدأ دورة جديدة الآن بالسعر الحالي. ويُظهر meta.request_credit_cost المبلغ.

إذا غابت مثلًا نقطة نهاية webhook موثّقة، تجيب الـ API مع ذلك بـ 200، لكن مع meta.activated: false. وتذكر حالة المراقب وstatus_reason السبب.

إذا تغيّر السعر، يتوقف المراقب النشط في نهاية الدورة مع pricing_consent_required. ومع resume توافق على السعر الجديد.

يؤرشف DELETE …/{id} المراقب نهائيًا. وهذا قرار نهائي ولا يُردّ شيء.

curl -X POST "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

import uuid
import requests

response = requests.post(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
data = response.json()

const response = await fetch("https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Idempotency-Key": crypto.randomUUID(),
  },
});
const data = await response.json();

إذا عطّلت نقطة نهاية webhook أو أرشفتها، تتوقف مؤقتًا جميع المراقبات التي ليس لها نقطة نهاية webhook أخرى مع paused_configuration. وبعد تفعيل نقطة نهاية webhook استأنف المراقب بـ resume.

الأخطاء

للأخطاء البنية {"error": "…", "meta": {"message": "…"}}. في برنامجك افحص قيمة error. النص في meta.message بالإنجليزية وقد يتغير. الأخطاء لا تكلّف شيئًا.

الأخطاء
الحالة	السبب	ما يمكنك فعله
400	`api_key` موجود في الـ URL.	أرسل المفتاح في الـ Header ‏`x-api-key`.
400	لـ `Idempotency-Key` صيغة غير صالحة.	صحّح الصيغة، مثلًا استخدم UUID.
401	لا يوجد مفتاح API أو رمز، أو أحدهما غير صالح.	أرسل المفتاح في الـ Header ‏`x-api-key`.
403	ينقص Bearer token الصلاحية `account:read`.	استخدم مفتاح API أو رمزًا بـ `account:read`.
403	لم يُؤكَّد عنوان البريد الإلكتروني لحسابك بعد، أو الحساب مقفل.	افتح الرابط من بريد التأكيد. وإذا كان الحساب مقفلًا، يمكن للدعم المساعدة.
403	ينقص Bearer token الصلاحية `monitoring:manage`.	استخدم مفتاح API أو رمز المسؤول.
404	لا يوجد مراقب بهذا المعرّف في حسابك.	تحقّق من المعرّف.
409	يوجد بالفعل مراقب لهذه الشركة (`duplicate_monitor`).	استخدم المراقب الموجود أو أرشفه أولًا.
409	استُخدم `Idempotency-Key` بالفعل مع بيانات مختلفة، أو هو أقدم من 24 ساعة، أو لا يزال قيد المعالجة.	استخدم مفتاحًا جديدًا أو انتظر قليلًا.
422	قيمة غير صالحة: `invalid_subject` أو `invalid_interval` أو `endpoint_required` أو `monitor_limit` أو `not_resumable`.	صحّح القيمة.
428	الـ Header ‏`Idempotency-Key` مفقود.	أرسل الـ Header.
429	طلبات كثيرة جدًا.	أعد المحاولة بعد `Retry-After`.
429	`creation_rate_limited`: مراقبات جديدة كثيرة جدًا خلال 24 ساعة.	أعد المحاولة بعد `Retry-After`.
503	Monitoring غير متاح مؤقتًا.	أعد المحاولة بعد قليل.

1{2  "error": "duplicate_monitor",3  "meta": {4    "message": "You already have a monitor for this company.",5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}

409 · مراقب ثانٍ للشركة نفسها