> ## 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 source Push personnalisée

> Enregistrez une source et envoyez des lots d'événements JSON ou CSV à Living Security à l'aide d'une clé d'accès API à portée limitée.

Utilisez une source Push personnalisée (Custom Push Source) lorsqu'un système envoie des enregistrements à Living Security au lieu d'être interrogé par un connecteur du Catalogue. L'expéditeur peut soumettre des tableaux JSON ou des fichiers CSV à un point de terminaison HTTPS régional.

## Avant de commencer

Vous avez besoin des éléments suivants :

* l'autorisation de gérer les intégrations et les clés d'accès dans Living Security
* un expéditeur côté serveur capable d'effectuer des requêtes HTTPS `POST`
* la région Living Security de votre organisation
* un nom de source stable et au moins un nom de flux

Les noms de source et les noms de flux sont des clés de routage permanentes. Les noms de source doivent comporter de 1 à 64 lettres minuscules, chiffres ou traits d'union. Les noms de flux acceptent également les traits de soulignement. Les deux doivent commencer par une lettre ou un chiffre.

<Warning>
  Traitez la clé d'accès API comme un secret. Ne la placez pas dans du code exécuté dans le navigateur, ne l'enregistrez pas dans le contrôle de code source et ne l'envoyez pas dans une demande d'assistance.
</Warning>

## 1. Enregistrer la source et les flux

<Steps>
  <Step title="Ouvrir Custom Push Source">
    Accédez à **Paramètres → Intégrations → Catalogue**, repérez **Custom Push Source**, puis sélectionnez **Ajouter**.
  </Step>

  <Step title="Nommer la source">
    Saisissez la clé de routage de la source et une description facultative. Utilisez par exemple `custom-phishing-sim` plutôt qu'un nom d'affichage contenant des espaces.
  </Step>

  <Step title="Ajouter des flux">
    Ajoutez chaque flux que l'expéditeur utilisera. Le couple source et flux doit exister avant le premier envoi; un couple inconnu renvoie `404 Not Found`.
  </Step>

  <Step title="Enregistrer la source">
    Après la création, ouvrez la source sous **Paramètres → Intégrations → Connecté**. Sa vue **Push via API** affiche le modèle de point de terminaison et les exécutions récentes.
  </Step>
</Steps>

## 2. Créer une clé d'ingestion Push

Accédez à **Paramètres → Access Keys**, sélectionnez **Create Access Key**, puis choisissez la portée **Push Ingest**. Copiez immédiatement la valeur générée; elle n'est affichée qu'une seule fois.

La clé est liée à une seule organisation Living Security. La requête d'envoi n'a pas besoin d'un en-tête d'organisation. Consultez [Clés d'accès API](/fr-CA/features/settings/api-keys) pour la rotation et la révocation.

## 3. Choisir le point de terminaison régional

Utilisez le nom d'hôte correspondant à l'organisation Living Security :

| Région | URL de base |
| - | - |
| États-Unis | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Union européenne | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Ajoutez `/push-ingest/{integrationKey}/{streamName}`. Le chemin est sensible à la casse et doit correspondre exactement à la source et au flux enregistrés.

<ParamField path="integrationKey" type="string" required>
  Le nom de la source enregistrée. Utilisez de 1 à 64 lettres minuscules, chiffres ou traits d'union, en commençant par une lettre ou un chiffre.
</ParamField>

<ParamField path="streamName" type="string" required>
  Le nom du flux enregistré. Les mêmes règles s'appliquent, et les traits de soulignement sont également autorisés.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Envoyez la clé d'accès d'ingestion Push sous la forme `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Utilisez `application/json` pour le JSON ou `text/csv` pour le CSV. Le serveur peut également détecter un tableau JSON lorsque cet en-tête est omis.
</ParamField>

<ParamField header="x-organization-id" type="string">
  UUID d'organisation facultatif. La clé d'accès détermine déjà l'organisation. Si vous envoyez cet en-tête, il doit correspondre à l'organisation de la clé; il ne permet pas de sélectionner une autre organisation.
</ParamField>

### Corps de la requête

Envoyez un tableau JSON non vide d'objets au niveau supérieur, ou les octets d'un fichier CSV avec une ligne d'en-tête. Il n'existe aucun champ d'enveloppe JSON nommé. Chaque lot peut contenir jusqu'à 10,000 enregistrements et 10 MB.

## 4. Envoyer un lot JSON

Envoyez un tableau JSON non vide dont les éléments sont des objets. `Content-Type: application/json` est recommandé et exigé par de nombreux produits expéditeurs, même si Living Security peut détecter un corps de type tableau sans cet en-tête.

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

Une requête réussie renvoie `202 Accepted`. L'onglet d'erreur affiche un `400 Bad Request` lorsque le corps JSON est mal formé :

<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'acceptation signifie que le lot a été stocké en vue d'un traitement asynchrone. Elle ne signifie pas que chaque enregistrement a déjà été interprété en activité.
Pour l'exemple `400`, corrigez le JSON ou envoyez un CSV avec `Content-Type: text/csv`, puis réessayez.

<ResponseField name="runId" type="string" required>
  L'ID d'exécution de ce lot accepté. Conservez-le pour vérifier l'état du traitement.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Le nombre d'enregistrements acceptés et stockés.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  Le nom de la source utilisée pour cet envoi.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  Le nom du flux utilisé pour cet envoi.
</ResponseField>

## Envoyer un CSV à la place

Définissez `Content-Type: text/csv` et envoyez les octets du fichier, comme illustré dans l'exemple de requête **CSV file** ci-dessus. La première ligne fournit les noms de champs.

Le texte booléen devient un booléen et le texte numérique ordinaire devient un nombre. Les valeurs commençant par un zéro, les grands entiers non sûrs, les dates et les autres textes demeurent des chaînes. Une cellule vide omet ce champ. Les lignes mal formées, les guillemets non équilibrés et les fichiers UTF-16 sont rejetés.

## Limites des requêtes et nouvelles tentatives

| Contrat | Valeur actuelle |
| - | - |
| Nombre maximal d'enregistrements | 10,000 par requête |
| Taille maximale du corps de la requête | 10 MB |
| Débit de requêtes par organisation | 600 requêtes par 60 secondes |

Divisez les exportations plus volumineuses en lots respectant les deux limites. Attendez chaque réponse et conservez le `runId` renvoyé dans les journaux de l'expéditeur.

| Réponse | Signification | Action de l'expéditeur |
| - | - | - |
| `202` | Lot accepté | Consigner le `runId`; ne pas renvoyer immédiatement |
| `400` | Nom, JSON, CSV, nombre d'enregistrements ou corps non valide | Corriger la requête; ne pas réessayer telle quelle |
| `401` | Clé manquante, expirée, révoquée ou non valide | Remplacer la clé et utiliser l'en-tête Bearer |
| `403` | La clé n'a pas la portée requise | Créer une clé ayant la portée **Push Ingest** |
| `404` | La source ou le flux n'est pas enregistré | Enregistrer le couple exact ou corriger l'URL |
| `413` | Le corps de la requête dépasse 10 MB | Diviser le lot en requêtes plus petites |
| `429` | Limitation temporaire au niveau de l'adresse IP | Respecter `Retry-After` lorsqu'il est présent et temporiser |
| `503` | Compartiment de débit de l'organisation ou limiteur indisponible | Attendre `Retry-After`, puis renvoyer le même lot |

La limite normale d'une organisation authentifiée renvoie `503`, et non `429`, de sorte que les expéditeurs de webhooks la traitent comme pouvant être réessayée. Un `503` est renvoyé avant que le lot ne soit stocké; renvoyer ce même lot après l'intervalle indiqué ne duplique pas une exécution acceptée.

## Vérifier le flux de données

Ouvrez la source Custom Push Source et consultez **Push History**. Confirmez le flux, le nombre d'enregistrements, l'attribution de la clé et l'état du traitement. Les données associées à un interpréteur maintenu peuvent ensuite devenir des personnes et une activité normalisée. Les données sans interpréteur demeurent stockées, mais ne produisent aucune activité.

<Info>
  Utilisez les noms de champs exacts et la structure de charge utile du guide propre au fournisseur lorsqu'il en existe un. Un `202` réussi prouve la livraison, et non qu'un schéma arbitraire correspond à l'activité de Living Security.
</Info>

## Liste de vérification de dépannage

* Copiez le point de terminaison à partir de la bonne source et remplacez l'espace réservé du flux.
* Envoyez la clé d'accès sous la forme `Authorization: Bearer …`; `x-api-key` n'est pas accepté.
* Confirmez que le corps est un tableau JSON de niveau supérieur, et non un objet unique ni une enveloppe autour des enregistrements.
* Confirmez l'orthographe de la source et du flux, y compris les traits d'union, les traits de soulignement et la casse.
* Consultez **Push History** avant de renvoyer un lot dont la réponse a été perdue.
* Lorsque vous communiquez avec le [soutien de Living Security](mailto:support@livingsecurity.com), indiquez l'organisation, la source, le flux, l'heure de la requête, le `runId` lorsqu'il est disponible et l'état de la réponse. N'incluez ni la clé d'accès ni la charge utile des événements.

## Voir aussi

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/fr-CA/integrations/zscaler-zia-cloud-nss">
    Configurez un flux de journaux Web Zscaler pris en charge avec la source, le flux, les en-têtes et la structure JSON exacts.
  </Card>

  <Card title="Clés d'accès API" icon="key" href="/fr-CA/features/settings/api-keys">
    Créez, renouvelez et révoquez des identifiants à portée limitée.
  </Card>

  <Card title="Sources de données des Signaux" icon="wave-pulse" href="/fr-CA/signals/data-sources">
    Découvrez comment l'activité interprétée des intégrations alimente les signaux.
  </Card>
</CardGroup>


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