Ana içeriğe atla
Randevu, bir hasta profili için fiziksel bir test konumunda bir sağlık çalışanı tarafından yapılan planlı bir kan alma işlemidir. Hastaya postayla gönderilen kitler randevu değildir — bkz. Evde test kiti siparişleri.

Alanlar

string
gerekli
Aniva tarafından otomatik oluşturulan UUID. Panel eklemek, kan almayı onaylamak ve sonuçları almak için bunu kullan.
string
gerekli
Bu randevunun ait olduğu profilin UUID’si.
string
Kan almanın yapılacağı test konumunun UUID’si. Evde test kitleri randevu değildir — bkz. Evde test kiti siparişleri.
string
ISO 8601 formatında planlanan kan alma tarih ve saati. Her zaman Z son ekiyle bir UTC anı olarak döndürülür (örn. 2026-04-15T08:30:00Z). Oluşturma / güncelleme sırasında değer bir saat dilimi göstergesi içermelidir (Z veya +02:00 gibi açık bir saat farkı) — saat dilimi olmayan tarih-saatler reddedilir. Gelecekte olmalı ve Aniva’nın işlettiği konumlarda en az 12 saat sonrası olmalıdır (minimum bildirim süresi).
string
gerekli
Güncel yaşam döngüsü durumu. pending, confirmed, blood_drawn veya cancelled değerlerinden biri olur. Aşağıdaki Yaşam döngüsü bölümüne bak. Laboratuvar sonucu tamamlanma ayrıntısı (in_progress veya completed) Sonuçları al üzerinden alınır; daha ayrıntılı gönderi ilerlemesi (yolda, teslim edildi vb.), yerleşik shipments dizisindeki her girişi Gönderiyi al üzerinden takip ederek elde edilir.
string
Randevu iptal edildiğinde kaydedilen serbest metin neden (ör. gelmeme, geç iptal, ‘Başarısız. Tekrar gerekli’). status değeri cancelled değilse null olur.
string[]
gerekli
Tüm laboratuvar sonuçları kesinleştiğinde her birine bir e-posta gönderilen, küçük harfe çevrilmiş adresler. Kapalıyken boştur. Bkz. Sonuçlar hazır e-postaları.
string
gerekli
Kan alma yöntemi: capillary (parmak ucundan veya üst koldan, mikrotüplere) ya da venous (damardan, tüplere). Randevuda belirlenen yöntemdir; belirlenmemişse konumun default_draw_method değeridir. Kan almadan sonra kullanılan yöntemdir.
string
gerekli
Randevunun oluşturulduğu zamanın ISO 8601 zaman damgası.
string
En son güncellemenin ISO 8601 zaman damgası. Randevu hiç güncellenmediyse null olur.
string[]
gerekli
Kan almayı onayla adımında kaydedilen, tarama sırasına göre laboratuvar kodları (tüp barkodları). Kan alma onaylanana kadar boştur. Venöz kan almada her tüpün üzerine basılı tek bir kod bulunur; kapiler kan almada her mikrotüpte ayrı bir kod bulunur. Sonuçlar ve belgeler bunlara lab_code üzerinden referans verir.
object[]
gerekli
{ panel_id, added_at } girişleri halinde bu randevuya eklenen paneller. Bkz. Panel ekleme.
object[]
gerekli
{ biomarker_id, added_at } girişleri halinde bu randevuya eklenen tekli biyobelirteçler. Bkz. Tekli biyobelirteçler.
object[]
gerekli
En eski bağlantı ilk sırada olacak şekilde, { id, added_at } girişleri halinde bu randevuya bağlı gönderiler. Bkz. Gönderi bağlama.
object
gerekli
Her randevu yanıtına gömülü olarak gelen hastanın tam profil nesnesi. Aşağıdaki alanlar bir alt kümedir. Randevuyu al tümünü listeler.

Yaşam döngüsü

Randevuların dört yaşam döngüsü durumu vardır:
Randevu durumu bilinçli olarak genel tutulmuştur — daha ayrıntılı ilerleme bilgisi özel uç noktalar üzerinden sunulur:
  • Laboratuvar sonucu tamamlanma durumu → Sonuçları al — üst düzey status alanı in_progress veya completed olur.
  • Gönderi ilerlemesi (yolda, teslim edildi vb.) → randevudaki yerleşik shipments dizisindeki her girişi Gönderiyi al üzerinden takip et — her gönderinin kendi status alanı ve status_updates olay günlüğü bulunur.
Her durum değişikliği bir appointment.* webhook gönderir; örneğin appointment.confirmed. Yeni bir saat veya konum ise appointment.rescheduled gönderir.
Bir randevuyu onaylamak (blood_drawn durumuna geçirmek) geri alınamaz. Laboratuvar kodunu/kodlarını gönderdiğinde laboratuvar sipariş süreci tetiklenir ve geri alınamaz. Güncelleme ve iptal işlemlerine yalnızca randevu pending veya confirmed durumundayken izin verilir.

Randevuları listeleme

API anahtarının erişebildiği tüm randevuları al:
Belirli bir profile göre filtrelemek için isteğe bağlı olarak ?profile_id={uuid} parametresini gönder. Bu parametre olmadan varsayılan zaman aralığı (son 2 aydan gelecek 1 aya kadar) uygulanır.

Randevu güncelleme

Kan alma onaylanmadan önce randevuyu yeniden planlayabilir veya test konumunu değiştirebilirsin:
Güncellemek için scheduled_at, location_id, draw_method ve results_ready_emails alanlarının herhangi bir kombinasyonunu gönder. Yalnızca değiştirmek istediğin alanları ekle.

Kan alma yöntemi

Her randevunun bir draw_method değeri vardır: capillary (parmak ucundan veya üst koldan, mikrotüplere) veya venous (damardan, tüplere). Bu yalnızca kan alma için geçerlidir. İdrar, sürüntü ve kan dışındaki diğer numuneler her iki yöntemde de aynı şekilde alınır. Varsayılan olarak konumun default_draw_method değeridir. Başka bir yöntem kullanmak için oluşturma veya güncelleme sırasında draw_method alanını ayarla ya da konumun varsayılanına dönmek için null olarak belirle. Konum bu yöntemi draw_methods listesinde belirtmeli ve planlanan testler bu yöntemle yapılabilmelidir; aksi halde istek 400 döndürür. Kan alma işleminden sonra bunu değiştiremezsin. Kan alma işleminden sonra draw_method, kullanılan yöntemi gösterir.

Profil, konum ve saat başına bir randevu

Bir profilde her (location_id, scheduled_at) çifti için iptal edilmemiş en fazla bir randevu bulunabilir — konumun kaç paralel randevu kabul ettiğinden bağımsız olarak, aynı kişiden aynı yerde ve aynı anda iki kez kan alınamaz. Hem Randevu oluştur hem de Randevuyu güncelle bunu uygular ve hâlihazırda var olan randevuyu gösteren bir appointment_id ile 409 döndürür. Bu yanıtı yeniden denenecek bir hata yerine randevunun zaten alınmış olduğu şeklinde değerlendir: belirttiği randevuyu getir, yeniden planla veya iptal et. Pratikte bu, tekrarlanan oluşturma isteklerinin güvenli olmasını sağlar. Ağ zaman aşımından sonra yeniden gönderdiğin ya da bir kullanıcının iki kez tetiklediği bir oluşturma isteği iki yerine tek bir randevuya dönüşür — yani aynı hasta için yinelenen randevuları sonradan düzeltmen gerekmez.
Güncellemeler yalnızca kan almadan önce — yani randevu pending veya confirmed durumundayken — yapılabilir. Randevu blood_drawn durumuna geçtikten veya cancelled olduktan sonra değiştirilemez. Tek istisna results_ready_emails: kan almadan sonra bunu tek başına değiştirmeye devam edebilirsin.

Randevu iptal etme

Artık gerek olmayan bir randevuyu iptal et:
Bu işlem randevu durumunu cancelled olarak ayarlar. İptal edilen randevu yanıtta döner. Nedeni kaydetmek için gövdede isteğe bağlı olarak cancellation_reason (en fazla 500 karakter) gönderebilirsin. Bu alan randevuda saklanır ve sonraki okumalarda cancellation_reason olarak döner.
İptal işlemi yalnızca kan almadan önce — yani randevu pending veya confirmed durumundayken — yapılabilir. Zaten blood_drawn durumuna geçmiş randevular iptal edilemez.

Panel ekleme

Kan almayı onaylamadan önce, yaptırmak istediğin kan tahlili panellerini şu çağrıyla ekle:
panel_ids alanında panel UUID’lerinden oluşan bir dizi gönder. Panel kimlikleri, iş ortağı hesabın için Aniva tarafından sağlanır.
Paneller kan almadan önce — yani randevu pending veya confirmed durumundayken — eklenmelidir. Randevu blood_drawn durumuna geçtikten sonra panel ekleyemez veya değiştiremezsin.

Panel kaldırma

Kan almadan önce panelleri kaldırman gerekirse şu çağrıyı yap:
panel_ids alanında panel UUID’lerinden oluşan bir dizi gönder. Kaldırma işlemi idempotenttir: bağlı olmayan bir panel yok sayılır.
Panel eklemede olduğu gibi kaldırma da yalnızca kan almadan önce — yani randevu pending veya confirmed durumundayken — yapılabilir. Randevu blood_drawn durumuna geçtikten sonra paneller kaldırılamaz.

Tekil biyobelirteçler

Hazır bir panelin dışında, tekil biyobelirteçleri ayrı testler olarak bir randevuya bağlayabilirsin. Bu, bir uygulayıcının önceden tanımlanmış bir paket yerine özel bir seçim yapmak istediği durumlarda işe yarar. Bağlanan biyobelirteçler, randevu yanıtında individual_biomarkers dizisi olarak (panels ile aynı düzeyde) görünür. Yönlendirme kararları, her biyobelirtecin laboratuvar bazlı eşleştirmelerine göre sipariş-lojistik akışı tarafından daha sonraki aşamada verilir. Biyobelirteç ekle (idempotent — zaten bağlı olan biyobelirteçler korunur):
Biyobelirteç kaldır (idempotent — bağlı olmayan biyobelirteçler yok sayılır):
Her iki uç nokta da bir biomarker_ids dizisi alır ve ortaya çıkan kümeyi her laboratuvarın kapalılık kurallarına göre doğrular — düzgün verilemeyen bir sipariş (ör. CRP ve HDL olmadan bir CRP/HDL oranı) eklemen gereken biyobelirteçlerle birlikte 400 döner ve hiçbir şeyi kaydetmez. Biyobelirteç kimliklerini bulmak için Biyobelirteçleri listele uç noktasını kullan.
Panel değişikliklerinde olduğu gibi tekil biyobelirteçler de yalnızca kan almadan önce — yani randevu pending veya confirmed durumundayken — eklenebilir veya kaldırılabilir. Randevu blood_drawn durumuna geçtikten sonra bu özel anlık görüntü dondurulur.

Kap gereksinimlerini önizleme

Panel veya tekil biyobelirteç ekledikten sonra, numune alımı için gerekecek fiziksel numune toplama kaplarını önizle:
Yanıttaki containers dizisi, gereken her kap için tür, ad, kapak rengi, hacim, üretici ürün numarası ve adet bilgilerini içerir. Bu, uygulayıcıların kan almadan önce doğru malzemeleri hazırlamasına yardımcı olur. Yanıt ayrıca bir pricing nesnesi taşır — bu, randevunun tüm sepet faturasıdır (devreye giren kalemler, bağlı paneller ve sunulan her biyobelirteç için senin fiyat listen üzerinden fiyatlandırılmış ve yanında perakende fiyatının yer aldığı birer satır; bkz. Fiyatlandırma); randevuda bağlı testler varsa ve anahtarın prices_view kapsamına sahipse doldurulur, aksi halde null olur. routing kasıtlı olarak hiçbir zaman paylaşılmaz ve her zaman null olur.
Önizleme, o anda bağlı olan panelleri ve biyobelirteçleri yansıtır. Önizlemeden sonra panel ekler veya kaldırırsan, güncel kap gereksinimlerini almak için önizleme uç noktasını yeniden çağır.

Kan almayı onaylama

Kan alındıktan sonra, laboratuvar sipariş akışını tetiklemek için laboratuvar kodlarını (tüp barkodlarını) gönder:
Her tüpün üzerinde tek bir kod basılıysa (venöz kan alma) lab_code gönder; her panel kendi koduyla kendi tüplerine alınıyorsa (kapiler kan alma) her kod için — kapsadığı panel_ids ile birlikte — birer kayıt içeren lab_codes gönder. Bu durumda her panel, kendi kodu altında ayrı bir laboratuvar istemi olur. Kodlar, randevu üzerinde lab_codes olarak döner. Kapiler kan almada alınan kan mikro tüplere doldurulur. Önce rezervasyon sırasına göre paneller yerleştirilir. Ardından tekil biyobelirteçler panel mikro tüplerindeki boş alanı doldurur. Daha fazla alana ihtiyaç duyduklarında yeni mikro tüpler açılır. Bunları eşit olarak dağıtırız. Her mikro tüp en fazla 150 µl tekil biyobelirteç alır. Panel veya biyobelirteç değiştiren çağrılar, ortaya çıkan küme bu kuralı bozduğunda 400 yanıtı verir. Bu işlem randevu durumunu blood_drawn olarak günceller ve laboratuvar sürecini başlatır. Bu işlem geri alınamaz.

Gönderi teslim alma

POST /api/v1/appointments/pickup, shipment_picked_up randevu durumuyla birlikte kaldırıldı. Yol artık kimliğe göre randevu rotasına düştüğü için 405 Method Not Allowed yanıtı veriyor. Uç nokta son döneminde çağrıyı kabul edip hiçbir şey yapmayan boş bir işlem olarak çalışıyordu; bu nedenle kaldırılması güvendiğin hiçbir davranışı değiştirmez.
Kan alma sonrası ilerlemeyi takip etmek için randevunun içinde yer alan shipments dizisindeki her kaydı Gönderiyi al uç noktasından izle — her gönderi kendi status değerini ve bir status_updates geçmişini taşır.

Gönderileri bağlama

Bir randevu bir veya daha fazla gönderiye bağlanabilir (ve tersi de geçerlidir — ilişki çoka çoktur). Mevcut bağlantı kümesi her iki tarafta da doğrudan görünür:
  • randevuda, { id, added_at } kayıtlarından oluşan bir shipments dizisi olarak;
  • gönderide, { id, added_at } kayıtlarından oluşan bir appointments dizisi olarak.
Her iki dizi de en eski bağlantıdan başlayarak sıralanır. Her id, tam veri yükü için ilgili ana ayrıntı uç noktasına (Gönderiyi al / Randevuyu al) çapraz referans verir. Gönderiler oluşturulurken Gönderi oluştur uç noktasındaki appointment_id alanı üzerinden bağlanır. Oluşturma sonrasında bağlantıları gönderi üzerinden Gönderiye randevu bağla ve Gönderiden randevu ayır ile yönet; her biri o gönderi için değişiklik sonrası randevu listesini döner. Bir randevunun paketlerini eksiksiz okumak için Gönderileri listele uç noktasını ?appointment_id= ile kullan. Değişiklik kuralı: bağlantılar şu koşullardan HERHANGİ BİRİ geçerliyken oluşturulabilir veya kaldırılabilir
  • randevu kan alma aşamasını geçmişse (blood_drawn) veya
  • gönderi 24 saatten daha kısa süre önce oluşturulmuşsa.
Bu aralığın dışında bağlantı kilitlenir; böylece geçmiş kayıtlar sabit kalır.

Laboratuvar sonuçlarını alma

Laboratuvar kan örneklerini işledikten sonra klinik ve genetik sonuçları al:
Yanıt, alınan sonuçların yanı sıra planlanan testleri (planned durumunda) de içerir; böylece nelerin hâlâ beklediğini takip edebilirsin. Üst düzey status alanı, her gönderim kapanana kadar in_progress, ardından completed (hiçbiri raporlanmadıysa fault) olur — randevunun laboratuvar işlemlerinin bitip bitmediğini anlamak için bunu kullan. Bir appointment.results.completed webhook’u bunun ne zaman gerçekleştiğini sana bildirir, böylece sürekli sorgulama yapman gerekmez. submissions dizisi bunu her biri kendi lab_code değerine sahip laboratuvar istemi bazında ayrıştırır. Alınan her sonuç ve belge, altında kaydedildiği lab_code değerini taşır. Laboratuvar raporu PDF’lerine documents dizisinde referans verilir — bunları GET /api/v1/documents/{id} ile indir.

Örnek randevu