Ana içeriğe atla
Bir gönderi tek bir fiziksel pakettir: kan örneklerini bir test konumundan laboratuvara taşıyan kurye alımı, evde test kiti hastasına giden kit veya o hastanın geri postaladığı örnek. Shipments API, gönderi siparişleri oluşturmanı, takip etmeni, değiştirmeni ve iptal etmeni sağlar; kim rezerve etmiş olursa olsun her paketi tek bir yerde listeler.

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ği destination alanından okunur.
  • booked_by — etiketi kimin bastırdığı: aniva veya external. Yalnızca aniva gönderileri Güncelle ve İptal et işlemlerini kabul eder; external bir paket aynı listede takip edilir ancak her iki işlemde de 501 döndürür.
İade etiketi taşıyan paket ile o etiketin geri getirdiği paket, 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.
  • appointments ve home_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ı 403 dö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österen synced_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 bir appointments dizisi olarak;
  • randevuda, { id, added_at } öğelerinden oluşan bir shipments dizisi olarak.
Her iki dizi de en eski bağlantı ilk sırada olacak şekilde sıralanır. Her 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.
Kurye paketi teslim aldıktan sonra gönderiler değiştirilemez. in_transit, delivered veya fault durumundaki bir gönderiyi güncelleme denemeleri 409 Conflict döndürü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.
Gönderiler teslim alındıktan sonra iptal edilemez. Zaten in_transit, delivered veya fault durumunda olan bir gönderiyi iptal etme denemeleri 409 Conflict döndürür. Zaten cancelled durumunda olan bir gönderiyi iptal etmek herhangi bir değişiklik yapmaz ve gönderiyle birlikte 200 döndürür — bkz. Idempotency.
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 etmek 409 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ındaki origin ve destination alanları, aşağıdaki yapıya sahip çözümlenmiş adres nesneleri içerir:
Bir muayenehane paketi için 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ındaki pickup 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 bir status_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ığında null olur (etiket oluşturma, taşıyıcının bilgi yok taraması, alan mevcut olmadan önce kaydedilen girişler). Asla cancelled olmaz — iptal bize aittir, bir taşıyıcı olayı değildir.
  • code — taşıyıcının kendi durum kodu (GO!‘nun GO10, GO90, GOY001 kodları; DHL’nin VA, ZF, LA, ZU kodları). Taşıyıcı kod sağlamadığında null olur. status alanının dil çevirileri arasında sabit kalır.
  • detail_code — taşıyıcının varsa daha ayrıntılı kodu: DHL’nin statusDetailed değeri, örneğin CNRFC_NRQRD_ZF (bir postaneye yönlendirildi), HLDCC_SERPT_LA (oradan teslim alınmaya hazır), DLVRD_SERPT_ZU (teslim alındı). Diğer durumlarda null olur.
  • 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 yoksa null olur.
  • 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).
Taşıyıcı paketi göndericiye geri gönderdiğinde zaman çizelgesine 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:
Dönüş ayağı satırı, iade etiketi yazdırıldığı andan itibaren mevcuttur ve hasta numuneyi postaya verene kadar pending durumunda kalır — bu gerçek durumdur, bir eksiklik değildir.