Informacje ogólne
Interfejs API Statystyki NFZ – Świadczenia to usługa sieciowa świadczona przez Narodowy Fundusz Zdrowia udostępniania zbioru danych z obszaru statystyk świadczeń opieki zdrowotnej w wymiarze ogólnym, rozliczeniowym i medycznym, które dotyczą produktów z katalogu:
- JGP,
- Świadczenia odrębne,
- Świadczenia do sumowania,
- Świadczenia radioterapii,
- Świadczenia wysokospecjalistyczne.
Budowa API Statystyki NFZ - Świadczenia zrealizowana została w ramach projektu „Otwarte Dane – dostęp, standard, edukacja” w ramach programu Operacyjnego Polska Cyfrowa na lata 2014-2020.
API Statystyki NFZ - Świadczenia jest źródłem informacji, które mogą posłużyć do stworzenia aplikacji dedykowanych świadczeniodawcom, analitykom rynku zdrowia, środowisku naukowemu.
Swagger i API Statystyki NFZ – Świadczenia
W celu ułatwienia korzystania z API Statystki NFZ - Świadczenia zdecydowaliśmy się dodać do dokumentacji Swagger UI. Jest to narzędzie umożliwiające w prosty sposób wizualizację i interakcję z zasobami API bez konieczności implementowania. Narzędzie dostępne jest w menu w sekcji Swagger
Standardowy mechanizm wyszukiwania danych
API Statystki NFZ - Świadczenia oferuje mechanizmy wyszukiwania z filtrowaniem pełnotekstowym po konkretnych polach oraz stronicowanie. Wszystkie parametry wyszukiwania podaje się w części query zaraz po przeszukiwanym zasobie porzedzając go znakiem pytajnika.(?)
Podaczas wyszukiwania w cześci query możemy używać standardowych pól:
page
- numer strony wyników do zwrócenia. Strony numerowane są od 1. Domyślna ilość wyników na stronie opisana jest w dokumentacji Swagger UI.
limit
- ilość wyników zróconych na stronie. Wartości domyślne i maksymalne zostały opisane szczegółowo w dokumentacji Swagger UI.
format
- określa format zwracanych wyników. Domyślnie dane zwracane są w formacie json — JavaScript object notation.
Pozostałe pola filtrowania pełnetekstowego opisuje szczegółowo dokumentacja Swagger UI dla każdego przeszukiwanego zasobu.
Zasoby
Punktem wyjścia jest zasób /index-of-table, który zwraca listę dostępnych tabel statystycznych według przekazanych kryteriów.
/index-of-tables
Zasób zwraca listę dostępnych tabel statystycznych według przekazanych kryteriów. W celu pozyskania danych statystycznych należy posłużyć się unikalnym identyfikatorem oraz wskazanym zasobem zwróconym dla poszczególnych tabel.
Wynik żądania zgodnie ze strukturą zwraca obiekt index-of-tables
(SwaggerUi).
Dane statystyczne zostały podzielone na pięć głównych sekcji:
Dane podstawowe
Do dyspozycj w tej sekcji jest 7 zasobów:
/basic-data/{id}
/hospitalizations-by-patient-gender/{id}
/hospitalizations-by-admission-type/{id}
/hospitalizations-by-admission-type-nfz-categorized/{id}
/hospitalizations-by-discharge-type/{id}
/hospitalizations-by-patient-age/{id}
/histogram-data/{id}
Wszystkie metody pobierają wymagają przekazania unikalnego identyfikatora tabeli zwróconego po wywołaniu zasobu /index-of-tables
/basic-data/{id}
Zasób zwraca dane ogólne dotyczące hosppitalizacji.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów basic-data
(SwaggerUi).
/hospitalizations-by-patient-gender/{id}
Zasób zwraca dane statystyczne dotyczące hosppitalizacji w podziale na płeć pacjenta.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
hospitalizations-by-patient-gender
(SwaggerUi).
/hospitalizations-by-admission-type/{id}
Zasób zwraca dane statystyczne dotyczące hosppitalizacji w podziale na tryb przyjęcia pacjenta.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
hospitalizations-by-admission-type
(SwaggerUi).
/hospitalizations-by-admission-type-nfz-categorized/{id}
Zasób zwraca dane statystyczne dotyczące hosppitalizacji w podziale na tryb przyjęcia pacjenta - kategoryzacja NFZ.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
hospitalizations-by-admission-type-nfz-categorized
(SwaggerUi).
/hospitalizations-by-discharge-type/{id}
Zasób zwraca dane statystyczne dotyczące hosppitalizacji w podziale na tryb wypisu pacjenta.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
hospitalizations-by-discharge-type
(SwaggerUi).
/hospitalizations-by-patient-age/{id}
Zasób zwraca dane statystyczne dotyczące hosppitalizacji w podziale na wiek pacjenta.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
hospitalizations-by-patient-age
(SwaggerUi).
/histogram-data/{id}
Zasób zwraca dane statystyczne dotyczące hospitalizacji do histogramu czasu pobytu.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
histogram
(SwaggerUi).
Dane rozliczeniowe
Do dyspozycj w tej sekcji są 2 zasobów: /hospitalizations-by-healthcare-service/{id}
oraz /hospitalizations-by-products-category/{id}
Wszystkie metody pobierają wymagają przekazania unikalnego identyfikatora tabeli zwróconego po wywołaniu zasobu /index-of-tables
/hospitalizations-by-healthcare-services/{id}
Zasób zwraca dane statystyczne dotyczące hosppitalizacji w podziale na zakres świadczeń.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
contract-product
(SwaggerUi).
/hospitalizations-by-product-cateogiry/{id}
Zasób zwraca dane statystyczne dotyczące hosppitalizacji w podziale na kategorie produktów sumowanych do JGP.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
product-cateogry
(SwaggerUi).
Dane medczyne
Do dyspozycj w tej sekcji są 2 zasobów: /icd9-procedures/{id}
oraz /icd10-diseases/{id}
Wszystkie metody pobierają wymagają przekazania unikalnego identyfikatora tabeli zwróconego po wywołaniu zasobu /index-of-tables
/icd9-procedures/{id}
Zasób zwraca dane statystyczne dotyczące hospitalizacji w rozbiciu procedury ICD9
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
procedure
(SwaggerUi).
/icd10-diseases/{id}
Zasób zwraca dane statystyczne dotyczące hospitalizacji w rozbiciu rozpoznania ICD10
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
disease
(SwaggerUi).
Słowniki
Do dyspozycj w tej sekcji są 2 zasobów: /benefits
oraz /sections
/benefits
Zasób zwraca dane słownikowe świadczeń w oparciu o przekazane parametry.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
benefit
(SwaggerUi).
/sections
Zasób zwraca dane słownikowe sekcji JGP w oparciu o przekazane parametry.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów
section
(SwaggerUi).
Info
W sekcji "Info" znajduje się zasób zwracający aktualną wersję API.
Struktura danych
Dane z API zwracane są zgodnie ze standardem JSON API. W każdej odpowiedzi znajduje się co najmniej jedna z poniższych sekcji:
z zastrzeżeniem, że data
i errors
nie mogą wystąpić razem w jednej odpowiedzi.
links
Ponieważ zasoby zwracające listę wyników są stronicowane (25 wyników na stronę),
dodatkowo w odpowiedziach dodawana jest sekcja links
, ułatwiająca poruszanie się po API (HATEOAS).
Dostępnych w sekcji jest 5 linków:
first
- do pierwszej strony wyników,prev
- do następnej strony wyników,self
- do aktualnej strony wyników,next
- do następnej strony wyników,last
- do ostaniej strony wyników,
Na przykład poniższe żądanie:
https://api.nfz.gov.pl/app-stat-api-jgp/sections?section=ocz&api-version=1.1
zwróci listę sekcji JGP zawierających fragment "ocz":
{
"meta": {
"@context": "/schemas/#section",
...
"count": 2,
"page": 1,
"limit": 10
...
},
"links": {
"first": "/sections?page=1&limit=10§ion=ocz",
"prev": null,
"self": "/sections?page=1&limit=10§ion=ocz",
"next": null,
"last": "/sections?page=1&limit=10§ion=ocz"
},
"data": [
"B - Choroby oczu",
"L - Choroby układu moczowo-płciowego"
]
}
Należy zwrócić uwagę na link prev
, który nie zawiera żadnej wartości (null
).
Spowodowane jest to użyciem domyślnych wartości paramterów (ponieważ ich nie przekazano). Domyślnie parametr page
= 1, dlatego opdowiedź z API zawiera pierwszą stronę wyników
dla której poprzednia nie istnieje.
data
Sekcja data
zawiera dane pasujące do kryteriów wyszukiwania. W tej sekcji możemy odnaleźć różnego rodzaju struktury w zależności od przeszukiwanego zasobu.
Przykład opowiedzi na zapytanie przeszukujące nazwy świadczeń z katalogu 1a (JGP) zawierające słowo lecz
https://api.nfz.gov.pl/app-stat-api-jgp/benefits?benefit=lecz&catalog=1a&api-version=1.1
{
"meta": {
"@context": "/schemas/#benefit",
...
"count": 83,
"page": 1,
"limit": 10
...
},
"links": {
"first": "/benefits?page=1&limit=10&benefit=lecz",
"prev": null,
"self": "/benefits?page=1&limit=10&benefit=lecz",
"next": "/benefits?page=2&limit=10&benefit=lecz",
"last": "/benefits?page=9&limit=10&benefit=lecz"
},
"data": [
{
"code": "5.51.01.0001045",
"name": "A45 CHOROBY NACZYŃ MÓZGOWYCH - LECZENIE ZACHOWAWCZE"
},
{
"code": "5.51.01.0001048",
"name": "A48 KOMPLEKSOWE LECZENIE UDARÓW MÓZGU > 7 DNI W ODDZIALE UDAROWYM"
},
{
"code": "5.51.01.0001049",
"name": "A49 UDAR MÓZGU - LECZENIE > 3 DNI"
},
{
"code": "5.51.01.0001050",
"name": "A50 UDAR MÓZGU - LECZENIE"
},
{
"code": "5.51.01.0001051",
"name": "A51 UDAR MÓZGU - LECZENIE TROMBOLITYCZNE > 7 DNI W ODDZIALE UDAROWYM"
},
{
"code": "5.51.01.0001066",
"name": "A66 PADACZKA - DIAGNOSTYKA I LECZENIE"
},
{
"code": "5.51.01.0001067",
"name": "A67 PADACZKA - DIAGNOSTYKA I LECZENIE > 3 DNI"
},
{
"code": "5.51.01.0001076",
"name": "A76 URAZY GŁOWY Z ISTOTNYM USZKODZENIEM MÓZGU LECZONE ZACHOWAWCZO"
},
{
"code": "5.51.01.0001077",
"name": "A77 URAZY GŁOWY BEZ ISTOTNEGO USZKODZENIA MÓZGU LECZONE ZACHOWAWCZO"
},
{
"code": "5.51.01.0002001",
"name": "B01 LECZENIE WYSIĘKOWEJ POSTACI AMD WERTEPORFINĄ PRZY ZASTOSOWANIU TERAPII FOTODYNAMICZNEJ"
}
]
}
Lista wszystkich możliwych schematów zwracanych w sekcji data
została opisana w osobnej sekcji dokumentacji - Schematy.
errors
Podczas pracy z API można natrafić na błędy, które w sposób zgodny ze standardem zawierają możliwie jak najwięcej informacji, ułatwiających rozwiązanie problemu.
Przykładowy błąd zwracany w przypadku gdy nie zostanie przekazany wymagany paramter (case
):
{
"errors": [
{
"id": "bf99b2fa-8b84-4488-9e6f-85e324dea9ff",
"errorr-result": "Cannot return results",
"errorr-reason": "Invalid value for {id} attribute",
"errorr-solution": "Provide proper value for attribute",
"error-help": "/errors/#1200007",
"error-code": 1200007
}
]
}
Struktura odpowiedzi została opisana w osobnej sekcji dokumentacji - Schematy.
Lista możliwych błędów została opisana w osobnej sekcji dokumentacji - Opis błędów
meta
Szczegóły dotyczące metadanych zostały opisanę w osobnej sekcji dokumentacji - Metadane