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

# Rozhraní API Custom Push Source

> Zaregistrujte zdroj a odesílejte do Living Security dávky událostí ve formátu JSON nebo CSV pomocí přístupového klíče API s omezeným rozsahem.

Použijte Custom Push Source, pokud systém odesílá záznamy do Living Security, místo aby byl dotazován konektorem z Katalogu. Odesílatel může na regionální koncový bod HTTPS odesílat pole JSON nebo soubory CSV.

## Než začnete

Potřebujete:

* oprávnění ke správě integrací a přístupových klíčů v Living Security
* odesílatele na straně serveru, který umí provádět požadavky HTTPS `POST`
* region Living Security vaší organizace
* stabilní název zdroje a alespoň jeden název streamu

Názvy zdrojů a názvy streamů jsou trvalé směrovací klíče. Název zdroje musí mít 1–64 znaků: malá písmena, číslice nebo pomlčky. U názvů streamů jsou povoleny také podtržítka. Oba názvy musí začínat písmenem nebo číslicí.

<Warning>
  S přístupovým klíčem API zacházejte jako s tajemstvím. Nevkládejte jej do kódu v prohlížeči, neukládejte jej do správy zdrojového kódu a neposílejte jej v žádosti o podporu.
</Warning>

## 1. Registrace zdroje a streamů

<Steps>
  <Step title="Otevřete Custom Push Source">
    Přejděte do **Nastavení → Integrace → Katalog**, vyhledejte **Custom Push Source** a vyberte **Přidat**.
  </Step>

  <Step title="Pojmenujte zdroj">
    Zadejte směrovací klíč zdroje a volitelný popis. Použijte například `custom-phishing-sim`, nikoli zobrazovaný název s mezerami.
  </Step>

  <Step title="Přidejte streamy">
    Přidejte každý stream, který bude odesílatel používat. Dvojice zdroje a streamu musí existovat před prvním odesláním; neznámá dvojice vrací `404 Not Found`.
  </Step>

  <Step title="Uložte zdroj">
    Po vytvoření otevřete zdroj v části **Nastavení → Integrace → Připojeno**. Zobrazení **Push via API** ukazuje vzor koncového bodu a poslední běhy.
  </Step>
</Steps>

## 2. Vytvoření klíče pro push-ingest

Přejděte do **Nastavení → Access Keys**, vyberte **Create Access Key** a zvolte rozsah **Push Ingest**. Vygenerovanou hodnotu ihned zkopírujte; zobrazí se pouze jednou.

Klíč je vázán na jednu organizaci v Living Security. Požadavek na odeslání nevyžaduje hlavičku organizace. Informace o rotaci a odvolání najdete v části [API Access Keys](/cs/features/settings/api-keys).

## 3. Výběr regionálního koncového bodu

Použijte název hostitele pro organizaci v Living Security:

| Region | Základní URL |
| - | - |
| Spojené státy | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Evropská unie | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Připojte `/push-ingest/{integrationKey}/{streamName}`. Cesta rozlišuje velikost písmen a musí přesně odpovídat registrovanému zdroji a streamu.

<ParamField path="integrationKey" type="string" required>
  Registrovaný název zdroje. Použijte 1–64 malých písmen, číslic nebo pomlček, počínaje písmenem nebo číslicí.
</ParamField>

<ParamField path="streamName" type="string" required>
  Registrovaný název streamu. Platí stejná pravidla a navíc jsou povolena podtržítka.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Odešlete přístupový klíč push-ingest jako `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Použijte `application/json` pro JSON nebo `text/csv` pro CSV. Server dokáže pole JSON rozpoznat i tehdy, když je tato hlavička vynechána.
</ParamField>

<ParamField header="x-organization-id" type="string">
  Volitelné UUID organizace. Organizaci již určuje přístupový klíč. Pokud tuto hlavičku odešlete, musí odpovídat organizaci klíče; nelze jí vybrat jinou organizaci.
</ParamField>

### Tělo požadavku

Odešlete neprázdné pole JSON objektů nejvyšší úrovně nebo bajty souboru CSV s řádkem záhlaví. Žádné pojmenované obalové pole JSON neexistuje. Jedna dávka může obsahovat až 10 000 záznamů a 10 MB.

## 4. Odeslání dávky JSON

Odešlete neprázdné pole JSON, jehož prvky jsou objekty. `Content-Type: application/json` se doporučuje a vyžaduje jej mnoho odesílajících produktů, i když Living Security dokáže rozpoznat tělo s polem i bez něj.

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

Úspěšný požadavek vrací `202 Accepted`. Karta chyb zobrazuje `400 Bad Request`, pokud je tělo JSON chybně formátované:

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

Přijetí znamená, že dávka byla uložena k asynchronnímu zpracování. Neznamená to, že všechny záznamy již byly převedeny na aktivitu.
V příkladu `400` opravte JSON nebo odešlete CSV s `Content-Type: text/csv` a akci opakujte.

<ResponseField name="runId" type="string" required>
  ID běhu pro tuto přijatou dávku. Uchovejte jej pro kontrolu stavu zpracování.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Počet přijatých a uložených záznamů.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  Název zdroje použitý pro toto odeslání.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  Název streamu použitý pro toto odeslání.
</ResponseField>

## Odeslání CSV místo JSON

Nastavte `Content-Type: text/csv` a odešlete bajty souboru, jak je uvedeno v příkladu požadavku **CSV file** výše. První řádek určuje názvy polí.

Textové logické hodnoty se převedou na logickou hodnotu a běžný číselný text na číslo. Hodnoty s počátečními nulami, nebezpečně velká celá čísla, data a další text zůstávají řetězci. Prázdné buňky dané pole vynechají. Chybně formátované řádky, nevyvážené uvozovky a soubory UTF-16 jsou odmítnuty.

## Limity požadavků a opakování

| Smlouva | Aktuální hodnota |
| - | - |
| Maximální počet záznamů | 10 000 na požadavek |
| Maximální velikost těla požadavku | 10 MB |
| Frekvence požadavků na organizaci | 600 požadavků za 60 sekund |

Větší exporty rozdělte do dávek, které splňují oba limity. Počkejte na každou odpověď a vrácené `runId` uchovávejte v protokolech odesílatele.

| Odpověď | Význam | Akce odesílatele |
| - | - | - |
| `202` | Dávka přijata | Zaznamenejte `runId`; neodesílejte okamžitě znovu |
| `400` | Neplatný název, JSON, CSV, počet záznamů nebo tělo | Opravte požadavek; neopakujte jej beze změny |
| `401` | Chybějící, vypršelý, odvolaný nebo neplatný klíč | Vyměňte klíč a použijte hlavičku Bearer |
| `403` | Klíč nemá požadovaný rozsah | Vytvořte klíč s rozsahem **Push Ingest** |
| `404` | Zdroj nebo stream není zaregistrován | Zaregistrujte přesnou dvojici nebo opravte URL |
| `413` | Tělo požadavku překračuje 10 MB | Rozdělte dávku na menší požadavky |
| `429` | Dočasné omezení na úrovni IP adresy | Pokud je přítomno `Retry-After`, dodržte je a zpomalte |
| `503` | Frekvenční limit organizace nebo omezovač není dostupný | Počkejte na `Retry-After` a poté odešlete stejnou dávku znovu |

Běžný limit ověřené organizace vrací `503`, nikoli `429`, takže odesílatelé webhooků jej považují za opakovatelný. `503` se vrací před uložením dávky; opětovné odeslání téže dávky po uvedeném intervalu nezpůsobí duplikaci přijatého běhu.

## Ověření toku dat

Otevřete Custom Push Source a zkontrolujte **Push History**. Ověřte stream, počet záznamů, přiřazení klíče a stav zpracování. Data s udržovaným interpretem se poté mohou stát osobami a normalizovanou aktivitou. Data bez interpretu zůstávají uložena, ale nevytvářejí aktivitu.

<Info>
  Pokud existuje průvodce specifický pro poskytovatele, použijte přesné názvy polí a strukturu datové části z něj. Úspěšné `202` prokazuje doručení, nikoli to, že se libovolné schéma mapuje na aktivitu v Living Security.
</Info>

## Kontrolní seznam pro řešení potíží

* Zkopírujte koncový bod z příslušného zdroje a nahraďte zástupný text streamu.
* Odešlete přístupový klíč jako `Authorization: Bearer …`; `x-api-key` se nepřijímá.
* Ověřte, že tělo je pole JSON nejvyšší úrovně, nikoli jednotlivý objekt ani obálka kolem záznamů.
* Ověřte pravopis zdroje a streamu, včetně pomlček, podtržítek a velikosti písmen.
* Před opětovným odesláním dávky, jejíž odpověď se ztratila, zkontrolujte **Push History**.
* Při kontaktování [podpory Living Security](mailto:support@livingsecurity.com) uveďte organizaci, zdroj, stream, čas požadavku, `runId` (je-li k dispozici) a stav odpovědi. Neuvádějte přístupový klíč ani datovou část událostí.

## Související

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/cs/integrations/zscaler-zia-cloud-nss">
    Nakonfigurujte podporovaný kanál webových protokolů Zscaler s přesným zdrojem, streamem, hlavičkami a strukturou JSON.
  </Card>

  <Card title="API Access Keys" icon="key" href="/cs/features/settings/api-keys">
    Vytvářejte, rotujte a odvolávejte přihlašovací údaje s omezeným rozsahem.
  </Card>

  <Card title="Signal Data Sources" icon="wave-pulse" href="/cs/signals/data-sources">
    Zjistěte, jak interpretovaná aktivita integrací podporuje Signály.
  </Card>
</CardGroup>


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