DurumEN
BaşlarkenPayment OrchestratorCüzdanBanka HesaplarıSigortaFraud & Fraud AIIdentitySanctionAutomationSDKDemo
Cüzdan
Son Kullanıcılar
Tekrar Oluşturma

Tekrar Oluşturma

Bu uçları kim çağırır?Dış API (s2s)
Taban yol
/api/v1/wallet
Kimlik
Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, Digest (body varsa), X-Signature. Zaman penceresi ±5 dk, nonce tek kullanımlık, anahtarda IP allow-list olabilir.
Yetki
Anahtarınız cüzdan ürününü ve çağrının gerektirdiği cüzdan iznini taşımalıdır; izni olmayan çağrı 403 WALLET_INSUFFICIENT_SCOPE alır. Uç başına izinler: Anahtar izinleri.
Çapraz yüzey
Bu uçlar zaten s2s yüzeyindedir — kendi sunucunuzdan imzalı olarak çağırabilirsiniz.

POST /api/v1/wallet/end-users iki ayrı koruma taşır:

  1. Idempotency-Key — aynı isteğin iki kez işlenmesini engeller.
  2. Program içi tekillik — bir programda aynı telefonla ya da aynı externalCustomerId ile ikinci bir son kullanıcı oluşmaz.

Mevcut kullanıcı, yeni bir istekle döndürülmez; tekillik ihlali her zaman hata olarak bildirilir. Mevcut kaydı almanın tek yolu aynı Idempotency-Key ile tekrar etmek ya da kullanıcıyı ayrıca okumaktır.

Senaryolar

#DurumSonuç
aAynı Idempotency-Key, aynı body200 — ilk başarılı yanıt aynen döner (aynı endUser.id, aynı defaultWallet). Yeni kayıt oluşmaz.
bAynı Idempotency-Key, farklı body409 WALLET_IDEMPOTENCY_CONFLICT — hiçbir şey değişmez.
cYeni Idempotency-Key, aynı programda aynı telefon409 WALLET_ENDUSER_EXISTS — mevcut kullanıcı döndürülmez.
dYeni Idempotency-Key, aynı programda aynı externalCustomerId, farklı telefon409 WALLET_ENDUSER_EXISTS
eAynı telefon, başka bir programınızdaBaşarılı — o programda ayrı bir son kullanıcı oluşur. Tekillik program içindedir.

a — Aynı anahtar, aynı body

İlk istek başarıyla tamamlandıysa, aynı anahtarla gönderilen her tekrar ilk yanıtı döner. Bu yanıt ilk oluşturma anındaki hâldir; kullanıcı bu arada dondurulduysa tekrar yanıtı bunu göstermez. Güncel durumu detay ucuyla okuyun.

  • İlk istek hâlâ işleniyorsa tekrar 409 WALLET_IDEMPOTENCY_IN_PROGRESS alır. Kısa bir süre sonra aynı anahtarla yeniden deneyin.
  • İlk istek hata ile sonuçlandıysa (örneğin WALLET_ENDUSER_EXISTS) anahtar serbest kalır; aynı anahtarla gönderilen tekrar yeniden değerlendirilir.

"Aynı body" karşılaştırması şu alanlar üzerinden yapılır: programId, accountType, phone, externalCustomerId, corporateAccountId, defaultCurrency. Telefon normalize edildikten sonra karşılaştırılır. displayName, kycRef ve kycLevelCache karşılaştırmaya girmez: bu alanları değiştirip aynı anahtarla tekrar gönderirseniz ilk yanıt döner ve yeni değerler uygulanmaz.

b — Aynı anahtar, farklı body

Yukarıdaki alanlardan biri farklıysa istek 409 WALLET_IDEMPOTENCY_CONFLICT ile reddedilir. Bu, bir anahtarı yanlışlıkla iki farklı müşteri için kullandığınızı gösterir; yeni müşteri için yeni bir anahtar üretin.

c — Aynı telefon, aynı program

Telefon program içinde tekildir. Programda bu telefonla kayıtlı bir son kullanıcı varsa yeni istek 409 WALLET_ENDUSER_EXISTS alır; mevcut kullanıcının bilgileri yanıtta yer almaz.

  • Kontrol kullanıcının durumuna bakmaz: FROZEN ya da CLOSED bir kullanıcının telefonuyla da aynı programda yeni kullanıcı açılamaz.
  • Telefonlar normalize edilmiş rakamlarla karşılaştırılır: +90 532 123 45 67 ile 905321234567 aynıdır, 05321234567 farklıdır. Numarayı her zaman ülke koduyla gönderin.

d — Aynı externalCustomerId, farklı telefon

externalCustomerId de program içinde tekildir. Başka bir telefonla gönderilse bile aynı değer 409 WALLET_ENDUSER_EXISTS alır. Değer büyük/küçük harfe duyarlıdır (A1 ile a1 farklıdır); yalnız baştaki ve sondaki boşluklar kırpılır. externalCustomerId göndermeyen kullanıcılar arasında bu kontrol yapılmaz.

e — Aynı telefon, başka program

Tekillik (program, telefon) ve (program, externalCustomerId) üzerinedir. Aynı kişi birden fazla programınızda ayrı son kullanıcılar olarak bulunabilir; her birinin kendi cüzdanı, bakiyesi ve limitleri vardır.

Önerilen entegrasyon deseni

  1. Anahtarı müşterinizden türetin. Idempotency-Key değerini kendi müşteri kimliğinizden kararlı biçimde üretin (örneğin enduser-crm-88213) ve aynı değeri externalCustomerId olarak da gönderin. Böylece zaman aşımı ya da ağ hatası sonrasında yapılan her tekrar, ilk yanıtı alır.

  2. Rastgele anahtar kullanmayın. Her denemede yeni bir anahtar üretmek tekrarı yeni bir istek yapar; ilk istek başarılı olduysa ikinci deneme 409 WALLET_ENDUSER_EXISTS alır.

  3. Çakışmada kullanıcıyı okuyun. 409 WALLET_ENDUSER_EXISTS aldığınızda kullanıcıyı externalCustomerId ile okuyun:

    curl "https://api-gateway.lunixi.com/api/v1/wallet/end-users/by-external/crm-88213?programId=5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "X-Signature: …"
    • Kayıt dönerse bu sizin müşterinizdir; endUser.id değerini saklayın.
    • 404 WALLET_NOT_FOUND dönerse telefon, programda başka bir externalCustomerId ile (ya da externalCustomerId olmadan) kayıtlı bir kullanıcıya aittir. Bu kaydı otomatik olarak sahiplenmeyin; müşterinizle telefon numarasını doğrulayın ve gerekirse kaydı merchant panelden inceleyin.
⚠️

Bir 409 WALLET_ENDUSER_EXISTS yanıtını "kullanıcı oluşturuldu" olarak yorumlamayın. Yanıt hangi kaydın çakıştığını söylemez; kullanıcıyı yalnız kendi kimliğinizle eşleştirdikten sonra işlem yapın.

OluşturmaListeleme