Leki — przebieg integracji¶

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

Zakres tego modułu¶

Moduł opisuje leki przyjmowane przez zwierzaka — dawkowanie, okres podawania i godzinę przypomnienia. Lek może istnieć samodzielnie albo być powiązany z wizytą zewnętrzną (wtedy przychodzi także w odpowiedzi tej wizyty).

Krok 1 — dodanie leku¶

POST /{petId}/pet-medicines
{ "medicineName": "Metacam",
  "type": "PILL",
  "dose": "1 tabletka",
  "startDate": "2026-09-10",
  "endDate": "2026-09-20",
  "hour": "8:00",
  "reminderInterval": "DAILY",
  "comment": "Po jedzeniu",
  "externalAppointmentId": null }

Pole	Wymagane	Uwagi
`medicineName` albo `medicineId`	tak (jedno z dwóch)	patrz niżej
`type`	nie	`PILL`, `SYRUP`, `DROPS`, `INJECTION`, `OTHER`
`dose`	nie	tekst dowolny
`startDate` / `endDate`	nie, ale patrz „Przypomnienia"	data
`hour`	nie	tekst `"HH:MM"`, np. `"08:00"`
`reminderInterval`	nie	patrz „Przypomnienia"
`comment`	nie
`externalAppointmentId`	nie	podpięcie leku pod istniejącą wizytę

Nazwa leku: `medicineName` czy `medicineId`¶

Lek można wskazać na dwa sposoby:

medicineId — pozycja z naszego słownika leków, pobierana z podpowiadarki:

GET /medicines-list
→ [ { "value": "<medicineId>", "label": "Metacam" } ]

Słownik liczy dziś 531 pozycji na język i zwracany jest w całości — nasza aplikacja pobiera go raz i filtruje lokalnie, i to samo polecamy. To jedyne miejsce w API, gdzie odpowiedź nie jest ograniczona do 100 pozycji: take działa tu jak zwykłe ucięcie listy (?take=20) i nie ma sufitu 100, a pominięty oznacza komplet. Można też zawęzić wynik po stronie serwera przez ?search=meta.

Nieznane medicineId kończy się 404.

Nazwy leków są polskie niezależnie od x-language. Słownik pochodzi z rejestru produktów leczniczych weterynaryjnych i nie jest tłumaczony — przy x-language: en wracają te same polskie nazwy. Dotyczy to zarówno podpowiadarki, jak i nazwy zagnieżdżonej w odczycie leku (Medicine.MedicinesContent[0].name).

medicineName — dowolny tekst, gdy leku nie ma w słowniku.

Zalecany układ formularza to podpowiadarka ze słownika z możliwością wpisania własnej nazwy — tak działa nasza aplikacja.

Powiązanie z wizytą¶

Podanie externalAppointmentId przypina lek do wizyty. Wizyta musi należeć do tego samego zwierzaka, inaczej 404.

Jedna nieoczywistość: jeżeli wizyta jest opakowaniem (treatAsWrapper: true), dodanie do niej leku dezaktywuje wszystkie pozostałe leki tej wizyty. Opakowanie niesie jeden bieżący lek — to zamierzone.

Krok 2 — lista aktywnych leków¶

GET /{petId}/pet-medicines

Zwraca { "petMedicines": [ … ] } — wyłącznie leki aktywne i nieprzeterminowane: pominięte są usunięte, dezaktywowane oraz te, których endDate już minęła. Kolejność od najnowszego.

Każda pozycja niesie zagnieżdżone Medicine (nazwa słownikowa w języku żądania) oraz ExternalAppointment z ewentualnym zabiegiem, jeśli lek jest powiązany z wizytą.

hour w odpowiedziach jest tekstem "HH:MM" (np. "08:00"), tak jak w wizytach; obok występuje liczbowe minute. null oznacza, że godzina nie jest ustawiona.

Krok 3 — edycja i usunięcie¶

PATCH  /{petId}/pet-medicines/{petMedicineId}
DELETE /{petId}/pet-medicines/{petMedicineId}

Edycja przyjmuje te same pola co dodawanie, bez nazwy leku i bez powiązania z wizytą — obu nie da się zmienić po utworzeniu. Wszystkie pozostałe są opcjonalne i pominięte zachowują dotychczasową wartość, z jednym wyjątkiem, tym samym co w wizytach: hour jest zawsze przeliczane, więc pominięcie go czyści godzinę.

DELETE to usunięcie miękkie: lek zostaje oznaczony jako usunięty i nieaktywny, znika z listy, a jego przyszłe przypomnienia są kasowane z osi czasu. Historia pozostaje.

Przypomnienia¶

Przypomnienia powstają automatycznie po naszej stronie dla leków aktywnych, z rozpoczętym podawaniem i z datą końca w przyszłości. Lek bez endDate nie wygeneruje przypomnień — to najczęstsza przyczyna pytania „dlaczego nie ma przypomnień".

Interwał¶

reminderInterval przyjmuje wartości DAILY, EVERY_4_HOURS, EVERY_8_HOURS, EVERY_12_HOURS, EVERY_24_HOURS, EVERY_WEEK, EVERY_MONTH.

Przypomnienia są dzienne — powstaje najwyżej jedno na dobę, o godzinie z pola hour:

Interwał	Kiedy powstaje przypomnienie
`EVERY_WEEK`	co 7 dni, licząc od `startDate`
`EVERY_MONTH`	ten sam dzień miesiąca co `startDate`
`DAILY`, `EVERY_24_HOURS`	codziennie
`EVERY_4/8/12_HOURS`	codziennie, raz — dawkowanie częstsze niż dobowe nie jest jeszcze odwzorowane w przypomnieniach
pominięty	codziennie

Interwał nie wpływa na okres podawania — ten wyznaczają startDate i endDate.

Przypomnienie pojawia się na osi czasu jako wpis typu PetMedicines, a jego related_record to notificationGroupId — tym identyfikatorem oznacza się wykonanie:

PUT /{petId}/pet-medicines/reminder/{notificationGroupId}/completed

Odpowiedź mówi, czy to wywołanie coś zmieniło:

Odpowiedź	Znaczenie
`{ "completed": true }`	przypomnienia zostały oznaczone
`{ "completed": false }`	nie było czego oznaczać — grupa była już zamknięta

Drugi przypadek nie jest błędem: wywołanie jest idempotentne, powtórzenie po prostu nic nie robi. Nieznany notificationGroupId to osobna sytuacja — 404.

Oznaczenie wykonania nie planuje kolejnego przypomnienia — następne powstaje samo, zgodnie z interwałem. To odwrotnie niż w pielęgnacji, gdzie completed przesuwa termin.

Zwróć uwagę, że notificationGroupId to inny byt niż petMedicineId — grupa dotyczy konkretnego wystąpienia przypomnienia.

Najczęstsze przyczyny błędów¶

Objaw	Przyczyna
`403` przy dowolnej operacji	Zwierzak nie należy do użytkownika z `x-user-id`
`404` przy dodawaniu leku	Nieznane `medicineId` albo wizyta z innego zwierzaka
`404` przy edycji lub usunięciu	Lek należy do innego zwierzaka niż podany w ścieżce
Lek nie pojawia się na liście	Minęła `endDate`, lek został usunięty albo dezaktywowany
Brak przypomnień	Lek nie ma `endDate` w przyszłości
Inne leki wizyty przestały być aktywne	Wizyta jest opakowaniem — niesie jeden bieżący lek
Godzina zniknęła po edycji	`hour` pominięte w `PATCH`; jest zawsze nadpisywane

Przykładowa sekwencja¶

GET   /partner/v1/pets/medicines-list                  → słownik leków (raz, do cache)
POST  /partner/v1/pets/{petId}/pet-medicines        → { petMedicine: { id } }
GET   /partner/v1/pets/{petId}/pet-medicines        → lista aktywnych

po nadejściu przypomnienia:
PUT   /partner/v1/pets/{petId}/pet-medicines/reminder/{notificationGroupId}/completed

zakończenie kuracji:
DELETE /partner/v1/pets/{petId}/pet-medicines/{petMedicineId}