Informacje ogólne
Budowa API Umowy NFZ 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 Umowy NFZ
W celu ułatwienia korzystania z API Umowy NFZ 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 Umowy NFZ 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
Umowy
W tej sekcji znajduje się 6 zasobów zwracających dane o umowach zawartych z NFZ.
/months/{id}
Zasób zwraca szczegóły miesięczny plan umowy podpisnanej przez NFZ ze świadczeniodawcą {id}.
Wynik żądania zgodnie ze strukturą zwraca obiekt months
(SwaggerUi).
/plans/{id}
Zasób zwraca szczegóły planu umowy wskazanego numerem {id}.
Wynik żądania zgodnie ze strukturą zwraca obiekt plans
(SwaggerUi).
/agreements
Zasób zwraca listę umów podpisanych przez NFZ ze świadczeniodawcami określoną parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt agreements
(SwaggerUi).
/agreements/{id}
Zasób zwraca szczegóły umowy podpisanej przez NFZ ze świadczeniodawcą o wskazanym {id}.
Wynik żądania zgodnie ze strukturą zwraca obiekt agreements
(SwaggerUi).
/available-years
Zasób zwraca listę lat dla któych dostępne są dane.
Wynik żądania zgodnie ze strukturą zwraca obiekt available-year
(SwaggerUi).
Słowniki
W tej sekcji znajduje się 2 zasoby słownikowe.
/contract-products
Zasób zwraca liste produktów kontraktowych spełniających kryteria wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt contract-products
(SwaggerUi).
/orthopedic-supplies
Zasób zwraca liste środków ortopedycznych spełniających kryteria wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt orthopedic-supplies
(SwaggerUi).
/providers
Zasób zwraca listę świadczeniodawców mających podpisaną umowę z NFZ, spełniających kryteria wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt providers
(SwaggerUi).
/service-types
Zasób zwraca liste rodzajów świadczeń spełniających kryteria wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt service-types
(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.
meta
Szczegóły dotyczące metadanych zostały opisanę w osobnej sekcji dokumentacji - Metadane
links
Ponieważ zasoby zwracające listę wyników są stronicowane (10 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-umw-api/sections?section=ocz
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.
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 (______):
{
"errors": [
{
"id": "bf99b2fa-8b84-4488-9e6f-85e324dea9ff",
"errorr-result": "Cannot return results",
"errorr-reason": "Invalid length for {________} 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