Zakres

Mandroya Senses udostępnia publicznie dane, na których opiera się ta strona: katalog usług wraz z cenami, pakiety, listę terapeutek, placówki partnerskie programu Mapa Rozwoju oraz wolne terminy. Dostęp nie wymaga klucza ani rejestracji, a odpowiedzi zwracane są w formacie JSON.

Opis w postaci maszynowej znajduje się w specyfikacji OpenAPI 3.1.

Zasady korzystania

Interfejs jest przeznaczony wyłącznie do odczytu. Wszystkie operacje wykonuje się metodą GET, bez nagłówków autoryzacyjnych.
Rezerwacji nie można złożyć programowo. Termin wybiera się w systemie pacjenta pod adresem wizyty.mandroya.pl.
Udostępniane dane obejmują wyłącznie ofertę, zespół i dostępność terminów. Nie zawierają żadnych danych pacjentów.
Ceny podawane są w złotych i dotyczą pojedynczej wizyty, o ile opis pola nie stanowi inaczej.
Katalog usług i cennik zmieniają się rzadko. Zalecamy buforowanie odpowiedzi po stronie klienta zamiast pobierania ich przy każdym żądaniu.

Wersjonowanie

Numer wersji jest częścią ścieżki. Bieżąca wersja to /api/v1 i jej należy używać w nowych integracjach.

W obrębie jednej wersji dopuszczamy zmiany, które nie łamią kontraktu: nowe pole w odpowiedzi, nowy endpoint, nowa wartość w polu opisowym. Klient powinien więc ignorować pola, których nie zna. Zmiana łamiąca kontrakt, czyli usunięcie pola, zmiana jego znaczenia albo typu, otrzyma nową ścieżkę /api/v2.

Wycofanie sygnalizujemy nagłówkami. Deprecation: true oznacza ścieżkę, która działa, ale nie jest zalecana w nowych integracjach; towarzyszy jej nagłówek Link z rel="deprecation", prowadzący do tej strony. Sunset z datą wyłączenia pojawi się dopiero wtedy, gdy wersja będzie faktycznie wygaszana, i nie wcześniej niż dwanaście miesięcy przed wyłączeniem. Dopóki daty nie ma, nie wysyłamy tego nagłówka, ponieważ data jest zobowiązaniem, a nie ozdobą.

Ścieżki bez numeru wersji, na przykład /api/public-services, działają nadal i wskazują na wersję pierwszą. Niosą już dziś nagłówek Deprecation: true, co należy czytać jako "użyj /api/v1", a nie jako zapowiedź wyłączenia. Zostają na stałe ze względu na integracje, które już z nich korzystają.

Limity zapytań

Ruch do API jest ograniczany. Bieżący limit to 120 zapytań na minutę na adres IP. Każda odpowiedź niesie nagłówki RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset, a także ich odpowiedniki z przedrostkiem X-. Po przekroczeniu limitu API zwraca status 429 wraz z nagłówkiem Retry-After.

Zbuduj klienta tak, aby czytał te nagłówki i po odpowiedzi 429 odczekał wskazany czas, zamiast ponawiać zapytanie od razu. Limity i sposób ich stosowania możemy zmienić, jeżeli będzie tego wymagała stabilność usługi.

Odpowiedzi niosą nagłówek Cache-Control: 60 sekund dla przeglądarki i 300 sekund dla buforów pośredniczących przy katalogu, pakietach, terapeutkach i placówkach, a 30 sekund przy terminach, które mają pozostać aktualne. Katalog i cennik zmieniają się rzadko, dlatego zalecamy buforowanie odpowiedzi po swojej stronie zgodnie z tym nagłówkiem.

Endpointy

Adres bazowy: https://mandroya.pl/api/v1

Usługi i ceny

GET /public-services zwraca katalog usług: nazwę, kategorię, czas trwania oraz cenę pojedynczej wizyty. Pole is_online_only wskazuje usługi prowadzone wyłącznie zdalnie, a is_self_bookable określa, czy usługę można zarezerwować samodzielnie. Pozycje z ceną 0 zł mają charakter techniczny.

curl -s https://mandroya.pl/api/v1/public-services

Pakiety

GET /public-packages zwraca pakiety wizyt. Pole usage_count określa liczbę wizyt, current_price cenę całego pakietu, a validity_weeks okres ważności w tygodniach. Cenę pojedynczej wizyty oblicza się, dzieląc current_price przez usage_count. Powiązanie z usługą wskazuje pole service_id.

curl -s https://mandroya.pl/api/v1/public-packages

Terapeutki

GET /public-therapists zwraca osoby przyjmujące w centrum wraz z usługami, które prowadzą. Pola avatar_url, bio oraz education mogą pozostawać puste.

curl -s https://mandroya.pl/api/v1/public-therapists

Placówki partnerskie

GET /public-institutions zwraca aktywne placówki objęte programem Mapa Rozwoju.

curl -s https://mandroya.pl/api/v1/public-institutions

Wolne terminy

GET /public-availability wymaga trzech parametrów: service_id pochodzącego z katalogu usług oraz date_from i date_to w formacie YYYY-MM-DD. Zakres dat nie może przekraczać 35 dni. Usługi nieoznaczone flagą is_self_bookable nie mają dostępnych terminów.

curl -s "https://mandroya.pl/api/v1/public-availability?service_id=UUID&date_from=2026-09-01&date_to=2026-09-14"

Wynik wymaga uważnej interpretacji. Terminy zwracane są jako siatka co 10 minut, w związku z czym liczba slotów nie odpowiada liczbie wizyt możliwych do umówienia. Okno od 13:00 do 18:30 obejmuje 29 slotów, mieści jednak 6 wizyt pięćdziesięciominutowych. Rzeczywistą pojemność dnia otrzymuje się przez upakowanie nienachodzących na siebie przedziałów o długości równej polu duration_minutes wybranej usługi.

Obsługa błędów

Błędy zwracane są w formacie JSON, ze statusem HTTP innym niż 200. Pole error występuje zawsze i zawiera komunikat w postaci czytelnej dla człowieka. W przypadku odwołania do nieznanej ścieżki odpowiedź zawiera dodatkowo pola code oraz hint.

{"error":"Zakres dat za duzy (max 35 dni)"}

{"error":"Nieznany endpoint API","code":"endpoint_not_found","hint":"https://mandroya.pl/openapi.json"}

{"error":"Za duzo zapytan. Odczekaj chwile i sprobuj ponownie.","code":"rate_limit_exceeded","hint":"https://mandroya.pl/api","retry_after_seconds":42}

Kontakt

Pytania dotyczące interfejsu prosimy kierować na adres senses@mandroya.pl.

API Mandroya Senses