Migration Genel Bakış

Migration endpoint'leri, mevcut bir kullanıcı tabanını Kullanıcı Oluştur ile teker teker oluşturmak yerine toplu olarak platforma aktarır. Hepsi user:create iznini gerektirir.

İki cüzdan akışı

Aktarılan her kullanıcı, satırın chain_id alanında belirttiği zincirde (bir chains ID'si; GET /v2/chains ile listelenir) bir cüzdan alır. Akışlar cüzdanın nereden geldiğine göre ayrılır:

Akış	Ne zaman kullanılır	Platformun kaydettiği	Endpoint'ler
Cüzdanlı	Kullanıcının zaten bir adresi var (kendi saklamalı ya da başka bir sistemden gelen).	Verilen zincirde verilen adresi tutan, kullanıcının e-postası (ya da external_id) ile adlandırılmış kendi saklamalı (self-custody) bir cüzdan (custody: false).	/v2/users/migrate/with-wallet, /with-wallet/bulk, /with-wallet/csv
Cüzdansız	Platform kullanıcı için bir custody cüzdanı oluşturmalı.	Zincirin varsayılan ağında asenkron oluşturulan bir custody cüzdanı (custody: true).	/v2/users/migrate/without-wallet, /without-wallet/bulk, /without-wallet/csv

Adres kullanıcıda değil cüzdanda saklanır: kullanıcı kaydında address alanı yoktur. Cüzdanı Kullanıcı Cüzdanlarını Listele ile okuyun.

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

• Tekil: tek kullanıcı içeren JSON gövdesi; oluşturulan kullanıcıyı döndürür.
• Toplu (Bulk): en fazla 500 kullanıcı içeren JSON gövdesi; satır bazlı sonuç döndürür.
• CSV: multipart yükleme (form alanı file, en fazla 5 MB ve 500 veri satırı); satır bazlı sonuç döndürür.

Kimlik kuralları (KVKK uyumlu)

Kişisel bilgiler (email, name, surname) isteğe bağlıdır. Her satırda şunlardan en az biri bulunmalıdır:

• email: standart tanımlayıcı;
• external_id: kişisel verinin saklanamadığı durumlar (KVKK / GDPR) için sizin sisteminizdeki opak tanımlayıcı.

email	external_id	Sonuç
✓	—	Klasik: e-posta, ad ve soyad saklanır
—	✓	KVKK: yalnızca external_id (ve gönderdiğiniz ad/soyad) saklanır
✓	✓	İkisi de saklanır; tekrar kontrolleri ikisi üzerinde de çalışır
—	—	Satır missing_email_and_external_id ile reddedilir

external_id kırpılır (trim); boş değer gönderilmemiş sayılır.

KYC davranışı (kyc_sent)

kyc_sent	Platform ne yapar
false (varsayılan)	KYC token'ını/token'larını zincirin her ağında cüzdana asenkron olarak gönderir. Cüzdansız akışta bu, cüzdan oluşturulduktan sonra olur.
true	Hiçbir şey göndermez ve cüzdanı zaten KYC doğrulanmış olarak kaydeder: zincirin her ağında (cüzdanlı) ya da zincirin varsayılan ağında (cüzdansız).

KYC kullanıcıda değil cüzdanda tutulur: aktarılan kullanıcının kyc alanı her zaman null olur. KYC'yi Kullanıcı Cüzdanını Getir ile okuyun.

Satır kontrolleri ve sebepler

Kontroller satır bazında, bu sırayla çalışır. Birine takılan satır başarısız değil atlanmış (skipped) sayılır; böylece hatalı tek bir satır toplu aktarımı durdurmaz.

Sebep	Koşul
missing_email_and_external_id	Tanımlayıcılardan hiçbiri gönderilmedi
duplicate_email	Bu e-postaya sahip bir kullanıcı zaten var
duplicate_external_id	Bu external_id değerine sahip bir kullanıcı zaten var
duplicate_wallet	(cüzdanlı) Bir kullanıcının zaten bu adreste bir cüzdanı var (büyük/küçük harf duyarsız karşılaştırılır)
invalid_chain	(cüzdanlı) chain_id hiçbir zinciri göstermiyor

Beklenmeyen bir şey olduğunda (depolama ya da kuyruk hatası, geçerli bir ID olmayan chain_id) satır başarısız (failed) sayılır; reason alanı o zaman serbest metindir.

Cüzdansız akışta zincir, kullanıcı kaydedildikten sonra çözümlenir. Bu yüzden chain_id değeri çözümlenemeyen bir satır, kullanıcı oluşturulmuş ve cüzdansız hâlde başarısız olur. Böyle bir satırı tekrar çalıştırmayın (artık tekrar olarak atlanır); cüzdanı Kullanıcı Cüzdanı Oluştur ile ekleyin.

Toplu yanıt biçimi

Tüm toplu ve CSV endpoint'leri sayımlar ve istek sırasıyla satır başına bir sonuç içeren 200 döndürür:

{
  "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 değeri created, skipped ya da failed olur.
• reason, skipped ve failed satırlarda bulunur.
• user_id yalnızca created satırlarda bulunur.
• email ve external_id satırın tanımlayıcılarını yansıtır; satır göndermediyse alan gelmez.

Tekil modda hatalar

Tekil endpoint'ler atlanan bir satırı satır raporu yerine HTTP 400, 10015 kodu ve message olarak sebep (örneğin "message": "duplicate_email") ile yanıtlar.

Hata biçimi için Hatalar sayfasına bakın.