Przejdź do głównej treści
Wizyta to zaplanowane pobranie krwi dla profilu pacjenta w stacjonarnym punkcie pobrań, wykonywane przez personel medyczny. Zestawy wysyłane pocztą do pacjenta nie są wizytami — zobacz Zamówienia domowych zestawów testowych.

Pola

string
wymagane
UUID generowany automatycznie przez Aniva. Użyj go, aby dodać panele, potwierdzić pobranie krwi i pobrać wyniki.
string
wymagane
UUID profilu, do którego należy ta wizyta.
string
UUID punktu pobrań, w którym odbędzie się pobranie krwi. Domowe zestawy testowe nie są wizytami — zobacz Zamówienia domowych zestawów testowych.
string
Zaplanowana data i godzina pobrania krwi w formacie ISO 8601. Zawsze zwracana jako czas UTC z przyrostkiem Z (np. 2026-04-15T08:30:00Z). Podczas tworzenia / aktualizacji wartość musi zawierać oznaczenie strefy czasowej (Z lub jawne przesunięcie, np. +02:00) — daty bez strefy czasowej są odrzucane. Musi być w przyszłości, a w lokalizacjach prowadzonych przez Aniva co najmniej 12 godzin naprzód (minimalne wyprzedzenie).
string
wymagane
Aktualny status cyklu życia. Jedna z wartości: pending, confirmed, blood_drawn lub cancelled. Zobacz Cykl życia poniżej. Szczegółowy stan realizacji wyników laboratoryjnych (in_progress lub completed) pochodzi z Pobierz wyniki; dokładniejszy postęp przesyłki (w drodze, dostarczona itp.) sprawdzisz, przechodząc z każdego wpisu w osadzonej tablicy shipments do Pobierz przesyłkę.
string
Dowolny tekst powodu zapisany przy anulowaniu wizyty (np. nieobecność, późne anulowanie, „Nieudane. Wymagane powtórzenie”). Ma wartość null, chyba że status to cancelled.
string[]
wymagane
Adresy zapisane małymi literami, z których każdy otrzymuje jednego e-maila, gdy wszystkie wyniki laboratoryjne będą ostateczne. Puste, gdy wyłączone. Zobacz E-maile o gotowych wynikach.
string
wymagane
Sposób pobrania krwi: capillary (z opuszka palca lub ramienia, do mikroprobówek) lub venous (z żyły, do probówek). Jest to metoda ustawiona dla wizyty, a w przeciwnym razie default_draw_method jej lokalizacji. Po pobraniu krwi jest to metoda, której użyto.
string
wymagane
Znacznik czasu ISO 8601 utworzenia wizyty.
string
Znacznik czasu ostatniej aktualizacji w formacie ISO 8601. Wartość null, jeśli wizyta nigdy nie była aktualizowana.
string[]
wymagane
Kody laboratoryjne (kody kreskowe probówek) zapisane w Potwierdź pobranie krwi, w kolejności skanowania. Puste do czasu potwierdzenia pobrania krwi. Pobranie żylne ma jeden kod wydrukowany na każdej probówce; pobranie kapilarne ma jeden kod na mikroprobówkę. Wyniki i dokumenty odwołują się do nich przez lab_code.
object[]
wymagane
Panele przypisane do tej wizyty jako wpisy { panel_id, added_at }. Zobacz Dodawanie paneli.
object[]
wymagane
Pojedyncze biomarkery przypisane do tej wizyty jako wpisy { biomarker_id, added_at }. Zobacz Pojedyncze biomarkery.
object[]
wymagane
Przesyłki powiązane z tą wizytą jako wpisy { id, added_at }, od najstarszego powiązania. Zobacz Łączenie przesyłek.
object
wymagane
Pełny obiekt profilu pacjenta, osadzony w każdej odpowiedzi dotyczącej wizyty. Poniższe pola stanowią jego część. Pobierz wizytę zawiera ich pełną listę.

Cykl życia

Wizyty mają cztery stany cyklu życia:
Status wizyty jest celowo ogólny — bardziej szczegółowy postęp jest dostępny przez dedykowane endpointy:
  • Realizacja wyników laboratoryjnych → Pobierz wyniki — główne pole status ma wartość in_progress lub completed.
  • Postęp przesyłki (w drodze, dostarczona itp.) → przejdź z każdego wpisu w osadzonej tablicy shipments w wizycie do Pobierz przesyłkę — każda przesyłka ma własny status oraz dziennik zdarzeń status_updates.
Każda zmiana statusu wysyła webhook appointment.*, na przykład appointment.confirmed. Nowy termin lub lokalizacja wysyła appointment.rescheduled.
Potwierdzenie wizyty (zmiana jej statusu na blood_drawn) jest nieodwracalne. Po przesłaniu kodu lub kodów laboratoryjnych uruchamiany jest proces zlecenia laboratoryjnego i nie można go cofnąć. Aktualizacje i anulowania są dozwolone tylko wtedy, gdy wizyta ma status pending lub confirmed.

Lista wizyt

Pobierz wszystkie wizyty dostępne dla twojego klucza API:
Opcjonalnie przekaż ?profile_id={uuid}, aby filtrować według konkretnego profilu. Bez tego parametru stosowane jest domyślne okno czasowe (od 2 miesięcy wstecz do 1 miesiąca w przód).

Aktualizacja wizyty

Przed potwierdzeniem pobrania krwi możesz zmienić termin lub punkt pobrań:
Przekaż dowolną kombinację pól scheduled_at, location_id, draw_method i results_ready_emails, aby zaktualizować wizytę. Uwzględnij tylko te pola, które chcesz zmienić.

Metoda pobrania krwi

Każda wizyta ma pole draw_method: capillary (z opuszka palca lub ramienia, do mikroprobówek) albo venous (z żyły, do probówek). Dotyczy to wyłącznie pobrania krwi. Mocz, wymazy i pozostałe próbki inne niż krew pobiera się tak samo przy obu metodach. Domyślnie jest to default_draw_method danej lokalizacji. Ustaw draw_method przy tworzeniu lub aktualizacji, aby użyć innej metody, albo ustaw null, aby wrócić do wartości domyślnej lokalizacji. Lokalizacja musi mieć tę metodę na swojej liście draw_methods, a zarezerwowane badania muszą być z nią możliwe, w przeciwnym razie żądanie zwróci 400. Po pobraniu krwi nie możesz jej zmienić. Po pobraniu krwi draw_method to metoda, której użyto.

Jedna wizyta na profil, lokalizację i termin

Profil może mieć najwyżej jedną nieanulowaną wizytę na parę (location_id, scheduled_at) — jednej osobie nie można pobrać krwi dwa razy w tym samym miejscu i czasie, niezależnie od tego, ile równoległych rezerwacji przyjmuje lokalizacja. Zarówno Utwórz wizytę, jak i Zaktualizuj wizytę egzekwują tę zasadę, zwracając 409 z polem appointment_id wskazującym na istniejącą już wizytę. Traktuj tę odpowiedź jako informację, że wizyta jest już zarezerwowana, a nie jako błąd do ponowienia: pobierz, przełóż lub anuluj wskazaną wizytę. W praktyce oznacza to, że powtórne żądania utworzenia są bezpieczne. Żądanie utworzenia wysłane ponownie po przekroczeniu limitu czasu sieci lub wywołane dwukrotnie przez użytkownika prowadzi do jednej wizyty zamiast dwóch — dzięki temu nigdy nie musisz później porządkować zduplikowanych rezerwacji dla tego samego pacjenta.
Aktualizacje są dozwolone tylko przed pobraniem krwi — tj. gdy wizyta ma status pending lub confirmed. Gdy wizyta przejdzie do statusu blood_drawn lub ma status cancelled, nie można jej modyfikować. Jedynym wyjątkiem jest results_ready_emails: nadal możesz zmienić samo to pole po pobraniu krwi.

Anulowanie wizyty

Anuluj wizytę, która nie jest już potrzebna:
Ustawia to status wizyty na cancelled. Anulowana wizyta jest zwracana w odpowiedzi. Opcjonalnie wyślij cancellation_reason (do 500 znaków) w treści żądania, aby zapisać powód. Zostanie on zapisany przy wizycie i zwracany jako cancellation_reason przy kolejnych odczytach.
Anulowanie jest dozwolone tylko przed pobraniem krwi — tj. gdy wizyta ma status pending lub confirmed. Wizyt, które przeszły już do statusu blood_drawn, nie można anulować.

Dodawanie paneli

Przed potwierdzeniem pobrania krwi dodaj panele badań krwi, które chcesz wykonać, wywołując:
Przekaż tablicę identyfikatorów UUID paneli w polu panel_ids. Identyfikatory paneli dostarcza Aniva dla twojego konta partnerskiego.
Panele trzeba dodać przed pobraniem krwi — tj. gdy wizyta ma status pending lub confirmed. Nie możesz dodawać ani zmieniać paneli, gdy wizyta przejdzie do statusu blood_drawn.

Usuwanie paneli

Jeśli musisz usunąć panele przed pobraniem krwi, wywołaj:
Przekaż tablicę identyfikatorów UUID paneli w polu panel_ids. Usuwanie jest idempotentne: panel, który nie jest przypisany, jest pomijany.
Podobnie jak dodawanie paneli, usuwanie jest dozwolone tylko przed pobraniem krwi — tj. gdy wizyta ma status pending lub confirmed. Paneli nie można usunąć, gdy wizyta przejdzie do statusu blood_drawn.

Pojedyncze biomarkery

Możesz przypisać do wizyty pojedyncze biomarkery jako badania dobierane indywidualnie, poza gotowym panelem. Przydaje się to, gdy specjalista chce dopasowanego zestawu zamiast gotowego pakietu. Przypisane biomarkery pojawiają się w odpowiedzi dla wizyty jako tablica individual_biomarkers (obok panels). Decyzje o kierowaniu zleceń zapadają dalej w potoku logistyki zleceń na podstawie mapowań każdego biomarkera w poszczególnych laboratoriach. Dodaj biomarkery (operacja idempotentna — już przypisane biomarkery zostają zachowane):
Usuń biomarkery (operacja idempotentna — biomarkery, które nie są przypisane, są pomijane):
Oba endpointy przyjmują tablicę biomarker_ids i sprawdzają wynikowy zestaw pod kątem reguł domknięcia każdego laboratorium — zlecenie, którego nie da się poprawnie złożyć (np. wskaźnik CRP/HDL bez CRP i HDL), zwraca 400 z biomarkerami, które musisz dodać, i niczego nie zapisuje. Użyj Wyświetl biomarkery, aby znaleźć identyfikatory biomarkerów.
Podobnie jak w przypadku zmian w panelach, pojedyncze biomarkery można dodawać lub usuwać tylko przed pobraniem krwi — tj. gdy wizyta ma status pending lub confirmed. Gdy wizyta przejdzie do statusu blood_drawn, niestandardowa migawka zostaje zamrożona.

Podgląd wymaganych pojemników

Po dodaniu paneli lub pojedynczych biomarkerów wyświetl podgląd fizycznych pojemników na materiał, które będą potrzebne do pobrania próbki:
Tablica containers w odpowiedzi zawiera typ, nazwę, kolor korka, objętość, numer katalogowy producenta i liczbę każdego wymaganego pojemnika. Pomaga to specjalistom przygotować odpowiednie materiały przed pobraniem krwi. Odpowiedź zawiera też obiekt pricing — pełne rozliczenie koszyka wizyty (naliczone pozycje, przypisane panele oraz po jednym wierszu na każdy dostarczony biomarker, wycenione według twojego cennika, z ceną detaliczną obok; zobacz Cennik), wypełniony, gdy wizyta ma przypisane badania, a twój klucz ma zakres prices_view, w przeciwnym razie null. routing celowo nigdy nie jest udostępniane i zawsze ma wartość null.
Podgląd odzwierciedla aktualnie przypisane panele i biomarkery. Jeśli dodasz lub usuniesz panele po wywołaniu podglądu, wywołaj ten endpoint ponownie, aby pobrać zaktualizowane wymagania dotyczące pojemników.

Potwierdzanie pobrania krwi

Po pobraniu krwi prześlij kody laboratoryjne (kody kreskowe probówek), aby uruchomić potok zleceń laboratoryjnych:
Wyślij lab_code, gdy jeden kod jest wydrukowany na każdej probówce (pobranie żylne), lub lab_codes z jednym wpisem na kod — każdy z panel_ids, które obejmuje — gdy każdy panel jest pobierany do własnych probówek z własnym kodem (pobranie włośniczkowe). Każdy panel jest wtedy osobnym zleceniem laboratoryjnym pod swoim kodem. Kody są zwracane jako lab_codes przy wizycie. Podczas pobrania włośniczkowego pobrana krew trafia do mikroprobówek. Najpierw umieszczane są panele, w kolejności rezerwacji. Pojedyncze biomarkery wypełniają następnie wolne miejsce w mikroprobówkach paneli. Gdy potrzebują więcej miejsca, otwierają nowe mikroprobówki. Rozkładamy je równomiernie. Każda mikroprobówka mieści maksymalnie 150 µl pojedynczych biomarkerów. Wywołania zmieniające panele lub biomarkery zwracają 400, gdy wynikowy zestaw narusza tę regułę. Zmienia to status wizyty na blood_drawn i uruchamia przetwarzanie w laboratorium. Ta operacja jest nieodwracalna.

Odbiór przesyłki

POST /api/v1/appointments/pickup został usunięty wraz ze statusem wizyty shipment_picked_up. Zwraca teraz 405 Method Not Allowed, ponieważ ścieżka przechodzi do trasy wizyty według ID. W ostatniej fazie endpoint ten działał jako no-op — przyjmował wywołanie i nic nie robił, więc jego usunięcie nie zmienia żadnego zachowania, na którym polegasz.
Aby śledzić postęp po pobraniu krwi, przejdź dla każdego wpisu w osadzonej tablicy shipments wizyty do Pobierz przesyłkę — każda przesyłka ma własny status oraz historię status_updates.

Łączenie przesyłek

Wizyta może być powiązana z jedną lub wieloma przesyłkami (i odwrotnie — relacja jest typu wiele-do-wielu). Aktualny zestaw powiązań pojawia się bezpośrednio po obu stronach:
  • w wizycie, jako tablica shipments z wpisami { id, added_at };
  • w przesyłce, jako tablica appointments z wpisami { id, added_at }.
Obie tablice są posortowane od najstarszego powiązania. Każde id odsyła do kanonicznego endpointu szczegółów (Pobierz przesyłkę / Pobierz wizytę) w celu pobrania pełnych danych. Przesyłki są łączone podczas tworzenia za pomocą pola appointment_id w Utwórz przesyłkę. Po utworzeniu zarządzaj powiązaniami z poziomu przesyłki za pomocą Dołącz wizyty do przesyłki oraz Odłącz wizyty od przesyłki; każdy z nich zwraca listę wizyt dla tej przesyłki po zmianie. Aby odczytać pełne dane paczek wizyty, użyj Wyświetl przesyłki z ?appointment_id=. Reguła modyfikacji jest taka: powiązania można tworzyć lub usuwać, gdy ALBO
  • wizyta jest już po pobraniu krwi (blood_drawn), albo
  • przesyłka została utworzona mniej niż 24 godziny temu.
Poza tym oknem powiązanie jest zablokowane, aby zapisy historyczne pozostały niezmienne.

Pobieranie wyników laboratoryjnych

Gdy laboratorium przetworzy próbki krwi, pobierz wyniki kliniczne i genetyczne:
Odpowiedź zawiera zaplanowane badania (status planned) obok otrzymanych wyników, więc możesz śledzić, co wciąż oczekuje. Pole status na najwyższym poziomie ma wartość in_progress, dopóki wszystkie zlecenia się nie zamkną, a następnie completed (lub fault, gdy żadne nie zwróciło wyników) — użyj go, aby ustalić, czy badania laboratoryjne z wizyty zostały zakończone. Webhook appointment.results.completed informuje cię, gdy to nastąpi, więc nie musisz cyklicznie odpytywać. Tablica submissions rozbija to na poszczególne zlecenia laboratoryjne, każde z własnym lab_code. Każdy otrzymany wynik i dokument zawiera lab_code, pod którym został zarejestrowany. Odwołania do plików PDF z raportami laboratoryjnymi znajdują się w tablicy documents — użyj GET /api/v1/documents/{id}, aby je pobrać.

Przykładowa wizyta