Wizyty u weterynarza i ankiety kontrolne — przebieg integracji¶

Ścieżki są względne wobec /partner/v1/med-visit. Uwierzytelnienie jak w pozostałych modułach: x-client-id, x-api-key, x-user-id.

Zakres tego modułu¶

Moduł dotyczy wizyt zarejestrowanych przez weterynarza z naszej sieci oraz ankiet kontrolnych, które po takiej wizycie wysyłamy właścicielowi.

Nie należy go mylić z wizytami zewnętrznymi. Różnica jest w tym, kto wpisuje dane:

	Kto wprowadza	Ankieta kontrolna
Wizyty u weterynarza (ten moduł)	lekarz w naszym panelu	tak, dwa dni po wizycie
Wizyty zewnętrzne	właściciel, przez aplikację partnera	nie

Takiej wizyty nie da się utworzyć przez API. Zakłada ją i wypełnia weterynarz po naszej stronie; użytkownik może ją wyłącznie odczytać, gdy zostanie zamknięta. Do tego dochodzi krótka ankieta kontrolna wysyłana po wizycie.

Cały moduł jest więc tylko do odczytu, z jednym wyjątkiem: odpowiedzią na ankietę.

Skąd bierze się wizyta¶

Weterynarz może założyć wizytę dopiero wtedy, gdy zwierzak jest powiązany z jego placówką. Dla użytkowników partnera prowadzą do tego dwie drogi — obie mieszczą się w uzgodnionym zakresie i żadna nie wymaga dodatkowego wywołania:

Droga	Jak powstaje powiązanie
Czat	pierwsza wiadomość dopina użytkownika i jego zwierzaki do placówki obsługującej czat — patrz dokumentacja czatu
PIN prediagnozy	użytkownik podaje weterynarzowi sześciocyfrowy `pin` z wyniku; lekarz otwiera nim prediagnozę, co wiąże zwierzaka i właścicieli z placówką — patrz dokumentacja prediagnozy

Druga droga jest tą, którą warto pokazać użytkownikowi wprost: to jedyny sposób, by zaniósł swoją prediagnozę do konkretnego gabinetu.

Na środowisku testowym

Dopóki żaden weterynarz nie założył wizyty dla testowego użytkownika, wywołania z tego modułu zwracają 404 — to poprawne zachowanie dla nieistniejącej wizyty, a nie usterka integracji. Jeśli potrzebne są dane do pracy nad ekranem, przygotujemy zamkniętą wizytę wraz z ankietą na wskazanym koncie.

Skąd wziąć identyfikator wizyty¶

Nie ma endpointu zwracającego listę wizyt użytkownika. Wizyty pojawiają się na osi czasu jako wpisy record_type: "MedVisit", a ich related_record to identyfikator wizyty:

GET /partner/v1/timeline/{petId}?period=PAST
→ { "record_type": "MedVisit", "related_record": "<visit_id>",
    "is_closed": true, "name": "Zapalenie ucha zewnętrznego" }

Odczyt wizyty¶

GET /user-visit/{visitId}/{petId}

Oba identyfikatory są sprawdzane: wizyta musi należeć do wskazanego zwierzaka, a zwierzak do użytkownika z x-user-id.

Zwracane są wyłącznie wizyty zamknięte. Wizyta otwarta — trwająca albo jeszcze nieuzupełniona przez weterynarza — kończy się 403, a nie pustą odpowiedzią. To zamierzone: dopóki weterynarz nie zamknie wizyty, jej treść nie jest gotowa do pokazania właścicielowi.

Kształt odpowiedzi¶

{ "id": "…", "is_closed": true, "is_telemedicine": false,
  "closed_at": "…", "pet_id": "…", "vet_id": "…", "clinique_id": "…",
  "weight": 12.5, "temp": 38.4, "activity": 3,
  "interview": "Od trzech dni drapie się po uchu…",
  "comment": "…", "med_diet": "…", "med_behavioral": "…",
  "med_treatments": "…", "med_treatments_duration": "…",
  "next_visit_date": "2026-10-02",
  "visit_duration": 1380, "visit_duration_formatted": "0 h 23 min 00 s",
  "Disease": "Zapalenie ucha zewnętrznego",
  "Examinations": ["Badanie otoskopowe"],
  "Medicines": ["Otibiovin"],
  "Vet": { … }, "Pet": { … }, "Prediagnosis": { … },
  "rating": { "id": "…", "rate": 5 } }

Cztery rzeczy warte uwagi:

Nazwy zamiast identyfikatorów. Disease, Examinations i Medicines to gotowe nazwy w języku żądania. Obok występują surowe pola med_examination i med_medicines — są to łańcuchy z tablicą identyfikatorów w JSON, nie tablice. Do wyświetlenia służą te pierwsze; surowych nie trzeba parsować.

Obiekty zagnieżdżone. Prediagnosis ma ten sam kształt co GET /prediagnosis/details/{prediagnosisId}. Pet to skrócony profil zwierzaka, a Vet — profil weterynarza; oba są opisane schematami w Swaggerze (PetShortInfoResponse) i nie mają osobnych endpointów. Wszystkie trzy występują tylko wtedy, gdy wizyta ma je powiązane.

visit_duration_formatted to gotowy tekst w formacie H h mm min ss s; obok visit_duration w sekundach.

rating jest null, dopóki właściciel nie ocenił wizyty. Wystawianie oceny nie jest częścią tego API.

Ankieta kontrolna¶

Po wizycie pytamy właściciela, jak zwierzak się czuje. Ankietę zakłada automat dwa dni po zakończeniu wizyty. Jeśli odpowiedź brzmi „bez zmian" albo „gorzej", po kolejnych dwóch dniach powstaje druga ankieta — stąd pole count.

Odpowiedź UNCHANGED lub WORSE trafia jako powiadomienie do placówki, w której odbyła się wizyta. To jedyne miejsce w tym module, gdzie API coś zmienia.

Odczyt¶

GET /monitoring/{monitoringId}

{ "id": "…", "med_visit_id": "…", "status": null, "count": 1,
  "pet_id": "…", "vet_id": "…", "clinic_id": "…", "prediagnosis_id": "…",
  "pet_name": "Burek", "email": "…", "answered_at": null,
  "created_at": "…", "updated_at": "…" }

status: null i answered_at: null oznaczają ankietę jeszcze niewypełnioną.

Odpowiedź¶

PATCH /monitoring/{monitoringId}
{ "state": "BETTER" }

`state`	Znaczenie
`HEALTHY`	wyzdrowiał
`BETTER`	lepiej
`UNCHANGED`	bez zmian
`WORSE`	gorzej

Inna wartość kończy się 400. Ankietę można nadpisać — ponowne wywołanie zmienia odpowiedź i aktualizuje answered_at.

Jak dowiedzieć się, że ankieta czeka¶

W momencie założenia ankiety wysyłamy zdarzenie visit.monitoring.created:

{ "type": "visit.monitoring.created", "userId": "…", "occurredAt": "…",
  "data": { "monitoringId": "…", "visitId": "…", "petId": "…", "count": 1 } }

To jedyne źródło identyfikatora ankiety — nie występuje on w odpowiedzi wizyty ani na osi czasu. Zdarzenie warto potraktować jako sygnał do wyświetlenia powiadomienia: u nas w tym samym momencie idzie mail do właściciela, ale użytkownikom integracji naszych maili ani powiadomień nie wysyłamy.

count mówi, która to ankieta w serii: 1 po wizycie, 2 po odpowiedzi „bez zmian" lub „gorzej".

Najczęstsze przyczyny błędów¶

Objaw	Przyczyna
`403` przy odczycie wizyty	Wizyta nie jest jeszcze zamknięta przez weterynarza
`403` mimo poprawnych identyfikatorów	Zwierzak nie należy do użytkownika z `x-user-id`
`404` przy odczycie wizyty	Wizyta należy do innego zwierzaka niż podany w ścieżce
`400` przy odpowiedzi na ankietę	`state` spoza czterech dozwolonych wartości
`med_examination` nie jest tablicą	To łańcuch z JSON-em; nazwy są w `Examinations`
Brak `Vet` albo `Prediagnosis`	Wizyta nie ma powiązanego weterynarza lub prediagnozy
Brak wizyt gdziekolwiek	Wizyty zakłada weterynarz z naszej sieci; przez API nie powstają

Przykładowa sekwencja¶

GET   /partner/v1/timeline/{petId}?period=PAST      → wpis MedVisit z related_record
GET   /partner/v1/med-visit/user-visit/{visitId}/{petId}

po nadejściu webhooka visit.monitoring.created:
GET   /partner/v1/med-visit/monitoring/{monitoringId}
PATCH /partner/v1/med-visit/monitoring/{monitoringId}   { "state": "BETTER" }