Informacje ogólne
Budowa API Statystyki NFZ - Programy Lekowe zrealizowana została w ramach projektu „Otwarte Dane – dostęp, standard, edukacja” w ramach programu Operacyjnego Polska Cyfrowa na lata 2014-2020.
Swagger i API Statystyki NFZ – Programy Lekowe
W celu ułatwienia korzystania z API Statystki NFZ - Programy Lekowe 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 - Programy Lekowe 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
Dane statystyczne zostały podzielone na trzy główne sekcje
Programy Lekowe
W tej sekcji znajduje się 8 zasobów zwracających dane statystyczne dotyczące wykonań refundacji aptecznych.
/drug-costs-by-drug-program/drug-costs-by-active-substance/drug-costs-by-drug-program-and-active-substance/drug-costs-by-patient-gender/drug-costs-by-patient-age/monthly-drug-costs/yearly-drug-costs/available-periods
/drug-costs-by-drug-program
Zasób zwraca informacje o kosztach leków w podziale na programy lekowe określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt drug-costs-by-drug-program-data
(SwaggerUi).
/drug-costs-by-active-substance
Zasób zwraca informację o kosztach leków w podziale na substancje czynne określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt drug-costs-by-active-substance-data
(SwaggerUi).
/drug-costs-by-drug-program-and-active-substance
Zasób zwraca dane statystyczne dotyczące kosztów leków w podziale na programy lekowe i substancje czynną określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt drug-costs-by-drug-program-and-active-substance-data
(SwaggerUi).
/drug-costs-by-patient-gender
Zasób zwraca dane statystyczne dotyczące kosztów leków w podziale na płeć pacjenta określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt drug-costs-by-patient-gender-data
(SwaggerUi).
/drug-costs-by-patient-age
Zasób zwraca dane statystyczne dotyczące kosztów leków w podziale na wiek pacjenta określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt drug-costs-by-patient-age-data
(SwaggerUi).
/monthly-drug-costs
Zasób zwraca dane statystyczne dotyczące kwoty refundacji NFZ i liczbie pacjentów w podziale na miesiące określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt monthly-drug-costs-data
(SwaggerUi).
/yearly-drug-costs
Zasób zwraca dane statystyczne dotyczące kwoty refundacji NFZ i liczbie pacjentów w podziale na lata określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt yearly-drug-costs-data
(SwaggerUi).
/available-periods
Zasób zwraca informacje o dostępnym zakresie dat dla których dostępne są dane statystyczne.
Wynik żądania zgodnie ze strukturą zwraca obiekt available-periods-data
(SwaggerUi).
Słowniki
W teje sekcji znajduje się 2 zasoby słownikowe.
/drug-programs
Zasób zwraca informacje o dostępnym zakresie dat dla których dostępne są dane statystyczne.
Wynik żądania zgodnie ze strukturą zwraca obiekt drug-programs
(SwaggerUi).
/active-substances
Zasób zwraca informacje o dostępnym zakresie dat dla których dostępne są dane statystyczne.
Wynik żądania zgodnie ze strukturą zwraca obiekt active-substances
(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,
{
"meta": {
...
},
"links": {
"first": "/active-substances?page=1&limit=10&format=json",
"prev": null,
"self": "/active-substances?page=1&limit=10&format=json",
"next": "/active-substances?page=2&limit=10&format=json",
"last": "/active-substances?page=14&limit=10&format=json",
"related": null
},
"data": [
"ABIRATERONI ACETAS - O - DOUSTNIE (ORAL, PER MOUTH) - 1 MG",
"ADALIMUMABUM - P - POZAJELITOWO (PARENTERAL) - 1 MG",
"ADEFOVIRI DIPIVOXILUM - O - DOUSTNIE (ORAL, PER MOUTH) - 1 MG",
"AFATYNIBUM - O - DOUSTNIE (ORAL, PER MOUTH) - 1 MG",
"AFLIBERCEPTUM - P - POZAJELITOWO (PARENTERAL) - 1 MG",
"ALEMTUZUMABUM - PI - POZAJELITOWO DOŻYLNIE (PARENTERA-INTRAVESICULAR) - 1 MG",
"ALGLUCOSIDASUM ALFA - P - POZAJELITOWO (PARENTERAL) - 1 MG",
"AMBRISENTANUM - O - DOUSTNIE (ORAL, PER MOUTH) - 1 MG",
"ANAKINRA - P - POZAJELITOWO (PARENTERAL) - 1 MG",
"APOMORPHINI HYDROCHLORIDUM HEMIHYDRICUM - P - POZAJELITOWO (PARENTERAL) - 1 MG"
]
}
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 wyszukujące dane statystyczne dot. kosztów leczenia w programie lekowym zawierającym słowo czerniak
{
"meta": {
"@context": null,
"count": 3,
"title": null,
"page": 1,
"url": null,
"limit": 10,
"provider": "Narodowy Fundusz Zdrowia",
"date-published": "2019-07-30T15:26:00+01:00",
"date-modified": "2019-07-31T18:46:13+02:00",
"description": null,
"keywords": null,
"language": "PL",
"content-type": "application/json; charset=utf-8",
"is-part-of": null
},
"links": {
"first": "/app-stat-api-pl/drug-costs-by-drug-program?page=1&limit=10&format=json&drugProgram=czerniak",
"prev": null,
"self": "/app-stat-api-pl/drug-costs-by-drug-program?page=1&limit=10&format=json&drugProgram=czerniak",
"next": null,
"last": "/app-stat-api-pl/drug-costs-by-drug-program?page=1&limit=10&format=json&drugProgram=czerniak",
"related": null
},
"data": {
"sums": {
"refund": 399608888.29
},
"data": [
{
"drug-program-code": "03.0001.359.02",
"drug-program-mz-code": "B.59",
"drug-program-name": "LEKI W PROGRAMIE LEKOWYM - LECZENIE CZERNIAKA SKÓRY LUB BŁON ŚLUZOWYCH",
"number-of-patients": 1410,
"refund": 212791910.8
},
{
"drug-program-code": "03.0001.372.02",
"drug-program-mz-code": "B.72",
"drug-program-name": "LEKI W PROGRAMIE LEKOWYM - LECZENIE CZERNIAKA SKOJARZONĄ TERAPIĄ DABRAFENIBEM I TRAMETYNIBEM",
"number-of-patients": 532,
"refund": 123241554.4
},
{
"drug-program-code": "03.0001.348.02",
"drug-program-mz-code": "B.48",
"drug-program-name": "LEKI W PROGRAMIE LEKOWYM - LECZENIE CZERNIAKA SKÓRY",
"number-of-patients": 310,
"refund": 63575423.09
}
]
}
}
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 zostanie przekazany zbyt długi paramter (drugProgram):
{
"errors": [
{
"id": "bf99b2fa-8b84-4488-9e6f-85e324dea9ff",
"errorr-result": "Cannot return results",
"errorr-reason": "Invalid length for {drugProgram} parameter",
"errorr-solution": "Provide proper value for attribute",
"error-help": "/errors/#6201001",
"error-code": 6201001
}
]
}
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