Ana içeriğe atla
Bir evde test kiti siparişi, hastaya eve postalanan, kendi uygulayabileceği bir test kiti gönderir. Aniva kiti kargolar, hasta evde kendi örneğini alır ve postayla geri gönderir. Bu, fiziksel bir test noktasında bir sağlık profesyoneli tarafından yapılan venöz kan alma işlemi olan randevudan farklıdır.
Evde test kiti siparişi uç noktaları home_kit_orders_view (okuma) veya home_kit_orders_manage (yazma) kapsamını gerektirir. Etkinleştir daha dar olan home_kit_orders_activate kapsamını da kabul eder. Sonuçları al ve Sonuçları e-postayla gönder ek olarak results_view gerektirir — laboratuvar sonuçları ve belgeler her zaman bu kapsamla korunur.

Alanlar

string
gerekli
Aniva tarafından otomatik oluşturulan UUID. Siparişi güncellemek, panelini değiştirmek, etkinleştirmek, iptal etmek ve sonuçları almak için bunu kullan.
string
gerekli
Bu evde test kiti siparişinin ait olduğu profilin UUID’si.
string
gerekli
Mevcut yaşam döngüsü durumu. pending, dispatched, activated veya cancelled değerlerinden biri. Aşağıdaki Yaşam döngüsü bölümüne bak. Laboratuvar sonuçlarının tamamlanma ayrıntısı (in_progress veya completed) Sonuçları al yanıtından elde edilir.
object
gerekli
Kitin postalanacağı adres — iki biçimden biri: bilinen bir test noktasına referans veren {location_id} ya da satır içi adres alanları (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email isteğe bağlı — konumlar API’siyle aynı alan adları). Tam olarak birini ver — ya bir konum referansı ya da satır içi adres, ikisi birden değil.
Packstation veya Postfiliale (yalnızca Almanya): street alanını Packstation veya Postfiliale, house_number alanını üç haneli istasyon numarası ve address_line_2 alanını alıcının DHL Postnummer numarası (6–10 hane, boşluk kullanılabilir) olarak ayarla. Postnummer olmadan paket kaydı yapılamaz. Postfach desteklenmez.
string
gerekli
Evde test kiti siparişinin oluşturulduğu zamanın ISO 8601 zaman damgası.
string
En son güncellemenin ISO 8601 zaman damgası. Evde test kiti siparişi hiç güncellenmediyse null.
object
Her evde test kiti siparişi yanıtına gömülü, hastaya ait tam profil nesnesi.
object[]
Evde test kiti siparişine bağlı panel — her zaman tam olarak bir { panel_id, added_at } girdisi bulunur, çünkü bir evde test kiti fiziksel bir kit ürünüyle 1:1 eşleşir. panel_id değerini Panelleri listele ile karşılaştır.
object[]
Evde test kiti siparişine paneli dışında eklenen biyobelirteçler. Her girdi { biomarker_id, added_at } şeklindedir. Her biomarker_id değerini home_kit=true ile Biyobelirteçleri listele üzerinden karşılaştır. Normal bir siparişte bunlar panele ek olarak seçilen tekil testlerdir; bir değişim kitinde ise laboratuvarın yeniden çalıştığı testlerdir.
string
Bu sipariş bir değişim kiti olduğunda yerine geçtiği evde test kiti siparişi. Normal bir siparişte null.
string
Değişimin neden gönderildiği, tek cümleyle. Normal bir siparişte null.
string[]
Tüm laboratuvar sonuçları kesinleştiğinde her birine birer e-posta gönderilen adresler, küçük harfle yazılır. Her zaman bulunur — kapalıyken boştur. Oluştur veya Güncelle sırasında ayarla. Sonuçlar hazır e-postaları bölümüne bak.
object
Aniva tarafından hiçbir zaman yorumlanmadan aynen geri döndürülen kendi anahtar/değer çiftlerin. Okumada her zaman bulunur — hiç ayarlamadıysan {} döner. En fazla 20 anahtar; anahtarlar [A-Za-z0-9_-] ile eşleşir ve en fazla 40 karakterdir; değerler string, sayı veya boolean olur ve string değerler en fazla 500 karakterdir; serileştirilmiş toplam 16.384 bayttır. aniva_ ile başlayan anahtarlar ayrılmıştır. Güncelle işleminde üst veriler birleştirilir: göndermediğin anahtarlar korunur, null olarak gönderilen anahtar silinir ve {} her şeyi temizler. Doğrulama ya hep ya hiç şeklinde çalışır. metadata alanına asla kişisel veya klinik veri koyma — hasta verisi olarak işlenmez.
string
Laboratuvar örnek kodu. Tek kod, üç görev: laboratuvar sonuçlarının altında raporlandığı kod, fiziksel kitin üzerine basılan kod ve hastanın kutudan etkinleştirme kodu olarak okuduğu kod. Kit paketlendiğinde atanır — Aniva bir kiti yeniden kargoladıktan sonraki durum hariç, sipariş pending durumundayken null olur (bkz. Yaşam döngüsü). Her zaman salt okunurdur. Eldeki bir kitin hangi siparişe ait olduğunu GET /api/v1/home-kit-orders?lab_code=… ile bul.
string
Etkinleştir üzerinden bildirilen örnek alma zaman damgası — hastanın örneğini gerçekten aldığı UTC zamanı. Kit etkinleştirilene kadar null. Laboratuvar raporunda yer alan örnek alma zamanı budur.
object[]
Bu siparişe bağlı paketler, en eski bağlantı başta olacak şekilde her biri { id, added_at } biçiminde — hastaya giden kit ve dönüşü takip edilen kitler için laboratuvara geri giden örnek, etiketler basıldığı anda görünür. Aniva bir kiti yeniden kargoladıktan sonraki durum hariç, sipariş pending durumundayken boştur. Tüm paketleri tek bir çağrıda GET /api/v1/shipments?home_kit_order_id={id} ile oku — Gönderiler bölümüne bak.

Yaşam döngüsü

Evde test kiti siparişleri dört yaşam döngüsü durumu sunar:
Aniva kayıp bir kiti yeniden gönderdiğinde sipariş tekrar pending durumuna döner, ancak lab_code kodunu ve shipments içindeki önceki paketlerini korur. Yeni kit aynı kodu taşır. Yeni kutuya kullanılmamış bir iade etiketi konur. Bu iki işlemi yalnızca Aniva yapar; API bunları sunmaz. Her işlem bir home_kit_order.pending veya home_kit_order.cancelled webhook gönderir.
Evde test kiti siparişinin durum yapısı bilinçli olarak geneldir. Hastaya ve hastadan yapılan teslimatların ilerleyişi siparişin gönderileri üzerinden takip edilir — dispatched kitin bir etiketi ve laboratuvar kodu olduğunu gösterir, hareket ettiğini değil; hareket edip etmediğini giden gönderinin status alanı bildirir. Laboratuvar sonuçlarının işlenmesi gönderimler üzerinde yürür. Laboratuvar sonuçlarının tamamlanma durumu (in_progress veya completed) Sonuçları al üzerinden sunulur — en üst düzeydeki status alanı tüm gönderimler kapanana kadar in_progress, ardından completed olur — ya da tüm gönderimler sonuç bildirmeden sonlandıysa fault olur.

Paketleri takip etme

Ne döndüğü kite bağlıdır. Bir kan kiti, Aniva paketledikten sonra iki gönderi olarak gelir: Aniva’dan hastaya giden paket ve hastadan laboratuvara giden paket (destination alanı laboratuvardır), paired_with üzerinden eşleştirilir. İade paketi — takip numarası zaten belli olarak — hasta onu postalayana kadar pending durumunda bekler. Bağırsak mikrobiyomu kiti tek bir gönderi olarak gelir: hastaya giden kit. İade zarfı ön ödemelidir ve takipsizdir, bu yüzden dönüş yolu için bir gönderi oluşturulmaz. booked_by etiketi kimin oluşturduğunu gösterir: "aniva" veya "external". Burada yalnızca bir "aniva" paketi değiştirilebilir ve etiket basıldıktan sonra yalnızca notes alanı değiştirilebilir. Her paket, bir postaneye yönlendirme için DHL’nin detail_code değeri dahil olmak üzere kargo şirketinin tüm status_updates bilgilerini taşır. Gönderideki home_kit_orders yalnızca erişim kapsamındaki siparişleri listeler. Bkz. Erişim.
Bir evde test kiti siparişinin içeriği yalnızca pending durumundayken değiştirilebilir. Sipariş dispatched durumuna geçtikten sonra (veya daha sonra — activated/cancelled), panel değişiklikleri ve /biomarkers uç noktaları 409 Conflict döndürür: fiziksel kit seçilen panele göre paketlenir, bu nedenle içeriği hastaya doğru yola çıktığı anda sabitlenir. Zaten kilitlenmiş bir siparişteki testleri gerçekten değiştirmen gerekiyorsa doğrudan Aniva’ya ulaş — bu genellikle hâlâ mümkündür ve kitin içeriğini tutarlı tutmak için değişikliği senin yerine biz yaparız. Kit zaten kullanıldıysa ve sonuçlarını veremediyse bunun yerine bir yedek kit sipariş et.

Evde test kiti siparişlerini listeleme

API anahtarının erişebildiği tüm evde test kiti siparişlerini getir:
Belirli bir profile göre filtrelemek için isteğe bağlı olarak ?profile_id={uuid} parametresini veya eldeki fiziksel bir kiti siparişiyle eşleştirmek için ?lab_code={code} parametresini gönder — etkinleştirme akışının doğal ilk adımı.

Evde test kiti siparişi oluşturma

Bir hasta profili için evde test kiti siparişi iste:
profile_id, bir delivery_address ve tek bir panel_id gönder. Sipariş pending durumunda oluşturulur. Yeniden denemenin ikinci bir kit sipariş etmemesi için isteğe bağlı bir Idempotency-Key üst bilgisi gönder — bkz. Idempotency. Tam olarak bir panel, çünkü bir evde test kiti fiziksel bir kit ürünüyle 1:1 eşleşir — panelin kendisi kittir. Yalnızca Aniva’nın evde test kiti olarak yapılandırdığı paneller sipariş edilebilir; diğer paneller 422 ile reddedilir. Sipariş hemen paketleme kuyruğuna girdiği ve paketleme anında başlayabildiği için oluşturma sırasında zorunludur. Sipariş pending durumundayken Güncelle üzerinden paneli değiştirebilirsin. Sonuçlarını veremeyen bir kit için ikinci bir kit göndermek üzere panel seçmek yerine replaces_home_kit_order_id gönder — bkz. Yedek kitler.

Yedek kitler

Bazen bir kit sonuçlarını veremez: hasta tüpü dolduramamıştır, numune çok az materyalle ulaşmıştır, laboratuvar bir kısmını analiz edememiştir. Bunun için bir yedek sipariş et:
Yedek, ilk kit hiç etkinleştirilmemiş olsa bile yeni bir laboratuvar koduna sahip yeni bir sipariştir: laboratuvarın yeni bir isteme ihtiyacı vardır ve tek bir kod altındaki iki numune birbirinden ayırt edilemez. Her iki sipariş de replaces_home_kit_order_id üzerinden birbirine bağlı olarak okunabilir kalır. Yerine yenisini oluşturduğun siparişe dokunulmaz. Durumunu, laboratuvar kodunu ve altında zaten kayıtlı olan sonuçları korur; böylece ilk kiti yine de postalayan bir hasta, laboratuvarın ondan okuyabildiği her şeyi alır. Panel devralınır. panel_id alanını ekleme; yedek sipariş, yerini aldığı siparişin panelini taşır — hastanın satın aldığı ürün ve kutunun markalaması budur. Farklı bir paneli yalnızca tüm paneli kapsayan bir yedek için gönder; bir panel ile bir belirteç alt kümesinin birlikte gönderilmesi 422 ile reddedilir, çünkü bir alt küme yalnızca seçildiği panel altında anlam taşır. Yedek siparişin paneli sonradan da değiştirilemez. Neyin yeniden çalıştırılacağını sen seçersin. Başarısız olan belirteçlerle biomarker_ids gönder, laboratuvar yalnızca bunları yeniden çalıştırır; böylece kit sadece gereken tüplerle gönderilir. Tüm paneli yeniden çalıştırmak için bu alanı ekleme — hiçbir şey analiz edilmediğinde doğru seçim budur. Bunun için ek bir kapsam gerekmez: hastanın zaten ödemesini yaptığı belirteçleri yeniden çalıştırmak alakart bir seçim değildir. Bu belirteçler sonradan kaldırılamaz, çünkü istemin tamamını oluştururlar.
Belirteçler tek tek değil, panelin grupları halinde yeniden çalıştırılır. Bir gruptaki tek bir belirteci belirtmek o grubun tamamını yeniden çalıştırır, çünkü istenenden fazlasını raporlayan bir laboratuvar siparişi verilemez. Tek bir belirteç için yapılan bir yedek sipariş bu nedenle birden fazla sonuçla dönebilir ve tüp sayısı belirteç listesinin düşündürdüğünden daha fazla olabilir.
Her kit için aynı anda yalnızca bir yedek yolda olabilir — bir yedek pending veya dispatched durumundayken aynı sipariş için ikinci bir oluşturma isteği, mevcut yedeği belirterek 409 döndürür. Sonuçlar, yedeğin kendi lab_code kodu altında ve kendi Sonuçları al uç noktası üzerinden gelir. Hiç ulaşmayan bir paketi yedek siparişle çözmezsin. Bunun yerine Aniva’ya bildir: bu yeni bir sipariş değil, aynı siparişin aynı laboratuvar koduyla yeniden gönderimidir.

Evde test kiti siparişini güncelleme

Teslimat adresini değiştir, paneli değiştir, üst verilerini güncelle veya sonuçlar hazır e-postalarını yenile:
Yalnızca değiştirmek istediğin alanları ekle. panel_id bağlı panelin yerini alır — kit başına tam olarak bir panel olduğundan değiştirme tek anlamlı panel işlemidir; bu nedenle panel ekleme/kaldırma uç noktaları yoktur. Adres ve panel yalnızca pending durumundayken değiştirilebilir; metadata siparişin tüm yaşam döngüsü boyunca yazılabilir kalır. results_ready_emails ise sipariş cancelled durumuna geçene kadar yazılabilir kalır.

Evde test kiti siparişini iptal etme

Artık gerekmeyen bir evde test kiti siparişini iptal et:
Bu işlem evde test kiti siparişinin durumunu cancelled olarak ayarlar. İptal edilen evde test kiti siparişi yanıtta döndürülür. Yalnızca pending durumundaki bir sipariş iptal edilebilir. dispatched durumundan itibaren kit paketlenmiş ve etiketlenmiştir — otomatik bir geri çağırma yoktur — ve çağrı 409 döndürür. Zaten kargoya verilmiş bir kitin durdurulması gerekiyorsa doğrudan Aniva’ya ulaş. Kiti lojistik merkezinden zaten sipariş edilmiş pending durumundaki bir siparişi iptal etmek onu orada da iptal eder ve çağrı yalnızca lojistik merkezi kabul ederse başarılı olur:
  • 409 — sipariş hâlâ pending görünse bile kit zaten paketlenmiş ve etiketlenmiştir, bu yüzden artık geri çağrılamaz.
  • 502 — lojistik merkezi iptali reddetti (hata, onların gerekçesini taşır) veya merkeze ulaşılamadı. Hiçbir şey değişmedi — sipariş hâlâ aktif ve tekrar iptal edilebilir.
Hata döndüren bir iptal işlemi siparişi tam olarak olduğu gibi bırakır; bu nedenle hiçbir kitin gelmeyeceğinin tek onayı 200 yanıtıdır. Zaten cancelled durumunda olan bir siparişi iptal etmek, hangi durumdan iptal edilmiş olursa olsun aynı 200 yanıtını döndürür.

Evde test kiti siparişini etkinleştirme

Hasta numunesini aldığında bunu bildir:
activated_at değerini gönder — hastanın numuneyi gerçekten aldığı an, UTC zaman damgası olarak. Laboratuvar raporunda yer alacak alım zamanı budur, bu yüzden kendi işleme zamanını değil gerçek alım anını gönder. Etkinleştirme son durumdur: sipariş activated durumuna geçer ve artık iptal edilemez veya değiştirilemez. Kan almayı onayla işleminin barkodsuz evde test kiti karşılığı — kitin kodu kit paketlenirken eklenir, bu yüzden bunu bilmene hiç gerek kalmaz. O ana kadar siparişin lab_code koduna sahip olması gerekir; kodu olmayan bir sipariş 409 döndürür. Etkinleştirme aynı zamanda laboratuvar siparişini de oluşturur: kitin paneli laboratuvarda kendi lab_code kodu altında sipariş edilir, böylece geri dönen numune beklenir ve laboratuvar raporladıkça sonuçlar eklenir. Bu işlem yanıttan sonra çalışır ve laboratuvar kaynaklı bir sorun isteğine yansıtılmak yerine Aniva tarafından çözülür.

Tekil biyobelirteçler

Panelin dışında, alakart testler olarak bir evde test kiti siparişine tekil biyobelirteçler ekleyebilirsin. Bu, kitin üzerine özelleştirilmiş bir seçim eklemek istediğinde kullanışlıdır. Eklenen biyobelirteçler, evde test kiti siparişi yanıtında bir individual_biomarkers dizisi olarak (panels ile aynı düzeyde) görünür. Her iki biyobelirteç uç noktası da home_kit_orders_manage kapsamına ek olarak home_kit_orders_individual_biomarker_selection yetki kapsamını gerektirir — evde test kitleri panele göre sipariş edilir, bu yüzden tekil belirteçler iş ortağı bazında etkinleştirilir. Entegrasyonunun buna ihtiyacı varsa Aniva’ya sor. Biyobelirteç ekle (idempotent — zaten bağlı olan biyobelirteçler korunur):
Biyobelirteçleri kaldır (idempotent — ekli olmayan bir ID yok sayılır):
Her iki uç nokta da bir biomarker_ids dizisi alır. Biyobelirteç ID’lerini bulmak için home_kit=true ile Biyobelirteçleri listele uç noktasını kullan. Biyobelirteçler yalnızca kit pending durumundayken değiştirilebilir (bkz. Yaşam döngüsü).

Laboratuvar sonuçlarını alma

Laboratuvar geri gönderilen örneği işledikten sonra klinik ve genetik sonuçları al:
Yanıt, gelen sonuçların yanı sıra planlanan testleri de (planned durumunda) içerir; böylece hâlâ bekleyenleri takip edebilirsin. Sonuçlar siparişin lab_code değeri altında toplanır ve laboratuvar analiz ettikçe belirteç belirteç gelir; bu yüzden kısmi yanıtlar normaldir. Üst düzey status alanı nihai rapora kadar in_progress, ardından completed olur (veya tüm laboratuvar siparişleri raporlanmadan sonlanırsa fault) — evde test kiti siparişinin laboratuvar işlemlerinin bitip bitmediğini anlamak için bunu kullan. Bir home_kit_order.results.completed webhook bildirimi bunun ne zaman gerçekleştiğini sana iletir, böylece sürekli sorgulama yapman gerekmez. Laboratuvar raporu PDF’lerine documents dizisinde referans verilir — bunları indirmek için GET /api/v1/documents/{id} kullan.

Örnek evde test kiti siparişi