Satıcı Onboarding'i

Satıcı kayıt defterinizde oluştuktan sonra; split ödeme alabilmesi için bir başvuru doldurması, kimlik doğrulamasından (KYC) geçmesi ve sözleşmenizi imzalaması gerekir. Bunların hiçbirini siz geliştirmezsiniz: tek bir onboarding token üretirsiniz ve satıcıya ya hosted portal linkini gönderirsiniz ya da akışın tamamını marketplace JS SDK ile kendi sayfanıza gömersiniz — hazır wizard olarak veya tamamen headless bir client olarak.

Onboarding token, tek bir satıcının onboarding'ine kapsamlı bir JWT'dir (varsayılan geçerlilik ~7 gün). Bir API key değildir: yalnızca o satıcının başvurusunu ilerletebilir. Süresi dolduğunda yenisini üretin — ilerleme kaldığı yerden devam eder.

Nasıl çalışır

Onboarding token üretin

Sunucunuzdan POST /marketplace/dealers/{id}/onboarding-token çağırın. Yanıtta token ve paylaşıma hazır hosted portal URL'i döner.

Satıcıya iletin

Hosted URL'i e-postayla gönderin ya da token ile SDK'yı başlatan kendi onboarding sayfanızı açın.

Satıcı akışı tamamlar

Başvuru bilgileri → KYC (Lunixi KYC SDK'sına devredilir) → sözleşme imzası. Dealer aşaması APPLICATION → KYC_PENDING → AWAITING_TERMS → CONTRACT_PENDING şeklinde ilerler.

Şartları girin ve etkinleştirin

Aşama AWAITING_TERMS olduğunda komisyon & payout şartlarını girin (POST /marketplace/dealers/{id}/terms). Satıcı imzaladıktan sonra POST /marketplace/dealers/{id}/activate ile etkinleştirin — aşama COMPLETED olur, satıcının durumu ACTIVE'e döner ve split ödemeye uygun hale gelir.

Onboarding token üretme

curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/dealers/d_8f2a.../onboarding-token \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "url": "https://altbayi.lunixi.com/m/eyJhbGciOiJIUzI1NiIsInR5cCI6..."
}

⚠️

Token'a magic link gibi davranın: elinde tutan herkes, süresi dolana kadar o satıcının başvuru sahibi gibi hareket edebilir. Güvenilir bir kanaldan iletin (satıcının doğrulanmış e-postası veya platformunuzdaki kimliği doğrulanmış bir oturum).

İki entegrasyon modu

Mod A — hosted portal

Satıcıya url değerini olduğu gibi gönderin. altbayi.lunixi.com üzerindeki portal; başvuru formu, KYC yakalama, sözleşme inceleme ve imza dahil onboarding wizard'ının tamamını sizin tarafınızda sıfır kodla render eder. En hızlı yol budur ve çoğu platform için doğru varsayılandır.

Mod B — gömülü SDK

Marketplace SDK'yı kendi sayfanıza yükleyin ve akışı kendi markanız altında yürütün. SDK iki seviye sunar:

Lunixi.marketplace.mount(target, config) — aynı hazır wizard, sizin DOM node'unuzun içinde render edilir.
Lunixi.marketplace.create({ token }) — headless client: her ekranı siz kurarsınız, SDK veriyi ve durum geçişlerini sağlar.

<div id="onboarding-root"></div>
 
<script src="https://cdn.lunixi.com/lunixi-marketplace.min.js"></script>
<script>
  const handle = Lunixi.marketplace.mount('#onboarding-root', {
    token: 'eyJhbGciOi...',          // POST .../onboarding-token yanıtından
    locale: 'tr',                    // varsayılan 'tr'
    theme: 'auto',                   // 'light' | 'dark' | 'auto'
    onStageChange(stage) {
      console.log('satıcı şu aşamada:', stage);
      // APPLICATION → KYC_PENDING → AWAITING_TERMS → CONTRACT_PENDING → COMPLETED
    },
    onCompleted() {
      window.location.href = '/satici/panel?onboarding=tamam';
    },
    onError(err) {
      console.error(err.code, err.message);
    },
  });
 
  // sayfadan ayrılırken handle.unmount()
</script>

Wizard, satıcının güncel aşamasına karşılık gelen fazı render eder — KYC'nin ortasında sekmeyi kapatan satıcı, kaldığı yerden devam eder. KYC adımı Lunixi KYC SDK'sını içeride kendisi compose eder; ayrıca entegre etmezsiniz.

İki mod da altta aynı portal API'siyle konuşur — satıcı hosted portalda başlayıp sonra sizin gömülü sayfanızı açarsa (ya da tersi), durum tutarlı kalır.

Alttaki portal API

SDK her çağrıyı X-Marketplace-Token header'ındaki onboarding token ile doğrular — asla secret key'inizle değil; secret key tarayıcıya ulaşmamalıdır. Referans için, SDK'nın sürdüğü endpoint'ler şunlardır:

Method	Path	SDK'daki karşılığı
GET	`/marketplace/portal/application`	`getApplicationStatus()`
POST	`/marketplace/portal/submit`	`submitApplication(payload)`
POST	`/marketplace/portal/sign`	`signContract(payload)`
GET	`/marketplace/portal/kyc-handoff`	`getKycHandoff()`

Normalde bunları doğrudan çağırmazsınız — SDK (veya hosted portal) çağırır. Ağ loglarında ve CSP allow-list'lerinizde tanıyabilmeniz için listelenmiştir.

KYC handoff

Kimlik doğrulama, marketplace akışının içinde yeniden yazılmamıştır. Başvuru KYC adımına ulaştığında:

SDK (veya portal) getKycHandoff() çağırır ve bu satıcı için aktif bir KYC session referansı alır.
Bu referans Lunixi KYC SDK'sını başlatır; belge yakalama, liveness ve doğrulama akışının kalanı orada yürür.
Doğrulama sonuçlandığında dealer aşaması otomatik ilerler — gömülü wizard'da bu kesintisizdir; headless entegrasyonlar KYC SDK tamamlandıktan sonra getApplicationStatus() ile tekrar sorgular.

Satıcılarınızı Lunixi dışında doğruluyorsanız (dealer oluştururken verificationMode: "EXTERNAL"), sonucu sunucunuzdan POST /marketplace/dealers/{id}/kyc-result ile kaydedin.

Sunucunuzdan ilerlemeyi izleme

Onboarding token satıcının görünümüdür. Kendi tarafınızda aynı başvuruyu secret key'inizle izler ve sürersiniz:

Endpoint	Amaç
`GET /marketplace/dealers/{id}/application`	Güncel aşama + sıradaki aksiyon sahibi
`POST /marketplace/dealers/{id}/terms`	Komisyon & payout şartlarını girme (aşama `AWAITING_TERMS`)
`POST /marketplace/dealers/{id}/submit`	Başvuruyu satıcı adına gönderme (asiste onboarding)
`POST /marketplace/dealers/{id}/sign`	Kanal dışında alınan sözleşme imzasını kaydetme
`POST /marketplace/dealers/{id}/activate`	Son kapı — aşama `COMPLETED`, durum `ACTIVE`

Her geçiş hash-zincirli audit log'a eklenir; herhangi bir satıcının onboarding geçmişinin tamamı yeniden kurulabilir.

Hatalar

Durum	Anlamı	Ne yapmalı
`401`	Onboarding token eksik, geçersiz veya süresi dolmuş (`MARKETPLACE_PORTAL_TOKEN_MISSING` / `MARKETPLACE_PORTAL_TOKEN_INVALID`)	Yeni token üretin (`POST .../onboarding-token`) ve tekrar iletin; ilerleme korunur
`400`	`marketplace.sub_dealer.not_found` — dealer bulunamadı veya size ait değil	Token üretiminde kullanılan dealer id'yi doğrulayın
`400`	`marketplace.onboarding.invalid_stage_transition` — aksiyon güncel aşama için geçerli değil (örn. şartlar girilmeden imza)	`getApplicationStatus()` okuyun ve raporladığı aşamayı render edin

İş kuralı hataları, hata kodu yanıt gövdesinin code alanında olacak şekilde HTTP 400 döner — HTTP durumuna değil koda göre dallanın.

Sonraki adımlar

Başlarken — dealer kayıt defteri, aşamalar ve komisyon kuralları
Split 2D Ödeme — yeni aktifleşen satıcılarınızla tahsilat
İşlemler & Payout — audit log & payout defteri

Başlarken 2D Ödeme