Migration Genel Bakış

Kullanıcı Migration endpoint'leri, mevcut bir kullanıcı tabanını entegrasyon üzerinden tokenization platformuna aktarmanıza olanak tanır. Standart Kullanıcı Oluştur akışıyla teker teker yapmak yerine, geçiş döneminde toplu olarak kullanıcı eklemek için tasarlanmıştır.

İki Cüzdan Akışı

Platform, kullanıcının halihazırda sahip olduğu bir cüzdan adresini kullanabilir veya kullanıcı adına yönetilen (custodial) bir cüzdan üretebilir. Migration endpoint'leri bu eksen üzerinden ikiye ayrılır:

Akış	Ne zaman kullanılır	Endpoint'ler
Cüzdanlı	Kullanıcının zaten bir cüzdan adresi var (kendi cüzdanı veya başka bir sistemden gelen).	/migrate/with-wallet, /migrate/with-wallet/bulk, /migrate/with-wallet/csv
Cüzdansız	Platformun kullanıcı için cüzdan üretmesi gerekiyor (asenkron).	/migrate/without-wallet, /migrate/without-wallet/bulk, /migrate/without-wallet/csv

Her akışın üç taşıma modu vardır:

• Tekil — Tek bir kullanıcı nesnesi içeren JSON gövdesi.
• Toplu (Bulk) — En fazla 500 kullanıcı içeren JSON dizisi; satır bazlı sonuç döner.
• CSV — Multipart yükleme (form alanı file); satır bazlı sonuç döner. Maksimum dosya boyutu: 5 MB, maksimum satır: 500.

Kimlik Kuralları (KVKK Uyumlu)

Kişisel bilgiler (email, name, surname) migration'da opsiyoneldir. Her satırda aşağıdaki iki tanımlayıcıdan en az biri bulunmalıdır:

• email — standart tanımlayıcı.
• external_id — sizin sisteminizdeki opak (anonim) tanımlayıcı; KVKK / GDPR gereği kişisel veri saklanamadığında kullanılır.

İkisi birlikte de gönderilebilir. Tanımlayıcı kombinasyonuna göre davranış:

email	external_id	Sonuç
✓	—	Klasik mod — email/name/surname saklanır.
—	✓	KVKK modu — yalnızca external_id saklanır. email, name, surname saklanmaz.
✓	✓	Hibrit mod — ikisi de saklanır. Duplicate kontrolü ikisi üzerinde de çalışır.
—	—	Satır missing_email_and_external_id nedeniyle reddedilir.

Cüzdanlı endpoint'lerde, kimlik moduna bakılmaksızın wallet_address her zaman zorunludur.

KYC Davranışı (kyc_sent)

Her migration satırı, kullanıcının önceki sisteminizde KYC sürecinin tamamlanıp tamamlanmadığını belirten kyc_sent alanını taşır.

kyc_sent	Platform ne yapar
false (varsayılan)	Standart akış — platform bu kullanıcı için KYC token event'i yayınlar.
true	Kullanıcı zaten KYC doğrulanmış kabul edilir (kyc.is_verified=true, kyc.token_sent=true) ve KYC event'i yayınlanmaz. Cüzdansız akışta, cüzdan üretim event'i downstream consumer'a skip_kyc=true olarak iletilir.

Duplicate Yönetimi

Satır bazlı duplicate kontrolleri kullanıcı oluşturulmadan önce çalışır. Duplicate satır başarısız değil, atlanmış (skipped) olarak işaretlenir — böylece tek bir hatalı satır toplu yüklemeyi durdurmaz.

Reason	Koşul
duplicate_email	Aynı email'e sahip bir kullanıcı zaten var.
duplicate_external_id	Aynı external_id değerine sahip bir kullanıcı zaten var (trim normalize edilir).
duplicate_wallet	(yalnızca cüzdanlı) Aynı cüzdan adresine sahip bir kullanıcı zaten var (büyük/küçük harf duyarsız).
missing_email_and_external_id	Tanımlayıcılardan hiçbiri gönderilmedi.

Toplu Yanıt Yapısı

Tüm bulk ve CSV endpoint'leri aynı yanıt yapısını döner — toplam sayaçlar ve satır bazlı sonuçlar:

{
  "total": 3,
  "success": 2,
  "skipped": 1,
  "failed": 0,
  "results": [
    { "email": "a@example.com", "user_id": "6913872755654191dede37da", "status": "created" },
    { "external_id": "EXT-1",    "user_id": "6913872755654191dede37db", "status": "created" },
    { "email": "dup@example.com", "status": "skipped", "reason": "duplicate_email" }
  ]
}

• status ∈ created | skipped | failed.
• reason yalnızca skipped ve failed satırlarda bulunur; created'da yer almaz.
• user_id yalnızca created satırlarda bulunur.
• email veya external_id (veya ikisi) her zaman bulunur — satırın kimliğini yansıtır.

Tekil Modda Hata Durumları

Tekil (bulk olmayan) endpoint'lerde, duplicate ve eksik kimlik hataları satır bazlı rapor yerine HTTP 400 ile aynı reason metnini içeren bir hata mesajı döner.

Yetkilendirme

Tüm migration endpoint'leri geçerli bir integration JWT (Authorization: Bearer …) gerektirir ve diğer integration API'leri ile aynı client/mTLS/IP/rate/usage middleware kurallarına tabidir. Detaylar için Integration Genel Bakış sayfasına bakınız.