Onay ve Bülten Uçları

İzinle ilgili üç ayrı konu üç ayrı uçla yürür ve karıştırılmaması gerekir:

Konu	Uç	Kim çağırır
Çerez onayı: bir tarayıcının izleme kategorilerine verdiği cevap	POST ve DELETE /public/sites/:siteKey/consent	Tarayıcı (widget ya da kendi onay çözümünüz)
Pazarlama izni: bir adresin e-posta ya da SMS almayı kabul etmesi, sizin sunucunuzdan	POST /public/sites/:siteKey/contacts/consent	Sizin arka ucunuz, newsletter_subscribe anahtarıyla
Bülten kaydı: bir formdan gelen e-posta	POST /public/sites/:siteKey/newsletter	Bülten widget'ı ya da kendi formunuz

Çerez onayının panel tarafı ve tarayıcı API'si için Onay Yönetimi sayfasına bakın. Kimlik kuralları: Kimlik Doğrulama ve Erişim.

Çerez onayı: consent

Kaydet

POST /api/v1/public/sites/:siteKey/consent

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/consent \
  -H "Content-Type: application/json" \
  -H "Origin: https://magaza.com" \
  -d '{
    "categories": { "necessary": true, "analytics": true, "marketing": false, "preferences": true },
    "visitorId": "VISITOR_ID",
    "sessionId": "SESSION_ID",
    "siteUserId": "MUSTERI-1001",
    "action": "accepted"
  }'

Alan	Zorunlu	Açıklama
categories	Evet	necessary, analytics, marketing, preferences anahtarlarıyla bir nesne. Yalnızca true değerler izin sayılır; necessary her zaman true saklanır; nesnedeki başka anahtarlar yok sayılır. Nesne yoksa 400
visitorId	Önerilir	Verilmezse sunucu anon_... biçiminde rastgele bir kimlik üretir ve kayıt hiçbir ziyaretçiye bağlanamaz
sessionId, siteUserId	Hayır	Bağlam
action	Hayır	Kararın nereden geldiği; aşağıdaki tablo

action değeri, panelde Cookie Consent (Çerez Onayı) → Analytics içindeki Onay yöntemi dağılımını belirler:

action	Panelde sayıldığı yöntem
accepted, declined	Banner
customized	Ayar ekranı
timeout	Varsayılan (süre doldu)
başka her değer	Programatik

categories içinde analytics, marketing ya da preferences'tan hiçbiri true değilse (ya da action declined ise) olay consent_declined, aksi hâlde consent_granted olarak yazılır. Her kayıt bir ConsentRecord satırı (yöntem, kategoriler, IP ve tarayıcı bilgisiyle) ve bir izleme olayı üretir.

Yanıt { "success": true }. Site bilinmiyor ya da doğrulanmamışsa HTTP 200 ve { "success": false, "error": "Site not verified" } döner. Bu uç hız sınırının dışındadır.

Geri çek

DELETE /api/v1/public/sites/:siteKey/consent

curl -X DELETE https://api.selwise.com/api/v1/public/sites/SITE_KEY/consent \
  -H "Content-Type: application/json" \
  -H "Origin: https://magaza.com" \
  -d '{ "visitorId": "VISITOR_ID" }'

visitorId ve siteUserId'den en az biri zorunludur; ikisi de yoksa 200 ve { "success": false, "error": "visitorId or siteUserId required" } döner. Çağrı, o ziyaretçinin (ve/veya müşterinin) tüm onay kayıtlarını geri çekilmiş işaretler (yalnızca necessary true), bir consent_withdrawn olayı yazar ve istemcinin yapması gereken temizliği söyler:

{
  "success": true,
  "message": "Consent withdrawn successfully",
  "clientAction": {
    "clearLocalStorage": true,
    "storageKey": "selwise_consent",
    "clearCookies": true,
    "cookiePattern": "_selwise_"
  }
}

storageKey, kanalın Cookie Consent → Policy ayarındaki saklama anahtarıdır (değiştirdiyseniz o). Sunucu tarayıcı depolamasına dokunamaz; bu temizliği çağıran taraf yapar. Widget'ın withdrawConsent() yöntemi bu çağrıyı ve temizliği birlikte yapar.

Pazarlama izni: contacts/consent

Bir alışverişçinin e-posta ya da SMS aboneliğini kendi sunucunuzdan açıp kapatmanın yoludur: hesabım sayfasındaki iletişim tercihleri, CRM, çağrı merkezi. Anahtar yalnızca newsletter_subscribe kapsamını taşımalı ve bu uç her zaman anahtar ister; tarayıcıdan çağrılmaz. Anahtarı Purpose olarak Consent sync seçerek oluşturun: API Anahtarları.

POST /api/v1/public/sites/:siteKey/contacts/consent
x-selwise-api-key: swpk_live_...
Content-Type: application/json

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/contacts/consent \
  -H "Content-Type: application/json" \
  -H "x-selwise-api-key: swpk_live_..." \
  -d '{
    "contacts": [
      { "kind": "email", "value": "musteri@ornek.com", "siteUserId": "MUSTERI-1001", "optIn": true, "note": "Hesabım > İletişim tercihleri" },
      { "kind": "phone", "value": "+905321112233", "optIn": true, "iys": "registered" },
      { "kind": "phone", "siteUserId": "MUSTERI-1001", "optIn": false }
    ]
  }'

Alan	Zorunlu	Açıklama
contacts	Evet	En çok 500 kayıt
kind	Evet	email veya phone
optIn	Evet	true izin verir, false geri çeker
value	Kayıt bilinmiyorsa	Adres ya da E.164 telefon; en çok 255 karakter. Hiç kaydı olmayan bir adrese izin vermek için zorunlu
siteUserId	Hayır	Müşteri kimliğiniz, en çok 64 karakter. value ile birlikte verilirse kayıt bu müşteriye bağlanır; tek başına verilirse karar müşterinin o türdeki tüm adreslerine uygulanır
iys	Hayır	Yalnızca telefon: numaranın İYS kaydı, registered veya rejected. Gönderirseniz izni İYS'ye kendiniz kaydetmişsiniz demektir; kanalda İYS entegrasyonu açık olsa da bu karar İYS'ye ayrıca bildirilmez
iysSource	Hayır	Kanalda İYS entegrasyonu açıksa kararın İYS'ye hangi kaynakla bildirileceği: HS_FIZIKSEL_ORTAM, HS_ISLAK_IMZA, HS_WEB, HS_CAGRI_MERKEZI, HS_SOSYAL_MEDYA, HS_EPOSTA, HS_MESAJ, HS_MOBIL, HS_EORTAM, HS_ETKINLIK, HS_2015, HS_ATM. Verilmezse HS_WEB (uygulama kanalında HS_MOBIL)
note	Hayır	İznin kanıtı (alışverişçinin gördüğü metin); en çok 500 karakter. Yalnızca optIn: true için saklanır

Yanıt, her kayıt için ne olduğunu söyler:

{
  "success": true,
  "received": 3,
  "processed": 3,
  "results": [
    { "index": 0, "status": "resubscribed" },
    { "index": 1, "status": "subscribed" },
    { "index": 2, "status": "unsubscribed" }
  ]
}

status	Anlamı
subscribed	İzin kaydedildi
resubscribed	Daha önce aboneliğini iptal etmiş biri yeniden izin verdi
unsubscribed	İzin geri çekildi
withdrawal_recorded	Hiç görülmemiş bir adres için ret kaydedildi; sonradan gelen bir toplu aktarım bu adresi aboneye çeviremez
unchanged	Kayıt zaten istenen durumdaydı
not_found	Yalnızca siteUserId verildi ama bu müşterinin o türde kaydı yok; izin vermek için value gönderin
invalid	Adres geçersiz
failed	Bu kayıt yazılamadı; diğerleri etkilenmez. Yeniden deneyin

processed, invalid, not_found ve failed dışındaki kayıt sayısıdır. Gövde sınıfla doğrulanır: bilinmeyen bir alan ya da 500'den fazla kayıt tüm isteği 400 yapar.

Durum	Neden
401	x-selwise-api-key başlığı hiç gönderilmemiş
403	Anahtar geçersiz, iptal edilmiş ya da newsletter_subscribe kapsamı yok
404, 403	Site anahtarı yok ya da kanal doğrulanmamış

Bülten kaydı: newsletter

POST /api/v1/public/sites/:siteKey/newsletter

Bülten widget'ının gönderdiği kayıt; kendi formunuzdan da çağırabilirsiniz. Alan adı doğrulaması (ya da anahtar) ister, dakikada 20 istekle sınırlıdır.

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/newsletter \
  -H "Content-Type: application/json" \
  -H "Origin: https://magaza.com" \
  -d '{
    "email": "musteri@ornek.com",
    "fullName": "Ayşe Yılmaz",
    "channels": ["email", "sms"],
    "phone": "+905321112233",
    "locale": "tr",
    "visitorId": "VISITOR_ID",
    "siteUserId": "MUSTERI-1001",
    "sourcePath": "/kampanya",
    "utmSource": "instagram",
    "utmMedium": "story",
    "utmCampaign": "bahar",
    "honeypot": ""
  }'

Alan	Zorunlu	Açıklama
email	Evet	Geçerli adres, en çok 255 karakter
channels	Hayır	email ve/veya sms. Verilmezse yalnızca e-posta. E-posta her durumda kaydedilir; sms listedeyse telefon da kaydedilir
phone	channels içinde sms varsa	E.164 biçiminde (+905321112233), en çok 32 karakter. Geçersizse hiçbir şey kaydedilmez ve 400 döner
fullName	Hayır	En çok 255 karakter
locale	Hayır	en veya tr
visitorId, siteUserId	Hayır	visitorId en çok 120, siteUserId en çok 255 karakter. Müşteri kimliğiniz kişi kaydına bağlanır
sourcePath, referrer, utmSource, utmMedium, utmCampaign	Hayır	Kaynak bilgisi (500, 1000, 120, 120, 160 karaktere kadar). referrer yoksa Referer başlığı kullanılır
honeypot	Hayır	Boş kalmalıdır. Dolu gelen istek bot sayılır ve sessizce başarılı yanıtlanır, hiçbir şey kaydedilmez

Yanıt { "success": true }. Aynı adresin tekrar kaydı atıf bilgisini yeniler ama aboneliğini iptal etmiş birini yeniden abone yapmaz.

Durum	Neden
400	email geçersiz, sms istendi ve phone geçersiz, ya da bilinmeyen alan; ya da Unknown site
429	Dakikada 20 istek aşıldı

Sırada ne var

• Onay Yönetimi — tarayıcı API'si ve banner
• Kişiler — kaydedilen izinler panelde nasıl görünür
• İYS — Türkiye'de ticari ileti izni