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.

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

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

Müşteri kaydı

{
  "externalId": "MUSTERI-1001",
  "email": "ali@ornek.com",
  "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",
    "marketing_consent": true
  }
}

Alan	Zorunlu	Açıklama
externalId	Evet*	Sizin sistemdeki müşteri kimliği. En fazla 64 karakter.
email	—	Düz e-posta. Karma değeri Selwise tarafından üretilir.
emailHash	—	E-postayı göndermek istemiyorsanız 64 karakterlik SHA-256 karması
phoneHash	—	Telefon numarasının SHA-256 karması
firstSeenAt	—	Müşterinin 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 hedefleyebileceğiniz serbest alanlar

* externalId yoksa email veya emailHash'ten türetilir. Üçü de yoksa satır reddedilir.

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. Bir özelliğin segment kurma ekranında görünmemesinin en yaygın sebebi budur.

Kimlik uzunluğu

externalId 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",
  "siteUserId": "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
siteUserId	—	Müşterinin externalId değeri. Yoksa emailHash ile bağlanır; o da yoksa sipariş anonim kaydedilir.
emailHash	—	Misafir siparişini müşteriye bağlamanın tek 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.

Dosyayı gönderme

Yöntem	Sınır	Ne zaman
URL	2 milyon satıra kadar	Normal kullanım
Satır içi	İstek başına 1000 kayıt	Küçük setler, parça parça gönderim

URL yöntemi için dosyayı HTTPS ile erişilebilir bir yere koyup adresini verirsiniz.

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.