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

# Custom Push Source API

> רישום מקור ושליחת אצוות אירועים בפורמט JSON או CSV אל Living Security באמצעות מפתח גישה ל-API בעל היקף הרשאות מוגדר.

השתמשו ב-Custom Push Source כאשר מערכת שולחת רשומות אל Living Security, במקום שהנתונים יישאבו באמצעות מחבר מה-Catalog. השולח יכול להגיש מערכי JSON או קובצי CSV אל נקודת קצה אזורית מסוג HTTPS.

## לפני שתתחילו

נדרשים לכם:

* הרשאה לנהל אינטגרציות ומפתחות גישה ב-Living Security
* שולח בצד השרת המסוגל לבצע בקשות HTTPS `POST`
* אזור Living Security של הארגון שלכם
* שם מקור קבוע ולפחות שם זרם אחד

שמות מקורות ושמות זרמים הם מפתחות ניתוב קבועים. שם מקור חייב להכיל 1–64 תווים: אותיות לטיניות קטנות, ספרות או מקפים. שמות זרמים מתירים גם קווים תחתונים. שניהם חייבים להתחיל באות או בספרה.

<Warning>
  התייחסו למפתח הגישה ל-API כאל סוד. אל תציבו אותו בקוד שרץ בדפדפן, אל תעלו אותו
  לניהול גרסאות, ואל תשלחו אותו בפנייה לתמיכה.
</Warning>

## 1. רישום המקור והזרמים

<Steps>
  <Step title="פתיחת Custom Push Source">
    עברו אל **הגדרות → שילובי → קטלוג**, אתרו את **Custom Push Source** ובחרו **הוסף**.
  </Step>

  <Step title="מתן שם למקור">
    הזינו את מפתח הניתוב של המקור ותיאור אופציונלי. לדוגמה, השתמשו ב-`custom-phishing-sim` ולא בשם תצוגה הכולל רווחים.
  </Step>

  <Step title="הוספת זרמים">
    הוסיפו כל זרם שבו ישתמש השולח. זוג המקור והזרם חייב להתקיים לפני השליחה הראשונה; זוג לא מוכר מחזיר `404 Not Found`.
  </Step>

  <Step title="שמירת המקור">
    לאחר היצירה, פתחו את המקור תחת **הגדרות → שילובי → מחובר**. התצוגה **Push via API** מציגה את תבנית נקודת הקצה ואת ההרצות האחרונות.
  </Step>
</Steps>

## 2. יצירת מפתח Push Ingest

עברו אל **הגדרות → Access Keys**, בחרו **Create Access Key** ובחרו את ההיקף **Push Ingest**. העתיקו מיד את הערך שנוצר; הוא מוצג פעם אחת בלבד.

המפתח קשור לארגון Living Security אחד. בקשת השליחה אינה דורשת כותרת ארגון. לפרטים על החלפה וביטול, ראו [מפתחות גישה ל-API](/he/features/settings/api-keys).

## 3. בחירת נקודת הקצה האזורית

השתמשו בשם המארח המתאים לארגון ה-Living Security שלכם:

| אזור | כתובת בסיס |
| - | - |
| ארצות הברית | `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>
  שלחו את מפתח הגישה מסוג Push Ingest בתור `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="/he/integrations/zscaler-zia-cloud-nss">
    הגדירו הזנת יומני אינטרנט נתמכת של Zscaler עם המקור, הזרם, הכותרות ומבנה ה-JSON המדויקים.
  </Card>

  <Card title="מפתחות גישה ל-API" icon="key" href="/he/features/settings/api-keys">
    יצירה, החלפה וביטול של אישורי גישה בעלי היקף הרשאות מוגדר.
  </Card>

  <Card title="מקורות נתונים של אותות" icon="wave-pulse" href="/he/signals/data-sources">
    למדו כיצד פעילות מפוענחת של אינטגרציות תומכת באותות.
  </Card>
</CardGroup>


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