API dla deweloperów

Uwierzytelnione REST API do danych o kolejkach SOR, katalogu placówek medycznych, oddziałach szpitali i świadczeniach NFZ. Wymaga konta i klucza API. Anonimowe zapytania są odrzucane. Istniejące endpointy SOR (/hospitals, /regions, /analytics) oraz wcześniejsze katalogowe (/facilities, /medical-sites, /catalog) zachowują dotychczasowy kształt odpowiedzi — nowe pola (np. org_units) są wyłącznie addytywne. Pełna dokumentacja z testerem na żywo: /developer.

Otwórz tester API Zobacz plany Moje klucze API

Autoryzacja

Każde zapytanie musi zawierać dwa nagłówki: X-Api-Key (publiczny identyfikator) i X-Api-Secret (sekret utworzony razem z kluczem). Sekret pokazujemy tylko raz — przy generowaniu. Przechowuj go po stronie serwera (nie w kodzie frontendu, nie w repozytorium).

Wymagane nagłówki

X-Api-Key: sor_live_XXXXXXXX
X-Api-Secret: <sekret z panelu>

curl

curl -H "X-Api-Key: $KEY" \
     -H "X-Api-Secret: $SECRET" \
     https://kolejkisor.pl/api/public/hospitals

JavaScript

await fetch("https://kolejkisor.pl/api/public/hospitals", {
  headers: {
    "X-Api-Key": process.env.SOR_KEY,
    "X-Api-Secret": process.env.SOR_SECRET,
  },
}).then(r => r.json());

Python

import requests, os
r = requests.get(
  "https://kolejkisor.pl/api/public/hospitals",
  headers={
    "X-Api-Key": os.environ["SOR_KEY"],
    "X-Api-Secret": os.environ["SOR_SECRET"],
  })
r.raise_for_status()
print(r.json())

Jak wygenerować klucz: zaloguj się, wejdź w Moje konto → Klucze API, kliknij „Wygeneruj klucz", zapisz sekret (nie zobaczysz go ponownie). Klucz można w dowolnym momencie unieważnić.

Limity i plany

Limity są wymuszane serwerowo. Po każdym zapytaniu odpowiedź zawiera nagłówki informacyjne:

X-RateLimit-Limit — max zapytań na minutę
X-RateLimit-Remaining — pozostałe w bieżącej minucie
X-RateLimit-Reset — timestamp unix, kiedy okno się odnowi
X-Daily-Limit / X-Daily-Used — kwota dzienna i zużycie
Retry-After — sekund do ponownej próby (przy 429)

Plan	Cena	Requesty / dzień	Req / min	Klucze	Historia
Starter	0 zł	50	10	1	—
Analityk	9,99 zł / mies.	2000	60	3	30 dni
Instytucja	29,99 zł / mies.	20 000	300	10	365 dni

Endpointy

GET/api/public/hospitalsStarter

Lista aktywnych SOR-ów (jednostki kolejkowe). Parametr: ?voivodeship=

GET/api/public/hospitals/nearest?lat=&lon=&limit=Starter

Najbliższe SOR-y względem współrzędnych WGS84.

GET/api/public/hospitals/{id}/currentStarter

Aktualne kolejki dla SOR-u (per priorytet triage).

GET/api/public/hospitals/{id}/history?from=&to=Analityk+

Historia pomiarów w oknie ISO. Wymaga planu Analityk+.

GET/api/public/facilitiesInstytucja+

Katalog kanonicznych szpitali (nie mylić z /hospitals). Parametry: ?q=&city=&voivodeship=&hasSor=yes|no&hasNfz=yes|no&page=. Wymaga planu Instytucja.

GET/api/public/facilities/{id}Instytucja+

Szczegóły szpitala: ścieżka publiczna, powiązane SOR-y, lista świadczeń NFZ, oddziały/jednostki medyczne (org_units). Wymaga planu Instytucja.

GET/api/public/facilities/{id}/org-unitsInstytucja+

Same oddziały i jednostki medyczne szpitala (RPWDL + powiązania NFZ). Wymaga planu Instytucja.

GET/api/public/medical-sitesInstytucja+

Katalog placówek niebędących szpitalami (POZ/AOS itd.). Parametry: ?q=&city=&voivodeship=&capability=&hasNfz=yes|no&page=. Wymaga planu Instytucja.

GET/api/public/medical-sites/{id}Instytucja+

Szczegóły placówki: kompetencje, świadczenia NFZ (eligible). Wymaga planu Instytucja.

GET/api/public/catalogInstytucja+

Zunifikowany katalog (szpitale + placówki). Parametry: ?q=&city=&voivodeship=&type=hospital|site&hasSor=yes|no&capability=&benefit=&page=. Wymaga planu Instytucja.

GET/api/public/benefitsInstytucja+

Katalog świadczeń NFZ. Parametry: ?q=&category=&voivodeship=&city=&featuredOnly=1&sort=&page=. Wymaga planu Instytucja.

GET/api/public/benefits/{slug}Instytucja+

Szczegóły świadczenia + oferty (czasy oczekiwania, lat/lon). Parametry: ?voivodeship=&city=&lat=&lon=&radiusKm=&sort=wait|distance&limit=. Wymaga planu Instytucja.

GET/api/public/regionsStarter

Agregaty per województwo (mediana, średnia, trend 3h).

GET/api/public/regions/{voivodeship}Starter

Ranking SOR-ów w województwie wraz z indeksem obciążenia.

GET/api/public/citiesStarter

Agregaty obciążenia SOR-ów per miasto.

GET/api/public/analytics/heatmap?voivodeship=&city=Instytucja+

Heatmapa 7×24 obciążenia. Wymaga planu Instytucja.

GET/api/public/analytics/rankingsInstytucja+

Ranking krajowy z metrykami. Wymaga planu Instytucja.

Kody błędów

HTTP	Kod	Znaczenie
401	unauthorized	Brakuje nagłówków X-Api-Key / X-Api-Secret.
401	invalid_key	Klucz nie istnieje w systemie.
401	invalid_secret	Sekret nie pasuje do klucza.
401	revoked_key	Klucz został unieważniony w panelu.
403	plan_upgrade_required	Twój plan nie obejmuje tego endpointu.
429	rate_limited	Przekroczono limit minutowy — spróbuj później.
429	daily_quota_exceeded	Przekroczono dzienny limit planu.
500	server_error	Wewnętrzny błąd — zgłoś na support.

Struktura odpowiedzi błędu: {"error":{"code":"...","message":"..."}}