Integracja z ZUS e-ZLA: jak działa wystawianie e-zwolnień w systemie medycznym

Integracja z ZUS e-ZLA pozwala wystawiać elektroniczne zwolnienia lekarskie bezpośrednio z systemu placówki — bez papierowych druków i logowania do ZUS PUE osobno. Technicznie to połączenie z usługą ZUS przez SOAP-API, budowa i walidacja dokumentu XML względem schematu XSD, podpis elektroniczny oraz obsługa wysyłki, anulowania i statusu. Ten artykuł pokazuje, co naprawdę obejmuje takie wdrożenie — na podstawie realnego projektu.

e-ZLA i P1 brzmią podobnie „urzędowo", ale to dwa zupełnie osobne światy integracji.

Czy ten artykuł jest dla Ciebie?

Będzie pomocny, jeśli:

• budujesz dedykowany system lub portal, w którym lekarz ma wystawiać e-zwolnienia,
• jesteś dyrektorem IT / decydentem i oceniasz zakres integracji,
• chcesz wiedzieć, czym e-ZLA różni się od P1 i dlaczego to osobny projekt,
• zależy Ci na realnym harmonogramie, a nie „to tylko kolejna integracja".

Jeśli szukasz wymagań technicznych wprost od źródła — publikuje je ZUS (BIP) w dokumentacji dla aplikacji gabinetowych — szczegóły interfejsu bywają aktualizowane, więc sprawdzaj wersję. Tu pokazujemy obraz całości i miejsca, w których wdrożenia się potykają.

Co to jest e-ZLA i integracja z ZUS

e-ZLA to elektroniczne zwolnienie lekarskie przekazywane do ZUS drogą elektroniczną. Zamiast druku papierowego lekarz wystawia dokument w systemie, a ten trafia do ZUS i do płatnika składek. Integracja oznacza, że Twój system potrafi to zrobić samodzielnie: zbudować dokument, podpisać, wysłać, w razie potrzeby anulować i sprawdzić status.

Od strony technicznej to osobne SOAP-API ZUS — inne niż P1. Ma własną dokumentację, własny schemat XSD do walidacji dokumentu i wymaga podpisu elektronicznego (np. certyfikatem PKCS#12) oraz rejestracji i klucza po stronie ZUS.

Czego nauczyło nas wdrożenie

Przy portalu systemu dla sieci placówek medycznych (projekt rzędu 450 zadań, ~1,5 roku) e-ZLA było jedną z integracji, którą przeszliśmy od rejestracji po produkcję. Zajęła nam ona około trzech tygodni więcej, niż zakładaliśmy — przez zawiłą specyfikację oraz testy zgodności szablonu XML i certyfikatu. Najciekawsze okazało się jednak to, czego nie widać w pierwszym opisie zadania:

Założenie: „skoro robimy już P1, e-ZLA dorzucimy przy okazji".

Rzeczywistość: e-ZLA to osobny SOAP z własnym schematem XSD i podpisem — u nas obudowany serwisem SickLeaveService nad klientem ZUS, z operacjami wystawienia, anulowania i odpytania statusu (createEzl, cancelEzl, getStatus). Ale największym zaskoczeniem nie była komunikacja z ZUS, lecz logika płatnika. Dane płatnika pobiera się po numerze PESEL pacjenta, a ubezpieczony bywa zatrudniony w kilku miejscach — a że niezdolność do pracy dotyczy każdego zatrudnienia, zwolnienie zwykle wystawia się dla wszystkich właściwych płatników, nie jednego wybranego. To zadanie oznaczyliśmy jako priorytetowe — bo to ono, a nie „wysłanie XML-a", decyduje, czy zwolnienie trafi tam, gdzie ma.

Ważny kontekst regulacyjny: od 1 stycznia 2023 r. profil na PUE ZUS (obecnie przemianowywanym na eZUS) jest obowiązkowy dla wszystkich płatników, a tym, którzy go nie założyli, ZUS tworzy profil techniczny. Dlatego klasyczny scenariusz „płatnik bez profilu → wydruk dla ubezpieczonego" stał się dziś przypadkiem brzegowym — ale dobrze zaprojektowany system i tak musi go obsłużyć.

Wniosek: w e-ZLA największą wartość ma nie kod wysyłający dokument, lecz poprawna obsługa reguł i przypadków brzegowych — oraz śledzenie zmian po stronie ZUS, bo one dezaktualizują założenia szybciej niż kod.

Co naprawdę obejmuje integracja z e-ZLA

• Dostęp do interfejsu i środowiska testowego ZUS oraz podpis dokumentu (certyfikat z ZUS albo podpis kwalifikowany; klucz w kontenerze PKCS#12, format podpisu wg wymagań ZUS).
• Moduł dokumentów — wystawianie, anulowanie, odpytywanie statusu (u nas: createEzl / cancelEzl / getStatus).
• Budowa i walidacja XML względem schematu XSD ZUS.
• Logika płatnika — pobranie po PESEL, obsługa kilku płatników, wybór właściwego.
• Sprawdzenie profilu ZUS PUE płatnika i ścieżka „druk dla pacjenta", gdy profilu brak.
• Obsługa błędów, logowanie i numer referencyjny zwrócony przez ZUS.
• Środowisko testowe przed produkcją.

Logika płatnika: gdzie potyka się większość integracji

Zwolnienie nie „wisi w próżni" — musi trafić do właściwych płatników składek. Dane płatnika system pobiera z ZUS po numerze PESEL pacjenta; w odpowiedzi dostaje listę płatników wraz z informacją o ich profilu. Stąd trzy realne decyzje projektowe, których nie widać w „wyślij XML":

• Kilku płatników — niezdolność do pracy dotyczy każdego zatrudnienia, więc zwolnienie zwykle wystawia się dla wszystkich właściwych płatników, nie jednego.
• Profil płatnika — od 2023 r. profil na PUE/eZUS jest obowiązkowy (ZUS tworzy profil techniczny), więc brak aktywnego profilu to dziś sytuacja wyjątkowa; mimo to system musi ją obsłużyć ścieżką wydruku e-ZLA dla ubezpieczonego.
• Asystent medyczny — e-ZLA bywa wystawiane przez upoważnionego asystenta w imieniu lekarza; to osobny przypadek uprawnień do obsłużenia.

Dobre e-ZLA poznaje się nie po tym, że wysyła XML, lecz po tym, jak obsługuje płatników, uprawnienia i przypadki brzegowe.

Z pola: błędy, które wyszły dopiero przy anulowaniu i druku

Teoria kończy się w momencie, gdy dokument jedzie do ZUS i coś wraca nie tak. Kilka realnych rzeczy z naszego backlogu, których nie znajdziesz w żadnej specyfikacji:

• Słownik powodów anulowania się rozjeżdżał. Opisy przyczyn anulowania w portalu nie zgadzały się co do słowa ze słownikiem ZUS PUE, przez co anulowanie bywało odrzucane. Rozwiązaniem było pobieranie najnowszego słownika wprost z ZUS i pokazywanie aktualnych wartości w oknie anulowania. Własna kopia po cichu się starzeje — i to ona była źródłem błędu.
• Anulowanie docierało puste. Dokument anulujący (AZLA) trafiał do ZUS bez danych — osobny błąd do wychwycenia, bo „wysłane" nie znaczy „poprawne".
• „Brak uprawnień" przy druku. Przy wydruku zwolnienia albo recepty z poziomu wizyty na koncie pacjenta pojawiał się komunikat o braku uprawnień; po poprawce pacjent drukuje własne ZLA, recepty i skierowania bez przeszkód.
• „Zwolnienie po ustaniu zatrudnienia". To nie kosmetyczny checkbox: gdy pacjent zakończył pracę, ale wciąż jest na zwolnieniu zaczętym w trakcie zatrudnienia, dokument idzie tylko do ZUS, nie do płatnika. Łatwo pomylić tę flagę z ustawieniami danych lekarza.
• Uzasadnienie wsteczne tylko, gdy trzeba. Pole uzasadnienia zwolnienia wstecznego pokazujemy dopiero wtedy, gdy w kalendarzu faktycznie cofniemy okres o ponad trzy dni; przy zwykłym zwolnieniu w ogóle się nie pojawia.

Pełną historię tego wdrożenia — z odcięciem od zewnętrznej platformy i własnym modelem danych placówek — opisaliśmy w case study system dla sieci placówek.

Red flags: kiedy uciekać od wykonawcy

• traktuje e-ZLA jak „dodatek do P1",
• nie wspomina o walidacji XSD i podpisie,
• pomija logikę płatnika (kilku płatników, profil PUE),
• nie ma obsługi anulowania i statusów,
• nie testuje na środowisku ZUS przed produkcją,
• nie wie, że od 2023 profil PUE jest obowiązkowy ani że PUE zmienia się w eZUS.

Utrzymanie i odpowiedzialność za zgodność

Integracja z ZUS to nie „zrób i zapomnij" — wymagania i nazewnictwo się zmieniają (obowiązek profilu od 2023, przejście PUE → eZUS). Zanim podpiszesz umowę, ustal:

• kto odpowiada za dostosowanie, gdy ZUS zmieni schemat lub wymagania — i na czyj koszt,
• jaki jest model wsparcia i SLA, gdy integracja przestanie działać w godzinach przyjęć,
• kto po Twojej stronie odpowiada za zgodność (RODO, przechowywanie kluczy, uprawnienia lekarzy i asystentów).

Co dalej

Jeśli budujesz system, w którym lekarz wystawia dokumenty urzędowe, e-ZLA rzadko występuje samo — zwykle idzie w parze z P1 i weryfikacją PWZ. Zaplanuj je jako trzy osobne integracje.

Warto też przeczytać:

• Integracja z P1 (e-Recepta, e-Skierowanie) — czego uczy wdrożenie
• Ile kosztuje oprogramowanie dla przychodni
• AI i systemy dla ochrony zdrowia

FAQ

Co to jest e-ZLA?

Elektroniczne zwolnienie lekarskie przekazywane do ZUS drogą elektroniczną — wystawiane w systemie zamiast na druku papierowym.

Czym integracja z e-ZLA różni się od P1?

To dwie odrębne integracje — P1 to e-Recepta i e-Skierowanie (Centrum e-Zdrowia), e-ZLA to zwolnienia (ZUS). Inne API, certyfikaty i dokumentacja.

Co jest potrzebne do integracji z e-ZLA?

Dostęp do interfejsu i środowiska testowego ZUS, podpis dokumentu (certyfikat z ZUS lub podpis kwalifikowany; klucz w kontenerze PKCS#12) oraz moduł budowy i walidacji XML wg schematu XSD.

Skąd system pobiera dane płatnika?

Z ZUS po numerze PESEL pacjenta, wraz z informacją o profilu każdego płatnika. Przy kilku płatnikach zwolnienie zwykle dotyczy wszystkich właściwych. Od 2023 r. profil na PUE/eZUS jest obowiązkowy (ZUS tworzy profil techniczny), więc brak profilu to dziś sytuacja wyjątkowa — obsługiwana wydrukiem dla ubezpieczonego.

Dowody i doświadczenia

Co zmieniło się w 2026?