Dokumentacja API Statystyki NFZ - Leki w Chemioterapii wersja 1.0

Informacje ogólne

Budowa API Statystyki NFZ - Leki w Chemioterapii 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 – Leki w Chemioterapii

W celu ułatwienia korzystania z API Statystki NFZ - Leki w Chemioterapii 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 - Leki w Chemioterapii 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

Chemioterapia

W tej sekcji znajduje się 6 zasobów zwracających dane statystyczne dotyczące wykonań refundacji aptecznych.

/active-substance-costs

Zasób zwraca dane statystyczne dotyczące kosztów substancji czynnych w chemioterapii, określonych parametrami wyszukiwania. Wynik żądania zgodnie ze strukturą zwraca obiekt active-substance-costs (SwaggerUi).

Przykład:

/active-substance-costs-by-gender

Zasób zwraca dane statystyczne dotyczące kosztów substancji czynnych w chemioterapii w podziale na płeć pacjenta, określonych parametrami wyszukiwania. Wynik żądania zgodnie ze strukturą zwraca obiekt active-substance-costs-by-gender (SwaggerUi).

Przykład:

/active-substance-costs-by-age

Zasób zwraca dane statystyczne dotyczące kosztów substancji czynnych w chemioterapii w podziale na grupy wiekowe pacjenta, określonych parametrami wyszukiwania. Wynik żądania zgodnie ze strukturą zwraca obiekt active-substance-costs-by-age (SwaggerUi).

Przykład:

/monthly-provisions

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-provisions (SwaggerUi).

Przykład:

/yearly-provisions

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-provisions (SwaggerUi).

Przykład:

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

Przykład:

Słowniki

W teje sekcji znajduje się 2 zasoby słownikowe.

/active-substances

Zasób zwraca informacje o dostępnych substancjach czynnych dla których dostępne są dane statystyczne. Wynik żądania zgodnie ze strukturą zwraca obiekt active-substances (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.

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-ch/sections?section=ocz

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