> ## 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.

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

> تتبع تكرار الإجراءات عبر نوافذ زمنية متجددة، واكتشاف حالات الشذوذ في السرعة، واستيعاب إشارات المخاطر تلقائيًا عند تجاوز العتبات.

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

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

## كيف يعمل

**1. تسجيل الإجراءات**

استدعِ `POST /v1/risk/velocity/record` في كل مرة يقوم فيها موضوع بإجراء متتبع — محاولات تسجيل الدخول، مكالمات API، طلبات المعاملات، أو أي نوع إجراء مخصص.

**2. تتبع النافذة المتجددة**

تزيد المنصة العدادات للموضوع ونوع الإجراء عبر أربع نوافذ متجددة (1 دقيقة، 5 دقائق، 1 ساعة، 24 ساعة). تتم إعادة تعيين النوافذ تلقائيًا عند انتهاء صلاحيتها.

**3. التسجيل المرجح**

يتم حساب درجة السرعة من عدد النوافذ. يتم ترجيح النوافذ القصيرة بشكل أكبر لاكتشاف الاندفاعات: 1 دقيقة × 30، 5 دقائق × 20، 1 ساعة × 10، 24 ساعة × 5.

**4. استيعاب الإشارة التلقائي**

عندما تصل نتيجة السرعة إلى 60 أو أعلى، تقوم المنصة تلقائيًا بإدخال إشارة مخاطر باستخدام `signal_type: "velocity"`. لا تحتاج إلى استدعاء API منفصل.

**5. المراجعة والرد**

استعلم عن نوافذ السرعة لموضوع ما، وسرد حالات الشذوذ عالية السرعة عبر المستأجر الخاص بك، وراجع الإشارات في وحدة التحكم أو عبر API.

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

* مستأجر Truthlocks نشط مع مفتاح API
* بيانات أحداث الإجراء من تطبيقك (محاولات تسجيل الدخول، مكالمات API، المعاملات، أو أي إجراء قابل للتكرار)

## تسجيل إجراء

أرسل طلب `POST` إلى `/v1/risk/velocity/record` مع الموضوع ونوع الإجراء والبيانات الوصفية الاختيارية:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/velocity/record \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user_abc123",
    "action_type": "login.failed",
    "ip_address": "198.51.100.42"
  }'
```

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

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

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/velocity/record",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "subject_id": "user_abc123",
        "action_type": "login.failed",
        "ip_address": "198.51.100.42",
    },
)
result = resp.json()
```

تُرجع الاستجابة عدد النوافذ الحالي، ودرجة السرعة المحسوبة، وما إذا كانت إشارة المخاطر قد تم استيعابها تلقائيًا:

```json theme={null}
{
  "subject_id": "user_abc123",
  "action_type": "login.failed",
  "windows": {
    "1m": 3,
    "5m": 8,
    "1h": 15,
    "24h": 42
  },
  "velocity_score": 72,
  "signal_ingested": true,
  "signal_id": "a1b2c3d4-..."
}
```

## نموذج التسجيل

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

| النافذة | الوزن | الغرض |
| :- | :- | :- |
| 1 دقيقة | 30 | يكتشف الاندفاعات السريعة (حشو بيانات الاعتماد، الهجمات الآلية) |
| 5 دقائق | 20 | يكتشف إساءة الاستخدام المستمرة قصيرة المدى |
| 1 ساعة | 10 | يحدد الأنماط متوسطة المدى |
| 24 ساعة | 5 | يشير إلى الشذوذات المستمرة على فترات أطول |

النتيجة النهائية محددة بحد أقصى 100. عندما تصل النتيجة إلى **60 أو أعلى**، يتم استيعاب إشارة مخاطر تلقائيًا مع `signal_type: "velocity"`.

### تفسير النتيجة

| نطاق الدرجات | التفسير | مثال |
| :- | :- | :- |
| 0–29 | عادي | نشاط المستخدم النموذجي |
| 30–59 | مرتفع | تردد أعلى من المتوسط، يستحق المراقبة |
| 60–79 | مرتفع | على الأرجح مؤتمت أو مسيء — إشارة يتم استيعابها تلقائيًا |
| 80–100 | حرج | شذوذ قوي — يوصى بالتحقيق الفوري |

## الاستعلام عن نوافذ السرعة

استرداد نوافذ السرعة الحالية لموضوع معين:

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

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/user_abc123", {
  headers: { "X-API-Key": "tl_live_..." },
});
const windows = await response.json();
```

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

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity/user_abc123",
    headers={"X-API-Key": "tl_live_..."},
)
windows = resp.json()
```

يتضمن الرد جميع أنواع الإجراءات المتتبعة للموضوع، مع عدد لكل نافذة ودرجة السرعة المحسوبة لكل منها:

```json theme={null}
{
  "subject_id": "user_abc123",
  "actions": [
    {
      "action_type": "login.failed",
      "windows": {
        "1m": 0,
        "5m": 2,
        "1h": 8,
        "24h": 23
      },
      "velocity_score": 45
    },
    {
      "action_type": "api.request",
      "windows": {
        "1m": 12,
        "5m": 45,
        "1h": 200,
        "24h": 800
      },
      "velocity_score": 87
    }
  ]
}
```

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

استعلام عن الموضوعات ذات درجات السرعة التي تتجاوز عتبة معينة عبر مستأجرك:

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

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25",
  { headers: { "X-API-Key": "tl_live_..." } }
);
const anomalies = await response.json();
```

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

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity",
    params={"min_score": 50, "limit": 25},
    headers={"X-API-Key": "tl_live_..."},
)
anomalies = resp.json()
```

تتضمن كل نتيجة الموضوع، ونوع الإجراء، وعدد النوافذ الحالي، ودرجة السرعة التي أهّلت الشذوذ:

```json theme={null}
{
  "anomalies": [
    {
      "subject_id": "user_abc123",
      "action_type": "login.failed",
      "windows": {
        "1m": 5,
        "5m": 12,
        "1h": 30,
        "24h": 85
      },
      "velocity_score": 68,
      "last_recorded_at": "2027-07-03T14:22:00Z"
    }
  ],
  "cursor": "eyJsYXN0X2lkIjo..."
}
```

## أنماط التكامل

### الحظر أو التقييد عند السرعة العالية

استخدم درجة السرعة من استجابة السجل لتحديد ما إذا كنت ستسمح بإجراء ما أو تقيده أو تحظره:

```javascript theme={null}
const result = await recordAction(subjectId, "api.request", ipAddress);

if (result.velocity_score >= 80) {
  await blockSubject(subjectId);
  await notifySecurityTeam(result);
} else if (result.velocity_score >= 60) {
  await throttleRequests(subjectId, { maxPerMinute: 5 });
} else if (result.velocity_score >= 30) {
  await addRateLimitWarning(subjectId);
}
```

### الدمج مع اكتشاف ATO

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

* **تسجيل السرعة** لاكتشاف إساءة الاستخدام العامة — إساءة استخدام معدل واجهة برمجة التطبيقات، إغراق المعاملات، البريد العشوائي للتسجيل
* **اكتشاف ATO** لأمان تسجيل الدخول المركز — سرعة تسجيل الدخول الفاشلة، تنبيهات حشو بيانات الاعتماد، ملفات تعريف مخاطر الموضوع

### المراقبة عبر webhooks

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

### أنواع الإجراءات المخصصة

يمكنك تتبع أي نوع من الإجراءات التي ينتجها تطبيقك. أمثلة شائعة:

| نوع الإجراء | حالة الاستخدام |
| :- | :- |
| `login.failed` | محاولات تسجيل الدخول الفاشلة |
| `api.request` | تكرار استدعاء API |
| `transaction.create` | محاولات الدفع أو التحويل |
| `registration.attempt` | رسائل البريد العشوائي لإنشاء الحساب |
| `password.reset` | إساءة استخدام إعادة تعيين كلمة المرور |
| `verification.request` | إغراق طلبات التحقق |

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

تزيد كل مكالمة إلى `POST /v1/risk/velocity/record` عداد استخدام `antifraud.velocity_records` لدورة الفوترة الخاصة بك. يمكنك مراقبة استهلاكك باستخدام [واجهة برمجة تطبيقات الاستخدام](https://docs.truthlocks.com/ar/api-reference/billing/usage.md) أو في وحدة التحكم ضمن **الإعدادات > الفوترة > الاستخدام** في قسم **مكافحة الاحتيال**.

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

## ما التالي

* [مرجع API لتسجيل إجراء السرعة](https://docs.truthlocks.com/ar/api-reference/risk/velocity-record.md)
* [مرجع API للحصول على نوافذ السرعة](https://docs.truthlocks.com/ar/api-reference/risk/velocity-windows.md)
* [مرجع API لسرد شذوذات السرعة](https://docs.truthlocks.com/ar/api-reference/risk/velocity-anomalies.md)
* [دليل إشارات المخاطر](https://docs.truthlocks.com/ar/guides/risk-signals.md)
* [دليل اكتشاف الاستيلاء على الحساب](https://docs.truthlocks.com/ar/guides/ato-detection.md)
* [دليل اكتشاف التزييف العميق وانتحال الشخصية](https://docs.truthlocks.com/ar/guides/deepfake-detection.md)


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