Tek liste, filtrelenmiş
GET /api/v1/shipments tek koleksiyondur. Bir gönderi tek başına durur — randevularla çoka-çok ilişkilidir ve bir evde test kiti siparişine ait olabilir — bu yüzden bir üst öğenin altında iç içe bir liste yoktur. Aynı listeyi ?appointment_id= veya ?home_kit_order_id= ile daralt, limit / offset ile sayfala ve elinde tek bir ID olduğunda üst öğenin satır içi shipments dizisini (hem randevularda hem evde test kiti siparişlerinde { id, added_at }) izleyerek Gönderiyi getir uç noktasına git.
İçerik ve kimin rezerve ettiği
Her gönderi, adreslerinden görünmeyen iki bilgi taşır:contents— paketin içinde ne olduğunu açıklayan serbest metin; oluşturulma sırasında ayarlanır ("Medizinisch freigestellte Probe","Home test kit") ve kuryeye gösterilir. Yalnızca bilgi amaçlıdır. Yön ayrı bir alan değildir: bir paketin laboratuvara gidip gitmediğidestinationalanından okunur.booked_by— etiketi kimin bastırdığı:anivaveyaexternal. Yalnızcaanivagönderileri Güncelle ve İptal et işlemlerini kabul eder;externalbir paket aynı listede takip edilir ancak her iki işlemde de501döndürür.
paired_with üzerinden birbirini işaret eder.
Erişim
- Bağlı en az bir randevu veya evde test kiti siparişi senin erişim bağlamında olduğunda ya da paket senin erişim bağlamındaki bir konumdan ayrıldığında o paketi okuyabilirsin.
appointmentsvehome_kit_orders, yalnızca senin erişim bağlamındaki randevuları ve siparişleri listeler.- Güncelle, İptal et, Randevuları bağla ve Randevuları ayır işlemleri, bağlı her evde test kiti siparişinin senin erişim bağlamında olmasını gerektirir. Aksi halde çağrı
403döndürür ve paketi yalnızca Aniva değiştirebilir.
Okumalar asla taşıyıcıyı çağırmaz
Her okuma veritabanımızdan sunulur. Bir arka plan eşitlemesi, her gönderiyi taşıyıcısıyla uzlaştırır (GO! için 10 dakikada bir, DHL için saatte bir) ve herhangi bir yanıtın ne kadar eski olduğunu gösterensynced_at değerini işler. Zorla yenileme yoktur — DHL her beş saniyede bir takip çağrısına izin verir, bu yüzden taşıyıcıya gidiş-dönüş yapan bir okuma sunulamaz.
Gönderi oluşturma
Bir gönderi oluştururken çıkışlocation_id değerini — kuryenin teslim alacağı test konumunu — belirtirsin. Hedef laboratuvarı da destination_lab ile belirtirsin. Gönderi o laboratuvarın kayıtlı gönderim adresine gider.
Konum, API anahtarının erişim bağlamında olmalıdır. Kullanılabilir konum ID’lerini bulmak için Konumları listele uç noktasını kullan.
Gönderiyi oluşturma sırasında belirli bir randevuya bağlamak için isteğe bağlı olarak appointment_id
iletebilirsin. Bağlantı her iki tarafta satır içi olarak görünür:
- gönderide,
{ id, added_at }öğelerinden oluşan birappointmentsdizisi olarak; - randevuda,
{ id, added_at }öğelerinden oluşan birshipmentsdizisi olarak.
id, tam veri yükü için
temel ayrıntı uç noktasına (Randevuyu getir /
Gönderiyi getir) çapraz referans verir — randevu bazında
kurye ilerlemesini görmek isteyen iş ortakları, randevunun shipments dizisindeki her öğeyi
gönderi ayrıntı uç noktasına kadar izler.
Bir gönderi birden fazla randevuya, bir randevu da birden fazla gönderiye bağlanabilir.
Oluşturma sonrasında bağlantıyı Randevuları gönderiye
bağla /
Randevuları gönderiden ayır ile yönet. Her
değişiklik işlemi, gönderinin değişiklik sonrası randevu listesini döndürür.
Değişiklik kuralı şudur: bağlantılar YA randevuda kan alma aşaması geçildiyse (blood_drawn) YA DA
gönderi 24 saatten daha kısa bir süre önce oluşturulduysa oluşturulabilir veya kaldırılabilir. Bu
pencerenin dışında, geçmiş kayıtların sabit kalması için bağlantı kilitlenir.
Yaşam döngüsü
Gönderiler aşağıdaki durumlardan geçer:
Her durum değişikliği bir
shipment.* webhook’u gönderir, örneğin
shipment.delivered. shipment.updated, yeni bir tarama gibi okuyabileceğin her değişiklikte tetiklenir.
Teslim alma programı kuralları
Bir gönderinin teslim alma programını oluştururken veya güncellerken aşağıdaki kurallar geçerlidir.pickup_date
(YYYY-MM-DD) ve pickup_time_from / pickup_time_till (HH:MM, 24 saat) yerel saat değerleridir ve
çıkış konumunun IANA saat diliminde yorumlanır — bunlarla birlikte bir saat dilimi göndermezsin.
Gönderileri değiştirme
PATCH /api/v1/shipments/{id} kullanarak bir gönderinin teslim alma programını, paket sayısını, ağırlığını ve notlarını güncelleyebilirsin. Lojistikle ilgili alanlardan herhangi biri değişirse (teslim alma tarihi, saati, paket sayısı veya ağırlık), mevcut lojistik siparişi otomatik olarak iptal edilir ve yenisi oluşturulur. Güncelleme gövdesine eklemediğin alanlar mevcut gönderideki haliyle korunur — örneğin yalnızca weight alanını güncellemek siparişi aynı teslim alma programıyla yeniden oluşturur. Güncellenen program alanları aynı teslim alma programı kurallarına göre doğrulanır.
Lojistik sağlayıcı güncelleme sırasında iptali veya yeniden oluşturmayı reddederse API, sağlayıcının hata mesajıyla birlikte 502 Bad Gateway döndürür.
Gönderileri iptal etme
DELETE /api/v1/shipments/{id} kullanarak bir gönderiyi iptal et. Bu işlem siparişi iptal etmek için lojistik sağlayıcının API’sini çağırır ve durumu cancelled olarak günceller.
Lojistik sağlayıcı, kendi nedenleriyle de iptali reddedebilir (örneğin iptal son saati geçmiş olabilir). Bu durumda API, sağlayıcının hata mesajı ve hata koduyla birlikte 502 Bad Gateway döndürür.
İade etiketleri
DHL iade etiketi, ilgili giden siparişin bir parçasıdır. DHL etiketi tek başına iptal edemez; bu nedenle bir iade etiketini izleyen satırı iptal etmek409 Conflict döndürür. Bunun yerine, pending durumundayken giden paketi iptal et. Bu işlem etiketi de birlikte iptal eder: giden paketin pending durumundaki her dönüş ayağı satırı cancelled olur ve status_updates alanında bir RETURN_LEG_CANCELLED kaydı alır. Hastanın zaten postaya verdiği bir iade paketi yoluna devam eder. Giden paket yola çıktıktan sonra etiket geçerliliğini korur ve Aniva dönüş ayağı satırını manuel olarak kapatır.
Gönderi referans ID’leri
Her gönderinin 11 karakterlik bir referans ID’si var: bir harf, tarih ve dört karakter,{letter}YYMMDDXXXX (örneğin P2611194821). Harf, gönderinin neye ait olduğunu gösterir, asla yönünü değil:
20 ile 22 Kasım 2026 arasındaki bir gönderi, başında bir kelime olan ID’sini korur:
API, MAN, AUTO veya KIT (örneğin AUTO261121UWKX). Her iki biçim de geçerli kalır. Bir ID’nin uzunluğunu veya ilk harfini kontrol etme. Gönderiyi getirmek, güncellemek veya iptal etmek için ID’yi kullan.
Gönderi adresleri
Gönderi yanıtındakiorigin ve destination alanları, aşağıdaki yapıya sahip çözümlenmiş adres nesneleri içerir:
origin adresi oluşturma sırasında belirttiğin test konumundan
çözümlenir ve destination, destination_lab alanında belirttiğin laboratuvardır.
Bir ev kiti paketi için hastanın teslimat adresi kitin destination adresi ve
numune dönüşünün origin adresidir; kiti paketleyen tesis ise kitin origin adresidir.
Adres location_id taşımaz — bir muayenehane paketini bağlı olduğu randevu üzerinden
eşleştir.
Teslim alma aralığı
Gönderi yanıtındakipickup alanı planlanan kurye teslim alma aralığını içerir. UTC anları olarak
from ve till zaman damgalarını (Z son ekli ISO 8601, örneğin 2026-04-15T07:00:00Z) ve bir
timezone dizesini (teslim alma konumunun IANA saat dilimi) kapsar. Oluşturma / güncelleme
sırasında gönderdiğin yerel saat pickup_date / pickup_time_* değerleri bu saat dilimi
kullanılarak bu mutlak anlara çözümlenir — from / till değerlerini tekrar teslim alma konumunun
yerel saatinde göstermek için timezone alanını kullan. Planlanmış bir teslim alma aralığı
yoksa bu alan null olur.
Durum güncellemeleri günlüğü
Her gönderi birstatus_updates dizisi taşır — lojistik sağlayıcının bildirdiği her yaşam döngüsü
olayı, en eskisi ilk sırada. Her kayıt şunları içerir:
state— gönderi durumu sözlüğündeki olay (pending,in_transit,delivered,fault); böylece taşıyıcının kodlarını bilmeden bir zaman çizelgesini okuyabilirsin. Olay herhangi bir durum taşımadığındanullolur (etiket oluşturma, taşıyıcının bilgi yok taraması, alan mevcut olmadan önce kaydedilen girişler). Aslacancelledolmaz — iptal bize aittir, bir taşıyıcı olayı değildir.code— taşıyıcının kendi durum kodu (GO!‘nunGO10,GO90,GOY001kodları; DHL’ninVA,ZF,LA,ZUkodları). Taşıyıcı kod sağlamadığındanullolur.statusalanının dil çevirileri arasında sabit kalır.detail_code— taşıyıcının varsa daha ayrıntılı kodu: DHL’ninstatusDetaileddeğeri, örneğinCNRFC_NRQRD_ZF(bir postaneye yönlendirildi),HLDCC_SERPT_LA(oradan teslim alınmaya hazır),DLVRD_SERPT_ZU(teslim alındı). Diğer durumlardanullolur.status— taşıyıcının insan tarafından okunabilir etiketi (örneğin"Shipment picked up","Die Sendung wurde abgeholt.").description— kodun açıklaması veya taşıyıcının daha uzun cümlesi. İkisi de yoksanullolur.location— taramanın gerçekleştiği yer, taşıyıcının adlandırdığı şekliyle: bir GO! deposu, bir DHL şehri. Serbest metindir, koordinat değildir.time— taşıyıcının bildirdiği şekliyle olayın ISO 8601 zaman damgası (saat dilimi farkıyla birlikte).
code değeri
RETURNED_TO_SENDER olan bir kayıt eklenir. Bu kaydın status alanı taşıyıcının gerekçesini
tutar. Gönderi bundan sonra, taşıyıcı paketi bize geri teslim ettikten sonra da fault durumunda
kalır.
Taşıyıcı henüz herhangi bir olay bildirmediyse liste boş olabilir.
Esas güncel durum için en üst düzeydeki status alanını kullan. Tek yönlü ilerler — pending,
in_transit ve delivered — en yeni olay bir sorun bildirdiği sürece fault bunun yerini alır;
taşıyıcılar olaylarını önem sırasına göre sıralamaz (DHL, teslim taramasından sonra pre-transit
kodlu bir yönlendirme bildirimi ekler), bu nedenle en yeni kayıt tek başına bir paketin hangi
aşamada olduğunu göstermez.
Örnek gönderi
Örnek ev kiti paketleri
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…, hastaya giden kiti ve geri dönen numuneyi eşleştirilmiş olarak döndürür:
pending durumunda kalır — bu gerçek durumdur, bir eksiklik değildir.