Veriyi Hazırlama

Aktarım dosyaları NDJSON biçimindedir: her satır bağımsız bir JSON nesnesi.

Neden NDJSON

Tek bir dev JSON dizisi, okunmak için tamamının belleğe alınmasını gerektirir. NDJSON satır satır işlenir; dosya boyutu ne olursa olsun bellek sabit kalır.

{"customerId":"C-1","email":"ali@ornek.com"}
{"customerId":"C-2","email":"ayse@ornek.com"}

Satırlar arasında virgül yok, dosyanın etrafında köşeli parantez yok.

Kullanıcı kaydı

İki veri seti vardır: kullanıcılar ve siparişler. Kullanıcı dosyasında bir satır bir kişidir ve platformun o kişi hakkında okuduğu her şeyi taşır — kimliği, e-postası, telefonu, adı, özellikleri ve e-posta/SMS izni. Ayrı bir "iletişim listesi" dosyası yoktur: sitenizin kullanıcı dışa aktarımı zaten bunların hepsini tek kayıtta verir.

{
  "customerId": "MUSTERI-1001",
  "email": "ali.yilmaz@ornek.com",
  "phone": "+905321112233",
  "firstName": "Ali",
  "lastName": "Yılmaz",
  "locale": "tr",
  "firstSeenAt": "2019-03-14T09:12:00+03:00",
  "lastSeenAt": "2026-08-30T18:44:00+03:00",
  "traits": {
    "loyalty_tier": "gold",
    "loyalty_points": 4820,
    "city": "İstanbul",
    "birthday": "1990-05-14"
  },
  "consent": {
    "email": {
      "optIn": true,
      "at": "2023-06-18T10:41:00+03:00",
      "source": "2023 bülten formu",
      "evidence": "https://ornek.com/bulten — CRM kaydı #4821"
    },
    "sms": {
      "optIn": true,
      "at": "2024-09-11T12:30:00+03:00",
      "evidence": "Sipariş onay kutusu, KVKK metni v3",
      "iys": "registered"
    }
  }
}

Alan	Zorunlu	Açıklama
customerId	Evet*	Sizin sistemdeki müşteri kimliği; mağazada Selwise.identify() ile geçirdiğinizle aynı olmalı. externalId, userId ve siteUserId adları da kabul edilir. En fazla 64 karakter.
email	Evet*	Düz e-posta. Mesaj gönderilebilmesi için gereken tek biçim budur; şifreli saklanır, hiçbir ekranda tam hâliyle gösterilmez.
emailHash	—	E-postayı paylaşmak istemiyorsanız 64 karakterlik SHA-256 karması. Yalnızca kimlik eşleşmesi içindir — karmaya e-posta gönderilemez.
phone	—	+905321112233 ya da Türkiye yazımıyla 05321112233. SMS için gerekir.
firstName, lastName, fullName	—	Ad. E-postada kişiye adıyla hitap edilir; profil sayfasında özellik olarak görünür. fullName verilmezse ad ve soyaddan oluşur.
locale	—	Dil kodu (tr, en). Mesajdaki fiyatlar bu dile göre biçimlenir.
firstSeenAt	—	Kişinin ilk göründüğü an. Kayıtlı değerle harmanlanır; yalnızca geriye çekebilir.
lastSeenAt	—	Son hareket. Yalnızca ileriye taşıyabilir.
traits	—	Segmentlerde ve senaryolarda kullanacağınız serbest alanlar
consent	—	E-posta ve SMS izni; aşağıda

* customerId ya da email (veya emailHash) — en az biri. customerId yoksa kişi e-postasıyla tanınır; aynı adresle sonradan gelen gerçek kimlik bu kaydı kendine katar. Yalnızca telefonu olan satır kimlik sayılmaz ve reddedilir.

Her alan nereye yazılır

Tek kayıt, platformun kişiyi okuduğu her yere dağıtılır:

Nereye	Ne	Kim okur
Kullanıcı profili	Kimlik, e-posta ve telefon karması, ilk/son görülme	Siparişler, segmentler, senaryolar, profil sayfası
Özellikler	traits, ayrıca firstName, lastName, fullName	Segment ve senaryo koşulları, profil sayfası
İletişim kaydı	Şifreli adres ve numara, ad, dil, izin ve kanıtı, İYS durumu	E-posta ve SMS gönderimi, kişiler ekranı, erişilebilirlik dalı

Adı iki yere birden yazılmasının sebebi budur: e-postadaki ad hitabı iletişim kaydından, profil sayfası ve segmentler özelliklerden okunur.

İzin: consent

"consent": {
  "email": { "optIn": false, "at": "2025-01-20T08:00:00+03:00" },
  "sms":   { "optIn": true, "at": "2024-02-03T16:05:00+03:00", "evidence": "Islak imzalı form", "iys": "registered" }
}

Alan	Zorunlu	Açıklama
optIn	Evet	true izin verildi, false geri çekildi ya da reddedildi
at	Onayda evet	İznin verildiği (geri çekildiği) an
evidence	Onayda evet	İzni neyin kanıtladığı: form bağlantısı, izin metni, imzalı kaydın yeri
source	—	Kendi kelimelerinizle nereden geldiği, örn. "2023 bülten formu"
ip	—	Kaydınızda varsa iznin verildiği IP
iys	—	Yalnızca sms: registered, rejected ya da unknown. Türkiye numaralarına SMS yalnızca registered ise gider.

Kurallar:

• Tarihi ya da kanıtı olmayan onay kaydedilmez. Kişi ve adresi yine aktarılır; o kanalda izinli sayılmaz ve rapor bunu sayar. Gönderen sizsiniz ve kanıt talebi size gelir — tarihsiz bir izni izinli saymak, önceden işaretlenmiş kutunun aynısıdır.
• Ret (false) hiçbir şey gerektirmez ve kalıcıdır: sonradan gelen bir toplu aktarım o adresi abone yapamaz.
• Dosyadaki onay, daha önce kaydedilmiş bir iptali geri almaz. Aboneliğini iptal etmiş biri ancak kendisi yeniden onay verirse (bülten formu, hesap ayarları, e-postadaki bağlantı) abone olur. Rapor bu adresleri ayrıca sayar.
• İzin adresi olan kanal içindir. E-posta izni düz email, SMS izni phone ister; emailHash ile e-posta izni verilemez.
• consent hiç yoksa adres saklanır ama izinsiz kalır — mesaj gönderilmez.

traits neyi kabul eder

Metin, sayı, boolean ve bunlardan oluşan düz listeler saklanır. İç içe nesneler ve 100 karakterden uzun anahtarlar sessizce atılır — satır reddedilmez, o alan yazılmaz. Tarihleri ISO biçiminde yazın ("birthday": "1990-05-14"); doğum günü gibi tarihe bağlı senaryo başlatıcıları bu biçimi okur.

Selwise'in siparişlerden ve ziyaretlerden kendisinin hesapladığı alanların adları — totalOrders, totalRevenue, lastOrderDate, daysSinceLastOrder, firstSeenDate gibi — özellik olarak kullanılamaz: segment koşulu siparişi olmayan kişide gerçek değer yerine sizin değerinizi okurdu. Bu anahtarlar atılır ve raporda listelenir; başka bir adla (crm_totalOrders) gönderin.

Kimlik uzunluğu

customerId platform genelinde sınırlı uzunluktadır. Çok uzun bir kimlik doğrulama adımında reddedilir. Bu sınır bilinçlidir: daha önce uzun kimlikler kabul edilip ilk siparişte veritabanı hatası veriyordu.

Sipariş kaydı

{
  "orderId": "SIP-2024-118412",
  "customerId": "MUSTERI-1001",
  "placedAt": "2024-11-03T14:22:09+03:00",
  "currency": "TRY",
  "status": "delivered",
  "subtotal": 1249.00,
  "discountTotal": 125.00,
  "shippingTotal": 0,
  "taxTotal": 208.17,
  "total": 1124.00,
  "channel": "web",
  "items": [
    {
      "productItemCode": "KM0020801100044",
      "name": "Smart Colour Mascara",
      "quantity": 2,
      "unitPrice": 249.00,
      "totalPrice": 498.00
    },
    { "productItemCode": "KM0018200500011", "quantity": 1, "unitPrice": 626.00 }
  ],
  "metadata": { "storeCode": "TR-034", "couponCode": "WELCOME10" }
}

Alan	Zorunlu	Açıklama
orderId	Evet	Sizin sistemdeki sipariş kodu. Tekrar eden aktarımlarda tekilleştirme bununla yapılır.
placedAt	Evet	ISO-8601 zaman damgası, tercihen UTC offset ile
customerId	—	Alıcının kullanıcı dosyasındaki customerId değeri (siteUserId, userId, externalId de kabul edilir). Yoksa sipariş e-postası üzerinden o adresin sahibi olan kullanıcıya bağlanır; o da yoksa sipariş kullanıcısız kaydedilir. Bkz. Kullanıcılar ve siparişler nasıl eşleşir.
email / emailHash	—	Misafir siparişini kullanıcıya bağlamanın yolu
items	—	Sipariş satırları
total	Koşullu	Satır yoksa zorunlu
currency	—	Verilmezse sitenin para birimi kullanılır
status	—	Sizin durum metniniz. İptal/iade anlamına gelenler ciro dışı sayılır.
subtotal, discountTotal, shippingTotal, taxTotal	—	Sipariş kırılımı
channel	—	web, app, store, callcenter
metadata	—	Mağaza kodu, kupon gibi kayıtla saklanacak diğer alanlar

Sipariş satırı alanları

Alan	Zorunlu	Açıklama
productItemCode	Evet	Ürün kodu. productCode, sku, itemCode, productId adları da kabul edilir.
quantity	—	Verilmezse 1
unitPrice	—	price adı da kabul edilir
totalPrice	—	Verilmezse birim fiyat × adet
name	—	Sipariş anındaki ürün adı (title da kabul edilir)

placedAt neden zorunlu

Siparişin gerçek tarihi budur ve tüm raporlar bu tarihe göre çalışır. Verilmezse aktarılan tüm geçmişiniz bugüne tarihlenir ve iki yıllık veri tek güne yığılır.

Ürün kodu

productItemCode alanı, ürün beslemenizdeki item_code ya da sku ile aynı olmalıdır. Bu eşleşme, aktarımın en kritik noktasıdır — doğrulama adımı size oran verir. Bkz. Doğrulama ve Uygulama.

Alan adı esnektir: productItemCode bulunamazsa sırasıyla productCode, sku, itemCode ve productId denenir. Hiçbiri yoksa satır hata vermez — ürün kodu boş kalır ve eşleşme oranı düşer. Bu yüzden doğrulama adımındaki oranı mutlaka okuyun.

Kullanıcılar ve siparişler nasıl eşleşir

Aynı kişi aktarıma birden fazla yoldan gelir: kullanıcı dosyasında bir satır olarak, sonra verdiği her siparişte — bazılarında hesabıyla, bazılarında misafir olarak, yalnızca e-postasıyla. İki dosyayı hangi sırayla aktarırsanız aktarın hepsi tek profilde toplanır. Kurallar şunlar:

1. Müşteri kimliği her zaman kazanır. Kullanıcı satırındaki customerId ile siparişteki customerId aynıysa kayıtlar aynı profile yazılır.
2. Kimliği olmayan satır, adresin sahibine bağlanır. Yalnızca e-postası olan bir sipariş ya da kullanıcı satırı önce aynı dosyada o adresi kullanan bir müşteri kimliğine, sonra daha önce aktarılmış kullanıcılarınıza bakılarak bağlanır.
3. Sahibi henüz yoksa misafir profil açılır. Her adres için tek bir misafir profil oluşur; aynı adresin ikinci misafir siparişi de ona yazılır.
4. Sonradan gelen gerçek kimlik misafir profili kendine katar. Önce siparişleri, sonra kullanıcıları aktardıysanız — ya da bir müşterinin önce misafir, sonra hesabıyla siparişi varsa — misafir profilin siparişleri, özellikleri, segment üyelikleri ve iletişim kaydı gerçek kullanıcıya taşınır ve misafir profil silinir.
5. Canlı iletişim kayıtları da bağlanır. Sitenizin bülten formundan daha önce gelmiş, kimliği olmayan bir e-posta kaydı, aynı adresle aktarılan kullanıcıya bağlanır.
6. Aynı adresi kullanan iki farklı müşteri kimliği birleştirilmez. Tek posta kutusunu paylaşan iki hesap sizin kararınızdır. Rapor bu adresleri sayar; böyle bir adrese sahip misafir satırı en son etkin kullanıcıya bağlanır.
7. Silinmiş kullanıcı geri gelmez. Kanalda silinmiş ya da KVKK/GDPR kapsamında unutulmuş bir kullanıcının profili, adresi ve izni yeniden yazılmaz; ona ait sipariş ciro için yazılır ama kişiye bağlanmaz.

E-postalar karşılaştırılmadan önce boşluklardan arındırılır ve küçük harfe çevrilir: Ayse@Ornek.COM ile ayse@ornek.com aynı adrestir. emailHash gönderiyorsanız karmayı bu biçimde üretin (sha256(küçük_harf(kırpılmış_adres))) — başka türlü üretilmiş bir karma hiçbir kayıtla eşleşmez ve bunu fark ettirecek bir hata da oluşmaz.

Doğrulama raporundaki eşleştirme satırları, uygulama adımının bu kurallarla ne yapacağını önceden söyler: kaç satırın e-postayla bir kullanıcıya bağlanacağını, kaç misafir profilin birleştirileceğini ve kaç adresin birden fazla müşteri kimliğince kullanıldığını.

Dosyayı gönderme

Yöntem	Sınır	Ne zaman
Dosya yükle	50 MB (gzip'li olabilir)	Normal kullanım
URL	2 milyon satıra kadar	Dosya 50 MB'tan büyükse
Satır içi	İstek başına 1000 kayıt	Küçük setler, deneme

Dosya yükleme NDJSON'ı, JSON dizisini ([{…},{…}]) ve {"results": […]} biçimindeki sayfalı dışa aktarımı kabul eder; hepsi yüklenirken satır başına bir kayıt olarak saklanır, rapordaki satır numaraları bu sıraya göredir. Excel ya da CSV dosyası kabul edilmez, önce JSON'a çevrilmesi gerekir.

Yüklenen dosya müşteri verisidir ve yalnızca kullanıldığı süre boyunca saklanır: aktarım başarıyla tamamlandığı anda Selwise'tan silinir. Hiç aktarılmazsa 24 saat sonra kendiliğinden silinir; Dosyayı sil ile hemen de silebilirsiniz. Doğrulama ve aktarım raporları dosya silindikten sonra da kalır.

URL yöntemi için dosyayı HTTPS ile erişilebilir bir yere koyup adresini verirsiniz. İmzalı bir bağlantının sorgu kısmı panelde gösterilmez ve aktarım bitince saklanmaz.

Satır içi yöntemde her istek bir dilim gönderir. Tekrar gönderilen bir dilim güvenlidir: kayıtlar tekil kimliklerine göre yazılır, aynı satır iki kez yazılmaz.

Satır sınırı

Tek bir satır en fazla 1 MB olabilir. Aşırı büyük traits nesneleri bu sınıra takılır.