> ## 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önderileri listele

> Randevu, ev kiti siparişi veya duruma göre filtrelenmiş gönderileri getir

API anahtarının erişebildiği gönderileri en yeniden başlayarak getir. Her paket bu tek listede
yer alır: bir muayenehaneden kurye alımı, evde test kiti hastasına giden kit ve geri dönen
numune. `appointment_id` veya `home_kit_order_id` ile tek bir üst kayda göre filtrele.

`shipments_view` veya `shipments_manage` kapsamını gerektirir.

Yanıt veritabanımızdan gelir ve hiçbir zaman taşıyıcıyı çağırmaz. Arka plan senkronizasyonu her
gönderiyi yeniler (GO! için 10 dakikada bir, DHL için saatte bir) ve her satırdaki `synced_at`
alanı taşıyıcıya en son ne zaman sorulduğunu gösterir.

## İstek

### Sorgu parametreleri

**appointment\_id** `string`

Yalnızca bu randevuya (UUID) bağlı gönderiler. Randevu mevcut değilse `404`, erişim bağlamının
dışındaysa `403`.

**home\_kit\_order\_id** `string`

Yalnızca bu evde test kiti siparişine (UUID) bağlı gönderiler. Normalde iki satır döner — hastaya
giden kit ve laboratuvara geri dönen numune (`destination` alanı laboratuvardır).
`appointment_id` ile aynı `404` / `403` kuralları geçerlidir.

**status** `string`

Yalnızca bu durumdaki gönderiler. `pending`, `in_transit`, `delivered`, `fault`, `cancelled`
değerlerinden biri.

**limit** `integer`

Döndürülecek maksimum gönderi sayısı. Varsayılan 100, en fazla 500.

**offset** `integer`

Atlanacak gönderi sayısı. Varsayılan 0. Sıralama kararlıdır (önce `created_at` azalan, sonra
referans), bu nedenle sayfalar çakışmaz.

## Yanıt

Başarılı olduğunda API, gönderi nesnelerinden oluşan bir diziyle `200 OK` döndürür.

**id** `string` *required*

Gönderi referans tanımlayıcısı.

**status** `string` *required*

Gönderi yaşam döngüsü durumu. `pending`, `in_transit`, `delivered`, `fault` veya `cancelled` değerlerinden biri.

**logistics\_provider** `string` *required*

Lojistik sağlayıcı. `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` veya `dhl_express` değerlerinden biri. Ev kiti paketi `dhl_parcel` veya yurt dışına Warenpost International olarak
gittiğinde `dhl_warenpost` olur.

**tracking\_number** `string`

Lojistik sağlayıcıdan alınan harici takip numarası. `null` olabilir.

**contents** `string`

Paketin içinde ne olduğuna dair oluşturma sırasında verilen serbest metin açıklaması (ör. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Yalnızca bilgi amaçlıdır — bir paketin bir laboratuvara
gidip gitmediği `destination` alanından, karşılığı ise `paired_with` alanından okunur. `null` olabilir.

**booked\_by** `string` *required*

Etiketi kimin yazdı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 takip edilir ancak her iki işlemde de `501` döndürür.

**paired\_with** `string`

İki paketli bir gönderideki diğer paketin referansı — iade etiketini taşıyan paket ile o etiketin
geri getirdiği paket. Her ikisinde de ayarlanır. Tek yönlü bir paket için `null`.

**origin** `object`

Alım adresi. `null` olabilir.

**adres nesnesi**

**name** `string` *required*

Alıcı, şirket veya konum adı.

**company\_name** `string`

Şirket / c/o satırı. `null` olabilir.

**street** `string` *required*

Kapı numarası olmadan sokak adı.

**house\_number** `string`

Kapı numarası. `null` olabilir.

**address\_line\_2** `string`

Bina, giriş veya kat. `null` olabilir.

**city** `string` *required*

Şehir.

**state** `string`

Eyalet veya il. `null` olabilir.

**postal\_code** `string` *required*

Posta kodu.

**country\_code** `string` *required*

ISO 3166-1 alpha-2 ülke kodu.

**phone** `string`

İletişim telefon numarası. `null` olabilir.

**email** `string`

İletişim e-postası. `null` olabilir.

**destination** `object`

Teslimat adresi. `origin` ile aynı yapıdadır. `null` olabilir.

**pickup** `object`

Planlanan alım aralığı. `null` olabilir.

**pickup nesnesi**

**from** `string` *required*

Alım aralığının UTC zamanı olarak başlangıcı (`Z` son ekli ISO 8601).

**till** `string` *required*

Alım aralığının UTC zamanı olarak bitişi (`Z` son ekli ISO 8601).

**timezone** `string` *required*

Alım konumunun IANA saat dilimi (ör. `Europe/Berlin`). `from` / `till` değerlerini alım konumunun yerel saatinde göstermek için kullan.

**notes** `string`

İsteğe bağlı notlar. `null` olabilir.

**status\_updates** `object[]` *required*

Lojistik sağlayıcıdan gelen kronolojik yaşam döngüsü olayları (en eskiden başlayarak). Sağlayıcı
henüz herhangi bir olay bildirmediyse boş dizi. Olay bazlı arayüz, denetim ve daha ayrıntılı
taşıyıcı sinyalleri için bunu kullan; esas güncel durum için `status` alanına güven.

**durum güncellemesi alanları**

**state** `string | null` *required*

Gönderi durumu sözlüğündeki olay — `pending`, `in_transit`, `delivered` veya
`fault` — böylece taşıyıcının kodlarını bilmeden bir zaman çizelgesini okuyabilirsin. Olay
bir durum taşımıyorsa `null` (etiket oluşturma, taşıyıcının bilgi yok taraması, bu alan var
olmadan önce kaydedilen girişler). Asla `cancelled` olmaz.

**code** `string | null` *required*

Taşıyıcının kendi durum kodu: GO!'nun `GO10` / `GO90` / `GOY001`, DHL'nin `VA` / `ZF` / `LA`
/ `ZU` kodları. Taşıyıcı kod sağlamadıysa `null`. `status` alanının dil çevirilerinde sabit
kalır.

**detail\_code** `string | null` *required*

Taşıyıcının varsa daha ayrıntılı kodu — DHL'nin `statusDetailed` alanı, örn. `CNRFC_NRQRD_ZF`
(postaneye yönlendirildi), `HLDCC_SERPT_LA` (oradan teslim alınmaya hazır), `DLVRD_SERPT_ZU`
(teslim alındı). Bu alana sahip olmayan taşıyıcılar için `null`.

**status** `string` *required*

Sağlayıcı kaynaklı durum etiketi (serbest metin, örn. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Kodun açıklaması veya taşıyıcının daha uzun cümlesi. İkisi de yoksa `null`.

**location** `string | null` *required*

Taramanın yapıldığı yer, taşıyıcının adlandırdığı şekliyle — bir GO! deposu (`"HUB Niederaula"`)
veya bir DHL şehri. Serbest metin, koordinat değil. Taşıyıcı bildirmediyse `null`.

**time** `string` *required*

Olayın gözlemlendiği zaman (ISO 8601, taşıyıcının bildirdiği saat farkıyla).

**appointments** `ShipmentAppointmentLink[]` *required*

Bu gönderiye bağlı randevular, en eski bağlantıdan başlayarak. Her giriş `{ id, added_at }`
şeklindedir; tam randevu verisi için her `id` değerini
[Randevuyu getir](https://docs.anivahealth.com/tr/api/appointments/get-appointment.md) ile karşılaştır. Bağlı randevu yoksa boş
dizi.
Yalnızca erişim bağlamındaki randevular listelenir.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Bu gönderiye bağlı evde test kiti siparişleri, en eski bağlantıdan başlayarak, aynı `{ id, added_at }`
yapısında. Her `id` değerini [Evde test kiti siparişini getir](https://docs.anivahealth.com/tr/api/home-kit-orders/get-home-kit.md)
ile karşılaştır. Muayenehane paketleri için boş dizi. Yalnızca erişim bağlamındaki siparişler
listelenir. [Erişim](https://docs.anivahealth.com/tr/concepts/shipments.md#erisim) bölümüne bak.

**synced\_at** `string`

Gönderinin taşıyıcısıyla en son ne zaman senkronize edildiği, UTC zamanı olarak. Okuma işlemleri
hiçbir zaman taşıyıcıyı çağırmaz — gönderileri arka plan senkronizasyonu güncel tutar — bu nedenle
yanıtın ne kadar eski olduğunu bu alan gösterir. İlk senkronizasyona kadar `null`.

**created\_at** `string` *required*

Oluşturulma zaman damgası (ISO 8601).

**updated\_at** `string`

Son güncelleme zaman damgası (ISO 8601). `null` olabilir.

## Tekrarlanan çağrılar

Aniva bu uç noktanın yanıtını her API anahtarı için 5 dakika boyunca saklar. Bu süre içinde
yapılan yinelenen bir çağrı saklanan yanıtı alır. `Cache-Status` ve `Age` başlıkları yanıtın
saklandığını ve ne kadar eski olduğunu gösterir.

Bir değişiklikten hemen haberdar olmak için `shipment.created` ve `shipment.updated` webhook olaylarına abone ol.
[Tekrarlanan okumalar](https://docs.anivahealth.com/tr/concepts/webhooks.md#tekrarlanan-okumalar) bölümüne bak.

## Hata yanıtları

| Durum | Açıklama |
| - | - |
| `400` | Geçersiz sorgu parametresi. |
| `403` | Yasak — eksik kapsam veya filtrelenen randevu / evde test kiti siparişi kapsamının dışında. |
| `404` | Filtrelenen randevu veya evde test kiti siparişi bulunamadı. |
| `500` | Dahili sunucu hatası. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "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": null,
    "status_updates": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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