Müşteri eklemek ve güncellemek

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

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):

Bütün alanlar: Müşteri oluştur.

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):

{
  "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

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.

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.

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

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.

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