Dokumentacja API

Strażnik KSC udostępnia REST API, które pozwala zintegrować Twoje systemy (SIEM, service desk, arkusze, automatyzacje) z rejestrem incydentów, dostawców i stanem zgodności. Wszystkie odpowiedzi są w formacie JSON i dotyczą wyłącznie danych Twojej organizacji.

Dane zwracane przez API (m.in. klasyfikacja incydentów i stan wymogów) mają charakter informacyjno-organizacyjny i nie stanowią porady prawnej. Ostateczna kwalifikacja incydentu oraz zgłoszenia do CSIRT/organów pozostają po stronie Twojej organizacji.

Podstawy i adres bazowy

Wszystkie endpointy mają wspólny prefiks /api/v1 i są dostępne pod adresem produkcyjnym:

https://ksc.mysec.pl/api/v1

API jest wersjonowane w ścieżce (v1). Zmiany niekompatybilne wstecz wprowadzimy pod nową wersją, nie ruszając v1.

Uwierzytelnianie

Każde zapytanie musi zawierać klucz API w nagłówku Authorization w schemacie Bearer:

Authorization: Bearer ksc_twoj_klucz

Klucze tworzysz i unieważniasz w panelu, w sekcji Klucze API. Pełny klucz (z prefiksem ksc_) pokazujemy tylko raz — zapisz go w bezpiecznym miejscu. Klucz działa wyłącznie w obrębie Twojej organizacji i nie ma dostępu do danych innych firm.

Zakresy klucza

Pole	Typ	Opis
READ_ONLY	zakres	Dostęp wyłącznie do odczytu (metody GET). Próba zapisu zwraca 403.
READ_WRITE	zakres	Odczyt oraz zapis (POST — tworzenie incydentów i dostawców).

Przykład (cURL)

curl https://ksc.mysec.pl/api/v1/compliance \
  -H "Authorization: Bearer ksc_twoj_klucz"

Konwencje i formaty

• Format danych: żądania i odpowiedzi to JSON (UTF-8). Ciało żądań POST wysyłaj z nagłówkiem Content-Type: application/json.
• Daty: wszystkie znaczniki czasu są w formacie ISO 8601 z czasem UTC (np. 2026-07-12T09:30:00.000Z).
• Identyfikatory: zasoby są identyfikowane nieprzewidywalnym łańcuchem znaków (id).
• Listy: endpointy zbiorcze zwracają obiekt z polem data (tablica). Pojedynczy zasób zwracany jest jako obiekt bezpośrednio.
• Kody sukcesu: 200 dla odczytu, 201 dla utworzenia zasobu.

Limity zapytań

Obowiązuje limit 120 zapytań na minutę na klucz API (okno stałe). Po przekroczeniu limitu API zwraca status 429 wraz z nagłówkiem Retry-After (liczba sekund do zresetowania okna). Zaprojektuj integrację tak, aby respektowała ten nagłówek i ponawiała zapytanie z odczekaniem.

Obsługa błędów

Błędy mają jednolity kształt JSON z kodem maszynowym i komunikatem po polsku:

{
  "error": {
    "code": "validation_error",
    "message": "Treść żądania musi być poprawnym JSON-em."
  }
}

Pole	Typ	Opis
401	unauthorized	Brak, nieprawidłowy, unieważniony lub wygasły klucz API.
403	forbidden	Klucz READ_ONLY przy zapisie albo dostęp organizacji jest zablokowany.
404	not_found	Zasób nie istnieje lub nie należy do Twojej organizacji.
422	validation_error	Ciało żądania nie jest poprawnym JSON-em lub nie spełnia walidacji pól.
429	rate_limited	Przekroczono limit zapytań — patrz nagłówek Retry-After.

Wykaz endpointów

Pola oznaczone * są wymagane.

GET/api/v1/compliance

Stan zgodności organizacji

Zwraca podsumowanie postępu wdrożenia wymogów oraz listę poszczególnych wymagań z ich statusem.

Przykładowa odpowiedź (200)

{
  "overview": {
    "total": 24,
    "done": 10,
    "inProgress": 6,
    "notStarted": 5,
    "notApplicable": 3,
    "percent": 48
  },
  "requirements": [
    { "code": "ORG-1", "name": "Polityka bezpieczeństwa", "status": "WDROZONE" }
  ]
}

percent liczony jest z pominięciem wymagań o statusie NIE_DOTYCZY. Wartości statusów — patrz słowniki.

GET/api/v1/incidents

Lista incydentów

Zwraca wszystkie incydenty Twojej organizacji (najnowsze pierwsze).

Przykładowa odpowiedź (200)

{
  "data": [
    {
      "id": "clx...",
      "title": "Podejrzane logowanie do systemu ERP",
      "description": "Wielokrotne nieudane próby logowania...",
      "detectedAt": "2026-07-11T22:14:00.000Z",
      "classification": "DO_OCENY",
      "status": "NOWY",
      "createdAt": "2026-07-12T06:02:11.130Z"
    }
  ]
}

POST/api/v1/incidents

Zgłoszenie incydentu

Tworzy nowy incydent i generuje wstępny szkic zgłoszenia (S46). Wymaga klucza READ_WRITE.

Parametry ciała

Pole	Typ	Opis
title*	string	Tytuł incydentu (3–200 znaków).
description*	string	Opis zdarzenia (10–5000 znaków).
detectedAt*	string (ISO 8601)	Data i czas wykrycia incydentu.
classification	enum	Klasyfikacja. Domyślnie `DO_OCENY`. Wartości — patrz słowniki.

Przykładowe żądanie

curl -X POST https://ksc.mysec.pl/api/v1/incidents \
  -H "Authorization: Bearer ksc_twoj_klucz" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Podejrzane logowanie do systemu ERP",
    "description": "Wielokrotne nieudane proby logowania z nietypowego IP.",
    "detectedAt": "2026-07-11T22:14:00Z",
    "classification": "DO_OCENY"
  }'

Odpowiedź 201 zwraca utworzony incydent w tym samym kształcie co na liście.

GET/api/v1/incidents/{id}

Szczegóły incydentu

Zwraca pojedynczy incydent po jego id. Gdy incydent nie istnieje lub nie należy do Twojej organizacji — status 404.

Przykładowa odpowiedź (200)

{
  "id": "clx...",
  "title": "Podejrzane logowanie do systemu ERP",
  "description": "Wielokrotne nieudane próby logowania...",
  "detectedAt": "2026-07-11T22:14:00.000Z",
  "classification": "DO_OCENY",
  "status": "NOWY",
  "createdAt": "2026-07-12T06:02:11.130Z"
}

GET/api/v1/suppliers

Lista dostawców

Zwraca rejestr dostawców Twojej organizacji.

Przykładowa odpowiedź (200)

{
  "data": [
    {
      "id": "clx...",
      "name": "Przykładowy Dostawca sp. z o.o.",
      "nip": "1234567890",
      "serviceDescription": "Hosting i utrzymanie infrastruktury",
      "criticality": "WYSOKA",
      "hasSystemAccess": true,
      "hasDataAccess": true,
      "hasContractSla": true,
      "hasSecurityClause": false,
      "riskNotes": null,
      "createdAt": "2026-07-12T06:02:11.130Z"
    }
  ]
}

POST/api/v1/suppliers

Dodanie dostawcy

Dodaje dostawcę do rejestru. Wymaga klucza READ_WRITE.

Parametry ciała

Pole	Typ	Opis
name*	string	Nazwa dostawcy (2–200 znaków).
serviceDescription*	string	Opis świadczonej usługi (3–1000 znaków).
nip	string	NIP dostawcy (do 20 znaków). Opcjonalny.
criticality	enum	Krytyczność. Domyślnie `SREDNIA`. Wartości: `WYSOKA`, `SREDNIA`, `NISKA`.
hasSystemAccess	boolean	Czy dostawca ma dostęp do systemów. Domyślnie false.
hasDataAccess	boolean	Czy dostawca ma dostęp do danych. Domyślnie false.
hasContractSla	boolean	Czy umowa zawiera SLA. Domyślnie false.
hasSecurityClause	boolean	Czy umowa zawiera klauzulę bezpieczeństwa. Domyślnie false.
riskNotes	string	Notatki o ryzyku (do 2000 znaków). Opcjonalne.

Przykładowe żądanie

curl -X POST https://ksc.mysec.pl/api/v1/suppliers \
  -H "Authorization: Bearer ksc_twoj_klucz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Przykladowy Dostawca sp. z o.o.",
    "serviceDescription": "Hosting i utrzymanie infrastruktury",
    "criticality": "WYSOKA",
    "hasSystemAccess": true,
    "hasDataAccess": true
  }'

Słowniki wartości

Klasyfikacja incydentu (`classification`)

Pole	Typ	Opis
DO_OCENY	domyślna	Incydent wymaga jeszcze oceny kwalifikacji.
POWAZNY	—	Incydent poważny w rozumieniu ustawy o KSC.
NIEPOWAZNY	—	Incydent nie spełnia progu poważnego.

Status incydentu (`status`)

Pole	Typ	Opis
NOWY	—	Zarejestrowany, przed dalszą obsługą.
WCZESNE_OSTRZEZENIE	—	Wysłano wczesne ostrzeżenie do CSIRT.
ZGLOSZENIE	—	Złożono właściwe zgłoszenie incydentu.
RAPORT_KONCOWY	—	Przekazano raport końcowy.
ZAMKNIETY	—	Obsługa incydentu zakończona.

Status wymagania (`status` w compliance)

Pole	Typ	Opis
WDROZONE	—	Wymóg wdrożony.
W_TRAKCIE	—	Wdrożenie w toku.
NIE_ROZPOCZETO	—	Wdrożenie nierozpoczęte.
NIE_DOTYCZY	—	Wymóg nie dotyczy organizacji (pomijany w procencie).

Krytyczność dostawcy (`criticality`)

Pole	Typ	Opis
WYSOKA	—	Wysoka krytyczność.
SREDNIA	domyślna	Średnia krytyczność.
NISKA	—	Niska krytyczność.

Masz pytania o integrację? Napisz do nas — chętnie pomożemy podłączyć Twoje systemy. Klucze API utworzysz w panelu w sekcji Klucze API.

Dokumentacja API

Podstawy i adres bazowy

Uwierzytelnianie

Zakresy klucza

Przykład (cURL)

Konwencje i formaty

Limity zapytań

Obsługa błędów

Wykaz endpointów

Stan zgodności organizacji

Lista incydentów

Zgłoszenie incydentu

Szczegóły incydentu

Lista dostawców

Dodanie dostawcy

Słowniki wartości

Klasyfikacja incydentu (classification)

Status incydentu (status)

Status wymagania (status w compliance)

Krytyczność dostawcy (criticality)

Klasyfikacja incydentu (`classification`)

Status incydentu (`status`)

Status wymagania (`status` w compliance)

Krytyczność dostawcy (`criticality`)