Endpointy zamówień domowych zestawów testowych wymagają zakresu
home_kit_orders_view (odczyt)
lub home_kit_orders_manage (zapis). Aktywuj akceptuje
również węższy zakres home_kit_orders_activate. Pobierz wyniki
i Wyślij wyniki e-mailem wymagają dodatkowo results_view —
dostęp do wyników laboratoryjnych i dokumentów zawsze jest nim chroniony.Pola
UUID wygenerowany automatycznie przez Aniva. Użyj go, aby zaktualizować zamówienie, zmienić jego
panel, aktywować je, anulować oraz pobrać wyniki.
Bieżący status cyklu życia. Jedna z wartości:
pending, dispatched, activated lub cancelled.
Zobacz Cykl życia poniżej. Szczegółowy stan kompletności wyników laboratoryjnych
(in_progress lub completed) pochodzi z Pobierz wyniki.Adres wysyłki zestawu — jedna z dwóch form:
{location_id} wskazujące na znany punkt badań albo
pola adresu podane bezpośrednio (name, street, city, postal_code, country_code;
opcjonalnie company_name / house_number / address_line_2 / state / phone / email —
takie samo nazewnictwo jak w API lokalizacji). Podaj dokładnie jedną formę — odwołanie do
lokalizacji albo adres podany bezpośrednio, nie obie naraz.Packstation lub Postfiliale (tylko Niemcy): ustaw
street na Packstation lub Postfiliale,
house_number na trzycyfrowy numer punktu, a address_line_2 na numer DHL Postnummer odbiorcy
(6–10 cyfr, dozwolone spacje). Bez numeru Postnummer nie można nadać przesyłki. Skrytka
Postfach nie jest obsługiwana.Znacznik czasu ISO 8601 ostatniej aktualizacji. Null, jeśli zamówienie domowego zestawu testowego nigdy nie było aktualizowane.
Pełny obiekt profilu pacjenta, osadzony w każdej odpowiedzi zamówienia domowego zestawu testowego.
Panel przypisany do zamówienia domowego zestawu testowego — zawsze dokładnie jeden wpis
{ panel_id, added_at }, ponieważ domowy zestaw testowy odpowiada w relacji 1:1 fizycznemu
zestawowi. Sprawdź panel_id w Wyświetl panele.Biomarkery przypisane do zamówienia domowego zestawu testowego poza jego panelem. Każdy wpis ma
postać
{ biomarker_id, added_at }. Sprawdź każde biomarker_id w
Wyświetl biomarkery z home_kit=true. W zwykłym zamówieniu są
to dodatkowe badania wybrane poza panelem, a w przypadku zestawu zastępczego
— badania, które laboratorium powtarza.Zamówienie domowego zestawu testowego, które to zamówienie zastępuje, gdy jest to
zestaw zastępczy.
null w zwykłym zamówieniu.Adresy zapisane małymi literami, z których każdy otrzymuje jeden e-mail, gdy wszystkie wyniki
laboratoryjne są ostateczne. Zawsze obecne — puste, gdy funkcja jest wyłączona. Ustaw je w
Utwórz lub
Zaktualizuj. Zobacz
E-maile o gotowych wynikach.
Twoje własne pary klucz/wartość, zwracane bez zmian i nigdy nieinterpretowane przez Aniva. Zawsze
obecne przy odczycie —
{}, gdy nic nie ustawisz. Maksymalnie 20 kluczy; klucze pasują do
[A-Za-z0-9_-] i mają maksymalnie 40 znaków; wartości to ciąg znaków, liczba lub wartość logiczna,
przy czym ciągi znaków mają maksymalnie 500 znaków; łącznie 16 384 bajty po serializacji. Klucze
zaczynające się od aniva_ są zarezerwowane. W Zaktualizuj
metadane są łączone: pominięte klucze pozostają bez zmian, klucz wysłany jako null zostaje
usunięty, a {} czyści wszystko. Walidacja działa na zasadzie wszystko albo nic. Nigdy nie
umieszczaj danych osobowych ani klinicznych w metadata — to pole nie jest traktowane jak dane
pacjenta.Kod próbki laboratoryjnej. Jeden kod, trzy role: identyfikator, pod którym raportowane są wyniki
laboratoryjne, kod wydrukowany na fizycznym zestawie oraz kod aktywacyjny, który pacjent odczytuje
z pudełka. Przydzielany podczas pakowania zestawu —
null, dopóki zamówienie ma status pending,
z wyjątkiem sytuacji po ponownej wysyłce zestawu przez Aniva (zobacz Cykl życia).
Zawsze tylko do odczytu. Dopasuj fizyczny zestaw do jego zamówienia za pomocą
GET /api/v1/home-kit-orders?lab_code=….Znacznik czasu pobrania zgłoszony przez Aktywuj —
moment faktycznego pobrania próbki przez pacjenta w czasie UTC.
null, dopóki zestaw nie zostanie
aktywowany. Ten czas pobrania widnieje na raporcie laboratoryjnym.Przesyłki powiązane z tym zamówieniem, od najstarszej, każda w formacie
{ id, added_at } —
zestaw w drodze do pacjenta oraz, dla zestawów ze śledzoną przesyłką zwrotną, próbka w drodze
z powrotem do laboratorium; pojawiają się w momencie wydrukowania etykiet. Puste, dopóki
zamówienie ma status pending, z wyjątkiem sytuacji po ponownej wysyłce zestawu przez Aniva.
Pobierz pełne dane przesyłek jednym wywołaniem GET /api/v1/shipments?home_kit_order_id={id} —
zobacz Przesyłki.Cykl życia
Zamówienia domowych zestawów testowych mają cztery stany cyklu życia:
Gdy Aniva ponownie wysyła zagubiony zestaw, zamówienie wraca do statusu
pending, ale zachowuje swój lab_code oraz
wcześniejsze paczki w shipments. Nowy zestaw ma ten sam kod. Do nowego pudełka trafia
nieużyta etykieta zwrotna. Tylko Aniva wykonuje te dwie zmiany; API ich nie udostępnia. Każda z nich wysyła
webhook home_kit_order.pending lub home_kit_order.cancelled.
Statusy zamówienia domowego zestawu testowego są celowo ogólne. Przebieg dostawy do pacjenta i od
niego śledzisz w przesyłkach zamówienia —
dispatched oznacza, że zestaw
ma etykietę i kod laboratoryjny, a nie że już wyruszył; o tym mówi status przesyłki wychodzącej.
Przetwarzanie wyników w laboratorium odbywa się w ramach zgłoszeń. Stan gotowości wyników (in_progress
lub completed) udostępnia Pobierz wyniki — główne pole
status ma wartość in_progress, dopóki wszystkie zgłoszenia nie zostaną zamknięte, a następnie
completed — albo fault, gdy wszystkie zgłoszenia zakończyły się bez raportu.Śledzenie paczek
destination to laboratorium), powiązane przez paired_with. Paczka
zwrotna ma status pending — z już znanym numerem śledzenia — dopóki pacjent jej nie
nada. Zestaw do badania mikrobiomu jelitowego pojawia się jako jedna przesyłka: zestaw do pacjenta. Jego koperta zwrotna jest
opłacona z góry i nie ma śledzenia, więc na drogę powrotną nic nie jest rejestrowane. Pole booked_by mówi, kto zamówił
etykietę: "aniva" lub "external". Zmieniać można tutaj tylko paczkę "aniva", a po wydrukowaniu etykiety wyłącznie jej
notes. Każda paczka zawiera pełną listę status_updates przewoźnika,
w tym detail_code firmy DHL dla przekierowania na pocztę.
Pole home_kit_orders w przesyłce zawiera tylko zamówienia z twojego kontekstu dostępu. Zobacz
Dostęp.
Lista zamówień domowych zestawów testowych
Pobierz wszystkie zamówienia domowych zestawów testowych dostępne dla twojego klucza API:?profile_id={uuid}, aby filtrować po konkretnym profilu, lub ?lab_code={code}, aby
powiązać fizyczny zestaw z jego zamówieniem — to naturalny pierwszy krok procesu aktywacji.
Tworzenie zamówienia domowego zestawu testowego
Złóż zamówienie domowego zestawu testowego dla profilu pacjenta:profile_id, delivery_address oraz pojedyncze panel_id. Zamówienie powstaje ze statusem pending.
Przekaż opcjonalny nagłówek Idempotency-Key, aby ponowienie żądania nie zamówiło drugiego zestawu — zobacz Idempotentność.
Dokładnie jeden panel, ponieważ domowy zestaw testowy odpowiada 1:1 fizycznemu produktowi — panel to zestaw. Zamówić można tylko panele skonfigurowane przez Aniva jako domowe zestawy testowe; każdy inny panel zostanie odrzucony z kodem 422. Jest wymagany przy tworzeniu, ponieważ zamówienie od razu trafia do kolejki pakowania i pakowanie może ruszyć natychmiast. Dopóki zamówienie ma status pending, możesz zmienić panel przez Aktualizuj.
Aby wysłać drugi zestaw w miejsce tego, który nie mógł dostarczyć wyników, przekaż replaces_home_kit_order_id zamiast wybierać panel — zobacz Zestawy zastępcze.
Zestawy zastępcze
Czasem zestaw nie może dostarczyć wyników: pacjent nie zdołał napełnić probówki, w próbce było za mało materiału, laboratorium nie mogło przeanalizować części badania. Zamów dla niego zestaw zastępczy:replaces_home_kit_order_id.
Zastępowane zamówienie pozostaje bez zmian. Zachowuje swój status, kod laboratoryjny oraz wszystkie już zapisane wyniki, więc pacjent, który mimo wszystko wyśle pierwszy zestaw, otrzyma wszystko, co laboratorium zdoła z niego odczytać.
Panel jest dziedziczony. Pomiń panel_id, a zestaw zastępczy przejmie panel z zastępowanego zamówienia — to kupił pacjent i taki branding ma pudełko. Przekaż inny panel tylko przy wymianie całego panelu; podanie panelu razem z podzbiorem markerów zostanie odrzucone z kodem 422, ponieważ podzbiór ma znaczenie tylko w ramach panelu, z którego pochodzi. Panelu zestawu zastępczego nie można też później zmienić.
To ty wybierasz, co powtórzyć. Przekaż biomarker_ids z markerami, które się nie udały, a laboratorium powtórzy tylko je, dzięki czemu zestaw zawiera wyłącznie potrzebne probówki. Pomiń to pole, aby powtórzyć cały panel — to właściwy wybór, gdy nic nie udało się przeanalizować. Nie wymaga to dodatkowego scope’u: powtórzenie markerów, za które pacjent już zapłacił, nie jest wyborem à la carte. Tych markerów nie można później usunąć, ponieważ stanowią całe zlecenie.
Markery są powtarzane w ramach grup panelu, a nie pojedynczo. Wskazanie jednego markera z grupy powtarza
całą tę grupę, ponieważ nie można złożyć zlecenia laboratoryjnego, które raportuje więcej, niż zamówiono.
Zestaw zastępczy dla pojedynczego markera może więc wrócić z więcej niż jednym wynikiem, a
liczba probówek może być większa, niż sugeruje lista markerów.
pending lub dispatched, kolejna próba utworzenia dla tego samego zamówienia zwraca 409 ze wskazaniem istniejącego zestawu. Wyniki spływają pod własnym lab_code zestawu zastępczego, przez jego własny Pobierz wyniki.
Zestaw zastępczy nie służy do obsługi paczki, która nigdy nie dotarła. Zamiast tego daj znać Aniva: to ponowna wysyłka tego samego zamówienia pod tym samym kodem laboratoryjnym, a nie nowe zamówienie.
Aktualizacja zamówienia domowego zestawu testowego
Zmień adres dostawy, zamień panel, zaktualizuj metadane lub zastąp adresy e-mail powiadomień o gotowych wynikach:panel_id zastępuje przypisany panel — przy dokładnie jednym panelu na zestaw podmiana to jedyna sensowna operacja, dlatego nie ma endpointów dodawania i usuwania panelu. Adres i panel można zmieniać tylko w statusie pending; metadata można zapisywać przez cały okres życia zamówienia. results_ready_emails można zapisywać, dopóki zamówienie nie ma statusu cancelled.
Anulowanie zamówienia domowego zestawu testowego
Anuluj zamówienie domowego zestawu testowego, które nie jest już potrzebne:cancelled. Anulowane zamówienie domowego zestawu testowego jest zwracane w odpowiedzi.
Anulować można tylko zamówienie ze statusem pending. Od statusu dispatched zestaw jest już spakowany i oklejony etykietą — nie ma automatycznego cofnięcia — a żądanie zwraca 409. Jeśli trzeba wstrzymać już wysłany zestaw, skontaktuj się bezpośrednio z Aniva.
Anulowanie zamówienia pending, którego zestaw został już zlecony do realizacji w centrum logistycznym, anuluje je także tam, a wywołanie powiedzie się tylko wtedy, gdy centrum logistyczne to zaakceptuje:
409— zestaw został już spakowany i oklejony etykietą, więc nie można go już wycofać, mimo że zamówienie wciąż ma statuspending.502— centrum logistyczne odrzuciło anulowanie (błąd zawiera podany powód) lub było nieosiągalne. Nic się nie zmieniło — zamówienie nadal jest aktywne i można spróbować anulować je ponownie.
200 potwierdza, że żaden zestaw nie zostanie wysłany.
Anulowanie zamówienia, które ma już status cancelled, zwraca to samo 200, niezależnie od tego, z jakiego statusu zostało anulowane.
Aktywacja zamówienia domowego zestawu testowego
Gdy pacjent pobierze próbkę, zgłoś to:activated_at — moment faktycznego pobrania próbki przez pacjenta jako znacznik czasu UTC. Ten czas pobrania znajdzie się na raporcie laboratoryjnym, więc przekaż rzeczywisty moment pobrania, a nie czas przetworzenia żądania. Aktywacja jest operacją końcową: zamówienie przechodzi w status activated i nie można go już anulować ani zmienić. To odpowiednik Potwierdź pobranie krwi dla domowego zestawu testowego, bez kodu kreskowego — kod zestawu jest nanoszony podczas pakowania, więc nigdy nie musisz go znać. Do tego czasu zamówienie musi już mieć lab_code; zamówienie bez niego zwraca 409.
Aktywacja składa także zlecenie laboratoryjne: panel zestawu jest zlecany w laboratorium pod jego lab_code, więc laboratorium oczekuje odesłanej próbki i podpina wyniki w miarę ich raportowania. Dzieje się to po wysłaniu odpowiedzi, a ewentualny problem po stronie laboratorium obsługuje Aniva, więc nie pojawi się on w odpowiedzi na twoje żądanie.
Pojedyncze biomarkery
Do zamówienia domowego zestawu testowego możesz dodać pojedyncze biomarkery jako badania à la carte, poza panelem. Przydaje się to, gdy chcesz dopasować zestaw dodatkowych badań. Dodane biomarkery pojawiają się w odpowiedzi zamówienia domowego zestawu testowego jako tablicaindividual_biomarkers (na tym samym poziomie co panels).
Oba endpointy biomarkerów wymagają zakresu uprawnień home_kit_orders_individual_biomarker_selection oprócz home_kit_orders_manage — domowe zestawy testowe zamawia się według paneli, więc pojedyncze markery są włączane osobno dla każdego partnera. Zapytaj Aniva, jeśli twoja integracja tego potrzebuje.
Dodaj biomarkery (operacja idempotentna — już przypisane biomarkery zostają zachowane):
biomarker_ids. Użyj Pobierz listę biomarkerów z home_kit=true, aby znaleźć ID biomarkerów. Biomarkery można zmieniać tylko wtedy, gdy zestaw ma status pending (zobacz Cykl życia).
Pobieranie wyników laboratoryjnych
Gdy laboratorium przetworzy odesłaną próbkę, pobierz wyniki kliniczne i genetyczne:planned) obok otrzymanych wyników, więc możesz śledzić, co wciąż oczekuje. Wyniki trafiają pod lab_code zamówienia i spływają marker po markerze w miarę ich analizy przez laboratorium, dlatego częściowe odpowiedzi są normalne. Główne pole status ma wartość in_progress do czasu raportu końcowego, a potem completed (lub fault, gdy każde zlecenie laboratoryjne zakończyło się błędem bez raportu) — na tej podstawie sprawdzisz, czy analiza laboratoryjna dla zamówienia domowego zestawu testowego jest zakończona. O tym momencie informuje webhook home_kit_order.results.completed, więc nie musisz odpytywać API. Odniesienia do plików PDF z raportami laboratoryjnymi znajdują się w tablicy documents — użyj GET /api/v1/documents/{id}, aby je pobrać.