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

# API pentru sursa push personalizată

> Înregistrați o sursă și trimiteți către Living Security loturi de evenimente JSON sau CSV, folosind o cheie de acces API cu domeniu restricționat.

Utilizați o sursă push personalizată atunci când un sistem trimite înregistrări către Living Security, în loc să fie interogat de un conector din Catalog. Expeditorul poate trimite matrice JSON sau fișiere CSV către un endpoint HTTPS regional.

## Înainte de a începe

Aveți nevoie de:

* permisiunea de a gestiona integrările și cheile de acces în Living Security
* un expeditor de pe partea de server, capabil să trimită solicitări HTTPS `POST`
* regiunea Living Security a organizației dumneavoastră
* un nume de sursă stabil și cel puțin un nume de flux

Numele surselor și numele fluxurilor sunt chei de rutare permanente. Numele surselor trebuie să conțină între 1 și 64 de litere mici, cifre sau cratime. Numele fluxurilor permit și caracterul de subliniere. Ambele trebuie să înceapă cu o literă sau o cifră.

<Warning>
  Tratați cheia de acces API ca pe un secret. Nu o includeți în codul din browser, nu o adăugați
  în controlul versiunilor și nu o trimiteți într-un tichet de asistență.
</Warning>

## 1. Înregistrați sursa și fluxurile

<Steps>
  <Step title="Deschideți sursa push personalizată">
    Accesați **Setări → Integrari → Catalog**, găsiți **Sursă push personalizată** și selectați **Adaugă**.
  </Step>

  <Step title="Denumiți sursa">
    Introduceți cheia de rutare a sursei și, opțional, o descriere. De exemplu, folosiți `custom-phishing-sim` în loc de un nume afișat care conține spații.
  </Step>

  <Step title="Adăugați fluxuri">
    Adăugați fiecare flux pe care îl va utiliza expeditorul. Perechea sursă–flux trebuie să existe înainte de primul push; o pereche necunoscută returnează `404 Not Found`.
  </Step>

  <Step title="Salvați sursa">
    După creare, deschideți sursa din **Setări → Integrari → Conectat**. Vizualizarea **Trimitere prin API** afișează modelul endpointului și execuțiile recente.
  </Step>
</Steps>

## 2. Creați o cheie push-ingest

Accesați **Setări → Chei de acces**, selectați **Creează cheie de acces** și alegeți domeniul **Ingestie push**. Copiați imediat valoarea generată; aceasta este afișată o singură dată.

Cheia este asociată unei singure organizații Living Security. Solicitarea push nu necesită un antet de organizație. Consultați [Chei de acces API](/ro/features/settings/api-keys) pentru rotire și revocare.

## 3. Alegeți endpointul regional

Utilizați numele de gazdă corespunzător organizației Living Security:

| Regiune | URL de bază |
| - | - |
| Statele Unite | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Uniunea Europeană | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Adăugați `/push-ingest/{integrationKey}/{streamName}`. Calea face distincție între majuscule și minuscule și trebuie să corespundă exact sursei și fluxului înregistrate.

<ParamField path="integrationKey" type="string" required>
  Numele sursei înregistrate. Utilizați între 1 și 64 de litere mici, cifre sau cratime, începând cu o literă sau o cifră.
</ParamField>

<ParamField path="streamName" type="string" required>
  Numele fluxului înregistrat. Se aplică aceleași reguli, iar caracterul de subliniere este de asemenea permis.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Trimiteți cheia de acces push-ingest sub forma `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Utilizați `application/json` pentru JSON sau `text/csv` pentru CSV. Serverul poate detecta o matrice JSON și atunci când acest antet lipsește.
</ParamField>

<ParamField header="x-organization-id" type="string">
  UUID-ul organizației, opțional. Cheia de acces determină deja organizația. Dacă trimiteți acest antet, acesta trebuie să corespundă organizației cheii; nu poate selecta altă organizație.
</ParamField>

### Corpul solicitării

Trimiteți o matrice JSON de nivel superior, nevidă, de obiecte, sau octeții unui fișier CSV cu un rând de antet. Nu există un câmp JSON de încadrare cu nume. Fiecare lot poate conține până la 10,000 de înregistrări și 10 MB.

## 4. Trimiteți un lot JSON

Trimiteți o matrice JSON nevidă ale cărei elemente sunt obiecte. `Content-Type: application/json` este recomandat și este necesar pentru multe produse de trimitere, chiar dacă Living Security poate detecta un corp de tip matrice și fără acesta.

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

O solicitare reușită returnează `202 Accepted`. Fila de eroare afișează un `400 Bad Request` atunci când corpul JSON este malformat:

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

Acceptarea înseamnă că lotul a fost stocat pentru procesare asincronă. Aceasta nu înseamnă că fiecare înregistrare a fost deja interpretată ca activitate.
Pentru exemplul `400`, corectați JSON-ul sau trimiteți CSV cu `Content-Type: text/csv`, apoi reîncercați.

<ResponseField name="runId" type="string" required>
  ID-ul execuției pentru acest lot acceptat. Păstrați-l pentru a verifica starea procesării.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Numărul de înregistrări acceptate și stocate.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  Numele sursei utilizate pentru acest push.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  Numele fluxului utilizat pentru acest push.
</ResponseField>

## Trimiteți CSV în schimb

Setați `Content-Type: text/csv` și trimiteți octeții fișierului, așa cum se arată în exemplul de solicitare **Fișier CSV** de mai sus. Primul rând furnizează numele câmpurilor.

Textul booleean devine valoare booleană, iar textul numeric obișnuit devine număr. Valorile cu zerouri la început, numerele întregi mari nesigure, datele calendaristice și alt text rămân șiruri de caractere. Celulele goale omit câmpul respectiv. Rândurile malformate, ghilimelele dezechilibrate și fișierele UTF-16 sunt respinse.

## Limite ale solicitărilor și reîncercări

| Contract | Valoare curentă |
| - | - |
| Număr maxim de înregistrări | 10,000 per solicitare |
| Dimensiune maximă a corpului solicitării | 10 MB |
| Rata de solicitări per organizație | 600 de solicitări la 60 de secunde |

Împărțiți exporturile mai mari în loturi care respectă ambele limite. Așteptați fiecare răspuns și păstrați `runId` returnat în jurnalele expeditorului.

| Răspuns | Semnificație | Acțiunea expeditorului |
| - | - | - |
| `202` | Lot acceptat | Înregistrați `runId`; nu retrimiteți imediat |
| `400` | Nume, JSON, CSV, număr de înregistrări sau corp nevalid | Corectați solicitarea; nu reîncercați fără modificări |
| `401` | Cheie lipsă, expirată, revocată sau nevalidă | Înlocuiți cheia și utilizați antetul Bearer |
| `403` | Cheia nu are domeniul necesar | Creați o cheie cu domeniul **Ingestie push** |
| `404` | Sursa sau fluxul nu este înregistrat | Înregistrați perechea exactă sau corectați URL-ul |
| `413` | Corpul solicitării depășește 10 MB | Împărțiți lotul în solicitări mai mici |
| `429` | Limitare temporară la nivel de IP | Respectați `Retry-After` atunci când este prezent și reduceți ritmul |
| `503` | Bucket-ul ratei organizației sau limitatorul este indisponibil | Așteptați `Retry-After`, apoi retrimiteți același lot |

Limita normală a organizației autentificate returnează `503`, nu `429`, astfel încât expeditorii de webhook-uri o tratează ca fiind reîncercabilă. Un `503` este returnat înainte ca lotul să fie stocat; retrimiterea aceluiași lot după intervalul indicat nu duplică o execuție acceptată.

## Verificați fluxul de date

Deschideți sursa push personalizată și consultați **Istoric push**. Confirmați fluxul, numărul de înregistrări, atribuirea cheii și starea procesării. Datele pentru care există un interpretor întreținut pot deveni apoi persoane și activitate normalizată. Datele fără interpretor rămân stocate, dar nu produc activitate.

<Info>
  Utilizați numele exacte ale câmpurilor și structura payloadului din ghidul specific
  furnizorului, atunci când există unul. Un `202` reușit dovedește livrarea, nu faptul că o
  schemă arbitrară se mapează pe activitatea din Living Security.
</Info>

## Listă de verificare pentru depanare

* Copiați endpointul din sursa corectă și înlocuiți substituentul pentru flux.
* Trimiteți cheia de acces sub forma `Authorization: Bearer …`; `x-api-key` nu este acceptat.
* Confirmați că trupul este o matrice JSON de nivel superior, nu un singur obiect sau o structură de încadrare în jurul înregistrărilor.
* Confirmați ortografia sursei și a fluxului, inclusiv cratimele, caracterele de subliniere și diferența dintre majuscule și minuscule.
* Consultați **Istoric push** înainte de a retrimite un lot al cărui răspuns s-a pierdut.
* Când contactați [Asistența Living Security](mailto:support@livingsecurity.com), includeți organizația, sursa, fluxul, ora solicitării, `runId` când este disponibil și starea răspunsului. Nu includeți cheia de acces sau payloadul evenimentelor.

## Resurse conexe

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/ro/integrations/zscaler-zia-cloud-nss">
    Configurați un flux compatibil de jurnale web Zscaler cu sursa, fluxul, antetele și structura JSON exacte.
  </Card>

  <Card title="Chei de acces API" icon="key" href="/ro/features/settings/api-keys">
    Creați, rotiți și revocați credențiale cu domeniu restricționat.
  </Card>

  <Card title="Surse de date pentru semnale" icon="wave-pulse" href="/ro/signals/data-sources">
    Aflați cum activitatea interpretată a integrărilor susține semnalele.
  </Card>
</CardGroup>


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