Informacje ogólne
Budowa API Statystyki NFZ - Refundacja Apteczna 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 – Refundacja Apteczna
W celu ułatwienia korzystania z API Statystki NFZ - Refundacja Apteczna 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 - Refundacja Apteczna 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
Refundacja apteczna
W teje sekcji znajduje się 8 zasobów zwracających dane statystyczne dotyczące wykonań refundacji aptecznych.
/provisions/quantity-top-of-provisions/value-top-of-provisions/monthly-provisions/yearly-provisions/atc-provisions/available-periods
Zasób zwraca listę wykonań refundacji aptecznych zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt provisions-data
(SwaggerUi).
Zasób zwraca listę wykonań refundacji aptecznych według największej liczby opakowań (top 10) zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów provision
(SwaggerUi).
Zasób zwraca listę wykonań refundacji aptecznych o największej kwocie refundacji (top 10) zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów provision
(SwaggerUi).
Zasób zwraca listę wykonań refundacji aptecznych w podziale na miesiące zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów monthly-provision
(SwaggerUi).
Zasób zwraca listę wykonań refundacji aptecznych w podziale na lata zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów yearly-provision
(SwaggerUi).
Zasób zwraca listę wykonań refundacji aptecznych w podziale na grupy ATC zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca listę obiektów atc-provision
(SwaggerUi).
Zasób zwraca informacje o dostępnym zakresie dat dla których dostępne są dane słownikowe.
Wynik żądania zgodnie ze strukturą zwraca obiekt available-periods
(SwaggerUi).
Słowniki
W teje sekcji znajduje się 8 zasobów zwracających dane statystyczne dotyczące wykonań refundacji aptecznych.
Zasób słownikowy zwraca nazwy grup ATC zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt atc
(SwaggerUi).
Zasób słownikowy zwraca nazwy porduktów leczniczych zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt medicine-product
(SwaggerUi).
Zasób słownikowy zwraca nazwy substancji aktywnych zgodnie z wybranymi parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt active-substance
(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-ra/sections?section=ocz&api-version=1.0
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 wyszukujące dane statystyczne dot. refundacji produktu leczniczego o nazwie clexane
https://api.nfz.gov.pl/app-stat-api-ra/provisions?page=1&limit=10&format=json&medicineProduct=clexane
{
"meta": {
"@context": "/schemas/#provisions-data",
...
"count": 19,
"page": 1,
"limit": 10
...
},
"links": {
"first": "/provisions?page=1&limit=10&format=json&medicineProduct=clexane",
"prev": null,
"self": "/provisions?page=1&limit=10&format=json&medicineProduct=clexane",
"next": null,
"last": "/provisions?page=1&limit=10&format=json&medicineProduct=clexane",
"related": null
},
"data": {
"sums": {
"quantity": 3364249.0174,
"refund": 357125607.33,
"donation": 2379699.45,
"contribution-of-patient": 90936364.2,
"value": 450441670.98
},
"data": [
{
"type": "provision",
"attributes": {
"medicine-product": "Clexane",
"international-name": "Enoxaparinum natricum",
"code": "05909990048427",
"dose": "4000 j.m. (40 mg)/0,4 ml",
"pack": "10 amp.-strzyk. 0,4 ml",
"quantity": 2217173.31741,
"refund": 190403118.04,
"donation": 1015737.12,
"contribution-of-patient": 59667385.7,
"value": 251086240.86
}
},
{
"type": "provision",
"attributes": {
"medicine-product": "Clexane",
"international-name": "Enoxaparinum natricum",
"code": "05909990774821",
"dose": "6000 j.m. (60 mg)/0,6 ml",
"pack": "10 amp.-strzyk. 0,6 ml",
"quantity": 648624.39999,
"refund": 85210502.83,
"donation": 736126.5,
"contribution-of-patient": 15685913.05,
"value": 101632542.38
}
},
{
"type": "provision",
"attributes": {
"medicine-product": "Clexane",
"international-name": "Enoxaparinum natricum",
"code": "05909990775026",
"dose": "8000 j.m. (80 mg)/0,8 ml",
"pack": "10 amp.-strzyk. 0,8 ml",
"quantity": 381860.6,
"refund": 65650838.92,
"donation": 443258.11,
"contribution-of-patient": 10263954.59,
"value": 76358051.62
}
},
{
"type": "provision",
"attributes": {
"medicine-product": "Clexane",
"international-name": "Enoxaparinum natricum",
"code": "05909990774920",
"dose": "10 000 j.m. (100 mg)/ml",
"pack": "10 amp.-strzyk. 1 ml z igłą",
"quantity": 61200.7,
"refund": 13585423.56,
"donation": 140452.79,
"contribution-of-patient": 4397569.51,
"value": 18123445.86
}
},
{
"type": "provision",
"attributes": {
"medicine-product": "Clexane",
"international-name": "Enoxaparinum natricum",
"code": "05909990048328",
"dose": "2000 j.m. (20 mg)/0,2 ml",
"pack": "10 amp.-strzyk. 0,2 ml",
"quantity": 55389,
"refund": 2275566.05,
"donation": 44124.93,
"contribution-of-patient": 921541.35,
"value": 3241232.33
}
},
{
"type": "provision",
"attributes": {
"medicine-product": "Clexane",
"international-name": "Enoxaparinum natricum",
"code": "05909990774814",
"dose": "6000 j.m. (60 mg)/0,6 ml",
"pack": "2 amp.-strzyk. 0,6 ml",
"quantity": 1,
"refund": 157.93,
"donation": 0,
"contribution-of-patient": 0,
"value": 157.93
}
}
]
}
}
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