Pola
UUID generowany automatycznie przez Aniva. Użyj go, aby dodać panele, potwierdzić pobranie krwi i pobrać wyniki.
UUID punktu pobrań, w którym odbędzie się pobranie krwi. Domowe zestawy testowe nie są wizytami — zobacz
Zamówienia domowych zestawów testowych.
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).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ę.Dowolny tekst powodu zapisany przy anulowaniu wizyty (np. nieobecność, późne anulowanie,
„Nieudane. Wymagane powtórzenie”). Ma wartość
null, chyba że status to cancelled.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.
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.Znacznik czasu ostatniej aktualizacji w formacie ISO 8601. Wartość null, jeśli wizyta nigdy nie była aktualizowana.
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.Panele przypisane do tej wizyty jako wpisy
{ panel_id, added_at }. Zobacz
Dodawanie paneli.Pojedyncze biomarkery przypisane do tej wizyty jako wpisy
{ biomarker_id, added_at }. Zobacz
Pojedyncze biomarkery.Przesyłki powiązane z tą wizytą jako wpisy
{ id, added_at }, od najstarszego powiązania. Zobacz
Łączenie przesyłek.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
statusma wartośćin_progresslubcompleted. - Postęp przesyłki (w drodze, dostarczona itp.) → przejdź z każdego wpisu w osadzonej
tablicy
shipmentsw wizycie do Pobierz przesyłkę — każda przesyłka ma własnystatusoraz dziennik zdarzeństatus_updates.
appointment.*, na przykład
appointment.confirmed. Nowy termin lub lokalizacja wysyła appointment.rescheduled.Lista wizyt
Pobierz wszystkie wizyty dostępne dla twojego klucza API:?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ń: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 poledraw_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: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: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: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 tablicaindividual_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):
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: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: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
Aby śledzić postęp po pobraniu krwi, przejdź dla każdego wpisu w osadzonej tablicyshipments 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
shipmentsz wpisami{ id, added_at }; - w przesyłce, jako tablica
appointmentsz wpisami{ id, added_at }.
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.
Pobieranie wyników laboratoryjnych
Gdy laboratorium przetworzy próbki krwi, pobierz wyniki kliniczne i genetyczne: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ć.