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

# PHI'ye yakın kitleleri kaydet

> PHI'ye yakın kitle registry'sinin walkthrough'u: bir liste veya segment ne zaman belirlemeli, atomik tam-replacement PUT nasıl çalışır, kampanya başlatma ön-denetimi nasıl tepki verir ve audit izi nasıl okunur.

# PHI'ye yakın kitleleri kaydet

PHI'ye yakın kitle registry'si, üyeleri PHI taşıyan — örneğin, tedavi davetine opt-in olmuş hastalar — contact list'lerinin ve segment'lerinin listesidir. [HIPAA kontrolleri](/compliance/hipaa#phi-adjacent-audience-registry) referansı iki endpoint'i belgelendirir; bu rehber onları production'da yönetmenize: ne belirlemeli, yazma semantiği nasıl çalışır, kampanya başlatmada ne olur ve audit izi nasıl okunur.

Registry **tenant-sahip**. Devotel sizin adlımıza asla kitle belirlemez ve sizin için asla PHI scope yapmaz — belirlemeler sizin attestation'ınızdır, BAA ile gate edilmiş kontrollerdir ve sadece HIPAA organizasyonunuzun kapsamında olduğunda etki yapar. BAA'yı henüz yürütmediyseniz ve HIPAA modunu etkinleştirmediyseniz, önce [HIPAA onboarding](/guides/hipaa-onboarding) dizisini çalıştırın.

## 1. Bir kitle ne zaman PHI'ye yakın olarak işaretlemeli

Belirleme **kaynak**'a bakar: üyelerinin kaynak verileri PHI içeren kitleleri işaretleyin, herhangi bir kampanyanın onlara ne göndereceğinden bağımsız olarak. Bir kitle PHI'ye yakındır çünkü üyelerinin geldiği yerden — bir hasta randevusu-hatırlatıcı importu, bir tedavi-davet opt-in listesi — bu hafta yazdığınız kopya dolayı değil. Bu yüzden belirleme kitle'nin kendisinde yer ve bir kampanya üzerinde değil: hangi kampanya kitleyi alırsa alsın, belirleme onunla birlikte gider.

Bir kitle'yi PHI'ye yakın olarak işaretleyin, eğer:

* Üyeleri PHI tutan bir sistemden import edildi (bir EHR exportu, bir hasta portalı opt-in senkronizasyonu).
* Liste veya segment PHI taşıyan kriterlere filtrelenmiş veya toplanmış (tanı-yakın etiketler, tedavi kohortleri).
* Compliance sorumlunuzun veri haritası kitleyi PHI kapsamında kaydeder.

Bir kitleyi "emniyet için" belirlemeyin. Bir belirleme [BAA başlatma gate'sini](#4-başlatma-öndenetimi-registry-nasıl-kullanır) kitleyi kullanan her kampanya'ya bağlar — PHI taşımayan kitleler belirlemek başlatmayı hiçbir uyumluluk sebebi olmadan engeller.

**Kim açıklayabilir:** her iki endpoint de `owner` veya `admin` rolünü ister — [BAA endpoint'lerinin](/compliance/baa) kullandığı aynı gate. Bir `developer` veya `viewer` `403` alır. Belirleme kararını HIPAA compliance sorumlunuzla tutun; platform *kim* her yazmada registry'i değiştirdiğini kaydet (bkz. [Audit izi](#5-audit-trail)).

## 2. Liste vs. segment id'leri seçin

Registry kitle id'lerini tutar — her giriş bir **contact-list id**'si veya bir **segment id**'sidir, düz string olarak geçirilir. Kampanya başlatma ön-denetimi sadece `list`- ve `segment`-tip kitlelerini registry'e karşı çözümleyebilir; contact-başı toplanmış kitleler (tüm contact'lar, CSV yükleme, el ile giriş) gönderme sırasında recipient-recipient değerlendirilir, bu yüzden belirlenecek registry id'leri yoktur.

Bir belirleme için id'yi yeniden çıkarmak için:

```bash theme={null}
# Contact list'leri
GET /api/v1/contacts/lists

# Segment'ler
GET /api/v1/contacts/segments
```

Belirlemekte olduğunuz liste veya segment'in `id` alanını kopyalayın. Id'ler trimlenmiş 1–128 karakter; daha uzun veya boş olanlar yazmada `422` ile reddedilir. Registry en fazla **500** id per organizasyon tutar — daha fazla taşıyan bir `PUT` `422` döndürür.

> **Kaynak** id'sini belirleyin, bir downstream kopya değil. Bir PHI taşıyan liste bir türetilmiş segment besliyorsa, türetilmiş segment'nin PHI içerip içermediğine karar verin ve onu açıkça belirleyin — ön-denetim kampanyanın gerçekten başvurduğu id'yi kontrol eder, başka hiçbir şey değil.

## 3. Atomik PUT değişimi

Registry **bir** yazma işlemine sahip: tam-replacement `PUT`. `PATCH` yoktur, id-başı `DELETE` yoktur — her yazma belirlenmiş küme'nin tamamını tek atomik ifade ile değiştirir, bu yüzden eşzamanlı bir `GET` asla kısmen uygulanan bir güncellemeyi görmez.

```bash theme={null}
PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"]
}
```

Yanıt saklanan kümeyi yansıtır:

```json theme={null}
{
  "data": {
    "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"],
    "replaced": true
  }
}
```

Body **idempotent**: aynı tam set'i iki kez göndermek aynı saklanan registry ve iki ayrı audit satırı üretir. Boş bir dizi her belirlemenizi temizler:

```bash theme={null}
PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": []
}
```

Yazma bir swap olduğu için, her client **read-modify-write** izlemelidir: mevcut registry'i `GET`, sonucu içinde id'nizini ekleyin veya çıkarın ve tam kümeni geri `PUT`. Body'yi asla sadece local state'ten oluşturmayın — diğer operatörün eklediği belirlemenleri sessizce düşüreceksiniz.

Bir belirlemeyi kaldırmak için registry'i o id olmadan `PUT`. Yeniden belirlemek için eklenen id ile `PUT`. Bir swap'ten kurnan bireysel id'ler değiştirilmez; sadece küme içi üyelik önemlidir.

## 4. Başlatma ön-denetiminin registry'i nasıl kullandığı

PHI'yi iki gate farklı noktalarda korur, ve registry ilkini besler:

1. **Başlatma ön-denetimi (kampanya seviyesi, katı gate).** Bir kampanya taslak/programlamadan çıkmadan önce, ön-denetim kitle id'sini registry'ye karşı çözümleyebilir. Belirlenmiş bir id ve terim içinde olmayan bir BAA başlatmayı `422 HIPAA_BAA_REQUIRED` ile reddeder — tek bir recipient kaydolmadan önce. Uyumluluk durumu okunamıyorsa, ön-denetim kitleyi sessizce kabul etmek yerine `500 HIPAA_BAA_GATE_DB_FAIL` ile kapalı hata verir.
2. **Recipient-başı send gate'i (mesaj zamanı, değiştirilmemiş).** Mevcut send gate'i her bireysel gönderime hâlâ uygulanır ve registry'ye başvurmaz — tek seferlik gönderimler sadece onunla yönetilir.

Engellenen bir başlatma aşağıdaki red ile yüzeye çıkar. `details.reason` hangi BAA durumu engelini açacağını tam size söyler:

```json theme={null}
{
  "error": {
    "code": "HIPAA_BAA_REQUIRED",
    "status": 422,
    "message": "The designated PHI-adjacent audience for this campaign requires an executed Business Associate Agreement (BAA) before outbound sends are permitted.",
    "details": {
      "reason": "pending",
      "audience": { "type": "list", "id": "list_9f2c1a" }
    }
  }
}
```

| `reason`     | Anlam                                              | Engel açma                                                      |
| ------------ | -------------------------------------------------- | --------------------------------------------------------------- |
| `not_signed` | PHI kapsamda attest edildi ama hiç BAA yürütülmedi | BAA'yı yürütün — [BAA akışı](/compliance/baa)                   |
| `pending`    | BAA yürütmesi başladı ama tamamlanmadı             | Yürütme adımını bitirin (`POST /api/v1/compliance/baa/execute`) |
| `expired`    | Yürütülen BAA bir yıllık terim süresini geçti      | BAA'yı yeniden yürütün                                          |

Engel açmanın **iki** yolu vardır, ve bunlar uyumluluk kararları, platform kararları değil:

* **BAA'yı çözün** — gate'in geçmesi için yürütün veya yeniden yürütün. Kitle gerçekten PHI taşıyorsa bu doğru yoldur.
* **Belirlemeyi kaldırın** — registry'i kitle id'si olmadan `PUT`. Bu doğru yoldur *sadece* kitlege hatalı belirlendiyse. Gate'i atlatmak için bir belirlemenin kaldırılması kendi audit log'unuzda görünürdür.

Dashboard kampanya asistanında, belirlenmiş bir kitle seçmek kitle adımında bir uyarı belirtir. Uyarı **İleri** düğmesini engellemez — belirleme kaldırılabilir veya başlatmadan önce BAA yürütülebilir — ama başlatmadaki katı gate her zaman uygulanır.

## 5. Audit izi

İki kayıt sınıfı organizasyonunzun audit log'una iner:

* **`hipaa.phi_audiences.set`** — her `PUT` için bir satır, işlem yapan kullanıcıyı, organizasyonu ve tam post-yazma id kümesini kaydet. Bu versiyon hikayeniz: registry ayrı bir revision resource'una sahip değil — audit satırlarının dizisi *versiyon geçmişi*. Belirli bir noktada belirlendiğini yeniden çıkarmak için `set` satırını geri okuyun; geri almak için önceki bir satırın id kümesini `PUT`.
* **`HIPAA_BAA_REQUIRED` başlatma reddi** — her engellenen başlatma, reddinen neden ve değerlendirilen kitle ile loglanır. Bu satırlar olay sıranızı da iki misli olarak katlar: bir red ya da uyumluluk işi bekliyor (BAA yürütülmemiş) veya bir belirleme ve bir kampanya anlaşmıyor.

Her iki sınıfı compliance programınızla eşleşen bir ritimde inceleyin — haftalık aktif sağlık workspace'i için çalışılabilir bir varsayılandır. Harici audit için delik bir araya getirirken PHI erişim log'unuzun yanında audit log'unu dışa aktarın; [delil paketi](/compliance/evidence-binder) HIPAA paketi BAA duruşu ve PHI erişim log'lamasını signed indirmeye doğar.

**Beklenmedik red için olay runbook'u:**

1. Reddın `details.reason`'ını ve `details.audience.id`'sini okuyun.
2. `GET /api/v1/compliance/baa/` kontrol edin — BAA `pending`/`expired`/yürütülmemişse, [BAA akışı](/compliance/baa) ile çözün.
3. BAA sağlıkliysa, kitlege kitesinin belirlenmesi gerekip gerekmediğini kontrol edin: `GET /api/v1/compliance/hipaa/phi-audiences` ve veri haritanızla karşılaştırın. Hatalı bir belirlemeyi swap ile kaldırın (`PUT` id olmadan).
4. Sonucu kendi olay kayıt defterinizde kaydedin — yukarıdaki audit satırları gösterdiğiniz deliktir.

## 6. Eşzamanlı yazma çatışmaları giderme

Registry `PUT`'ı asla `409` dönmüyor — tek ifade atomik swap bir yazmanın her zaman commit olması demek, ve son yazar kazanır. Çatışma riski **operatörler arasında kayıp güncellemeler**, reddedilen yazmalar değil:

* Operatör A ve operatör B her ikisi de `GET` yapar.
* A `list_aaa` ekler ve `PUT`. B — A öncesi snapshot'tan çalışarak — `list_bbb` ekler ve `PUT`.
* B'nin swap'ı `list_aaa`'yı sessizce düşürür.

Önlemler:

* **Yazmadan hemen önce oku.** Read-modify-write penceresini kısa tutun; getirilmiş registry'yi bir düzenleme oturumu boyunca taşımayın — `PUT` için hazır olduğunuzda tekrar `GET`.
* **Yazmadan sonra doğrula.** Bir kez daha `GET` ve id'nizin mevcut olduğunu ve ilgisiz bir belirlemenin kaybolmadığını onaylayın. Bir şey kaybolsa, audit log'unun `hipaa.phi_audiences.set` satırları kimin yazmada kimin üzerine yazdığı ve hangi kümeyi geri getirdiğini göster.
* **Registry düzenlemeleri organizasyonel olarak sıralandırın.** Belirleme compliance attestasyonu olduğu için, düzenlemeleri bir rol'den (compliance sorumlusu) geçir, operatörler arasında yaymama unorumdan — race'i tamamen kaldıran bir prosedürevi fix.

Başarı yerine `422` görüyorsanız, sebep validasyon, çatışma değil: **500**'den fazla id, trimlendikten sonra boş bir id veya 128 karakterden uzun bir id. Trimi atın ve tam küme ile tekrar deneyin.

## Ayrıca bkz.

* [PHI'ye yakın kitle belirlemeleri](/compliance/phi-audiences) — registry sözleşmesinin endpoint referansı (tavan, replacement semantics, audit action)
* [HIPAA uyumluluk kontrolleri](/compliance/hipaa) — registry'nin beslediği tam kontrol referansı
* [BAA — Business Associate Agreement](/compliance/baa) — başlatma ön-denetiminin zorladığı yaşam döngüsü
* [HIPAA onboarding: BAA'dan audit hazırlığına](/guides/hipaa-onboarding) — kitleleri belirlemeden önce sağlık workspace'ini audit hazırlığına getiren sıra
* [Send gate'ler](/compliance/send-gates) — başlatma ön-denetimini tamamlayan recipient-başı gate

```
```