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

# سجل التصيد الاحتيالي عبر البريد الإلكتروني

> أعد إنشاء سجل التصيد الاحتيالي على مستوى الحدث الخاص بالمزوّد السابق من أحداث وكيانات المحاكاة في تقارير /v1.

هذا التقرير هو سجل تصيد احتيالي على مستوى الحدث: صف واحد لكل تفاعل محاكاة تمت ملاحظته (التاريخ، الإجراء، البريد الإلكتروني للمستلم، الموضوع، المرسل، مستوى الصعوبة). ويظل بصيغة طويلة (long-form)، ولا يختزل سجل الشخص في نتيجة واحدة.

يحتسب الاستعلام آخر **12 شهرًا تقويميًا** ضمن `occurred_after`
(منتصف الليل بتوقيت UTC في اليوم نفسه من الشهر قبل اثني عشر شهرًا، وليس مدة 365 يومًا).

<Note>
  لا يتوفر عنوان IP الخام للعميل أبدًا في `/v1`، وذلك بحكم التصميم حفاظًا على الخصوصية وليس تعيينًا قيد الانتظار. أما نوع الجهاز فهو فئة مشتقة في صف الحدث؛
  ويظل `user_agent` الخام خاصًا. راجع
  [الفروقات عن التصدير القديم](#%D8%A7%D9%84%D9%81%D8%B1%D9%88%D9%82%D8%A7%D8%AA-%D8%B9%D9%86-%D8%A7%D9%84%D8%AA%D8%B5%D8%AF%D9%8A%D8%B1-%D8%A7%D9%84%D9%82%D8%AF%D9%8A%D9%85).
</Note>

إن الإعداد وبيانات الاعتماد والترقيم الصفحي وإعادة المحاولة عند تجاوز حد المعدل هي نفسها الواردة في
[دليل الاتصال بـ Power BI / Excel](/ar/developers/v1/powerbi). أضف استعلام
`Fn_FetchAll` المشترك أولًا؛ إذ يستدعيه هذا التقرير بالاسم.

## نطاقات المفاتيح المطلوبة

| النطاق | الاستخدام |
| - | - |
| `reporting:read` | `GET /v1/reporting/simulation_events` |
| `entity:read` | `GET /v1/entities` (الربط بالبريد الإلكتروني واسم العرض) |

لا يمكن للمفتاح الذي مُنح `simulation:read` فقط استدعاء نقطة نهاية أحداث التقارير
(تُرجع واجهة API القيمة `403`). راجع
[اختيار مستوى التفصيل المناسب](/ar/developers/v1/powerbi#%D8%A7%D8%AE%D8%AA%D8%B1-%D9%85%D8%B3%D8%AA%D9%88%D9%89-%D8%A7%D9%84%D8%AA%D9%81%D8%B5%D9%8A%D9%84-%D8%A7%D9%84%D9%85%D9%86%D8%A7%D8%B3%D8%A8).

## نقاط النهاية المصدر

| نقطة النهاية | الدور |
| - | - |
| `GET /v1/reporting/simulation_events` | حقائق على مستوى الحدث. مستوى التفصيل هو تفاعل واحد مُدخل. توجد `email_subject` و`sender_email` و`sender_domain` و`difficulty_tier` في هذا الصف، لذا لا يربط الاستعلام نتائج على مستوى الحملة لهذه الحقول. |
| `GET /v1/entities` | يحل `entity_id` ← البريد الإلكتروني / اسم العرض. يُغفل حدث التقارير البريد الإلكتروني للمستلم (استثناء صارم في قارئ التقارير). ويُعد المرور على `/entities` الطريقة التي يُملأ بها عمود "البريد الإلكتروني" القديم. |

المرشحات المسموح بها في قائمة الأحداث (أي مرشح آخر يُرجع `400`):
`limit`، `page_token`، `simulation`، `entity`، `event_type`،
`occurred_after`.

تنتمي عائلة التقارير هذه إلى [مجموعة بيانات معاينة](/ar/developers/v1/powerbi#%D9%85%D8%AC%D9%85%D9%88%D8%B9%D8%A7%D8%AA-%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%A5%D8%B9%D8%AF%D8%A7%D8%AF-%D8%A7%D9%84%D8%AA%D9%82%D8%A7%D8%B1%D9%8A%D8%B1-%D8%A7%D9%84%D8%AA%D8%AC%D8%B1%D9%8A%D8%A8%D9%8A%D8%A9-%D8%A7%D9%84%D8%AA%D8%B5%D9%8A%D9%91%D8%AF-%D8%A7%D9%84%D8%A7%D8%AD%D8%AA%D9%8A%D8%A7%D9%84%D9%8A-%D9%84%D9%83%D9%84-%D8%B4%D8%AE%D8%B5).
افحص مخطط مجموعة البيانات وسياسات البيانات في
`GET /v1/reporting/datasets` و
`GET /v1/reporting/datasets/simulation_events`.

### مستوى التفصيل

صف واحد لكل حدث محاكاة في التقارير. الشخص الذي فتح الرسالة نفسها ثم نقر عليها ينتج صفين. تظهر أيضًا الأحداث التي قيمة `entity_id` فيها فارغة
(لا يوجد فاعل / مستلم / مشارك مستهدف)، وفي هذه الحالة تكون قيمة `email`
فارغة.

يُوسَّع نطاق النافذة الزمنية في API بمقدار دقيقة واحدة؛ ويُعاد تطبيق الحد الدقيق لـ
`occurred_at >= WindowStart` محليًا بحيث لا تعتمد السنة الأخيرة على ما إذا كان الخادم يعامل `occurred_after` على أنه
شامل أو غير شامل.

ميزانية الطلبات: مرور واحد مُرقَّم على الأحداث ضمن النافذة، إضافة إلى مرور واحد
على الكيانات. اضبط `limit = "500"` دائمًا.

## تعيين الأعمدة

أسماء الأعمدة القديمة مأخوذة من تصدير المزوّد السابق لديك. حقول `/v1`
هي أسماء API العامة؛ ويعيد الاستعلام تسمية بعضها لأغراض التقرير.

| العمود القديم | حقل `/v1` أو الاشتقاق | عمود التقرير |
| - | - | - |
| التاريخ | `Event.occurred_at` (كتاريخ؛ ويُحتفظ بالقيمة الخام `occurred_at` باسم `datetimezone`) | `date` |
| الإجراء | `Event.event_type` — رموز مغلقة مدرجة أدناه | `action` |
| البريد الإلكتروني | `Entity.email` (الربط عبر `entity_id`) | `email` |
| الموضوع | `Event.email_subject` | `subject` |
| المرسل | `Event.sender_email` | `from` |
| الصعوبة | `Event.difficulty_tier` — عدد صحيح من 1 إلى 5، حيث 1 الأسهل و5 الأصعب | `difficulty` |
| عنوان IP الخام | لا يتوفر أبدًا في `/v1` | محذوف، وليس فارغًا |
| نوع الجهاز | `Event.device_type` — فئة مشتقة؛ تكون فارغة عندما لا تكون للحدث فئة مشتقة | `device_type` |

### رموز الإجراءات

`action` هو رمز التقارير المغلق. يُعيَّن "Email Sent" القديم إلى
`simulation.delivered` (`delivered` هو الفعل العام؛ أما الرمز المتداول عبر الشبكة فهو
`simulation.delivered`).

| قيمة `action` |
| - |
| `simulation.delivered` |
| `simulation.opened` |
| `simulation.link_clicked` |
| `simulation.credentials_submitted` |
| `simulation.attachment_opened` |
| `simulation.reported` |
| `simulation.bounced` |
| `simulation.qr_scanned` |
| `simulation.replied` |

حقول إضافية يُحتفظ بها لأنها متوفرة في API: `sender_domain` و`full_name` و
`event_id` و`entity_id` و`simulation_id` و`occurred_at`، إضافة إلى
`entity_type` و`entity_status` من ربط الكيانات.

## الفروقات عن التصدير القديم

* **عنوان IP الخام غير متاح أبدًا.** لن يعرض `/v1` عنوان IP الخام للعميل، وذلك
  بحكم التصميم حفاظًا على الخصوصية وليس تعيينًا قيد الانتظار. ولا يضيف الاستعلام عمودًا نائبًا لعنوان IP.
* **نوع الجهاز مشتق وليس خامًا.** `device_type` هو فئة جهاز مشتقة لأحداث النقر والإرسال والإبلاغ. تشمل الرموز المرصودة
  `desktop` و`mobile` و`tablet` و`unknown`، لكن المُصدِر يخزن سلسلة
  حرة الصيغة؛ لذا تعامل معها كنص مفتوح وليس كتعداد مغلق. وتكون فارغة
  عندما لا تكون للحدث فئة مشتقة، ويظل النص الخام لـ `user_agent`
  خاصًا.
* **"Email Sent" هو `simulation.delivered`.** استخدم هذا الرمز عند
  التصفية أو عدّ عمليات الإرسال. ولا تبحث عن السلسلة القديمة `email_sent`.
* **البريد الإلكتروني للمستلم يُستنتج بالربط وليس حقلًا في الحدث.** يُغفل حدث التقارير
  البريد الإلكتروني؛ ويمر الاستعلام على `/entities` لملئه.
* **آخر 12 شهرًا تقويميًا**، وليس مدة 365 يومًا، وليس
  السجل الكامل.
* **صيغة طويلة وغير مختزلة.** صف واحد لكل تفاعل، وليس نتيجة واحدة
  لكل شخص.

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="إعداد Power BI وExcel" href="/ar/developers/v1/powerbi">
    بيانات الاعتماد والترقيم الصفحي وتحميل هذه الاستعلامات في Power BI أو Excel.
  </Card>

  <Card title="المستخدمون الأكثر عرضة للاختراق" href="/ar/developers/v1/reports/most-susceptible-users">
    ملخص لكل شخص لعمليات النقر وبيانات الاعتماد والإبلاغ خلال 12 شهرًا.
  </Card>

  <Card title="الامتثال لكل شخص" href="/ar/developers/v1/reports/per-person-compliance">
    عمليات التسجيل في التدريب على مستوى الشخص × التعيين.
  </Card>

  <Card title="مفاتيح API" href="/ar/developers/developer-hub/api-keys">
    امنح `reporting:read` و`entity:read` للمفتاح الذي يحدّث هذا التقرير.
  </Card>
</CardGroup>


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