Dokumentacja API Umowy NFZ wersja 1.0

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).

Przykład:

/orthopedic-supplies

Zasób zwraca liste środków ortopedycznych spełniających kryteria wyszukiwania. Wynik żądania zgodnie ze strukturą zwraca obiekt orthopedic-supplies (SwaggerUi).

Przykład:

/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).

Przykład:

/service-types

Zasób zwraca liste rodzajów świadczeń spełniających kryteria wyszukiwania. Wynik żądania zgodnie ze strukturą zwraca obiekt service-types (SwaggerUi).

Przykład:

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

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