> ## 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.

# Randevular

> Aniva laboratuvar testi API'sinde kan alma randevuları nasıl çalışır: randevu alma, paneller, biyobelirteçler, durum değişiklikleri ve iptal.

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](https://docs.anivahealth.com/tr/concepts/home-kit-orders.md).

## Alanlar

**id** `string` *required*

Aniva tarafından otomatik oluşturulan UUID. Panel eklemek, kan almayı onaylamak ve sonuçları almak için bunu kullan.

**profile\_id** `string` *required*

Bu randevunun ait olduğu profilin UUID'si.

**location\_id** `string`

Kan almanın yapılacağı test konumunun UUID'si. Evde test kitleri randevu değildir — bkz.
[Evde test kiti siparişleri](https://docs.anivahealth.com/tr/concepts/home-kit-orders.md).

**scheduled\_at** `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](https://docs.anivahealth.com/tr/api/appointments/create-appointment.md#minimum-bildirim-sueresi)).

**status** `string` *required*

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ü](#yasam-doenguesue) bölümüne bak. Laboratuvar sonucu
tamamlanma ayrıntısı (`in_progress` veya `completed`) [Sonuçları al](https://docs.anivahealth.com/tr/api/appointments/get-results.md)
ü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](https://docs.anivahealth.com/tr/api/shipments/get-shipment.md) üzerinden takip
ederek elde edilir.

**cancellation\_reason** `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.

**results\_ready\_emails** `string[]` *required*

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ı](https://docs.anivahealth.com/tr/concepts/results.md#sonuclar-hazir-e-postalari).

**draw\_method** `string` *required*

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](https://docs.anivahealth.com/tr/concepts/locations.md)
`default_draw_method` değeridir. Kan almadan sonra kullanılan yöntemdir.

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

Randevunun oluşturulduğu zamanın ISO 8601 zaman damgası.

**updated\_at** `string`

En son güncellemenin ISO 8601 zaman damgası. Randevu hiç güncellenmediyse null olur.

**lab\_codes** `string[]` *required*

[Kan almayı onayla](https://docs.anivahealth.com/tr/api/appointments/confirm-blood-draw.md) 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.

**panels** `object[]` *required*

`{ panel_id, added_at }` girişleri halinde bu randevuya eklenen paneller. Bkz.
[Panel ekleme](#panel-ekleme).

**individual\_biomarkers** `object[]` *required*

`{ biomarker_id, added_at }` girişleri halinde bu randevuya eklenen tekli biyobelirteçler. Bkz.
[Tekli biyobelirteçler](#tekil-biyobelirtecler).

**shipments** `object[]` *required*

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](#goenderileri-baglama).

**profile** `object` *required*

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](https://docs.anivahealth.com/tr/api/appointments/get-appointment.md) tümünü listeler.

**özellikler**

**id** `string`

İlişkili profilin UUID'si.

**first\_name** `string`

Hastanın adı.

**last\_name** `string`

Hastanın soyadı.

**email** `string`

Hastanın e-posta adresi.

**date\_of\_birth** `string`

`YYYY-MM-DD` formatında doğum tarihi.

**sex** `integer`

ISO/IEC 5218 standardına göre biyolojik cinsiyet.

## Yaşam döngüsü

Randevuların dört yaşam döngüsü durumu vardır:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Durum | Anlamı |
| - | - |
| `pending` | Randevu planlandı ve onay bekliyor. [Güncellenebilir](https://docs.anivahealth.com/tr/api/appointments/update-appointment.md) veya [iptal edilebilir](https://docs.anivahealth.com/tr/api/appointments/cancel-appointment.md). |
| `confirmed` | Planlama onaylandı (örn. muayenehane tarafından), ancak henüz kan alınmadı. Hâlâ güncellenebilir veya iptal edilebilir. |
| `blood_drawn` | Laboratuvar kodları [Kan almayı onayla](https://docs.anivahealth.com/tr/api/appointments/confirm-blood-draw.md) üzerinden gönderildi ve laboratuvar sipariş süreci tetiklendi. Paneller dondurulur; randevu yeniden planlanamaz veya iptal edilemez. |
| `cancelled` | Randevu iptal edildi. Son durumdur — başka bir geçiş yapılamaz. |

> [!NOTE]
>
> 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](https://docs.anivahealth.com/tr/api/appointments/get-results.md) — ü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](https://docs.anivahealth.com/tr/api/shipments/get-shipment.md) ü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](https://docs.anivahealth.com/tr/concepts/webhooks.md) gönderir; örneğin
> `appointment.confirmed`. Yeni bir saat veya konum ise `appointment.rescheduled` gönderir.

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

```
GET /api/v1/appointments
```

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:

```
PATCH /api/v1/appointments/{id}
```

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](https://docs.anivahealth.com/tr/api/appointments/create-appointment.md) hem de
[Randevuyu güncelle](https://docs.anivahealth.com/tr/api/appointments/update-appointment.md) 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.

> [!NOTE]
>
> 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:

```
DELETE /api/v1/appointments/{id}
```

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.

> [!NOTE]
>
> İ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:

```
POST /api/v1/appointments/{id}/panels
```

`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.

> [!NOTE]
>
> 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:

```
DELETE /api/v1/appointments/{id}/panels
```

`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.

> [!NOTE]
>
> 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):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Biyobelirteç kaldır (idempotent — bağlı olmayan biyobelirteçler yok sayılır):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

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](https://docs.anivahealth.com/tr/api/biomarkers/list-biomarkers.md) uç noktasını kullan.

> [!NOTE]
>
> 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:

```
GET /api/v1/appointments/{id}/preview
```

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](https://docs.anivahealth.com/tr/concepts/pricing.md)); 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.

> [!NOTE]
>
> Ö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:

```
POST /api/v1/appointments/{id}/confirm
```

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

> [!WARNING]
>
> `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](https://docs.anivahealth.com/tr/api/shipments/get-shipment.md) 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](https://docs.anivahealth.com/tr/api/shipments/get-shipment.md) /
[Randevuyu al](https://docs.anivahealth.com/tr/api/appointments/get-appointment.md)) çapraz referans verir.

Gönderiler oluşturulurken [Gönderi oluştur](https://docs.anivahealth.com/tr/api/shipments/create-shipment.md) 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](https://docs.anivahealth.com/tr/api/shipments/attach-appointments-to-shipment.md) ve
[Gönderiden randevu ayır](https://docs.anivahealth.com/tr/api/shipments/detach-appointments-from-shipment.md) 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](https://docs.anivahealth.com/tr/api/shipments/list-shipments.md) 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:

```
GET /api/v1/appointments/{id}/results
```

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

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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