Kullanım & Entitlement

Çalışma zamanında ürünüzü abonelik motoruna iki endpoint bağlar: usage/record metered bir özelliğin tüketimini raporlar (faturalama), usage/check-entitlement ise bir müşterinin bir özelliği şu anda kullanıp kullanamayacağını sorar (uygulama/enforcement). Özellik tipleriyle birlikte, aynı modelden metered faturalama, sert kotalar ve boolean kapılar elde edersiniz.

Her iki endpoint de secret key'inizi Bearer token olarak kullanır ve https://api-gateway.lunixi.com/api/v1/subscriptions altındadır.

QUOTA vs METERED_USAGE

	`QUOTA`	`METERED_USAGE`
Cevapladığı soru	"Bu müşteri X'i hâlâ yapabilir mi?"	"Ne kadar X yaptı?"
Çalışma zamanı çağrısı	Aksiyondan önce `usage/check-entitlement`	Aksiyondan sonra `usage/record`
Müşteriyi ne zaman durdurur	Hak tükendiğinde (kontrol başarısız döner)	Asla — ölçer, faturaya yansır
Sıfırlanma	Özelliğin `resetPeriodDays` değerinde	Sayaç penceresi `resetPeriodDays`'e göre sıfırlanır
Kıyas için `BOOLEAN`	`check-entitlement` yalnızca plana göre izinli/izinsiz döner	—

Hem sınırlı hem faturalanan bir özellik için ikisini birleştirin: önce entitlement'ı kontrol edin, aksiyon başarılı olunca kullanımı kaydedin.

Kullanım kaydetme (metered billing)

POST /subscriptions/usage/record — METERED_USAGE (veya pencereli QUOTA) bir özellik için tüketim raporlar. idempotencyKey dedupe sağlar: aynı isteği tekrar denemek asla çift saymaz.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/usage/record \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_01JX5B8R3M",
    "featureCode": "api-calls",
    "quantity": 25,
    "idempotencyKey": "req-7f3a91c2"
  }'

Kabul edilen her kayıt bir usage.recorded webhook'u üretir. Kaydedilen miktarlar aboneliğin dönem faturasına yansıtılır.

⚠️

idempotencyKey'i, ölçtüğünüz iş olayından türetin (istek id'niz, job id, mesaj id) — her denemede rastgele değerden değil. Tekrar denemeyi güvenli yapan budur: aynı olay, aynı key, tek sayım.

Entitlement kontrolü (kota uygulama)

POST /subscriptions/usage/check-entitlement — müşteri bazında, bir özelliğin şu anda kullanılıp kullanılamayacağını sorar. BOOLEAN (var / yok) ve QUOTA (hak kaldı / tükendi) özellikleri için çalışır.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/usage/check-entitlement \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_01JX2F9K4T",
    "featureCode": "reports-export"
  }'

{
  "allowed": true,
  "featureCode": "reports-export"
}

Aksiyonu allowed üzerinden kapılayın. Red, müşterinin planında özelliğin olmadığı ya da mevcut pencerede QUOTA hakkının tükendiği anlamına gelir.

Entegrasyon deseni: her çağrıyı kapılayın, başarıdan sonra kaydedin

Sınırlı ve metered bir API özelliği için standart şablon:

Aksiyondan önce kontrol edin

check-entitlement'ı müşteri ve özellik ile çağırın. allowed false ise kendi upgrade mesajınızla reddedin (kendi API'nizde HTTP 402/403).

İşi yapın

Aksiyonu yalnızca entitlement geçtikten sonra çalıştırın.

Başarıdan sonra kaydedin

usage/record'u istekten türetilmiş bir idempotency key ile çağırın — başarısız olmuş iş için asla kullanım kaydetmeyin.

// Express tarzı middleware + handler
async function requireFeature(req, res, next) {
  const r = await fetch(
    'https://api-gateway.lunixi.com/api/v1/subscriptions/usage/check-entitlement',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.LUNIXI_SECRET_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        customerId: req.customer.lunixiId,
        featureCode: 'api-calls',
      }),
    },
  );
  const { allowed } = await r.json();
  if (!allowed) return res.status(402).json({ error: 'quota_exceeded' });
  next();
}
 
app.post('/v1/reports', requireFeature, async (req, res) => {
  const report = await generateReport(req.body);   // asıl iş
 
  await fetch('https://api-gateway.lunixi.com/api/v1/subscriptions/usage/record', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LUNIXI_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: req.customer.subscriptionId,
      featureCode: 'api-calls',
      quantity: 1,
      idempotencyKey: `report-${report.id}`,       // iş olayından türetilmiş key
    }),
  });
 
  res.json(report);
});

Yüksek hacimli yollarda kendi tarafınızda batch'leyin: kısa bir pencerede abonelik başına sayımları toplayın ve toplam quantity + pencereden türetilmiş idempotencyKey ile (örn. api-calls-sub_x-2026-07-06T14:05) tek usage/record gönderin. Daha az çağrı, aynı faturalama sonucu.

Hatalar

Durum	Anlamı	Ne yapmalı
`400`	Doğrulama hatası (eksik `idempotencyKey`, pozitif olmayan `quantity`)	Gövdeyi düzeltin
`401`	Eksik/geçersiz Bearer key	`Authorization` header'ını kontrol edin
`404`	Bilinmeyen `subscriptionId`, `customerId` veya `featureCode`	Id'leri doğrulayın; feature kodları özellik tanımıyla eşleşmeli
`409`	Idempotency çakışması — aynı key, farklı payload	Bir key'i yalnızca birebir aynı olay için tekrar kullanın
`422`	Özellik tipi bu işlemi desteklemiyor (örn. `BOOLEAN` özelliğe kullanım kaydı)	Özelliğin `type` değerini kontrol edin

Webhooks

Event	Ne zaman
`usage.recorded`	Bir kullanım kaydı kabul edildi
`invoice.created`	Kullanımın yansıtıldığı dönem faturası oluşturuldu

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

Sonraki adımlar

Özellikler & Eklentiler — ölçtüğünüz ve kapıladığınız özellikleri tanımlayın
Planlar — özellikleri ve hakları planlara bağlayın
Faturalar — metered kullanımın faturalandığı yer

Faturalar Genel Bakış