> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gönderiler

> Aniva API'sinde lojistik nasıl çalışır: laboratuvara numune gönderileri ve evde test kiti paketleri, takip ve durum bilgisiyle.

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](https://docs.anivahealth.com/tr/api/shipments/get-shipment.md) 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](https://docs.anivahealth.com/tr/api/shipments/update-shipment.md) ve [İptal et](https://docs.anivahealth.com/tr/api/shipments/cancel-shipment.md) 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](https://docs.anivahealth.com/tr/api/shipments/update-shipment.md), [İptal et](https://docs.anivahealth.com/tr/api/shipments/cancel-shipment.md), [Randevuları bağla](https://docs.anivahealth.com/tr/api/shipments/attach-appointments-to-shipment.md) ve [Randevuları ayır](https://docs.anivahealth.com/tr/api/shipments/detach-appointments-from-shipment.md) 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](https://docs.anivahealth.com/tr/api/locations/list-locations.md) 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](https://docs.anivahealth.com/tr/api/appointments/get-appointment.md) /
[Gönderiyi getir](https://docs.anivahealth.com/tr/api/shipments/get-shipment.md)) ç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](https://docs.anivahealth.com/tr/api/shipments/attach-appointments-to-shipment.md) /
[Randevuları gönderiden ayır](https://docs.anivahealth.com/tr/api/shipments/detach-appointments-from-shipment.md) 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:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Durum | Anlamı |
| - | - |
| `pending` | Kurye siparişi oluşturuldu ve teslim alınmayı bekliyor. |
| `in_transit` | Kurye paketi teslim aldı ve paket yolda. |
| `delivered` | Paket teslim edildi. |
| `fault` | Taşıma sırasında bir sorun oluştu veya taşıyıcı paketi göndericiye geri gönderdi. |
| `cancelled` | Gönderi iptal edildi. |

Her durum değişikliği bir `shipment.*` [webhook'u](https://docs.anivahealth.com/tr/concepts/webhooks.md) 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.

| Kural | Ayrıntı |
| - | - |
| **Yalnızca hafta içi** | `pickup_date` pazartesi–cuma günlerinden biri olmalıdır. |
| **Bugün veya gelecek** | `pickup_date` geçmiş bir tarih olamaz. |
| **Aynı gün son saati** | Aynı gün teslim alımlar 16:00 Europe/Berlin sonrasında reddedilir. |
| **Zaman aralığı** | `pickup_time_from` ve `pickup_time_till` 09:00–19:00 arasında olmalıdır. |
| **En az 2 saatlik aralık** | Teslim alma aralığı en az 2 saat olmalıdır. |

## 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](#teslim-alma-programi-kurallari) göre doğrulanır.

> [!WARNING]
>
> 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.

> [!WARNING]
>
> 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](https://docs.anivahealth.com/tr/concepts/idempotency.md).

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:

| Harf | Gönderi |
| - | - |
| `P` | Bu API üzerinden oluşturduğun bir gönderi. |
| `M` | Aniva ekibinin oluşturduğu bir gönderi. |
| `C` | Aniva'nın günlük sevkiyatından bir gönderi. |
| `K` | Ev kiti paketi. |
| `F`, `S` | Aniva'nın kendi stok paketleri. |

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:

```json theme={null}
{
  "name": "Aniva Berlin Mitte",
  "company_name": null,
  "street": "Unter den Linden",
  "house_number": "42",
  "address_line_2": null,
  "postal_code": "10117",
  "city": "Berlin",
  "state": null,
  "country_code": "DE",
  "phone": "+4930987654321",
  "email": "berlin-mitte@anivahealth.com"
}
```

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

```json theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## Ö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:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.