Özellikler & Eklentiler

Özellikler (features), bir planın müşteriye ne hak verdiğini tanımlar — bir anahtar, bir kota ya da ölçülen bir sayaç. Özellikleri planlara bağlarsınız ve çalışma zamanında entitlement API ile uygularsınız. Eklentiler (add-ons) ise tek bir aboneliğe bağlı ek ücret kalemleridir — tek seferlik kurulum ücreti ya da yinelenen koltuk paketi gibi — ve o aboneliğin faturalarında tahsil edilir.

Aşağıdaki tüm endpoint'ler secret key'inizi Bearer token olarak kullanır ve https://api-gateway.lunixi.com/api/v1/subscriptions altındadır. Liste endpoint'leri cursor pagination kullanır (pageSize, pageToken).

Özellik tipleri

Tip	Davranış	`resetPeriodDays`
`BOOLEAN`	Aç/kapa yetenek — müşteri ya sahiptir ya değildir (örn. "SSO girişi")	—
`QUOTA`	Müşterinin tükettiği sabit bir hak; hak bittiğinde entitlement kontrolü başarısız döner	Opsiyonel — hak her N günde sıfırlanır (aylık kota için 30)
`METERED_USAGE`	Ucu açık sayaç; tüketimi siz raporlarsınız, faturaya yansıtılır	Opsiyonel — sayaç penceresi her N günde sıfırlanır

QUOTA "bu müşteri X'i hâlâ yapabilir mi?" sorusuna cevap verir — bir limittir. METERED_USAGE "ne kadar X yaptı?" sorusuna cevap verir — bir faturalama sayacıdır. Her tipin çalışma zamanı davranışı için Kullanım & Entitlement sayfasına bakın.

Özellik oluşturma

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/features \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "api-calls",
    "name": "API calls",
    "type": "METERED_USAGE",
    "resetPeriodDays": 30
  }'

{
  "id": "feat_01JX4A7Q2K",
  "code": "api-calls",
  "name": "API calls",
  "type": "METERED_USAGE",
  "resetPeriodDays": 30
}

code, daha sonra referans verdiğiniz değerdir — plan yapılandırmasında, usage/record ve usage/check-entitlement çağrılarında. Sabit tutun; bir görüntü etiketi değil, API kimliği gibi davranın.

Özellik yönetimi

Method	Path	Ne yapar
`POST`	`/subscriptions/features`	Özellik oluşturur
`GET`	`/subscriptions/features`	Özellikleri listeler (cursor pagination)
`PATCH`	`/subscriptions/features/:id`	İsim, `resetPeriodDays` vb. günceller
`DELETE`	`/subscriptions/features/:id`	Özelliği kaldırır

Çeviriler

Özellik görüntü adları yerelleştirilebilir — müşteri portalı ve hosted pricing yüzeyleri ziyaretçinin locale'ini otomatik seçer:

Method	Path	Ne yapar
`GET`	`/subscriptions/features/:id/translations`	Özelliğin tüm çevirilerini listeler
`PATCH`	`/subscriptions/features/:id/translations/:locale`	Tek locale'in çevirisini yazar/günceller

curl -X PATCH https://api-gateway.lunixi.com/api/v1/subscriptions/features/feat_01JX4A7Q2K/translations/tr \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "API çağrıları" }'

Eklentiler

Bir eklenti (add-on) plana değil, tek bir aboneliğe (subscriptionId) bağlıdır. Müşteriden müşteriye değişen her şey için kullanın: onboarding ücreti, ek koltuklar, premium destek katmanı.

Zorunlu alanlar: subscriptionId, code (kalem için kalıcı tanımlayıcınız), name ve unitAmount.
unitAmount minor-unit (kuruş) integer'dır — 25000 = ₺250,00.
isRecurring: false → bir sonraki faturada bir kez tahsil edilir.
isRecurring: true → eklenti silinene kadar her dönem faturasında tahsil edilir.

⚠️

API genelinde tüm tutarlar minor-unit (kuruş) integer'dır. "unitAmount": 25000 = ₺250,00 — asla ondalık göndermeyin.

Eklenti oluşturma

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/addons \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_01JX5B8R3M",
    "code": "extra-seats-5",
    "name": "Extra seat pack (5)",
    "unitAmount": 25000,
    "isRecurring": true
  }'

{
  "id": "addon_01JX5C1T9P",
  "subscriptionId": "sub_01JX5B8R3M",
  "code": "extra-seats-5",
  "name": "Extra seat pack (5)",
  "unitAmount": 25000,
  "isRecurring": true
}

Eklenti yönetimi

Method	Path	Ne yapar
`POST`	`/subscriptions/addons`	Aboneliğe eklenti bağlar
`GET`	`/subscriptions/addons`	Eklentileri listeler (cursor pagination)
`PATCH`	`/subscriptions/addons/:id`	Tutar, isim veya yinelenme ayarını günceller
`DELETE`	`/subscriptions/addons/:id`	Kaldırır — yinelenen eklentiler sonraki faturalarda görünmez

Hatalar

Durum	Anlamı	Ne yapmalı
`400`	Doğrulama hatası (bilinmeyen `type`, integer olmayan `unitAmount`, eksik `code`)	İstek gövdesini düzeltin; tutarlar minor-unit integer olmalı
`401`	Eksik/geçersiz Bearer key	`Authorization` header'ını ve key ortamını kontrol edin
`404`	Özellik, eklenti veya `subscriptionId` bulunamadı	Id'nin hesabınıza ait olduğunu doğrulayın
`409`	Yinelenen özellik `code` değeri	Özellik kodları benzersizdir — mevcut özelliği kullanın ya da yeni kod seçin

Webhooks

Özellik ve eklenti CRUD işlemleri kendine ait webhook event'i üretmez. Etkileri ilgili event'lerde görünür:

Event	Ne zaman
`usage.recorded`	Metered bir özelliğe kullanım kaydı girildiğinde
`invoice.created`	Dönem faturası oluştuğunda — eklenti kalemleri burada görünür
`plan.updated`	Bir plan (özellik yapılandırması dâhil) değiştiğinde

Teslimat ve imza doğrulaması için Webhooks sayfasına bakın.

Sonraki adımlar

Kullanım & Entitlement — tüketimi kaydedin, kotaları çalışma zamanında uygulayın
Planlar — özellikleri planlara bağlayın, fiyatlandırın
Abonelikler — eklentilerin bağlandığı aboneliği oluşturun
Faturalar — eklenti ücretlerinin yansıdığı yer

Planlar Abonelikler