> ## 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 de Custom Push Source

> Registreu una font i envieu lots d'esdeveniments en format JSON o CSV a Living Security amb una clau d'accés d'API d'àmbit restringit.

Utilitzeu una Custom Push Source quan un sistema envia registres a Living Security en lloc de ser consultat per un connector del Catalog. L'emissor pot enviar matrius JSON o fitxers CSV a un endpoint HTTPS regional.

## Abans de començar

Necessiteu:

* permís per gestionar integracions i claus d'accés a Living Security
* un emissor del costat del servidor que pugui fer sol·licituds HTTPS `POST`
* la regió de Living Security de la vostra organització
* un nom de font estable i almenys un nom de flux

Els noms de font i de flux són claus d'encaminament permanents. Els noms de font han de tenir entre 1 i 64 caràcters, i han de ser lletres minúscules, dígits o guions. Els noms de flux també admeten guions baixos. Tots dos han de començar amb una lletra o un dígit.

<Warning>
  Tracteu la clau d'accés d'API com un secret. No la poseu en codi del navegador, no la pengeu
  al control de versions ni l'envieu en un tiquet de suport.
</Warning>

## 1. Registreu la font i els fluxos

<Steps>
  <Step title="Obriu Custom Push Source">
    Aneu a **Settings → Integrations → Catalog**, cerqueu **Custom Push Source** i seleccioneu **Add**.
  </Step>

  <Step title="Poseu nom a la font">
    Introduïu la clau d'encaminament de la font i una descripció opcional. Per exemple, utilitzeu `custom-phishing-sim` en lloc d'un nom visible amb espais.
  </Step>

  <Step title="Afegiu fluxos">
    Afegiu cada flux que utilitzarà l'emissor. El parell format per la font i el flux ha d'existir abans del primer enviament; un parell desconegut retorna `404 Not Found`.
  </Step>

  <Step title="Deseu la font">
    Un cop creada, obriu la font a **Settings → Integrations → Connected**. La seva vista **Push via API** mostra el patró de l'endpoint i les execucions recents.
  </Step>
</Steps>

## 2. Creeu una clau push-ingest

Aneu a **Settings → Access Keys**, seleccioneu **Create Access Key** i trieu l'àmbit **Push Ingest**. Copieu immediatament el valor generat; només es mostra una vegada.

La clau està vinculada a una sola organització de Living Security. La sol·licitud d'enviament no necessita cap capçalera d'organització. Consulteu [API Access Keys](/ca/features/settings/api-keys) per a la rotació i la revocació.

## 3. Trieu l'endpoint regional

Utilitzeu el nom d'amfitrió de l'organització de Living Security:

| Regió | URL base |
| - | - |
| Estats Units | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Unió Europea | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Afegiu-hi `/push-ingest/{integrationKey}/{streamName}`. La ruta distingeix majúscules i minúscules i ha de coincidir exactament amb la font i el flux registrats.

<ParamField path="integrationKey" type="string" required>
  El nom de la font registrada. Utilitzeu entre 1 i 64 lletres minúscules, dígits o guions, començant amb una lletra o un dígit.
</ParamField>

<ParamField path="streamName" type="string" required>
  El nom del flux registrat. S'apliquen les mateixes regles i també s'admeten els guions baixos.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Envieu la clau d'accés push-ingest com a `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Utilitzeu `application/json` per a JSON o `text/csv` per a CSV. El servidor també pot detectar una matriu JSON quan s'omet aquesta capçalera.
</ParamField>

<ParamField header="x-organization-id" type="string">
  UUID d'organització opcional. La clau d'accés ja determina l'organització. Si envieu aquesta capçalera, ha de coincidir amb l'organització de la clau; no permet seleccionar una altra organització.
</ParamField>

### Cos de la sol·licitud

Envieu una matriu JSON de nivell superior no buida d'objectes o els bytes d'un fitxer CSV amb una fila de capçalera. No hi ha cap camp contenidor JSON amb nom. Cada lot pot contenir fins a 10,000 registres i 10 MB.

## 4. Envieu un lot JSON

Envieu una matriu JSON no buida els elements de la qual siguin objectes. `Content-Type: application/json` és recomanable i molts productes emissors l'exigeixen, tot i que Living Security pot detectar un cos de tipus matriu sense aquesta capçalera.

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

Una sol·licitud correcta retorna `202 Accepted`. La pestanya d'error mostra un `400 Bad Request` quan el cos JSON està mal format:

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

L'acceptació vol dir que el lot s'ha emmagatzemat per al seu processament asíncron. No vol dir que tots els registres ja s'hagin interpretat com a activitat.
Per a l'exemple de `400`, corregiu el JSON o envieu CSV amb `Content-Type: text/csv` i torneu-ho a provar.

<ResponseField name="runId" type="string" required>
  L'identificador d'execució d'aquest lot acceptat. Conserveu-lo per consultar l'estat del processament.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  El nombre de registres acceptats i emmagatzemats.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  El nom de la font utilitzada en aquest enviament.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  El nom del flux utilitzat en aquest enviament.
</ResponseField>

## Envieu CSV en lloc de JSON

Definiu `Content-Type: text/csv` i envieu els bytes del fitxer, tal com es mostra a l'exemple de sol·licitud **CSV file** anterior. La primera fila proporciona els noms dels camps.

El text booleà es converteix en un booleà i el text numèric ordinari es converteix en un número. Els valors amb zeros a l'esquerra, els enters grans no segurs, les dates i la resta de text romanen com a cadenes. Les cel·les buides ometen aquest camp. Es rebutgen les files mal formades, les cometes no equilibrades i els fitxers UTF-16.

## Límits de les sol·licituds i reintents

| Contracte | Valor actual |
| - | - |
| Màxim de registres | 10,000 per sol·licitud |
| Mida màxima del cos de la sol·licitud | 10 MB |
| Taxa de sol·licituds per organització | 600 sol·licituds cada 60 segons |

Dividiu les exportacions més grans en lots que compleixin els dos límits. Espereu cada resposta i conserveu el `runId` retornat als registres de l'emissor.

| Resposta | Significat | Acció de l'emissor |
| - | - | - |
| `202` | Lot acceptat | Registreu el `runId`; no el torneu a enviar immediatament |
| `400` | Nom, JSON, CSV, nombre de registres o cos no vàlids | Corregiu la sol·licitud; no la reintenteu sense canvis |
| `401` | Clau absent, caducada, revocada o no vàlida | Substituïu la clau i utilitzeu la capçalera Bearer |
| `403` | La clau no té l'àmbit necessari | Creeu una clau amb l'àmbit **Push Ingest** |
| `404` | La font o el flux no estan registrats | Registreu el parell exacte o corregiu l'URL |
| `413` | El cos de la sol·licitud supera els 10 MB | Dividiu el lot en sol·licituds més petites |
| `429` | Limitació temporal a nivell d'IP | Respecteu `Retry-After` si hi és present i espereu abans de reintentar |
| `503` | El compartiment de taxa de l'organització o el limitador no estan disponibles | Espereu `Retry-After` i torneu a enviar el mateix lot |

El límit normal de l'organització autenticada retorna `503`, no `429`, de manera que els emissors de webhooks el tracten com a reintentable. Un `503` es retorna abans que s'emmagatzemi el lot; tornar a enviar el mateix lot després de l'interval indicat no duplica una execució acceptada.

## Verifiqueu el flux de dades

Obriu la Custom Push Source i reviseu **Push History**. Confirmeu el flux, el nombre de registres, l'atribució de la clau i l'estat del processament. Les dades amb un intèrpret mantingut poden convertir-se després en persones i activitat normalitzada. Les dades sense intèrpret romanen emmagatzemades, però no generen activitat.

<Info>
  Utilitzeu els noms de camp exactes i l'estructura de la càrrega útil de la guia
  específica del proveïdor quan n'hi hagi una. Un `202` correcte demostra el lliurament, no que un
  esquema arbitrari s'assigni a l'activitat de Living Security.
</Info>

## Llista de comprovació per a la resolució de problemes

* Copieu l'endpoint de la font correcta i substituïu el marcador de posició del flux.
* Envieu la clau d'accés com a `Authorization: Bearer …`; `x-api-key` no s'accepta.
* Confirmeu que el cos és una matriu JSON de nivell superior, no un sol objecte ni un contenidor al voltant dels registres.
* Confirmeu l'ortografia de la font i del flux, incloent-hi guions, guions baixos i majúscules o minúscules.
* Reviseu **Push History** abans de tornar a enviar un lot la resposta del qual s'hagi perdut.
* Quan contacteu amb [Living Security Support](mailto:support@livingsecurity.com), inclogueu l'organització, la font, el flux, l'hora de la sol·licitud, `runId` si està disponible i l'estat de la resposta. No inclogueu la clau d'accés ni la càrrega útil de l'esdeveniment.

## Relacionat

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/ca/integrations/zscaler-zia-cloud-nss">
    Configureu un feed de registres web de Zscaler compatible amb la font, el flux, les capçaleres i l'estructura JSON exactes.
  </Card>

  <Card title="API Access Keys" icon="key" href="/ca/features/settings/api-keys">
    Creeu, roteu i reviqueu credencials d'àmbit restringit.
  </Card>

  <Card title="Signal Data Sources" icon="wave-pulse" href="/ca/signals/data-sources">
    Conegueu com l'activitat interpretada de les integracions dona suport als Signals.
  </Card>
</CardGroup>


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