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
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.
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.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.En son güncellemenin ISO 8601 zaman damgası. Evde test kiti siparişi hiç güncellenmediyse null.
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.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.Bu sipariş bir değişim kiti olduğunda yerine geçtiği evde test kiti
siparişi. Normal bir siparişte
null.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.
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.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.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.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
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.
Evde test kiti siparişlerini listeleme
API anahtarının erişebildiği tüm evde test kiti siparişlerini getir:?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: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.
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: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: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âpendinggö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.
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 birindividual_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):
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: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.