Przejdź do głównej treści
Po potwierdzeniu pobrania krwi i przetworzeniu próbek przez laboratorium wyniki stają się dostępne dla wizyty. Pobierzesz je przez GET /api/v1/appointments/{id}/results — zawierają wyniki biomarkerów klinicznych, wyniki biomarkerów genetycznych oraz dokumenty raportów laboratoryjnych do pobrania.

Status wyników

Główne pole status w odpowiedzi z wynikami wskazuje ogólny postęp przetwarzania: Poszczególne wyniki w odpowiedzi mają własny status (zobacz niżej), dzięki czemu możesz wyświetlać wyniki częściowe, gdy ogólny status to nadal in_progress. Aby dowiedzieć się o zmianach wyników, zasubskrybuj webhooki. Zdarzenie appointment.results.updated uruchamia się przy każdej zmianie treści wyników, a appointment.results.completed — gdy główny status zmieni się na completed. Zamówienia domowych zestawów testowych wysyłają te same zdarzenia z prefiksem home_kit_order.. Każde zdarzenie zawiera adres URL wyników do pobrania. Nadal możesz odpytywać ten endpoint, aby uzgadniać dane. Tablica submissions rozbija główny status na poszczególne zlecenia laboratoryjne. Pobranie krwi obejmujące kilka probówek lub kilka laboratoriów ma kilka wpisów, każdy z kodem lab_code (kodem kreskowym probówki), pod którym został zarejestrowany, oraz własnym statusem in_progress / completed / fault. Wpis ze statusem fault został odrzucony lub porzucony w laboratorium i nigdy nie zwróci wyników: próbka często trafiła do innego laboratorium, które następnie tworzy własny wpis. Główny status ma wartość completed, gdy każdy wpis został zamknięty i co najmniej jeden zwrócił wyniki. Każdy otrzymany wynik i każdy dokument ma ten sam lab_code, dzięki czemu wiesz, z której probówki pochodzi dana wartość.

Wyniki kliniczne

Wyniki kliniczne to standardowe pomiary biomarkerów krwi — na przykład poziom witaminy D, cholesterol, hormony tarczycy i tym podobne. Każdy wynik kliniczny zawiera:
  • id — identyfikator wiersza wyniku laboratoryjnego. Pozostaje taki sam, gdy laboratorium koryguje ten wiersz, więc używaj go do operacji upsert. null dla wyniku planned.
  • biomarker_name i category — co zostało zmierzone i jego grupa (np. Witaminy, Hormony).
  • lab_code — kod laboratoryjny (kod kreskowy probówki), pod którym zarejestrowano wynik, jeden z kodów laboratoryjnych zamówienia. null dla wyniku planned oraz dla wyników zaraportowanych przez laboratorium bez kodu.
  • value i value_operator — właściwy pomiar. Operator ma wartość eq (równa się) dla dokładnych wartości albo lt/gt, gdy laboratorium raportuje wartość poniżej lub powyżej zakresu pomiarowego.
  • unit — jednostka miary (np. ng/mL, µIU/mL).
  • reference_range_lab — granice min/max zakresu normalnego i optymalnego podane przez laboratorium dla tego wyniku, przeliczone na tę samą skalę co value. Granica pozostawiona przez laboratorium jako otwarta ma wartość null, więc przedział jednostronny, taki jak < 50, przychodzi jako normal_min: null, normal_max: 50. Każdy wynik zawiera przedział, względem którego został zmierzony, więc pacjent z wynikami z kilku pobrań krwi lub laboratoriów otrzymuje właściwy zakres dla każdego wyniku.
  • reference_range_lab_absent_reason — powód, dla którego reference_range_lab ma wartość null. Ma wartość null, gdy zakres jest obecny, oraz przy wyniku planned. Zobacz Gdy brakuje zakresu laboratoryjnego.
  • aniva_range — wartości porównawcze opracowane przez Aniva w tej samej skali co value. Różnią się w zależności od wieku, płci i tygodnia ciąży. normal_* to zakres ogólny. optimal_* to zakres węższy. Wartości mają charakter wyłącznie informacyjny. Nie stanowią porady medycznej, diagnozy ani oceny wyniku. Aniva nie ustawia na ich podstawie żadnej flagi. Jako standard dla wyniku stosuj reference_range_lab. Ma wartość null, gdy twój klucz nie ma uprawnienia aniva_ranges_view lub gdy Aniva nie ma wartości dla tego biomarkera.
  • tested_at — data wykonania badania.
  • comment — dowolna adnotacja tekstowa z laboratorium do tego konkretnego wyniku (np. wskazówki dotyczące zakresu referencyjnego, ostrzeżenia o jakości próbki). null, gdy laboratorium jej nie dołączyło.
  • status_reason — powód, dla którego wynik likely_wrong jest wątpliwy lub wynik fault albo undeliverable jest bezużyteczny. null dla każdego innego statusu. Odrębne od pola comment, które jest własną notatką laboratorium i często bywa puste w przypadku błędnych wyników.
  • origin — kto dostarczył dokument, z którego pochodzi wartość; te same wartości co dla pola origin dokumentu poniżej. Wartość z przesłanego dokumentu (member_upload, staff_upload, partner_upload) pochodzi z odczytu pliku przez Aniva, a nie z raportu laboratoryjnego: przed użyciem klinicznym zweryfikuj ją z plikiem. null dla wyniku planned.
  • lab_reported — dosłowny i nieprzeliczony wiersz z raportu laboratorium wykonującego badanie. Zobacz niżej.

Zakresy Aniva

aniva_range zawiera wartości porównawcze opracowane przez Aniva na podstawie opublikowanych źródeł oraz własnej selekcji. Zakresy różnią się w zależności od wieku, płci i tygodnia ciąży. sources wymienia opublikowane źródła, które Aniva zapisała dla tych wartości. Lista może być pusta.
Wartości mają charakter ogólnej informacji. Nie stanowią porady medycznej, diagnozy, stwierdzenia medycznego ani oceny wyniku. Aniva nie udostępnia ich jako wyrobu medycznego. Aniva nie porównuje z nimi wyniku i nie ustawia na ich podstawie żadnej flagi. Standardem dla wyniku pozostają reference_range_lab oraz ocena lekarza.
Zasady dla twojego produktu:
  • Wyświetlaj zakres Aniva wyłącznie jako uzupełnienie zakresu laboratorium, nigdy zamiast niego.
  • Jeśli na podstawie zakresu Aniva tworzysz flagę, ostrzeżenie lub zalecenie, robisz to we własnym imieniu i na własną odpowiedzialność.
  • Wyświetlaj komunikat z twojej umowy z Aniva wszędzie tam, gdzie wyświetlasz zakres Aniva.
Aby uzyskać dostęp, podpisz krótką umowę dotyczącą zakresów Aniva. Następnie dodamy uprawnienie aniva_ranges_view do twojego klucza. Wartości mogą ulec zmianie bez uprzedzenia.

Wartości znormalizowane a oryginalny wiersz laboratorium

value, unit i reference_range_lab są znormalizowane: każdy pomiar przeliczamy na kanoniczną jednostkę biomarkera i raportujemy pod naszą własną nazwą biomarkera, dzięki czemu ten sam analit można porównywać między laboratoriami i w czasie. Tego właśnie potrzebujesz do analizy trendów i porównań między laboratoriami, a nie jest to widok z pliku PDF laboratorium, który przegląda lekarz — fosfataza alkaliczna wydrukowana jako 48 U/l (40 - 129) trafia do ciebie jako 0.8 µkat/L. lab_reported przekazuje równolegle ten wydrukowany wiersz: nazwę i kod analitu z laboratorium, wartość i jednostkę w formie z wydruku, przedział referencyjny zarówno jako tekst (< 50, > 55, 40 - 129), jak i oryginalne, nieprzeliczone granice z laboratorium, a także flagę nieprawidłowości, status wyniku i notatkę. Używaj lab_reported, gdy człowiek uzgadnia twoje dane z raportem laboratorium, a pól kanonicznych — do wszelkich obliczeń. Wypełnione są wyłącznie pola faktycznie przesłane przez laboratorium; nic w lab_reported nie jest wnioskowane, uzupełniane domyślnie ani przeliczane, a cały obiekt ma wartość null, gdy nie mamy surowego zapisu dla wyniku.

Gdy brakuje zakresu laboratoryjnego

Gdy reference_range_lab ma wartość null, pole reference_range_lab_absent_reason wyjaśnia dlaczego: Niektóre laboratoria drukują wartość docelową lub poziom ryzyka zamiast zakresu referencyjnego, na przykład Ziel: <200. >240 hoch albo <5.7 neg >=6.5 pos. Nie trafiają one do reference_range_lab, więc jego granice mają wartość null, a powód to lab_text_only. Wyświetlaj wydrukowany tekst dosłownie. Zakres jednostronny, taki jak < 20, jest zakresem. Przychodzi w reference_range_lab z jedną granicą null, a powód ma wartość null. Wyświetlając go, pozostaw otwartą stronę otwartą.

Statusy wyników klinicznych

Wyświetlając wyniki pacjentom, używaj bezpośrednio pola value — zawiera ono już skorygowaną wartość, jeśli taka istnieje.
Nigdy nie prezentuj wyniku fault jako wyniku badania — jego value jest wypełnione, ale potwierdzone jako błędne.

Wyniki genetyczne

Wyniki genetyczne przedstawiają ustalenia na poziomie genów z analizy DNA. Każdy wynik odpowiada jednemu genowi (np. APOE, MTHFR) i zawiera:
  • id — identyfikator wiersza wyniku laboratoryjnego. Pozostaje taki sam, gdy laboratorium koryguje ten wiersz, więc używaj go do operacji upsert. null dla wyniku planned.
  • gene — symbol genu.
  • lab_code — kod laboratoryjny (kod kreskowy probówki), pod którym zarejestrowano wynik. null dla wyniku planned oraz dla wyników zaraportowanych przez laboratorium bez kodu.
  • genotype — wykryty genotyp (np. E3/E4).
  • clinical_significance — klasyfikacja wyniku oparta na ACMG.
  • risk_description — zrozumiałe dla człowieka wyjaśnienie, co oznacza ten genotyp.
  • comment — dowolna adnotacja tekstowa z laboratorium do tego konkretnego wyniku. null, gdy laboratorium jej nie dołączyło.
  • status_reason — powód, dla którego wynik likely_wrong jest wątpliwy lub wynik fault albo undeliverable jest bezużyteczny. null dla każdego innego statusu.
  • origin — kto dostarczył dokument, z którego pochodzi wartość, tak jak w wynikach klinicznych.
  • variants — konkretne wykryte warianty genetyczne, każdy ze szczegółami na poziomie SNV.

Wartości znaczenia klinicznego

Statusy wyników genetycznych

Struktura wariantu

Każdy wynik genetyczny zawiera tablicę variants. Każdy wariant obejmuje:
  • name — nazwa zwyczajowa (np. APOE E4).
  • clinical_significance — znaczenie na poziomie wariantu (może różnić się od znaczenia na poziomie genu).
  • conditions — powiązane choroby lub schorzenia wraz z opisami.
  • snvs — bazowe warianty pojedynczego nukleotydu, każdy z polami rs_id, allele, reference_allele i opcjonalną notacją HGVS.

Dokumenty

Tablica documents w odpowiedzi z wynikami zawiera odniesienia do plików raportów laboratoryjnych do pobrania. Każdy dokument ma:
  • id — UUID pliku. Przekaż go do GET /api/v1/documents/{id}, aby pobrać plik.
  • file_name — nazwa pliku, taka sama jak przy pobieraniu (np. 20260405 - Quade Befund - 7642001234.pdf).
  • original_file_name — dokładna nazwa pliku dostarczona przez laboratorium lub osobę przesyłającą (np. 7642001234_B0012_FA_E.pdf).
  • origin — kto dostarczył plik: lab, member_upload, staff_upload lub partner_upload (przesłany przez ciebie za pomocą Prześlij dokument).
  • content_type — typ mediów pliku (np. application/pdf). Większość raportów to pliki PDF. Przesłane skany mogą być obrazami lub plikami CSV.
  • etag — wersja zawartości pliku; zmienia się przy każdej zmianie bajtów. Zapisz ją i pobieraj ponownie tylko wtedy, gdy się zmieni. To standardowy znacznik encji HTTP, stosowany w S3 lub Google Cloud Storage.
  • size_bytes — rozmiar pliku w bajtach.
  • lab_code — kod laboratoryjny (kod kreskowy probówki), do którego należy raport; null, jeśli laboratorium żadnego nie podało.
Dostęp do dokumentów jest weryfikowany względem profilu będącego właścicielem dokumentu.

Wysyłanie wyników e-mailem do klienta

Możesz powiadomić klienta e-mailem, że jego wyniki są gotowe. Wywołaj Wyślij wyniki e-mailem dla wizyty lub Wyślij wyniki e-mailem dla zamówienia domowego zestawu testowego. Każde wywołanie wysyła jedną wiadomość e-mail. Wywołania nie są deduplikowane.
  • E-mail trafia na adres email profilu. Zastępczy adres @aniva.email jest odrzucany.
  • E-mail wyświetla nazwę i logo głównej grupy profili tego profilu.
  • E-mail jest w języku language profilu, domyślnie po angielsku.
  • Ustaw with_reports na true, aby dołączyć raporty laboratoryjne.
  • Dodaj note, aby wyświetlić w e-mailu osobistą notatkę, maksymalnie 1 000 znaków.
Jeśli profil ma wyłączone e-maile transakcyjne, wywołanie zwraca 409 z powodem unsubscribed. Aby włączyć je ponownie, ustaw transactional_emails_enabled na true za pomocą Zaktualizuj profil.

E-maile o gotowości wyników

Możesz otrzymać e-mail, gdy wyniki rezerwacji będą gotowe. Ustaw results_ready_emails (do 5 adresów) w Utwórz wizytę lub Utwórz zamówienie domowego zestawu testowego. Listę możesz później zmienić w Zaktualizuj wizytę lub Zaktualizuj zamówienie domowego zestawu testowego; [] wyłącza e-maile.
  • Poproś nas o ustawienie domyślnych adresów e-mail dla twojej grupy profili. Rezerwacja utworzona bez results_ready_emails otrzymuje je automatycznie. Podanie listy zastępuje je dla tej rezerwacji, więc dopisz domyślny adres e-mail, jeśli chcesz go zachować. [] nie wysyła żadnych e-maili.
  • Każdy adres otrzymuje jeden e-mail, gdy wszystkie wyniki laboratoryjne z rezerwacji będą ostateczne.
  • Adres dodany po uzyskaniu ostatecznych wyników otrzymuje e-mail od razu.
  • Wiadomość zawiera link do strony z wynikami w panelu administracyjnym Aniva. Klient jej nie otrzymuje.
  • Twój klucz wymaga dostępu results_view do pacjenta. Bez niego żądanie zwraca 403.

Pokaż wyniki w swojej aplikacji

Utwórz sesję osadzania zwraca jednorazowy adres URL do strony wyników tylko do odczytu. Otwórz go w WebView w swojej aplikacji, aby pacjent zobaczył wyniki bez logowania.
  • Twój klucz wymaga zakresów embed i results_view dla pacjenta. Poproś Aniva o zakres embed.
  • Wywołuj go ze swojego serwera za każdym razem, gdy pacjent otwiera wyniki. Adres URL działa raz przez 5 minut, a strona utrzymuje następnie 60-minutową sesję.
  • route otwiera jedną z udostępnianych stron: listę biomarkerów, pojedynczy biomarker lub Twin 3D.
  • appearance ustawia motyw, kolor przycisków i linków oraz widoczność twojego logo.
  • report ogranicza stronę do jednej wizyty, jednego zamówienia domowego zestawu testowego lub jednego raportu laboratoryjnego przesłanego za pomocą POST /api/v1/documents. Pacjent widzi wtedy tylko wyniki tego raportu.
  • Strona pokazuje wyłącznie wyniki laboratoryjne, tak jak to API. Nie zawiera plików, czatu ani ustawień.

Przykładowa odpowiedź z wynikami