# Tarif: SaaS aboneliği

> Kriptoyla aylık ya da yıllık plan. Her dönem hatırlatmalı bir fatura; uygulama erişimin kimde olduğunu Perly Pay'e sorar.

Kripto bir cüzdandan çekilemez, bu yüzden abonelik faturayla yenilenir: dönem bitmeden alıcı sıradakini alır, ödenene kadar hatırlatmalar gelir. Otomatik tahsilat yok. Uygulama günleri kendisi saymaz — `entitlements.check`'e sorar.

> **Not:** Asistanla: bu tarifi projende Perly Pay eklentisinin `sell-subscription` skill'i uygular. Çalıştırılabilir örnek, eklenti deposundaki `examples/saas-subscription` (MIT).

## Nasıl çalışır

1. **Plan** — `model: "subscription"` ve `recurring.interval` (`month`, `year`…) ile bir ürün ve fiyat; istersen deneme ve ek süre günleri.
2. **Abonelik** — Müşteri olarak kullanıcıyla bu fiyata kesilen bir fatura, aboneliği ve ilk faturasını açar. Ödenmesi planı etkinleştirir.
3. **Özelliklere erişim** — `entitlements.check({ customer_external_id, product })` → `has_access` ve `ends_at`, sunucuda, her ziyarette ya da kısa bir önbellekle.
4. **Dinle** — `invoice.fulfilled` — ilk ödeme ve her yenileme; `subscription.past_due`, `subscription.unpaid` ve `subscription.ended` — uyarmak ve kapatmak için.
5. **Alıcı için yönetim** — Müşteri portalı bağlantısı (`portalSessions.create`): açık yenilemeyi ödemek, önceden ödemek ya da iptal etmek.

**Subscribe, then gate**

```js
const invoice = await pay.invoices.create(
  { line_items: [{ price: PRO_MONTHLY }], customer: customer.id, metadata: { user: userId }, return_url },
  { idempotencyKey: `subscribe-${userId}-${today}` },
);
redirect(invoice.url); // invoice.subscription is the new subscription

const { has_access } = await pay.entitlements.check({ customer_external_id: userId, product: PRO });
```

Ek süre günleri, plan değişikliği ve durumlar [Subscriptions and reminders](https://pay.perly.io/docs/subscriptions.md) sayfasında.

## Örneği çalıştır

1. **Kur** — `examples/saas-subscription` içinde `npm install` (Node 20.12+).
2. **Anahtar** — `.env.example` dosyasını `.env` olarak kopyala ve test anahtarını (`sk_test_…`) `PERLY_PAY_SECRET_KEY` içine yaz.
3. **Hazırla** — `npm run setup` senin anahtarınla bir ürün ve fiyat oluşturur ve `.env` için kimliklerini yazdırır.
4. **Çalıştır** — README'sinde dediği gibi `npm start` (ya da `npm run dev`).
5. **Cüzdansız öde** — Ana sayfada abone ol, faturada **Simulate payment**'a bas, sonra `/pro?user=you@example.com` adresini aç: Pro dönem sonuna kadar açık.

## Tuzaklar

- "Cüzdanından biz çekeriz" diye söz vermek. Hiçbir şey tahsil edilmez; "faturayla yenilenir" de.
- Eksik ya da uydurma müşteri e-postası: yenileme faturaları ve hatırlatmalar oraya gider.
- Gecikmenin ilk dakikasında erişimi kapatmak. `past_due`'nun ne anlama geldiğine karar ver (ek süre günleri içinde).
- Alıcı ödemeden döndüğünde erişim açmak. "Ödendi" yalnızca doğrulanmış bir `invoice.fulfilled` webhook'u ya da sunucundan bir `entitlements.check` demektir.