Znanylekarz api – co warto wiedzieć przed integracją

Planujesz wdrożyć znanylekarz api w gabinecie lub systemie rezerwacji? Sprawdź, jaki jest realny zakres integracji, jakie są wymagania OAuth 2.0, limity i webhooki oraz na co uważać przed przejściem z sandboxu na produkcję.

Czym jest ZnanyLekarz API i jaki ma realny zakres

Jeśli planujesz integrację systemu gabinetowego z portalem do rezerwacji wizyt, najpierw warto uporządkować nazewnictwo. Oficjalnie nie mówimy tu o produkcie pod nazwą „ZnanyLekarz API”, ale o Docplanner Integrations API v1.14.0. Dla Polski bazowy adres integracji to https://www.znanylekarz.pl/api/v3/integration. To ważne, bo już na etapie analizy technicznej musisz wiedzieć, z jaką dokumentacją i jakim środowiskiem naprawdę pracujesz.

W praktyce znanylekarz api nie jest prostym dodatkiem do strony internetowej ani pojedynczym modułem „włącz i działaj”. To rozbudowany interfejs integracyjny obejmujący około 32 endpointy i 44 operacje. Taki zakres pozwala spiąć nie tylko same wizyty, ale też strukturę całego gabinetu: placówki, specjalistów, adresy, usługi, grafiki, wolne terminy, rezerwacje, przerwy w pracy i niektóre elementy związane z ubezpieczycielami.

Docplanner Integrations API v1.14.0: podstawowe fakty

Z biznesowego punktu widzenia najważniejsze są trzy fakty. Po pierwsze, API ma konkretną wersję i konkretny zakres, więc integracja musi być projektowana pod aktualną specyfikację, a nie pod ogólne założenie, że „jakoś zsynchronizuje terminy”. Po drugie, jest to API przeznaczone do rzeczywistej wymiany danych operacyjnych. Po trzecie, dostęp do niego nie działa jak w przypadku wielu otwartych usług SaaS, gdzie wystarczy wygenerować token w panelu i zacząć wysyłać zapytania.

Dla właściciela małego gabinetu oznacza to jedno: jeśli chcesz wdrożyć znanylekarz api, musisz potraktować temat jak normalny projekt integracyjny. Potrzebujesz ustalonego modelu danych, opisu scenariuszy biznesowych i wiedzy, które elementy mają być tylko odczytywane, a które także zapisywane lub aktualizowane.

Jakie obszary gabinetu obejmuje integracja

Zakres API jest szeroki i właśnie dlatego wdrożenie może być bardzo użyteczne, ale też wymagające. Integracja obejmuje między innymi:

• placówki i ich identyfikatory,
• lekarzy lub specjalistów przypisanych do konkretnej lokalizacji,
• adresy i kalendarze dostępne dla pacjentów,
• usługi wraz z opisem, ceną i widocznością,
• wolne sloty terminów,
• tworzenie, potwierdzanie, anulowanie i przenoszenie rezerwacji,
• przerwy w grafiku i czasową niedostępność,
• część powiadomień oraz zdarzeń synchronizacyjnych.

Taki zakres jest korzystny, bo pozwala ograniczyć ręczne przepisywanie wizyt między systemami. Jednocześnie oznacza, że błędnie ustawiona usługa albo źle przypisany kalendarz potrafią zepsuć cały proces zapisów. Jeśli pacjent widzi na portalu „pierwszą wizytę fizjoterapeutyczną”, a w systemie gabinetowym ta sama usługa ma inną nazwę, inny czas trwania albo inny identyfikator, to integracja zaczyna działać pozornie poprawnie, ale operacyjnie generuje chaos.

Dlaczego to ważne dla fizjoterapeuty i małej placówki

W gabinecie fizjoterapii kalendarz bywa bardziej złożony niż w wielu innych specjalizacjach. Jedna usługa trwa 30 minut, inna 45, a pierwsza konsultacja z badaniem może zajmować nawet 60 minut. Do tego dochodzą wizyty domowe, terapia blizny po zabiegach, rehabilitacja sportowa czy masaż leczniczy. Każda z tych usług może mieć inną cenę, inne warunki rezerwacji i inny sposób prezentacji dla pacjenta.

Dlatego przed wdrożeniem warto zadać sobie pytanie, czy integracja ma służyć tylko do publikacji wolnych terminów, czy również do pełnej synchronizacji zmian. Mały gabinet najwięcej zyskuje wtedy, gdy znanylekarz api obejmuje nie tylko pobieranie slotów, ale też aktualizację grafiku, blokad, przerw i statusów rezerwacji. W przeciwnym razie łatwo doprowadzić do sytuacji, w której pacjent zarezerwuje termin dostępny na portalu, ale zajęty już w wewnętrznym systemie pracy.

Dostęp do API: zgody, OAuth 2.0 i warunki po stronie gabinetu

Najczęstszy błąd na starcie polega na założeniu, że skoro profil istnieje, to integracja jest tylko kwestią programistyczną. W praktyce dostęp do API zależy jednocześnie od warunków technicznych, formalnych i biznesowych. Dopiero ich połączenie otwiera drogę do realnego wdrożenia.

OAuth 2.0 client_credentials w praktyce

Uwierzytelnianie odbywa się przez OAuth 2.0 w przepływie client_credentials. W prostych słowach oznacza to, że system integrujący pobiera token dostępu na podstawie danych klienta technicznego, a potem dołącza ten token do kolejnych wywołań API. Nie loguje się tu pacjent ani fizjoterapeuta w przeglądarce. To komunikacja serwer-serwer.

Dla Ciebie oznacza to kilka praktycznych wymagań. Po pierwsze, dane uwierzytelniające muszą być przechowywane poza kodem źródłowym, najlepiej jako bezpieczne zmienne środowiskowe lub w menedżerze sekretów. Po drugie, trzeba obsłużyć wygasanie tokenów i automatyczne odświeżanie dostępu. Po trzecie, nie wolno traktować tokena jako stałego hasła „na zawsze”, bo to ryzykowne i operacyjnie niepoprawne.

Jakie zgody i zakresy trzeba uzyskać

Samo techniczne wsparcie OAuth nie wystarczy. Dostęp wymaga zgody ZnanyLekarz lub Docplanner, nadania odpowiednich zakresów oraz aktywowania konkretnych uprawnień po stronie platformy. W praktyce oznacza to, że zakres widocznych endpointów i możliwych operacji może zależeć od ustaleń integracyjnych.

To ważne szczególnie wtedy, gdy planujesz nie tylko odczyt danych, ale także tworzenie i modyfikowanie rezerwacji. Inny zakres uprawnień będzie potrzebny do pobierania usług i slotów, a inny do potwierdzania wizyt czy obsługi zdarzeń związanych ze zmianą terminu. Dlatego już na etapie briefu warto rozpisać dokładnie, które operacje mają działać:

• odczyt listy usług,
• odczyt dostępnych terminów,
• zakładanie rezerwacji,
• potwierdzanie lub anulowanie wizyt,
• obsługa zmian w grafiku i przerw,
• odbiór webhooków i synchronizacja zdarzeń.

Im precyzyjniej opiszesz scenariusze, tym mniejsze ryzyko, że po stronie biznesowej dostaniesz dostęp tylko do części funkcji, a resztę trzeba będzie negocjować później.

Profil zweryfikowany, dokumenty i plan subskrypcyjny

Poza warstwą techniczną liczy się też gotowość samego profilu. Dla specjalisty lub gabinetu oznacza to zwykle zweryfikowany profil, komplet dokumentów potwierdzających uprawnienia zawodowe oraz aktywną konfigurację usług. Brak dokumentów może w praktyce blokować aktywność profilu albo ograniczać możliwość wykorzystania części funkcji.

Do tego dochodzi kwestia planu subskrypcyjnego. Część funkcji może być dostępna tylko w płatnych pakietach albo wymagać dodatkowej aktywacji. Dlatego jeśli rozważasz znanylekarz api dla gabinetu fizjoterapii, sprawdź nie tylko samą dokumentację techniczną, ale także model rozliczenia. Czasem koszt wdrożenia nie wynika z kodu, tylko z konieczności aktywacji określonych modułów po stronie platformy.

Warto też pamiętać, że gotowość integracyjna to nie to samo co obecność w katalogu specjalistów. Możesz mieć poprawnie uzupełniony profil, opinie pacjentów i widoczne usługi, a mimo to nie być gotowym do pełnej synchronizacji kalendarza. To dwa różne poziomy dojrzałości operacyjnej.

Najważniejsze endpointy przed wdrożeniem rezerwacji online

Jeżeli chcesz wdrożyć działające rezerwacje online, nie musisz na początku używać całego API. Najwięcej wartości dają zwykle cztery obszary: usługi, kalendarze, sloty i rezerwacje. To one decydują o tym, czy pacjent zobaczy właściwą ofertę i czy wybrany termin naprawdę będzie możliwy do zarezerwowania.

Usługi i ich parametry: cena, opis, widoczność, limity wieku

Usługi to fundament całej integracji. API pozwala pobierać listę usług ogólnych oraz usług przypisanych do konkretnego gabinetu lub adresu. Możesz zarządzać takimi parametrami jak cena, opis, widoczność usługi czy limity wiekowe pacjentów. To z pozoru proste pola, ale właśnie tutaj zaczyna się większość błędów mapowania.

Dla fizjoterapii warto uporządkować ofertę w sposób jednoznaczny. Przykładowe mapowanie może wyglądać tak:

Usługa w gabinecie	Co trzeba ustalić w integracji
Pierwsza wizyta fizjoterapeutyczna	Czas 60 minut, cena, opis badania i terapii próbnej
Terapia blizny	Osobny identyfikator usługi, inny opis wskazań i przebiegu
Rehabilitacja sportowa	Przypisanie do właściwego specjalisty i długości wizyty
Wizyta domowa	Ograniczenie dostępności do wybranych dni lub stref adresowych
Masaż leczniczy	Oddzielna cena, czas i widoczność w kalendarzu

Jeśli po jednej stronie masz usługę „Pierwsza konsultacja”, a po drugiej „Pierwsza wizyta fizjoterapeutyczna z badaniem”, integracja może uznać je za dwa różne byty. Dlatego nazwy, identyfikatory, czas trwania i przypisania do specjalisty powinny być spójne co do jednego rekordu.

Sloty, kalendarze i przerwy w grafiku

Endpoint /slots służy do pobierania dostępnych terminów i ma bardzo konkretny limit: zwraca terminy maksymalnie 180 dni do przodu. To istotne przy budowie formularza rezerwacji, kalendarza na stronie albo synchronizacji z systemem gabinetowym. Jeśli próbujesz pokazać pacjentowi terminy na 9 czy 12 miesięcy do przodu, to po prostu wyjdziesz poza zakres tego zasobu.

Poza samymi slotami liczy się też logika kalendarza. API pozwala zarządzać kalendarzem placówki lub adresu, w tym jego włączaniem i wyłączaniem. Da się również obsługiwać przerwy w grafiku. To szczególnie ważne przy fizjoterapii, gdzie dzień pracy bywa dzielony na bloki: konsultacje poranne, zabiegi popołudniowe, wizyty domowe, przerwa techniczna, szkolenie albo urlop.

Jeżeli integracja pobiera tylko wolne terminy, ale nie uwzględnia przerw, pacjent może zobaczyć pozornie dostępne okno czasowe. To klasyczny problem wdrożeniowy. W dobrze zaprojektowanej synchronizacji kalendarz nie pokazuje tylko tego, co wolne, ale także wie, dlaczego coś nie jest dostępne.

Tworzenie, potwierdzanie i zmiana rezerwacji

Największa odpowiedzialność spoczywa na operacjach rezerwacyjnych. API pozwala tworzyć wizyty, potwierdzać je, anulować i przenosić. Dla gabinetu oznacza to możliwość pełnej obsługi cyklu życia wizyty, ale tylko wtedy, gdy zadbasz o spójność między systemami.

W praktyce powinieneś zaplanować co najmniej taki scenariusz:

1. Pobranie listy usług i ich identyfikatorów.
2. Pobranie dostępnych slotów dla danej usługi i specjalisty.
3. Utworzenie rezerwacji na wybrany termin.
4. Potwierdzenie zmiany statusu po obu stronach integracji.
5. Obsługę anulowania lub przeniesienia wizyty bez utraty spójności kalendarza.

To właśnie tutaj widać, czy znanylekarz api został wdrożony jako realna synchronizacja, czy tylko jako nakładka marketingowa. Jeśli nie zaimplementujesz obsługi zmian i anulacji, system zadziała dobrze tylko do pierwszego przesunięcia wizyty przez pacjenta lub recepcję.

Wymagania techniczne: limity, webhooki i bezpieczeństwo danych

Wiele integracji wygląda dobrze na etapie prezentacji, a zaczyna sprawiać problemy dopiero podczas realnego ruchu. Najczęściej winne nie są same endpointy, tylko szczegóły techniczne: limity zapytań, brak obsługi callbacków, błędna konfiguracja serwera lub zbyt swobodne podejście do danych pacjentów.

Jak obsłużyć 429 Too Many Requests

API stosuje rate limiting. Po przekroczeniu limitu dostajesz status 429 Too Many Requests. To nie jest błąd przypadkowy, tylko kontrolowany mechanizm ochrony usługi. Do dyspozycji masz też nagłówki: X-RateLimit-Limit, X-RateLimit-Remaining oraz X-RateLimit-Reset. Na ich podstawie możesz monitorować zużycie puli zapytań i decydować, kiedy zwolnić tempo.

W praktyce dobra integracja powinna robić trzy rzeczy. Po pierwsze, ograniczać liczbę niepotrzebnych wywołań, na przykład przez cache usług lub harmonogram pobierania danych. Po drugie, wdrożyć mechanizm retry z opóźnieniem, najlepiej z narastającym czasem oczekiwania. Po trzecie, logować przypadki 429, bo nagły wzrost takich odpowiedzi zwykle oznacza błąd projektowy albo zmianę ruchu.

Dla małego gabinetu problem 429 nie musi pojawiać się codziennie, ale może uderzyć w najmniej wygodnym momencie, na przykład przy równoczesnym pobieraniu slotów, usług i zmian w kalendarzu. Jeśli nie masz planu awaryjnego, pacjent zobaczy brak terminów albo nieudane potwierdzenie wizyty, mimo że przyczyna leży wyłącznie w obsłudze limitów.

Webhooki i whitelista adresów IP

Drugim krytycznym obszarem są webhooki, czyli automatyczne powiadomienia o zdarzeniach. API wspiera model push i pull, więc możesz zarówno pobierać dane cyklicznie, jak i odbierać zdarzenia dotyczące nowych, potwierdzonych czy przeniesionych wizyt. To bardzo przydatne, bo zmniejsza opóźnienia synchronizacji.

Warunek jest jeden: serwer odbierający webhooki musi akceptować ruch z właściwych adresów. W praktyce trzeba whitelistować adresy IP ZnanyLekarz, a ich lista jest publikowana dynamicznie w plikach JSON lub TXT. To oznacza, że nie wystarczy jednorazowa konfiguracja firewalla wykonana pół roku temu. Trzeba przewidzieć aktualizację listy albo regularną kontrolę zmian.

Jeśli webhooki nie dochodzą, system gabinetowy zaczyna żyć własnym życiem. Pacjent zmienia termin na portalu, ale recepcja nadal widzi starą godzinę. Z technicznego punktu widzenia integracja działa częściowo, lecz operacyjnie staje się niebezpieczna. Dlatego webhooki warto testować nie tylko pod kątem odpowiedzi 200, ale też pod kątem kompletności i kolejności zdarzeń.

RODO, tokeny i dane pacjenta

Każda integracja rezerwacyjna dotyka danych pacjenta, a więc obszaru objętego RODO. Nie chodzi wyłącznie o imię i nazwisko. W grę mogą wchodzić terminy wizyt, dane kontaktowe, informacje o usłudze i kontekst medyczny wynikający z typu rezerwacji. Dlatego projekt integracji powinien być oparty na zasadzie minimalizacji danych: pobierasz i przechowujesz tylko to, co naprawdę jest potrzebne do obsługi procesu.

Równie ważne jest bezpieczeństwo tokenów OAuth. Nie powinny trafiać do repozytorium, logów aplikacyjnych ani paneli administracyjnych dostępnych bez kontroli uprawnień. Dobrą praktyką jest szyfrowanie sekretów, ograniczenie dostępu tylko do serwera aplikacyjnego i regularna rotacja danych uwierzytelniających, jeśli proces po stronie organizacyjnej na to pozwala.

Z punktu widzenia gabinetu fizjoterapii to nie jest „formalność dla działu IT”. To element bezpieczeństwa całej relacji z pacjentem. Jedno źle zabezpieczone konto techniczne może oznaczać nie tylko problem techniczny, ale też realne ryzyko incydentu z danymi.

Proces wdrożenia: sandbox, testy i migracja na produkcję

Rozsądne wdrożenie nie zaczyna się od produkcji. Najpierw potrzebujesz środowiska testowego, poprawnego mapowania zasobów i scenariuszy biznesowych. Dopiero potem warto przechodzić do pracy na prawdziwych wizytach. To szczególnie ważne tam, gdzie jeden błąd może od razu uderzyć w pacjentów i grafik terapeuty.

Co testować w środowisku sandbox

Środowisko sandbox pozwala sprawdzić integrację bez ryzyka dla realnych rezerwacji. To miejsce, w którym powinieneś przetestować nie tylko pojedyncze endpointy, ale cały przepływ pracy. Najlepiej przejść przez kompletny zestaw scenariuszy:

• pobranie placówek, specjalistów i adresów,
• mapowanie usług z prawidłowym czasem trwania i ceną,
• pobieranie slotów dla różnych dni i typów wizyt,
• utworzenie rezerwacji i jej potwierdzenie,
• anulowanie wizyty,
• przeniesienie wizyty na inny termin,
• obsługę przerwy w grafiku, urlopu i wyłączenia kalendarza,
• odbiór webhooków oraz reakcję systemu na zdarzenia push.

Jeżeli którykolwiek z tych etapów nie działa stabilnie w sandboxie, produkcja tylko powiększy problem. Szczególnie w przypadku znanylekarz api nie warto skracać testów, bo błędy zwykle ujawniają się dopiero przy zmianie terminu, anulacji albo chwilowym braku dostępności specjalisty.

Najczęstsze błędy przy mapowaniu danych

Najwięcej problemów nie wynika z samego kodu, tylko z niespójnych danych. Dotyczy to zwłaszcza małych placówek, które przez lata rozwijały usługi w sposób naturalny, bez jednego standardu nazewnictwa. W integracji takie różnice wychodzą natychmiast.

Typowe błędy to:

• różne nazwy tej samej usługi w dwóch systemach,
• brak zgodności identyfikatorów lekarzy lub fizjoterapeutów,
• niepoprawne przypisanie adresu do kalendarza,
• pominięcie wizyt domowych jako osobnego scenariusza,
• brak obsługi przerw w grafiku,
• niedopasowany czas trwania usługi względem rzeczywistej pracy gabinetu.

Przykład z praktyki: jeśli rehabilitacja sportowa trwa w systemie gabinetowym 50 minut, a w portalu 45 minut, to te 5 minut różnicy zacznie się kumulować w harmonogramie. Po kilku wizytach grafik przestaje być realny, mimo że każda pojedyncza rezerwacja wygląda poprawnie. To właśnie dlatego etap mapowania powinien być prowadzony równie dokładnie jak development.

Kiedy warto rozmawiać z opiekunem po stronie ZnanyLekarz

Pełna integracja zwykle wymaga rozmowy z przedstawicielem lub opiekunem po stronie platformy. Najlepiej zrobić to jeszcze przed właściwym developmentem, gdy znasz już zakres potrzeb i potrafisz nazwać swoje scenariusze. Wtedy łatwiej ustalić, jakie funkcje są dostępne, jakie uprawnienia trzeba aktywować i czy są dodatkowe warunki po stronie biznesowej.

Taka rozmowa jest szczególnie potrzebna, jeśli chcesz objąć integracją kilka lokalizacji, kilku specjalistów, wizyty domowe albo niestandardowe usługi. Im bardziej złożony model pracy gabinetu, tym większa korzyść z wcześniejszego potwierdzenia założeń. To często skraca wdrożenie bardziej niż kolejne godziny programowania.

Korzyści i ograniczenia integracji dla gabinetu fizjoterapii

Na końcu warto spojrzeć na temat uczciwie. Integracja może bardzo pomóc, ale nie jest magicznym przyciskiem, który sam naprawi organizację zapisów. Działa dobrze tylko wtedy, gdy procesy w gabinecie są już w miarę uporządkowane i da się je przełożyć na logikę systemu.

Co naprawdę zyskuje mały gabinet

Największą korzyścią jest automatyzacja. Zamiast ręcznie przenosić terminy, potwierdzać dostępność i poprawiać kalendarz w kilku miejscach, możesz zsynchronizować kluczowe dane między portalem a systemem gabinetowym. To oszczędza czas i ogranicza liczbę pomyłek.

Dla małego gabinetu fizjoterapii realne korzyści zwykle wyglądają tak:

• mniej ręcznej pracy przy umawianiu wizyt,
• spójniejszy kalendarz i mniej ryzyka podwójnych rezerwacji,
• lepsza widoczność usług i specjalistów,
• szybsza reakcja na zmiany terminów,
• czytelniejsza oferta dla pacjenta już na etapie wyboru wizyty.

To szczególnie przydatne, gdy oferta obejmuje różne typy świadczeń: pierwszą wizytę, terapię blizny, rehabilitację sportową, masaż leczniczy i wizyty domowe. Pacjent szybciej znajduje właściwą usługę, a Ty ograniczasz liczbę telefonów z pytaniem, który termin i który wariant terapii wybrać.

Ograniczenia operacyjne i kosztowe

Korzyści nie kasują ograniczeń. Integracja oznacza koszt przygotowania, testów, utrzymania i ewentualnych zmian po aktualizacjach. Do tego mogą dojść opłaty wynikające z planu subskrypcyjnego albo aktywacji dodatkowych funkcji. Jeśli model pracy gabinetu jest niestandardowy, wzrasta też koszt dopracowania mapowania danych.

Warto uczciwie pamiętać o trzech ograniczeniach. Po pierwsze, trzeba utrzymywać spójność zasobów po obu stronach. Po drugie, regulaminy, warunki i zakres funkcji mogą się zmieniać, więc integrację trzeba nadzorować. Po trzecie, opinie pacjentów pozostają własnością platformy, choć specjalista może na nie odpowiadać. To istotne, jeśli traktujesz portal nie tylko jako źródło wizyt, ale też jako miejsce budowania reputacji.

Jak ocenić, czy integracja się opłaci

Najprościej policzyć to na konkretnych scenariuszach. Jeśli tygodniowo masz 40 wizyt, z czego 10 do 15 trafia z kanału online, a każda ręczna obsługa lub korekta terminu zajmuje 3 do 5 minut, miesięcznie robi się z tego kilka godzin pracy administracyjnej. Do tego dochodzi koszt pomyłek: podwójnych zapisów, błędnie ustawionych usług czy utraconych terminów.

Integracja opłaca się wtedy, gdy:

• masz regularny napływ rezerwacji online,
• korzystasz z więcej niż jednego kalendarza lub adresu,
• oferujesz kilka typów usług o różnym czasie trwania,
• często zdarzają się zmiany terminów i anulacje,
• chcesz ograniczyć pracę recepcyjną bez utraty kontroli nad grafikiem.

Jeśli natomiast prowadzisz bardzo prosty grafik, masz jedną usługę i niewiele zmian, pełne wdrożenie może być mniej opłacalne niż prostsza organizacja zapisów. Dlatego decyzję o wdrożeniu znanylekarz api najlepiej podejmować nie na podstawie samej dostępności technologii, ale na podstawie realnego procesu pracy gabinetu.

Najczęściej zadawane pytania

Integracja z Docplanner ma sens wtedy, gdy jest dobrze przygotowana po stronie danych, uprawnień i procesu pracy gabinetu. Najwięcej zyskasz nie z samego dostępu do API, ale z przewidywalnej synchronizacji usług, kalendarzy i rezerwacji. Jeśli przed wdrożeniem uporządkujesz te elementy, łatwiej ocenisz, czy rozwiązanie rzeczywiście wesprze codzienną pracę gabinetu.

Dowiedz się więcej – Kliknij tutaj: tusprawnosc.pl