> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# إشارات المخاطر

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

تتيح لك إشارات المخاطر إدخال بيانات اكتشاف الاحتيال في Truthlocks من أي مزود خارجي — خدمات بصمات الأجهزة، وواجهات برمجة تطبيقات سمعة IP، وأدوات التحقق من البريد الإلكتروني، ومحركات تحليل المستندات، أو قواعدك الداخلية الخاصة. بمجرد استيعابها، تتوفر الإشارات من خلال API وصفحة **المخاطر والاحتيال > الإشارات** في وحدة التحكم.

> [!NOTE]
>
> جدار الحماية لمكافحة الاحتيال والهوية متاح **بشكل عام**. جميع مسارات الكشف الخمسة — استيعاب الإشارة المباشر، وتطبيع الأحداث، ومسح التزييف العميق، واكتشاف الاستيلاء على الحساب (ATO)، وتسجيل السرعة — هي تكامل مع أمثلة API متعددة اللغات (cURL، JavaScript، Python)، وأدلة شاملة، و[إشعارات الويب هوك](https://docs.truthlocks.com/ar/guides/webhooks.md) في الوقت الفعلي لجميع أنواع الإشارات. أصبحت [قرارات المخاطر](https://docs.truthlocks.com/ar/api-reference/risk/evaluate.md) الآلية، و[إدارة الحالات](#case-management)، و[تصدير SIEM للاحتيال](#siem-export) متاحة الآن.

يمكنك إنشاء إشارات بخمس طرق:

* **الاستيعاب المباشر** - أرسل إشارة مسجلة بالكامل عبر `POST /v1/risk/signals` عندما يكون لديك بالفعل درجة مخاطر من مزود خارجي. يدعم عمليات إعادة المحاولة المتطابقة عبر رأس `Idempotency-Key`.
* **تسوية الأحداث** - أرسل حدث هوية خام عبر `POST /v1/risk/events` ودع المنصة تقوم بتعيينه تلقائيًا إلى نوع إشارة ودرجة أساسية. راجع [تسوية الأحداث](#event-normalization).
* **تسجيل إشارات التزييف العميق وانتحال الشخصية** - إرسال مؤشرات أو درجات منتجة خارجيًا لتقييم العتبة عبر `POST /v1/risk/deepfake/scan`. تؤدي عمليات الفحص التي تسجل 60 أو أعلى إلى استيعاب إشارة مخاطر تلقائيًا. راجع [دليل اكتشاف التزييف العميق](https://docs.truthlocks.com/ar/guides/deepfake-detection.md).
* **اكتشاف الاستيلاء على الحساب** — تقييم أحداث تسجيل الدخول مقابل الاستدلالات القائمة على السرعة عبر `POST /v1/risk/ato/evaluate`. يتم إنشاء التنبيهات وإدخال إشارات المخاطر تلقائيًا عند تجاوز العتبات. راجع [دليل اكتشاف ATO](https://docs.truthlocks.com/ar/guides/ato-detection.md).
* **تسجيل السرعة والشذوذ** — سجل إجراءات الموضوع عبر `POST /v1/risk/velocity/record` واجعل المنصة تتتبع التكرار عبر نوافذ زمنية متجددة (1 دقيقة، 5 دقائق، 1 ساعة، 24 ساعة). الإجراءات التي تنتج درجة سرعة مرجحة تبلغ 60 أو أعلى تستوعب تلقائيًا إشارة خطر. انظر [دليل تسجيل السرعة](https://docs.truthlocks.com/ar/guides/velocity-scoring.md).

### اختيار مسار الاستيعاب

| السيناريو | الاستخدام | نقطة النهاية |
| :- | :- | :- |
| لديك درجة مخاطر من أداة احتيال خارجية | استيعاب مباشر | `POST /v1/risk/signals` |
| تريد تسجيل الأحداث الأصلية للمنصة (عمليات تسجيل الدخول الفاشلة، اكتشافات التزييف العميق) تلقائيًا | تسوية الأحداث | `POST /v1/risk/events` |
| تريد تسجيل مؤشرات التزييف العميق أو انتحال الشخصية المقدمة | مسح التزييف العميق | `POST /v1/risk/deepfake/scan` |
| تريد اكتشاف محاولات الاستيلاء على الحساب بناءً على سرعة تسجيل الدخول | اكتشاف ATO | `POST /v1/risk/ato/evaluate` |
| تريد اكتشاف شذوذ السرعة عبر أي نوع من الإجراءات | تسجيل السرعة | `POST /v1/risk/velocity/record` |
| أنت تستخدم مصادر إشارة متعددة | جميع المصادر الخمسة — تصل الإشارات إلى نفس المسار | أي نقطة نهاية |

تنتج جميع المسارات الخمسة نفس سجلات إشارة المخاطر. يمكنك الاستعلام عن الإشارات وتصفيتها ومراجعتها من أي مسار باستخدام [نقطة النهاية القائمة](https://docs.truthlocks.com/ar/api-reference/risk-signals/list.md) وصفحة وحدة التحكم **المخاطر والاحتيال > الإشارات**.

## كيف يعمل

**1. استيعاب الإشارات**

أرسل طلب `POST` إلى `/v1/risk/signals` مع مصدر الإشارة، والنوع، ودرجة المخاطرة، والموضوع الذي يتعلق به. أرفق أي سياق إضافي في كائن `payload`.

**2. الاستعلام والتصفية**

استخدم `GET /v1/risk/signals` لسرد الإشارات مع عوامل تصفية للمصدر ونوع الإشارة والموضوع والحد الأدنى للنتيجة. يتم تقسيم النتائج إلى صفحات باستخدام ترقيم الصفحات المستند إلى المؤشر.

**3. المراجعة في وحدة التحكم**

افتح **المخاطر والاحتيال > الإشارات** في وحدة تحكم المستأجر لتصفح الإشارات، والتصفية حسب المصدر أو النتيجة، وفحص تفاصيل الإشارة الفردية.

## المتطلبات الأساسية

* مستأجر Truthlocks نشط مع مفتاح API
* مصدر واحد على الأقل للكشف عن الاحتيال في المنبع ينتج إشارات مسجلة

## استيعاب إشارة

أرسل طلب `POST` بالحقول المطلوبة:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/signals \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "signal_source": "external",
    "signal_type": "velocity",
    "risk_score": 85,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f",
    "payload": {
      "ip": "203.0.113.42",
      "country": "US",
      "reason": "multiple_accounts_same_device"
    },
    "ip_address": "203.0.113.42"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/signals", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    signal_source: "external",
    signal_type: "velocity",
    risk_score: 85,
    subject_type: "user",
    subject_id: "usr_8f14e45f",
    payload: {
      ip: "203.0.113.42",
      country: "US",
      reason: "multiple_accounts_same_device",
    },
    ip_address: "203.0.113.42",
  }),
});
const signal = await response.json();
```

```python Python theme={null}
import httpx
import uuid

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/signals",
    headers={
        "X-API-Key": "tl_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "signal_source": "external",
        "signal_type": "velocity",
        "risk_score": 85,
        "subject_type": "user",
        "subject_id": "usr_8f14e45f",
        "payload": {
            "ip": "203.0.113.42",
            "country": "US",
            "reason": "multiple_accounts_same_device",
        },
        "ip_address": "203.0.113.42",
    },
)
signal = resp.json()
```

### الحقول المطلوبة

| الحقل | النوع | الوصف |
| :- | :- | :- |
| `signal_source` | string | مصدر الإشارة — `verification`، `login`، `attestation`، `external`، أو `manual` |
| `signal_type` | string | ما تم اكتشافه (مثال: `velocity`، `geo_anomaly`، `device_fingerprint`، `behavior`، `deepfake`، `ato`، `impersonation`) |
| `risk_score` | integer | درجة المخاطرة من `0` (آمن) إلى `100` (مخاطرة عالية). الدرجات التي تساوي أو تزيد عن 80 تؤدي إلى مراجعة تلقائية. |
| `subject_type` | string | نوع الكيان: `user`، `issuer`، `attestation`، `session`، `ip`، أو `device` |
| `subject_id` | string | معرف الكيان الذي يتم تقييمه |

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

| الحقل | النوع | الوصف |
| :- | :- | :- |
| `payload` | object | JSON عشوائي مع سياق خاص بالإشارة (عناوين IP، تحديد الموقع الجغرافي، الأسباب) |
| `ip_address` | string | عنوان IP المصدر المرتبط بهذا الحدث |
| `user_agent` | string | سلسلة User-Agent المرتبطة بهذا الحدث |

### الثبات

قم بتضمين رأس `Idempotency-Key` (UUID) لمنع الإشارات المكررة أثناء عمليات إعادة المحاولة. إذا أرسلت نفس المفتاح مرتين، يتم تجاهل التكرار بصمت.

## الاستعلام عن الإشارات

### قائمة مع عوامل التصفية

```bash theme={null}
curl "https://api.truthlocks.com/v1/risk/signals?source=external&min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."
```

الفلاتر المتاحة:

| المعلمة | الوصف |
| :- | :- |
| `source` | التصفية حسب مصدر الإشارة |
| `signal_type` | التصفية حسب نوع الإشارة |
| `subject_type` | التصفية حسب نوع الموضوع |
| `subject_id` | التصفية حسب معرف الموضوع |
| `min_score` | الحد الأدنى لدرجة العتبة (0-100) |
| `limit` | النتائج لكل صفحة (الحد الأقصى 100) |
| `cursor` | مؤشر للصفحة التالية |

### الحصول على إشارة واحدة

```bash theme={null}
curl https://api.truthlocks.com/v1/risk/signals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: tl_live_..."
```

## عرض Console

توفر صفحة **المخاطر والاحتيال > الإشارات** في وحدة التحكم قائمة قابلة للبحث والتصفية لجميع الإشارات المستوعبة. يعرض كل صف المصدر، والنوع، والنتيجة (ملونة حسب الخطورة)، ومرجع الموضوع، والطابع الزمني.

استخدم المرشحات الموجودة في الجزء العلوي من الصفحة لتضييق النتائج حسب المصدر أو نوع الإشارة أو الحد الأدنى للدرجة. انقر فوق أي صف لعرض تفاصيل الإشارة الكاملة بما في ذلك كائن بيانات التعريف `payload`.

## إرشادات التسجيل

التسجيل المتسق عبر المصادر يجعل التحليل اللاحق أكثر موثوقية. نوصي بالنطاقات التالية:

| النطاق | التفسير | مثال |
| :- | :- | :- |
| 0 – 30 | مخاطر منخفضة | جهاز معروف جيد، IP موثوق |
| 30 – 60 | مخاطر معتدلة | استخدام VPN، سرعة الحساب الجديد |
| 60 – 80 | مخاطر عالية | بريد إلكتروني مؤقت، عنوان IP لمركز بيانات |
| 80 – 100 | مخاطر حرجة | جهاز احتيال معروف، سفر مستحيل |

> [!WARNING]
>
> الدرجات التي تبلغ 80 أو أعلى تؤدي إلى قرارات مراجعة تلقائية. تفسير الدرجات بما يتجاوز العتبة التلقائية متروك لك — تقوم المنصة بتخزين وإرجاع الدرجات كما هي ولا تقوم بتطبيعها عبر المصادر.

## تسوية الأحداث

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

أرسل طلب `POST` إلى `/v1/risk/events` مع مصدر الحدث ونوعه وموضوعه:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/events \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_source": "login",
    "event_type": "login.failed.repeated",
    "subject_id": "user_abc123",
    "ip_address": "198.51.100.42",
    "payload": { "attempt_count": 8, "window_seconds": 120 }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/events", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_source: "login",
    event_type: "login.failed.repeated",
    subject_id: "user_abc123",
    ip_address: "198.51.100.42",
    payload: { attempt_count: 8, window_seconds: 120 },
  }),
});
const result = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/events",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "event_source": "login",
        "event_type": "login.failed.repeated",
        "subject_id": "user_abc123",
        "ip_address": "198.51.100.42",
        "payload": {"attempt_count": 8, "window_seconds": 120},
    },
)
result = resp.json()
```

يتضمن الرد كلاً من `event_id` الخام و`signal_id` المعياري، حتى تتمكن من تتبع المسار الكامل من الحدث إلى الإشارة:

```json theme={null}
{
  "event_id": "2a4b6c8d-...",
  "signal_id": "9f3a1c2d-...",
  "event_type": "login.failed.repeated",
  "signal_type": "ato",
  "risk_score": 70,
  "normalized": true,
  "created_at": "2027-05-01T10:00:00Z"
}
```

عندما يكون `normalized` هو `true`، تطابق الحدث مع تعيين معروف. عندما يكون `false`، استخدمت المنصة البديل العام.

### تعيينات الأحداث المضمنة

تأتي المنصة مع تعيينات معايرة مسبقًا لأحداث الهوية الشائعة:

| نوع الحدث | نوع الإشارة | النتيجة الأساسية |
| :- | :- | :- |
| `verification.failed` | behavior | 60 |
| `verification.invalid_sig` | behavior | 75 |
| `login.failed.repeated` | ato | 70 |
| `login.suspicious_geo` | geo\_anomaly | 65 |
| `attestation.deepfake_suspect` | deepfake | 85 |
| `session.hijack_suspect` | ato | 90 |

يتم قبول أنواع الأحداث غير المعروفة بنوع الإشارة `behavior` ودرجة أساسية 10.

### حقول الحدث

**مطلوب:**

| الحقل | النوع | الوصف |
| :- | :- | :- |
| `event_source` | string | النظام الذي أنشأ الحدث — `attestation`، `verification`، `login`، أو `consumer_portal` |
| `event_type` | string | اسم الحدث الخام (مثل `login.failed.repeated`، `attestation.deepfake_suspect`) |
| `subject_id` | string | معرف الكيان المشارك في الحدث |

**اختياري:**

| الحقل | النوع | الوصف |
| :- | :- | :- |
| `event_ref_id` | string | معرف مرجعي خارجي (معرف شهادة، معرف جلسة) للمرجعية المتقاطعة |
| `ip_address` | string | عنوان IP المصدر |
| `payload` | object | حمولة الحدث الخام لسياق الإثراء |

> [!NOTE]
>
> استخدم تسوية الأحداث عندما تنشأ أحداثك من داخل المنصة (تسجيلات الدخول، التحقق، الشهادات). استخدم [نقطة نهاية استيعاب الإشارة المباشرة](https://docs.truthlocks.com/ar/api-reference/risk/ingest-signal.md) عندما يكون لديك بالفعل إشارة مسجلة من مصدر خارجي.

## عزل المستأجر

إشارات المخاطر معزولة تمامًا للمستأجر باستخدام [أمان على مستوى الصف (RLS)](https://docs.truthlocks.com/ar/security/rls.md). ترتبط كل إشارة بالمستأجر المصادق عليه وقت الاستيعاب، ويمكن للاستعلامات فقط إرجاع الإشارات التي تنتمي إلى المستأجر المتصل.

## اكتشاف التزييف العميق وانتحال الشخصية

توسع [واجهة برمجة تطبيقات اكتشاف التزييف العميق](https://docs.truthlocks.com/ar/guides/deepfake-detection.md) مسار إشارة المخاطر من خلال المسح التلقائي للمحتوى المتلاعب والاحتيال في الهوية. أرسل الصور أو مقاطع الفيديو أو المستندات أو الشهادات للتحليل، وتقوم عمليات المسح التي تتجاوز عتبة المخاطر بإنشاء إشارة مخاطر تلقائيًا - لا حاجة إلى استدعاء API إضافي.

راجع [دليل اكتشاف التزييف العميق وانتحال الشخصية](https://docs.truthlocks.com/ar/guides/deepfake-detection.md) لسير العمل الكامل، ومرجع المؤشرات، وأمثلة التعليمات البرمجية.

## الكشف عن الاستيلاء على الحساب

توسع [واجهة برمجة تطبيقات اكتشاف ATO](https://docs.truthlocks.com/ar/guides/ato-detection.md) مسار إشارة المخاطر من خلال مراقبة تسجيل الدخول المستندة إلى السرعة. أرسل أحداث تسجيل الدخول إلى `POST /v1/risk/ato/evaluate` وتتتبع المنصة المحاولات الفاشلة لكل موضوع في نافذة متجددة مدتها ساعة واحدة. عندما يتجاوز الموضوع عتبة (5 أو 10 أو 20 محاولة تسجيل دخول فاشلة)، يتم إنشاء تنبيه ويتم استيعاب إشارة مخاطر تلقائيًا - لا حاجة إلى استدعاء API إضافي.

راجع [دليل اكتشاف الاستيلاء على الحساب](https://docs.truthlocks.com/ar/guides/ato-detection.md) لسير العمل الكامل، ومرجع العتبة، وأنماط التكامل.

## تسجيل السرعة والشذوذ

توسع [واجهة برمجة تطبيقات تسجيل السرعة](https://docs.truthlocks.com/ar/guides/velocity-scoring.md) مسار إشارة المخاطر من خلال تتبع الإجراءات متعددة النوافذ واكتشاف الشذوذ. سجل أي إجراء للموضوع عبر `POST /v1/risk/velocity/record` وتتتبع المنصة التردد عبر أربع نوافذ متجددة (دقيقة واحدة، 5 دقائق، ساعة واحدة، 24 ساعة). يتم حساب درجة سرعة مرجحة من عدد النوافذ، مع الانحياز نحو النوافذ القصيرة لاكتشاف الاندفاع. عندما تصل النتيجة إلى 60 أو أعلى، يتم استيعاب إشارة مخاطر مع `signal_type: "velocity"` تلقائيًا - لا حاجة إلى استدعاء API إضافي.

راجع [دليل تسجيل السرعة والشذوذ](https://docs.truthlocks.com/ar/guides/velocity-scoring.md) لسير العمل الكامل، ونموذج التسجيل، وأنماط التكامل.

## إشعارات خطاف الويب (Webhook)

يمكن لإشارات المخاطر التي تم إنشاؤها بواسطة أي من مسارات الكشف الخمسة أن تؤدي إلى إشعارات [webhook](https://docs.truthlocks.com/ar/guides/webhooks.md) في الوقت الفعلي. اشترك في `risk.signal.created` أو `risk.signal.escalated` للتفاعل مع الإشارات الجديدة دون استقصاء. يغطي هذا الإشارات من الاستيعاب المباشر، وتطبيع الأحداث، ومسح التزييف العميق، وتنبيهات ATO، وشذوذ السرعة.

راجع [دليل الويب هوكس](https://docs.truthlocks.com/ar/guides/webhooks.md#risk-signal-notifications) لأمثلة الحمولة وأنماط التكامل.

## قياس الاستخدام

يتم قياس ميزات مكافحة الاحتيال لكل دورة فوترة. يزيد كل مسار اكتشاف عداد الاستخدام الخاص به:

| المقياس | الإجراء المقاس |
| :- | :- |
| `antifraud.risk_signals` | إشارات المخاطر المستوعبة أو المولدة (جميع المسارات الخمسة) |
| `antifraud.deepfake_scans` | طلبات فحص التزييف العميق وانتحال الشخصية |
| `antifraud.velocity_records` | سجلات إجراءات تسجيل السرعة |

تختلف الحصص حسب مستوى الخطة. يمكنك التحقق من استهلاكك الحالي باستخدام [واجهة برمجة تطبيقات الاستخدام](https://docs.truthlocks.com/ar/api-reference/billing/usage.md) أو في وحدة التحكم ضمن **الإعدادات > الفوترة > الاستخدام** في قسم **مكافحة الاحتيال**. للتحقق مما إذا كانت عملية معينة مسموح بها قبل إجرائها، استخدم [نقطة نهاية التحقق من الحد](https://docs.truthlocks.com/ar/api-reference/billing/entitlements.md).

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

يتضمن الرد جميع عدادات مكافحة الاحتيال مع حقول `used`، `limit`، و`period` حتى تتمكن من مراقبة الاستهلاك برمجيًا.

> [!NOTE]
>
> راجع [نظرة عامة على الفواتير](https://docs.truthlocks.com/ar/billing/overview.md#metered-products) للحصول على القائمة الكاملة للمنتجات الـ 16 المقاسة وأسعارها الافتراضية.

## ما التالي

* [دليل السرعة وتسجيل الشذوذ](https://docs.truthlocks.com/ar/guides/velocity-scoring.md)
* [دليل اكتشاف الاستيلاء على الحساب](https://docs.truthlocks.com/ar/guides/ato-detection.md)
* [دليل اكتشاف التزييف العميق وانتحال الشخصية](https://docs.truthlocks.com/ar/guides/deepfake-detection.md)
* [مرجع API لاستيعاب إشارة المخاطر](https://docs.truthlocks.com/api-reference/risk-signals/ingest)
* [مرجع API لتطبيع حدث الهوية](https://docs.truthlocks.com/ar/api-reference/risk/normalize-event.md)
* [مرجع API لسرد إشارات المخاطر](https://docs.truthlocks.com/ar/api-reference/risk-signals/list.md)
* [مرجع API للحصول على إشارة المخاطر](https://docs.truthlocks.com/ar/api-reference/risk-signals/get.md)
* [أمان مستوى الصف](https://docs.truthlocks.com/ar/security/rls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.