Dokumentacja API Statystyki NFZ - Świadczenia wersja 1.1

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
Dane rozliczeniowe
Dane medyczne
Słowniki
Info

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:

data
errors
meta

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