Başlarken

Bu rehber zinciri bir kez, server-side uçtan uca yürütür: bir ürün oluşturun, plan ile fiyatlandırın, müşteriyi upsert edin, kart kaydedin, aboneliği başlatın ve durumu teyit eden webhook'ları dinleyin. Tüm çağrılar https://api-gateway.lunixi.com adresine erişim token'ınızla (Authorization: Bearer at_live_…) yapılır; tüm listeleme endpoint'leri pageSize / pageToken ile sayfalanır.

Tutarlar minor-unit (kuruş) integer'dır: "price": 49900 = ₺499,00.

Ürün oluşturun

Ürün, satılan şeydir; fiyatları ona planlar bağlar.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/products \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "pro",
    "name": "Pro",
    "description": "Büyüyen ekipler için"
  }'

Plan oluşturun

Plan; fiyatı, para birimini, opsiyonel deneme süresini ve billing kuralını — faturanın hangi ritimde üretileceğini — taşır.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/plans \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "<product-id>",
    "code": "pro-monthly",
    "name": "Pro Aylık",
    "price": 49900,
    "currency": "TRY",
    "trialPeriodDays": 7,
    "billing": {
      "frequency": "MONTHLY",
      "interval": 1,
      "timezone": "Europe/Istanbul",
      "lastDayOfMonthFix": true
    }
  }'

Dunning alanları (maxDunningAttempts, dunningScheduleDays, gracePeriodDays) ve billing kuralının tamamı için Planlar sayfasına bakın.

Müşteriyi upsert edin

Müşteriler sizin externalId'nizle anahtarlanır ve PUT ile oluşturulur — istediğiniz kadar çağırın, aynı external id her zaman aynı müşteriye çözülür. "Bu kullanıcıyı daha önce oluşturmuş muydum?" takibi yok.

curl -X PUT https://api-gateway.lunixi.com/api/v1/subscriptions/customers \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-8421",
    "name": "Ayşe",
    "surname": "Yılmaz",
    "email": "[email protected]",
    "gsmNumber": "+905550000000"
  }'

Sonrasında kendi anahtarınızla GET /api/v1/subscriptions/customers/by-external/user-8421 üzerinden erişebilirsiniz.

Kart kaydedin

Kart verisi sunucunuza asla uğramaz: kartı tarayıcıda güvenli kart formuyla toplayın (Portal SDK'nın cardForm'u veya hosted checkout formu) — form size bir paymentMethodToken döndürür. Ardından kartı müşteriye kaydedin:

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/cards \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customer-id>",
    "paymentMethodToken": "<kart-formundan-gelen-token>",
    "brand": "VISA",
    "bin": "454360",
    "last4": "1234",
    "expireMonth": 12,
    "expireYear": 2028,
    "isDefault": true
  }'

⚠️

Kart kaydı 3DS ister. Kart sahibi, kayıt sürecinin parçası olarak 3D Secure ile doğrulanır — doğrulanmamış kart vault'a giremez. Zamanlamayı verificationMode ile kontrol edin: ON_ADD kayıt anında doğrular, FIRST_CHARGE doğrulamayı ilk çekime erteler.

Aboneliği oluşturun

Parçaları birleştirin: müşteri + plan + tahsilat yöntemi. idempotencyKey zorunludur — aynı key ile tekrarlanan istek asla ikinci bir abonelik oluşturmaz.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customer-id>",
    "planId": "<plan-id>",
    "idempotencyKey": "sub-user-8421-pro-monthly-001",
    "collectionMethod": "AUTO_CHARGE",
    "paymentCardId": "<card-id>"
  }'

7 günlük deneme süresiyle abonelik trial durumunda başlar ve otomatik dönüşür; hemen faturalamak için skipTrial: true gönderin.

Webhook'ları dinleyin

Polling yapmayın — tepki verin. İlk etapta önemli iki event:

Event	Ne zaman
`subscription.created`	Abonelik kaydı oluştu (trial'da olabilir).
`subscription.activated`	Abonelik canlı — erişimi şimdi açın.

İlerleyen aşamada subscription.trial_will_end, invoice.paid, invoice.payment_failed ve subscription.canceled event'lerini de isteyeceksiniz. Endpoint kurulumu ve imza doğrulaması için Webhooks sayfasına bakın.

Hatalar

Durum	Anlamı	Ne yapmalı
`400`	Doğrulama hatası (eksik `idempotencyKey`, hatalı `billing` kuralı, negatif `price`…)	İstek gövdesini düzeltin; yanıt hatalı alanları listeler.
`401`	Eksik veya geçersiz API key	`Authorization: Bearer at_live_…` gönderin.
`404`	Referans verilen nesne bulunamadı (`productId`, `planId`, `customerId`, `paymentCardId`)	Önce bağımlılığı oluşturun — yukarıdaki adım sırasını izleyin.
`409`	Çakışma (mükerrer `code`, farklı gövdeyle idempotency tekrarı)	Yeni bir `code` / yeni bir `idempotencyKey` kullanın ya da orijinal gövdenin birebir aynısını gönderin.

Sonraki adımlar

Pricing & Portal SDK — yukarıdakilerin tamamını kendi pricing sayfanızdan yapın
Abonelikler — iptal, duraklatma, devam ettirme, plan değişikliği
Faturalar — başarısız çekimi yeniden deneyin, fatura void edin
Kullanım & Entitlement — metered özellikler ve kota kontrolleri

Genel Bakış Pricing & Portal SDK