# Müşteri eklemek ve güncellemek

> **Ne yaparsınız:** Müşteri kartı oluşturur, bilgilerini değiştirir, arşive alıp geri getirir ve KVKK silme isteğini yerine getirirsiniz.
> **Hangi uçlar:** [Müşteri oluştur](https://developer.siparis.app/uc/musteri-olustur), [Müşteriyi getir](https://developer.siparis.app/uc/musteriyi-getir), [Müşteriyi güncelle](https://developer.siparis.app/uc/musteriyi-guncelle), [Müşteriyi arşivle](https://developer.siparis.app/uc/musteriyi-arsivle), [Müşteriyi geri getir](https://developer.siparis.app/uc/musteriyi-geri-getir), [Müşteriyi anonimleştir (KVKK)](https://developer.siparis.app/uc/musteriyi-anonimlestir-kvkk)
> **Gereken izin:** `customers:write` ve `personal_data:write`; arşiv için `archive:write`, KVKK için ayrıca `customers:erase`.

API adresi `https://api.siparis.app/v1`. İşlemler panelin müşteri servislerini kullanır. Anahtarınızı sunucuda `SIPARIS_API_KEY` ortam değişkenine kaydedin; [Başlarken](https://developer.siparis.app/baslarken) bağlantıyı kurmayı anlatır. Örneklerde `curl` ve `jq` gerekir.

## 1. İzinleri seçin

Kapsamlar (anahtarın erişim izinleri) işe göre ayrıdır:

| İş | Gerekli kapsam |
| --- | --- |
| Müşteri oluşturmak | `customers:write`, `personal_data:write` |
| Ad, telefon, e-posta, adres, fatura veya pazarlama iznini değiştirmek | `customers:write`, `personal_data:write` |
| Yalnız iç notu değiştirmek | `customers:write`, `internal_notes:write` |
| Arşivlemek veya geri getirmek | `customers:write`, `archive:write` |
| Kartı okumak | `customers:read`; kişisel alanlar için ayrıca `personal_data:read` |
| İç notu okumak | Ayrıca `personal_data:read`, `internal_notes:read` |

Yazma izni okuma izni vermez: oluşturma yanıtında her zaman `cus_` kimliği vardır, kişisel okuma izni yoksa ad ve iletişim bilgileri atlanır. Anahtarı yalnız işletme sahibi yönetir; anahtarın marka sınırı bütün işlemlerde geçerlidir.

## 2. Müşteriyi ekleyin

Örnek ad ve iletişim bilgilerini değiştirin. Tek markalı işletmede veya marka sınırlı anahtarda `store` atlanabilir; birden çok markaya erişiyorsanız `/me` yanıtından seçtiğiniz satış markasının `sto_` kimliğini `"store": "sto_..."` alanıyla gönderin.

İlk örnek için zorunlu alanlar (POST /v1/customers):

| Alan | Tür | Açıklama | Örnek |
| --- | --- | --- | --- |
| `name` | metin (en çok 500 karakter) | Müşterinin adı; personal_data:write gerekir. | `"Örnek Müşteri"` |

Bütün alanlar: [Müşteri oluştur](https://developer.siparis.app/uc/musteri-olustur).

```bash
cat > musteri.json <<'JSON'
{
  "name": "Örnek Müşteri",
  "phone": "05000000000",
  "email": "musteri@example.com",
  "address": {
    "city": "İstanbul",
    "district": "Kadıköy",
    "address_line": "Örnek Sokak No: 1"
  },
  "marketing_consent": false
}
JSON

export SIPARIS_MUSTERI_TEKRAR='musteri-20261016-001-ekle'
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_MUSTERI_TEKRAR" \
  -H 'Content-Type: application/json' \
  --data-binary @musteri.json \
  --dump-header musteri-basliklari.txt --output musteri-yaniti.json
cat musteri-yaniti.json
export SIPARIS_CUSTOMER_ID="$(jq -r '.id' musteri-yaniti.json)"
```

`Idempotency-Key` tekrar anahtarıdır: aynı isteği güvenle yeniden göndermek için sizin ürettiğiniz benzersiz metin. Başarı `201` döner. `id` müşteri kimliği, `Location` kartın API yolu, `revision` kartın sürüm numarası (her değişiklikte artar), `ETag` ise sürüm etiketidir.

Örnek HTTP 201 yanıtı (uydurma veri):

```json
{
  "archived": false,
  "created_at": "2026-10-16T09:00:00Z",
  "id": "cus_1234567890abcdef1234567890abcdef",
  "revision": 1,
  "store": "sto_1234567890abcdef1234567890abcdef",
  "updated_at": "2026-10-16T09:00:00Z"
}
```



Aynı e-posta bulunursa veya mevcut müşteri eşleştirme kuralına göre telefon eşleşirse `409 customer_exists` ve `existing_customer: "cus_..."` gelir. Yeni kart açılmaz, var olan kart değiştirilmez; bu kimliği okuyup güncelleyebilirsiniz. Telefonun son 10 hanesi eşleştirilir; aynı telefon fakat farklı iki e-posta ayrı kişidir. Arşivdeki kartlar eşleştirmeye girmez.

Fatura için `invoice` içinde `company_name`, `tax_office`, `tax_number` birlikte gönderilir; panelin vergi numarası doğrulaması uygulanır. Pazarlama iznine müşterinin gerçek iznini yazın.

## 3. Güncel kartı okuyun ve değiştirin

```bash
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers/$SIPARIS_CUSTOMER_ID" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --dump-header musteri-basliklari.txt --output musteri-guncel.json
cat musteri-guncel.json
export SIPARIS_MUSTERI_ETAG="$(awk 'tolower($1)=="etag:" {gsub("\r","",$2); print $2}' musteri-basliklari.txt)"

curl --fail-with-body --silent --show-error --request PATCH \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers/$SIPARIS_CUSTOMER_ID" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_CUSTOMER_ID-ad-degistir-1" \
  -H "If-Match: $SIPARIS_MUSTERI_ETAG" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Örnek Müşteri Yeni"}'
```

Yalnız gönderdiğiniz alan değişir. Adres nesnesi bütün adresi değiştirir. Panelden veya başka bir yazılımdan yapılan değişiklikler de sürümü artırır.

`If-Match` başlığına son okuduğunuz `ETag` değerini yazın; kullanmanız önerilir. Kart siz okuduktan sonra değiştiyse `412 revision_mismatch` gelir ve yazma yapılmaz. Kartı yeniden okuyun, değişikliği kontrol edin ve yeni tekrar anahtarıyla gönderin.

## 4. Arşive alın ve geri getirin

Bu iki komut `customers:write` ve `archive:write` ister. Boş JSON nesnesi gönderilir; isterseniz güncel `If-Match` de ekleyebilirsiniz.

```bash
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers/$SIPARIS_CUSTOMER_ID/archive" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_CUSTOMER_ID-arsiv-1" \
  -H 'Content-Type: application/json' --data '{}'
```

Kart listeden kalkar; kendisi, siparişleri ve üyelik bağı kalır. Kimliğiyle GET isteği arşivdeki kartı okuyabilir.

```bash
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers/$SIPARIS_CUSTOMER_ID/restore" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_CUSTOMER_ID-geri-getir-1" \
  -H 'Content-Type: application/json' --data '{}'
```

Kart yeniden listelenir. Arşiv anonimleştirme değildir; KVKK ile anonimleşmiş kart geri getirilemez.

`customer.created`, `customer.updated`, `customer.archived`, `customer.restored` olayları [olay akışından](https://developer.siparis.app/olaylar) izlenebilir; olay yükünde kişisel veri bulunmaz.

## 5. KVKK silme isteği

**Geri alınamaz.** İşletme sahibi Geliştirici > Anahtar oluştur > Özel şablonunda hassas `customers:erase` kapsamını ayrıca seçer. Bu uç birlikte `customers:write`, `customers:erase` ve `personal_data:write` ister; kişisel veri erişimi için sahibin açık KVKK seçimi gerekir.

Müşteri kaydı silinmez. Ad “Silinmiş müşteri” olur; telefon, e-posta, adres, kartın fatura bilgisi ve kişisel notlar temizlenir. Siparişlerin kişisel alanları ve işlem geçmişindeki kopyaları da anonimleşir; arama anahtarları temizlendiği için eski `email=` veya `phone=` araması artık müşteriyi bulmaz. Vitrin üyeliği kapanır, devam eden abonelikler iptal edilir ve kayıtlı kartlar kullanıma kapatılır. Siparişler ürün, tutar, tarih ve durumlarıyla; kesilmiş faturalar yasal saklama kapsamında; muhasebe kayıtları ve para/stok geçmişi yerinde kalır.

Açık sipariş varsa `409 customer_anonymization_blocked` döner: önce siparişleri tamamlayın veya iptal edin, ardından yeni tekrar anahtarı kullanın. Arşivdeki müşteri de anonimleştirilebilir.

```bash
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers/$SIPARIS_CUSTOMER_ID/anonymize" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_CUSTOMER_ID-kvkk-1" \
  -H 'Content-Type: application/json' \
  --data '{"confirm":"anonymize","reason":"Müşterinin KVKK silme isteği"}'
```

`confirm` zorunludur ve tam olarak `anonymize` olmalıdır; eksik veya yanlışsa `422 validation_error` gelir. `reason` isteğe bağlıdır; kişisel veri yazmayın. Başarı `200` ve anonim müşteri nesnesidir. Zaten anonim müşteride yeni anahtarla da `200` döner ve değişiklik yapılmaz.

`customer.anonymized` olayında müşteri yalnız `cus_` kimliğiyle belirtilir; kişisel veri yoktur. Webhook aynı olayı taşır; sonraki okuma ve yeni dışa aktarmalar anonim veriyi verir. Anonimleşmiş kart etkin müşteri listesinden ve müşteri dışa aktarmasından kalkar, kimliğiyle okunabilir. Daha önce hazırlanmış dışa aktarma dosyalarına erişim, dosya oluşturulduktan **7 gün** sonra kapanır. Kendi sisteminizdeki kişisel veri kopyalarını da bu olayla güncelleyin. Tekrar makbuzlarında gövde veya kişisel veri tutulmaz; eski oluşturma/güncelleme isteğinin tekrarı da anonimleşmiş güncel kaydı verir.

## 6. Tekrar ve sık hatalar

Bağlantı kesilirse aynı yöntem, yol, gövde, `If-Match` ve tekrar anahtarıyla yeniden gönderin: iş ikinci kez uygulanmaz, `Idempotent-Replayed: true` ile kartın güncel hali gelir. Yeni iş veya düzeltilmiş hata için yeni anahtar kullanın.

| Hata | Yapılacak iş |
| --- | --- |
| `409 customer_exists` | `existing_customer` kimliğini kullanın. |
| `412 revision_mismatch` | Kartı yeniden okuyup yeni ETag ve tekrar anahtarı kullanın. |
| `409 customer_anonymization_blocked` | Açık siparişleri tamamlayın veya iptal edin; yeni tekrar anahtarıyla deneyin. |
| `422 validation_error` | `confirm` alanına tam olarak `anonymize` yazın. |
| `409 customer_restore_conflict` | Arşiv durumunu ve üyelik bağını panelden kontrol edin. |

Ortak hatalar (kapsam, marka, tekrar anahtarı) her ucun sayfasındadır. [Müşterileri bulmak](https://developer.siparis.app/musterileri-bulmak) rehberi ham e-posta/telefon aramasını ve müşterinin siparişlerini anlatır.