Jak konfigurować alerty listy obserwowanych

Endpoint /api/v1/watchlist/alerts steruje tym, kiedy i w jaki sposób otrzymujesz powiadomienia o zmianach wykrytych w company monitor: GET odczytuje ustawienia, PATCH je zmienia. Masz jeden globalny profil dla wszystkich monitorowanych firm i możesz nadać wybranym firmom własne ustawienia.

Zanim zaczniesz – domyślne ustawienia

Każde konto ma globalny profil alertów, który startuje z alertami wyłączonymi (alerts_enabled: false, notify_via_email: false, próg warning). Każda firma dodana do listy – także przywrócona po usunięciu – dziedziczy ten profil. Firma z własnymi ustawieniami ma pierwszeństwo przed profilem globalnym.

Odczyt ustawień

GET bez parametrów zwraca profil globalny, z identifier_type i identifier_value – ustawienia obowiązujące wskazaną firmę z Twojej listy. Pole source mówi, skąd pochodzą: global albo company_override. Odczyt nic nie zmienia (updated: 0).

GET /api/v1/watchlist/alerts

curl "https://api.entiway.com/api/v1/watchlist/alerts" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

curl "https://api.entiway.com/api/v1/watchlist/alerts?identifier_type=NIP&identifier_value=1234560007" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "updated": 0,
    "settings": {
      "source":              "global",
      "alerts_enabled":      false,
      "alert_min_severity":  "warning",
      "alert_event_classes": null,
      "alert_categories":    null,
      "notify_via_email":    false
    }
  }
}

Konfiguracja globalna

Pomiń zarówno identifier_type jak i identifier_value. Zmieniasz profil globalny – obowiązuje od razu wszystkie firmy bez własnych ustawień, bez przepisywania każdej z nich. Zmieniają się tylko pola podane w żądaniu. W poniższym przykładzie każdy event na poziomie warning lub wyższym wyzwala powiadomienie email.

PATCH /api/v1/watchlist/alerts

curl -X PATCH "https://api.entiway.com/api/v1/watchlist/alerts" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_min_severity": "warning",
    "alerts_enabled":     true,
    "notify_via_email":   true
  }'

{
  "success": true,
  "data": {
    "updated": 1,
    "settings": {
      "source":              "global",
      "alerts_enabled":      true,
      "alert_min_severity":  "warning",
      "alert_event_classes": null,
      "alert_categories":    null,
      "notify_via_email":    true
    }
  }
}

Globalny z force – wszystkie firmy wracają do globalnych

Dodanie force: true zmienia profil globalny i jednocześnie zdejmuje własne ustawienia ze wszystkich firm na liście – każda wraca do profilu globalnego. updated = 1 (profil) + liczba przywróconych firm. Użyj, gdy chcesz wymusić jednolitą politykę na całej watchliście.

PATCH /api/v1/watchlist/alerts

  -d '{
    "alert_min_severity": "warning",
    "alerts_enabled":     true,
    "notify_via_email":   true,
    "force":             true
  }'

Konfiguracja per firma

Przekaż identifier_type i identifier_value, żeby wskazać firmę z Twojej listy (numer jak przy dodawaniu: bez spacji i myślników, zera wiodące uzupełniane; firma spoza listy → 404). Firma dostaje własne ustawienia (source: company_override) – zaczynają od aktualnych globalnych, zmieniają się tylko podane pola. Przyszłe zmiany profilu globalnego jej nie dotyczą, dopóki nie wrócisz do globalnych (use_global_settings albo force). W przykładzie poniżej powiadomienie wyzwalają tylko eventy klasy risk i anomaly w kategoriach finance lub status na poziomie high lub wyższym.

PATCH /api/v1/watchlist/alerts

  -d '{
    "alert_min_severity":  "high",
    "alerts_enabled":      true,
    "notify_via_email":    true,
    "alert_event_classes": ["risk", "anomaly"],
    "alert_categories":    ["finance", "status"],
    "identifier_type":     "NIP",
    "identifier_value":    "1234560007"
  }'

Powrót jednej firmy do globalnych

use_global_settings: true z identyfikatorem firmy usuwa jej własne ustawienia – firma znów korzysta z profilu globalnego (source: global). Profil globalny i pozostałe firmy się nie zmieniają.

PATCH /api/v1/watchlist/alerts

  -d '{
    "use_global_settings": true,
    "identifier_type":     "NIP",
    "identifier_value":    "1234560007"
  }'

Tabela parametrów

Parametry PATCH są przekazywane jako body JSON i żaden z osobna nie jest wymagany – zmieniają się tylko podane pola. Żądanie musi zawierać co najmniej jedno ustawienie albo use_global_settings: true; puste → 422.

Priorytety ustawień

Gdy wykryta zostaje zmiana, system rozstrzyga które ustawienia alertów zastosować w następującej kolejności:

1. Własne ustawienia firmy (source: company_override) – zawsze stosowane w pierwszej kolejności.
2. Profil globalny (source: global) – dla wszystkich pozostałych firm.
3. Wartości domyślne profilu globalnego (alerty wyłączone, próg warning) – dopóki profilu nie zmienisz.