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

# Interfejs API Custom Push Source

> Zarejestruj źródło i wysyłaj do Living Security partie zdarzeń w formacie JSON lub CSV za pomocą klucza dostępu API o ograniczonym zakresie.

Użyj Custom Push Source, gdy system przesyła rekordy do Living Security, zamiast być odpytywany przez konektor z Katalogu. Nadawca może przesyłać tablice JSON lub pliki CSV na regionalny punkt końcowy HTTPS.

## Zanim zaczniesz

Potrzebne są:

* uprawnienie do zarządzania integracjami i kluczami dostępu w Living Security
* nadawca po stronie serwera, który może wykonywać żądania HTTPS `POST`
* region Living Security przypisany do Twojej organizacji
* stała nazwa źródła i co najmniej jedna nazwa strumienia

Nazwy źródeł i nazwy strumieni są trwałymi kluczami routingu. Nazwy źródeł muszą składać się z 1–64 małych liter, cyfr lub łączników. Nazwy strumieni dopuszczają dodatkowo znaki podkreślenia. Obie nazwy muszą zaczynać się od litery lub cyfry.

<Warning>
  Traktuj klucz dostępu API jako dane poufne. Nie umieszczaj go w kodzie przeglądarki, nie zatwierdzaj go w systemie kontroli wersji ani nie przesyłaj w zgłoszeniu do pomocy technicznej.
</Warning>

## 1. Zarejestruj źródło i strumienie

<Steps>
  <Step title="Otwórz Custom Push Source">
    Przejdź do **Ustawienia → Integracje → Katalog**, znajdź **Custom Push Source** i wybierz **Dodatek**.
  </Step>

  <Step title="Nazwij źródło">
    Wprowadź klucz routingu źródła oraz opcjonalny opis. Na przykład użyj `custom-phishing-sim` zamiast nazwy wyświetlanej ze spacjami.
  </Step>

  <Step title="Dodaj strumienie">
    Dodaj każdy strumień, którego będzie używał nadawca. Para źródło–strumień musi istnieć przed pierwszym przesłaniem; nieznana para zwraca `404 Not Found`.
  </Step>

  <Step title="Zapisz źródło">
    Po utworzeniu otwórz źródło w sekcji **Ustawienia → Integracje → Połączono**. Widok **Push via API** zawiera wzorzec punktu końcowego i ostatnie uruchomienia.
  </Step>
</Steps>

## 2. Utwórz klucz push-ingest

Przejdź do **Ustawienia → Access Keys**, wybierz **Create Access Key** i wybierz zakres **Push Ingest**. Skopiuj wygenerowaną wartość od razu; jest wyświetlana tylko raz.

Klucz jest powiązany z jedną organizacją w Living Security. Żądanie przesłania danych nie wymaga nagłówka organizacji. Informacje o rotacji i unieważnianiu znajdziesz w artykule [API Access Keys](/pl/features/settings/api-keys).

## 3. Wybierz regionalny punkt końcowy

Użyj nazwy hosta odpowiadającej organizacji w Living Security:

| Region | Bazowy adres URL |
| - | - |
| Stany Zjednoczone | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Unia Europejska | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Dołącz `/push-ingest/{integrationKey}/{streamName}`. Ścieżka rozróżnia wielkość liter i musi dokładnie odpowiadać zarejestrowanemu źródłu i strumieniowi.

<ParamField path="integrationKey" type="string" required>
  Zarejestrowana nazwa źródła. Użyj 1–64 małych liter, cyfr lub łączników, zaczynając od litery lub cyfry.
</ParamField>

<ParamField path="streamName" type="string" required>
  Zarejestrowana nazwa strumienia. Obowiązują te same zasady, a dozwolone są także znaki podkreślenia.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Prześlij klucz dostępu push-ingest jako `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Użyj `application/json` dla JSON lub `text/csv` dla CSV. Serwer potrafi również wykryć tablicę JSON, gdy ten nagłówek zostanie pominięty.
</ParamField>

<ParamField header="x-organization-id" type="string">
  Opcjonalny identyfikator UUID organizacji. Klucz dostępu już określa organizację. Jeśli prześlesz ten nagłówek, musi on odpowiadać organizacji klucza; nie można za jego pomocą wybrać innej organizacji.
</ParamField>

### Treść żądania

Wyślij niepustą tablicę JSON obiektów najwyższego poziomu lub bajty pliku CSV z wierszem nagłówka. Nie ma nazwanego pola opakowującego JSON. Każda partia może zawierać do 10 000 rekordów i 10 MB.

## 4. Wyślij partię JSON

Wyślij niepustą tablicę JSON, której elementami są obiekty. Nagłówek `Content-Type: application/json` jest zalecany i wymagany przez wiele produktów wysyłających, mimo że Living Security potrafi wykryć treść będącą tablicą bez niego.

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

Pomyślne żądanie zwraca `202 Accepted`. Karta błędu pokazuje `400 Bad Request`, gdy treść JSON jest nieprawidłowo sformułowana:

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

Przyjęcie oznacza, że partia została zapisana do przetwarzania asynchronicznego. Nie oznacza, że każdy rekord został już zinterpretowany jako aktywność.
W przypadku przykładu `400` popraw JSON lub wyślij CSV z nagłówkiem `Content-Type: text/csv`, a następnie ponów próbę.

<ResponseField name="runId" type="string" required>
  Identyfikator uruchomienia dla tej przyjętej partii. Zachowaj go, aby sprawdzić stan przetwarzania.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Liczba przyjętych i zapisanych rekordów.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  Nazwa źródła użyta w tym przesłaniu.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  Nazwa strumienia użyta w tym przesłaniu.
</ResponseField>

## Wysyłanie w formacie CSV

Ustaw `Content-Type: text/csv` i wyślij bajty pliku, jak pokazano w przykładzie żądania **CSV file** powyżej. Pierwszy wiersz określa nazwy pól.

Tekst logiczny jest zamieniany na wartość logiczną, a zwykły tekst liczbowy na liczbę. Wartości z wiodącym zerem, zbyt duże liczby całkowite, daty i pozostały tekst pozostają ciągami znaków. Puste komórki powodują pominięcie danego pola. Nieprawidłowo sformułowane wiersze, niezrównoważone cudzysłowy oraz pliki UTF-16 są odrzucane.

## Limity żądań i ponawianie

| Ograniczenie | Bieżąca wartość |
| - | - |
| Maksymalna liczba rekordów | 10 000 na żądanie |
| Maksymalny rozmiar treści żądania | 10 MB |
| Limit szybkości żądań na organizację | 600 żądań na 60 sekund |

Podziel większe eksporty na partie spełniające oba limity. Czekaj na każdą odpowiedź i zachowuj zwrócony `runId` w dziennikach nadawcy.

| Odpowiedź | Znaczenie | Działanie nadawcy |
| - | - | - |
| `202` | Partia została przyjęta | Zapisz `runId`; nie wysyłaj ponownie od razu |
| `400` | Nieprawidłowa nazwa, JSON, CSV, liczba rekordów lub treść | Popraw żądanie; nie ponawiaj go bez zmian |
| `401` | Brak klucza lub klucz wygasły, unieważniony albo nieprawidłowy | Wymień klucz i użyj nagłówka Bearer |
| `403` | Klucz nie ma wymaganego zakresu | Utwórz klucz z zakresem **Push Ingest** |
| `404` | Źródło lub strumień nie jest zarejestrowane | Zarejestruj dokładną parę lub popraw adres URL |
| `413` | Treść żądania przekracza 10 MB | Podziel partię na mniejsze żądania |
| `429` | Tymczasowe ograniczanie na poziomie adresu IP | Zastosuj się do `Retry-After`, jeśli występuje, i wydłuż odstępy między próbami |
| `503` | Pula limitu organizacji lub mechanizm ograniczania jest niedostępny | Poczekaj na `Retry-After`, a następnie wyślij ponownie tę samą partię |

Standardowy limit uwierzytelnionej organizacji zwraca `503`, a nie `429`, dzięki czemu nadawcy webhooków traktują go jako możliwy do ponowienia. Odpowiedź `503` jest zwracana przed zapisaniem partii; ponowne wysłanie tej samej partii po wskazanym czasie nie powoduje zduplikowania przyjętego uruchomienia.

## Weryfikacja przepływu danych

Otwórz Custom Push Source i przejrzyj **Push History**. Sprawdź strumień, liczbę rekordów, przypisanie klucza i stan przetwarzania. Dane z utrzymywanym interpreterem mogą następnie stać się osobami i znormalizowaną aktywnością. Dane bez interpretera pozostają zapisane, ale nie generują aktywności.

<Info>
  Jeśli istnieje przewodnik dla konkretnego dostawcy, użyj z niego dokładnych nazw pól i struktury ładunku. Pomyślne `202` potwierdza dostarczenie, a nie to, że dowolny schemat jest mapowany na aktywność w Living Security.
</Info>

## Lista kontrolna rozwiązywania problemów

* Skopiuj punkt końcowy z właściwego źródła i zastąp symbol zastępczy strumienia.
* Prześlij klucz dostępu jako `Authorization: Bearer …`; `x-api-key` nie jest akceptowane.
* Upewnij się, że treść jest tablicą JSON najwyższego poziomu, a nie pojedynczym obiektem ani kopertą otaczającą rekordy.
* Sprawdź pisownię źródła i strumienia, w tym łączniki, znaki podkreślenia i wielkość liter.
* Przed ponownym wysłaniem partii, której odpowiedź została utracona, przejrzyj **Push History**.
* Kontaktując się z [pomocą techniczną Living Security](mailto:support@livingsecurity.com), podaj organizację, źródło, strumień, czas żądania, `runId` (jeśli jest dostępny) i stan odpowiedzi. Nie dołączaj klucza dostępu ani ładunku zdarzeń.

## Powiązane

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/pl/integrations/zscaler-zia-cloud-nss">
    Skonfiguruj obsługiwany kanał dzienników webowych Zscaler, używając dokładnego źródła, strumienia, nagłówków i struktury JSON.
  </Card>

  <Card title="API Access Keys" icon="key" href="/pl/features/settings/api-keys">
    Tworzenie, rotacja i unieważnianie poświadczeń o ograniczonym zakresie.
  </Card>

  <Card title="Signal Data Sources" icon="wave-pulse" href="/pl/signals/data-sources">
    Dowiedz się, w jaki sposób zinterpretowana aktywność integracji wspiera Sygnały.
  </Card>
</CardGroup>


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