Faturalandırma ve Ödemeler API'si

Çalışma alanı aboneliklerini yönetin, PayTR üzerinden ödemeleri işleyin, faturaları görüntüleyin ve kuponları doğrulayın.

Checkout Başlat

Bir PayTR ödeme oturumu oluşturur ve bir iFrame URL'si döner.

POST /api/workspaces/{slug}/billing/checkout/

İstek Gövdesi:

Alan	Tür	Açıklama
plan_slug	string	Plan tanımlayıcısı (örn. pro, business)
billing_interval	string	month veya year
coupon_code	string	İsteğe bağlı indirim kodu

Yanıt:

{
  "iframe_token": "abc123...",
  "iframe_url": "https://www.paytr.com/odeme/guvenli/abc123...",
  "merchant_oid": "SG-c86cd04d-1712567890123",
  "amount": 9990,
  "currency": "TL"
}

PayTR ödeme formunu görüntülemek için iframe_url değerini bir <iframe> içine gömün.

Aboneliği Getir

Aktif aboneliği ve çalışma alanı limitlerini döner.

GET /api/workspaces/{slug}/billing/subscription/

Yanıt:

{
  "subscription": {
    "id": "sub_id",
    "plan_slug": "pro",
    "status": "active",
    "billing_interval": "month",
    "currency": "TL",
    "amount_per_period": 9990,
    "current_period_start": "2026-04-08T00:00:00Z",
    "current_period_end": "2026-05-08T00:00:00Z",
    "cancel_at_period_end": false
  },
  "limits": {
    "plan_slug": "pro",
    "plan_name": "SetGet Pro",
    "max_users": -1,
    "max_projects": -1,
    "max_storage_gb": 100,
    "ai_tokens_monthly": 50000,
    "features": { "time_tracking": true, "custom_properties": true },
    "is_active": true
  }
}

Abonelik yoksa subscription değeri null olur ve limits ücretsiz katman varsayılanlarını döner.

Aboneliği İptal Et

POST /api/workspaces/{slug}/billing/cancel/

İstek Gövdesi:

Alan	Tür	Açıklama
immediate	boolean	true = hemen iptal, false = dönem sonunda iptal

Faturaları Listele

GET /api/workspaces/{slug}/billing/invoices/?offset=0&per_page=20

Yanıt:

{
  "results": [
    {
      "id": "inv_id",
      "invoice_number": "INV-2026-000001",
      "plan_name": "SetGet Pro",
      "billing_interval": "month",
      "total_amount": 9990,
      "currency": "TL",
      "period_start": "2026-04-08T00:00:00Z",
      "period_end": "2026-05-08T00:00:00Z",
      "created_at": "2026-04-08T12:00:00Z"
    }
  ],
  "total": 1
}

Ödemeleri Listele

GET /api/workspaces/{slug}/billing/payments/?offset=0&per_page=20

Durum bilgisi (pending, success, failed, refunded) dahil ödeme geçmişini döner.

Kuponu Doğrula

POST /api/workspaces/{slug}/billing/validate-coupon/

İstek Gövdesi:

{
  "code": "WELCOME20",
  "plan_slug": "pro",
  "amount": 9990
}

Yanıt:

{
  "valid": true,
  "discounted_amount": 7992,
  "discount_display": "-19.98"
}

PayTR Callback (Webhook)

PayTR, ödeme sonuçlarını bu uç noktaya gönderir. Bu uç noktayı doğrudan çağırmayın.

POST /api/webhooks/paytr/callback/

Bu uç nokta herkese açıktır (kimlik doğrulama gerekmez). PayTR hash imzasını doğrular ve düz metin olarak OK yanıtı döner.

Abonelik Durumları

Durum	Açıklama
trialing	Ücretsiz deneme süresi
active	Ödenmiş ve aktif
past_due	Ödeme başarısız, ödemesiz süre içinde
suspended	Ödemesiz süre dolmuş
canceled	Kullanıcı tarafından iptal edildi
expired	Abonelik dönemi sona erdi