TBJ.Integrations.NFZ.UmwApi 1.0.1

TBJ.Integrations.NFZ.UmwApi

Typowany klient .NET 8, 9, 10 dla publicznego API umów NFZ (app-umw-api).

Pakiet dostarcza async klientów HTTP do pobierania danych o umowach, planach, środkach ortopedycznych, produktach kontraktowych, rodzajach świadczeń, świadczeniodawcach oraz dostępnych latach danych. API NFZ jest publiczne i nie wymaga uwierzytelniania.

Spis treści

• Wymagania
• Instalacja
• Rejestracja w DI
• Klienci
• Paginacja i strumieniowanie
• Przykłady użycia
• Obsługa błędów
• Cykl życia serwisów
• Wersjonowanie i publikacja
• Repozytorium i paczka

Wymagania

• .NET 8, 9 lub 10
• Dostęp do internetu (publiczne API NFZ — bez klucza API)

Instalacja

dotnet add package TBJ.Integrations.NFZ.UmwApi

Rejestracja w DI

builder.Services.AddNfzUmwApi(builder.Configuration);

{
  "NfzUmwApi": {
    "BaseUrl": "https://api.nfz.gov.pl/app-umw-api",
    "Timeout": "00:00:30",
    "DictionaryCacheTtl": "24:00:00",
    "DictionaryCacheSizeLimit": 5000
  }
}

Możesz też skonfigurować klienta inline:

builder.Services.AddNfzUmwApi(opt =>
{
    opt.BaseUrl = "https://api.nfz.gov.pl/app-umw-api";
    opt.Timeout = TimeSpan.FromSeconds(30);
    opt.DictionaryCacheTtl = TimeSpan.FromHours(24);
    opt.DictionaryCacheSizeLimit = 5000;
});

Klienci

Paginacja i strumieniowanie

Metody GetPageAsync zwracają stronę wyników wraz z całkowitą liczbą rekordów. Metody GetAllAsync zwracają IAsyncEnumerable<T> i automatycznie przechodzą przez wszystkie strony:

await foreach (var agreement in agreements.GetAllAsync(new GetAgreementsRequest
{
    Branch = "01",
    Year = 2024
}))
{
    Console.WriteLine(agreement.Attributes?.ProviderName);
}

Przykłady użycia

public class NfzService(IAgreementsClient agreements, IDictionariesClient dictionaries)
{
    public async Task ShowAgreementsAsync(string branch, int year)
    {
        var page = await agreements.GetPageAsync(new GetAgreementsRequest
        {
            Branch = branch,
            Year = year
        });

        Console.WriteLine($"Znaleziono {page.TotalCount} umów");

        await foreach (var agreement in agreements.GetAllAsync(new GetAgreementsRequest
        {
            Branch = branch,
            Year = year
        }))
        {
            Console.WriteLine(agreement.Attributes?.ProviderName);
        }
    }
}

Szczegółową dokumentację i dodatkowe przykłady znajdziesz w folderze docs/TBJ.Integrations.NFZ.UmwApi.

Obsługa błędów

Wszystkie błędy HTTP oraz błędy semantyczne API NFZ są konwertowane do wyjątku NfzApiException.

try
{
    var detail = await agreements.GetDetailAsync(new GetAgreementDetailRequest { Id = "nieistniejące-id" });
}
catch (NfzApiException ex)
{
    Console.WriteLine($"HTTP {ex.HttpStatusCode}: {ex.Message}");
}

Cykl życia serwisów

Wersjonowanie i publikacja

Projekt używa MinVer do automatycznego wersjonowania przez tagi Git.

git tag nfz-umwapi/v1.0.1
git push origin nfz-umwapi/v1.0.1

Wypchnięcie tagu uruchamia workflow release.yml, który publikuje paczkę na NuGet.org (Trusted Publishing) oraz GitHub Packages i tworzy zamrożoną gałąź release/nfz-umwapi/1.0.1.

Wymagane sekrety w ustawieniach repozytorium: NUGET_USER oraz RELEASE_PAT.

Repozytorium i paczka

• Repozytorium: https://github.com/tbudaj/TBJ.Integrations.NFZ.UmwApi
• Paczka NuGet: https://www.nuget.org/packages/TBJ.Integrations.NFZ.UmwApi

Licencja

MIT