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

# واجهة برمجة تطبيقات مصدر الدفع المخصص

> سجّل مصدرًا وأرسل دفعات أحداث بصيغة JSON أو CSV إلى Living Security باستخدام مفتاح وصول API ذي نطاق محدد.

استخدم مصدر الدفع المخصص (Custom Push Source) عندما يرسل نظام ما السجلات إلى Living Security بدلًا من أن يستعلم عنها موصّل من كتالوج. يمكن للمُرسِل إرسال مصفوفات JSON أو ملفات CSV إلى نقطة نهاية HTTPS إقليمية.

## قبل البدء

تحتاج إلى ما يلي:

* صلاحية إدارة التكاملات ومفاتيح الوصول في Living Security
* مُرسِل من جهة الخادم قادر على إجراء طلبات HTTPS `POST`
* منطقة Living Security الخاصة بمؤسستك
* اسم مصدر ثابت واسم تدفق واحد على الأقل

اسما المصدر والتدفق هما مفتاحا توجيه دائمان. يجب أن يتكوّن اسم المصدر من 1–64 حرفًا من الأحرف الإنجليزية الصغيرة أو الأرقام أو الواصلات. يُسمح أيضًا بالشرطات السفلية في أسماء التدفقات. ويجب أن يبدأ كلاهما بحرف أو رقم.

<Warning>
  تعامل مع مفتاح وصول API بوصفه سرًّا. لا تضعه في شيفرة المتصفح، ولا تودعه في
  نظام التحكم بالمصدر، ولا ترسله في تذكرة دعم.
</Warning>

## 1. تسجيل المصدر والتدفقات

<Steps>
  <Step title="فتح مصدر الدفع المخصص">
    انتقل إلى **الإعدادات ← التكاملات ← كتالوج**، وابحث عن **Custom Push Source**، ثم حدّد **إضافة**.
  </Step>

  <Step title="تسمية المصدر">
    أدخل مفتاح توجيه المصدر ووصفًا اختياريًا. على سبيل المثال، استخدم `custom-phishing-sim` بدلًا من اسم عرض يحتوي على مسافات.
  </Step>

  <Step title="إضافة التدفقات">
    أضف كل تدفق سيستخدمه المُرسِل. يجب أن يكون زوج المصدر والتدفق موجودًا قبل أول عملية دفع؛ إذ يؤدي زوج غير معروف إلى إرجاع `404 Not Found`.
  </Step>

  <Step title="حفظ المصدر">
    بعد الإنشاء، افتح المصدر ضمن **الإعدادات ← التكاملات ← متصل**. يعرض عرض **Push via API** نمط نقطة النهاية وعمليات التشغيل الأخيرة.
  </Step>
</Steps>

## 2. إنشاء مفتاح دفع واستيعاب

انتقل إلى **الإعدادات ← Access Keys**، وحدّد **Create Access Key**، ثم اختر النطاق **Push Ingest**. انسخ القيمة المُنشأة فورًا؛ إذ تُعرض مرة واحدة فقط.

يرتبط المفتاح بمؤسسة واحدة في Living Security. لا يحتاج طلب الدفع إلى ترويسة للمؤسسة. راجع [مفاتيح وصول API](/ar/features/settings/api-keys) للاطلاع على التدوير والإلغاء.

## 3. اختيار نقطة النهاية الإقليمية

استخدم اسم المضيف الخاص بمؤسسة Living Security:

| المنطقة | عنوان URL الأساسي |
| - | - |
| الولايات المتحدة | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| الاتحاد الأوروبي | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

أضف `/push-ingest/{integrationKey}/{streamName}`. المسار حساس لحالة الأحرف ويجب أن يطابق المصدر والتدفق المسجلين تمامًا.

<ParamField path="integrationKey" type="string" required>
  اسم المصدر المسجل. استخدم 1–64 حرفًا من الأحرف الإنجليزية الصغيرة أو الأرقام أو الواصلات، على أن يبدأ بحرف أو رقم.
</ParamField>

<ParamField path="streamName" type="string" required>
  اسم التدفق المسجل. تنطبق القواعد نفسها، ويُسمح أيضًا بالشرطات السفلية.
</ParamField>

<ParamField header="Authorization" type="string" required>
  أرسل مفتاح وصول الدفع والاستيعاب على الصورة `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  استخدم `application/json` لصيغة JSON أو `text/csv` لصيغة CSV. يمكن للخادم أيضًا اكتشاف مصفوفة JSON عند حذف هذه الترويسة.
</ParamField>

<ParamField header="x-organization-id" type="string">
  معرّف UUID اختياري للمؤسسة. يحدد مفتاح الوصول المؤسسة بالفعل. إذا أرسلت هذه الترويسة، فيجب أن تطابق مؤسسة المفتاح؛ ولا يمكنها اختيار مؤسسة أخرى.
</ParamField>

### نص الطلب

أرسل مصفوفة JSON من المستوى الأعلى غير فارغة من الكائنات، أو بايتات ملف CSV مع صف رأس. لا يوجد حقل JSON مُغلِّف مُسمّى. يمكن أن تحتوي كل دفعة على ما يصل إلى 10,000 سجل و10 MB.

## 4. إرسال دفعة JSON

أرسل مصفوفة JSON غير فارغة عناصرها كائنات. `Content-Type: application/json` موصى به وتشترطه كثير من المنتجات المُرسِلة، مع أن Living Security يمكنها اكتشاف نص الطلب من نوع مصفوفة بدونه.

<RequestExample>
  ```bash JSON batch theme={null}
  curl --request POST \
    'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
    --header 'Authorization: Bearer <access-key>' \
    --header 'Content-Type: application/json' \
    --data '[
      {
        "email": "person@example.com",
        "event_at": "2026-09-21T14:30:00Z",
        "action": "reported"
      }
    ]'
  ```

  ```bash CSV file theme={null}
  curl --request POST \
    'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
    --header 'Authorization: Bearer <access-key>' \
    --header 'Content-Type: text/csv' \
    --data-binary '@events.csv'
  ```
</RequestExample>

يُرجع الطلب الناجح `202 Accepted`. تعرض علامة تبويب الخطأ `400 Bad Request` عندما يكون نص JSON غير صالح:

<ResponseExample>
  ```json 202 Accepted theme={null}
  {
    "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
    "recordsAccepted": 1,
    "integrationKey": "custom-phishing-sim",
    "streamName": "events"
  }
  ```

  ```json 400 Invalid JSON theme={null}
  {
    "statusCode": 400,
    "timestamp": "2026-09-22T14:30:00.000Z",
    "path": "/api/v1/push-ingest/custom-phishing-sim/events",
    "message": "Request body is not valid JSON. Send a JSON array of objects, or set Content-Type: text/csv to push a CSV.",
    "error": "Bad Request"
  }
  ```
</ResponseExample>

يعني القبول أن الدفعة خُزّنت للمعالجة غير المتزامنة. ولا يعني أن كل سجل قد فُسِّر بالفعل إلى نشاط.
بالنسبة إلى مثال `400`، صحّح JSON أو أرسل CSV باستخدام `Content-Type: text/csv`، ثم أعد المحاولة.

<ResponseField name="runId" type="string" required>
  معرّف التشغيل لهذه الدفعة المقبولة. احتفظ به للتحقق من حالة المعالجة.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  عدد السجلات المقبولة والمخزّنة.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  اسم المصدر المستخدم في عملية الدفع هذه.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  اسم التدفق المستخدم في عملية الدفع هذه.
</ResponseField>

## إرسال CSV بدلًا من ذلك

اضبط `Content-Type: text/csv` وأرسل بايتات الملف، كما هو موضح في مثال الطلب **CSV file** أعلاه. يوفّر الصف الأول أسماء الحقول.

يتحول النص المنطقي إلى قيمة منطقية، ويتحول النص الرقمي العادي إلى رقم. أما القيم ذات الأصفار البادئة، والأعداد الصحيحة الكبيرة غير الآمنة، والتواريخ، وسائر النصوص فتبقى سلاسل نصية. تؤدي الخلايا الفارغة إلى حذف الحقل المقابل. وتُرفض الصفوف المشوهة وعلامات الاقتباس غير المتوازنة وملفات UTF-16.

## حدود الطلبات وإعادة المحاولة

| العقد | القيمة الحالية |
| - | - |
| الحد الأقصى للسجلات | 10,000 لكل طلب |
| الحد الأقصى لنص الطلب | 10 MB |
| معدل الطلبات لكل مؤسسة | 600 طلب كل 60 ثانية |

قسّم عمليات التصدير الأكبر إلى دفعات تستوفي كلا الحدين. انتظر كل استجابة واحتفظ بقيمة `runId` المُرجعة في سجلات المُرسِل.

| الاستجابة | المعنى | إجراء المُرسِل |
| - | - | - |
| `202` | قُبلت الدفعة | سجّل `runId`؛ ولا تعد الإرسال فورًا |
| `400` | اسم أو JSON أو CSV أو عدد سجلات أو نص طلب غير صالح | صحّح الطلب؛ ولا تعد المحاولة دون تغيير |
| `401` | المفتاح مفقود أو منتهي الصلاحية أو ملغى أو غير صالح | استبدل المفتاح واستخدم ترويسة Bearer |
| `403` | المفتاح لا يملك النطاق المطلوب | أنشئ مفتاحًا بنطاق **Push Ingest** |
| `404` | المصدر أو التدفق غير مسجل | سجّل الزوج المطابق تمامًا أو صحّح عنوان URL |
| `413` | يتجاوز نص الطلب 10 MB | قسّم الدفعة إلى طلبات أصغر |
| `429` | تقييد مؤقت على مستوى عنوان IP | التزم بـ `Retry-After` عند وجوده وأبطئ معدل الإرسال |
| `503` | سلة معدل المؤسسة أو أداة تحديد المعدل غير متاحة | انتظر `Retry-After`، ثم أعد إرسال الدفعة نفسها |

يُرجع حد المؤسسة المصادَق عليها المعتاد `503` وليس `429`، ولذلك تتعامل المُرسِلات عبر Webhook معه على أنه قابل لإعادة المحاولة. يُرجَع `503` قبل تخزين الدفعة؛ ولا تؤدي إعادة إرسال الدفعة نفسها بعد الفاصل الزمني المذكور إلى تكرار تشغيل مقبول.

## التحقق من تدفق البيانات

افتح Custom Push Source وراجع **Push History**. تأكد من التدفق وعدد السجلات ونسبة المفتاح وحالة المعالجة. يمكن بعد ذلك أن تتحول البيانات التي لها مفسّر مُصان إلى أشخاص ونشاط موحَّد. أما البيانات التي ليس لها مفسّر فتبقى مخزّنة لكنها لا تنتج نشاطًا.

<Info>
  استخدم أسماء الحقول الدقيقة وبنية الحمولة من الدليل الخاص بالمزوّد عند وجوده.
  يثبت `202` الناجح أن التسليم قد تم، لا أن مخططًا عشوائيًا يُطابَق مع نشاط
  Living Security.
</Info>

## قائمة التحقق لاستكشاف الأخطاء وإصلاحها

* انسخ نقطة النهاية من المصدر الصحيح واستبدل عنصر التدفق النائب.
* أرسل مفتاح الوصول على الصورة `Authorization: Bearer …`؛ فـ `x-api-key` غير مقبول.
* تأكد من أن النص مصفوفة JSON من المستوى الأعلى، وليس كائنًا واحدًا أو غلافًا حول السجلات.
* تأكد من هجاء المصدر والتدفق، بما في ذلك الواصلات والشرطات السفلية وحالة الأحرف.
* راجع **Push History** قبل إعادة إرسال دفعة فُقدت استجابتها.
* عند التواصل مع [دعم Living Security](mailto:support@livingsecurity.com)، أرفق المؤسسة والمصدر والتدفق ووقت الطلب و`runId` عند توفره وحالة الاستجابة. لا ترفق مفتاح الوصول أو حمولة الأحداث.

## ذو صلة

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/ar/integrations/zscaler-zia-cloud-nss">
    قم بإعداد خلاصة سجلات ويب مدعومة من Zscaler باستخدام المصدر والتدفق والترويسات وبنية JSON المحددة بدقة.
  </Card>

  <Card title="مفاتيح وصول API" icon="key" href="/ar/features/settings/api-keys">
    أنشئ بيانات الاعتماد محددة النطاق وأدِرها وألغِها.
  </Card>

  <Card title="مصادر بيانات الإشارات" icon="wave-pulse" href="/ar/signals/data-sources">
    تعرّف كيف يدعم النشاط المُفسَّر للتكاملات الإشارات.
  </Card>
</CardGroup>


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