T-SOFT/Uygulama Geliştirme/Faturalama

Faturalama

Uygulamanız mağazadan ücreti T-SOFT üzerinden alır. Tahsilat ve gelir paylaşımı T-SOFT'ta yürür; kart bilgisi uygulamanıza hiç gelmez. İki yol vardır:

YolNe içinFiyatı nereden belirlersiniz
PlanlarUygulamayı kullanmanın ücreti: ücretsiz, tek seferlik, aylık ya da yıllıkPartner panelinde, uygulamanızın Planlar sekmesinde
Tek seferlik ücretUygulamanın içinde ara sıra satılan şey: kredi paketi, rapor, kurulum hizmetiKodunuzda, Admin API ile; tutarı her seferinde siz gönderirsiniz
Aylık ve yıllık ücretli planlara abonelik, deneme süresi ve kullanıma göre ücret hazırlanıyor. Bu planları bugün tanımlayabilirsiniz ama mağaza seçemez. Yayına alındığında değişiklik günlüğünde duyurulur.

Planlar

Uygulamanızın fiyatını planlarla belirlersiniz. Mağaza sahibi planları uygulama sayfanızda görür ve uygulamayı yüklerken birini seçer. Siz de mağazanın planını Admin API'den okuyup özellikleri ona göre açarsınız.

Plan tanımlama

Planları partner panelinde, uygulamanızın Planlar sekmesinden ekleyin. Her planın adı, KDV hariç fiyatı, dönemi, isteğe bağlı kısa açıklaması ve en fazla 10 özellik maddesi olur.

DönemÖdeme
Aylık (30 gün)Her 30 günde bir
Yıllık (365 gün)Her 365 günde bir
Tek seferlikBir kez ödenir, süresiz kullanılır
  • Fiyata 0 girerseniz plan ücretsiz olur. Bir uygulamanın en fazla bir ücretsiz planı olur.
  • Her dönemde en fazla 4 etkin plan olur. Ücretli plan en az 1 TL'dir.
  • Deneme süresi yalnız aylık ve yıllık ücretli planlarda verilir, en fazla 30 gün.
  • Fiyat değişikliği yalnız yeni mağazalara uygulanır; planı zaten seçmiş mağaza eski fiyattan devam eder.
  • Plan silinmez, arşivlenir. Arşivlenen plan yeni mağazalara gösterilmez; onu seçmiş mağazalar planda kalır.
  • Uygulamanızın T-SOFT'un belirlediği bir market fiyatı varsa plan ekleyemezsiniz; önce market fiyatının kaldırılması için T-SOFT ile iletişime geçin.

Planlarınız tsoftapps.com'daki uygulama sayfanızda ve panelin yükleme ekranında görünür. Planı olmayan uygulama ücretsizdir.

Mağaza planı seçer

Mağaza sahibi uygulamayı yüklerken planlardan birini seçer. Ücretsiz planda yükleme hemen tamamlanır. Tek seferlik ücretli planda mağaza sahibi önce T-SOFT ödeme sayfasında öder; yükleme ödemeden sonra kendiliğinden tamamlanır. Uygulamayı kaldırıp yeniden yükleyen mağaza aynı tek seferlik plan için yeniden ödemez.

Seçilen plan, mağazanın uygulamanızdaki aboneliği olur. Mağazanın en fazla bir etkin aboneliği vardır; başka bir plana geçerse eski abonelik biter, yenisi başlar. Uygulama kaldırılınca abonelik biter.

Aktif planı okuyun

Mağazaya hangi özellikleri açacağınıza aboneliğin planId alanına bakarak karar verin. Plan adı değişebilir; kimlik değişmez.

server/plan.ts
const response = await fetch(`https://${storeDomain}/api/v3/admin/2026-01/integration/app-subscriptions`, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/vnd.api+json",
  },
})

const { data } = await response.json()
const subscription = data[0] ?? null
// subscription?.attributes.planId partner panelindeki planın kimliğidir
const isPro = subscription?.attributes.planId === PRO_PLAN_ID

Liste boşsa mağaza plan seçmemiştir; uygulamanızın planı yoksa liste her zaman boştur. Tüm alanlar için Uygulama abonelikleri.

Plan değişikliğinden haberdar olun

Mağaza bir plan seçince ya da başka bir plana geçince app_subscription.updated olayı gelir. Plan değişiminde iki olay gelir: biten abonelik için cancelled, yenisi için active. Olayın data alanı Aboneliği getirme ucunun döndürdüğü kayıttır.

Olaya config/webhooks ile abone olun; events dizisine app_subscription.updated ekleyin. Uygulama kaldırılınca abonelik biter ama bu olay gönderilmez, çünkü uygulama artık kurulu değildir; kaldırmayı kaldırma bildirimiyle öğrenirsiniz.

Tek seferlik ücret nasıl işler

Uygulama sunucusu      POST /integration/app-one-time-charges  → ücret: pending
Uygulama (iframe)      app.billing.confirm({ id })             → panel onay ekranını açar
Mağaza sahibi          Onayla → T-SOFT ödeme sayfası            → ödeme alınınca: active
                       Reddet                                   → declined
Uygulama               { status } yanıtı + GET ile doğrulama    → hizmeti verin

Uygulamanızın içinde ara sıra satılan şeyler için mağazadan tek seferlik ücret isteyin. Mağaza sahibi ücreti panelin onay ekranında görür, onaylar ve T-SOFT ödeme sayfasında öder. Ücret 48 saat içinde ödenmezse expired olur. Durumların tamamı Uygulama ücretleri sayfasındadır.

Tek seferlik ücret alma

Sunucuda ücreti oluşturun

Ücreti uygulama token'ınızla Admin API'de oluşturun. Tutar KDV hariçtir; KDV, uygulama ilanınızdaki orana göre eklenir ve mağaza sahibine toplamla birlikte gösterilir.

server/charges.ts
const response = await fetch(`https://${storeDomain}/api/v3/admin/2026-01/integration/app-one-time-charges`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/vnd.api+json",
    "Content-Type": "application/vnd.api+json",
  },
  body: JSON.stringify({
    data: {
      type: "app-one-time-charges",
      attributes: { name: "1000 SMS kredisi", price: "49.90", currency: "TRY" },
    },
  }),
})

const { data } = await response.json()
// data.id iframe'e gönderilir; data.attributes.status "pending"

Bu uç nokta kapsam istemez. Tüm alanlar ve hatalar için Ücret oluşturma.

Mağaza sahibine onaylatın

Ücretin kimliğini iframe'deki uygulamanıza verin ve panel köprüsüyle onay ekranını açın. Bunun için @tekrom/tsoft-app-gate 0.7.0 ya da sonraki sürüm gerekir.

app/billing.ts
import { createApp, AppBridgeError } from "@tekrom/tsoft-app-gate"

const app = createApp()

async function buyCredits() {
  const { id } = await fetch("/api/charges", { method: "POST" }).then((r) => r.json())

  try {
    const { status } = await app.billing.confirm({ id })
    if (status === "active") await app.toast("Krediler yükleniyor")
  } catch (error) {
    if (error instanceof AppBridgeError && error.code === "charge_not_found") {
      await app.toast("Ücret bulunamadı", { variant: "error" })
    }
  }
}

Panel ekranda uygulamanızın adını, ücretin adını, KDV hariç tutarı, KDV'yi ve toplamı gösterir. Mağaza sahibi onaylarsa ödeme sayfası aynı pencerede açılır. Pencere kapanınca promise son durumla çözülür:

statusNe oldu
activeÖdeme alındı
declinedMağaza sahibi reddetti
pendingPencere ödeme tamamlanmadan kapatıldı
expiredÜcretin süresi dolmuştu

Çağrının varsayılan zaman aşımı yoktur; ödeme dakikalar sürebilir. Ücret yoksa ya da başka bir uygulamanınsa charge_not_found hatası alırsınız.

Sonucu sunucuda doğrulayın

Köprüden gelen durum yalnız arayüzü güncellemek içindir. Hizmeti vermeden önce ücreti sunucunuzdan okuyun; status değerinin active, test değerinin false olduğunu görün.

GET /integration/app-one-time-charges/{id}
curl 'https://<domain>/api/v3/admin/2026-01/integration/app-one-time-charges/0b5f8a52-3c1e-4d7a-9f00-1a2b3c4d5e6f' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Her ücret için hizmeti bir kez verin; ücretin id'sini kendi kaydınızda saklayıp tekrar işlemeyin. Pencere pending ile kapandıysa ödeme sonradan tamamlanabilir; app_one_time_charge.updated olayı gelince ya da ücreti yeniden okuyarak öğrenirsiniz.

Webhook ile haberdar olun

Ücretin durumu değişince app_one_time_charge.updated olayı gelir: ücret ödendiğinde (active), mağaza sahibi reddettiğinde (declined), süresi dolduğunda (expired) ve ödeme sonradan iade edildiğinde (refunded). İade olayını aldığınızda verdiğiniz hizmeti geri alın. Ödeme penceresi kapandıktan sonra tamamlanan ödemeleri de bu olayla öğrenirsiniz. Ücretin oluşturulması olay üretmez.

Olaya her mağazada, kurulumdan sonra config/webhooks ile abone olun; abonelik write_webhooks kapsamını ister:

{
  "data": {
    "type": "webhooks",
    "attributes": {
      "payloadUrl": "https://sms.example.com/webhooks/tsoft",
      "payloadSecret": "<kendi ürettiğiniz rastgele değer>",
      "format": "2026-01",
      "events": ["app_one_time_charge.updated"]
    }
  }
}

Olayın data alanı, Ücreti getirme ucunun döndürdüğü app-one-time-charges kaydıdır. Olay yalnız kendi ücretleriniz için gelir. İmzayı Webhook'lar sayfasındaki gibi doğrulayın; aynı olay birden çok kez gelebileceği için ücretin id'si üzerinden tek kez işleyin.

Test ücreti

Geliştirirken test: true gönderin. Test ücreti aynı onay ekranından geçer ama ödeme sayfası açılmaz, tahsil edilmez ve gelir paylaşımına girmez; mağaza sahibi onaylayınca doğrudan active olur.

{
  "data": {
    "type": "app-one-time-charges",
    "attributes": { "name": "1000 SMS kredisi", "price": "49.90", "currency": "TRY", "test": true }
  }
}

Test ücreti yalnız partner panelinden oluşturduğunuz geliştirme mağazasında açılabilir; erişim izniyle bağlandığınız müşteri mağazaları dahil başka her mağazada 403 test_charge_not_allowed döner.

Hizmeti vermeden önce test alanının false olduğunu da doğrulayın. test: true bir ücret para çekilmeden active olur; ona gerçek hizmet açmayın.

Gelir

Ödenen her plan ve ücret T-SOFT'ta bir sipariş olarak kaydedilir ve uygulamanızın gelir paylaşımı kuralıyla hak edişinize eklenir. Hak edişinizi ve faturalarınızı partner panelinde görürsünüz.

Sonraki adımlar