Marketplace API

Marketplace, bir tenant’ın tek tek satın alabileceği ürünlerin kataloğudur. Ücretsiz çekirdek her tenant’a bir yetki tabanı verir; katalog ürünleri bu tabanı artırır (ek şube, e-Fatura entegrasyonu, gelişmiş raporlar, AI kontörü gibi). Plan, tier ya da paket yoktur; ücretli her yetenek yıllık lisans (license_annual) ön koşuluyla satılır.

Bir ürün satın alındığında bir TenantAddOn satırı oluşur ve entitlement projektörü o satırın grants haritasını tenant’ın mevcut hak setine katar (fold). Kombinleme kuralı anahtar önekine göre değişir:

Tüm uçlar /api global ön eki altındadır. Fiyatlar TRY cinsindendir ve kataloğda kuruş (priceCents) olarak tutulur: 490000 = ₺4.900,00. Tutarlar KDV dahil (gross) gösterilir. Taban URL, kimlik realm’leri, hata zarfı ve rate-limit katmanları için API Temelleri sayfasına bakın.

Uçlar

Bunlar tenant-seviyesi uçlardır: X-Branch-Id beklemezler. Checkout intent ve iptal ucu para/hak hareketi yaptığı için buna göre korunur.

Kataloğu listele

Katalog herkese açıktır (landing sitesinde de görünür); kimlik doğrulama gerektirmez. Yalnızca published durumundaki ürünler döner ve her satır UI için kırpılmıştır.

# Tüm published ürünler
curl https://hummytummy.com/api/v1/marketplace/addons
 
# kind ile filtrele: license | module | integration | capacity | credit | service
curl "https://hummytummy.com/api/v1/marketplace/addons?kind=integration"

const res = await fetch(
  "https://hummytummy.com/api/v1/marketplace/addons?kind=integration",
);
const addons = await res.json();

Yanıt:

[
  {
    "code": "module_inventory",
    "name": "Stok & Maliyet Yönetimi",
    "description": "Reçete, stok sayımı, satın alma siparişi, fire takibi, tedarikçi yönetimi ve şubeler arası transfer.",
    "kind": "module",
    "billing": "annual",
    "priceCents": 390000,
    "currency": "TRY",
    "deps": [],
    "requiresLicense": true,
    "creditKind": null,
    "creditUnits": null,
    "maxQuantity": null,
    "sortOrder": 11,
    "i18n": { "tr": { "name": "…", "description": "…" }, "en": { "…": "…" } }
  }
]

Katalog özeti

Tüm sellable ürünler tek bakışta. Açtığı sütunu burada yalnızca referans için gösterilir; public katalog payload’ının parçası değildir. Ayrıntılar için Yetki Matrisi.

Emekliye ayrılmış kodlar (kds_extra_screen, kds_extra_station, extra_tablet) arşivlendi, silinmedi: MarketplaceAddOn.code yeniden kullanılamaz ve TenantAddOn.addOnId onDelete: Restrict taşır. Üçü de hiçbir kodun okumadığı limit.kdsScreens / limit.kdsStations / limit.tablets anahtarlarını veriyordu; à-la-carte modeli cihaz kapasitesi fiyatlamasını tamamen bıraktı.

Ürün satın al (checkout intent)

Bir ürün satın almanın tek yolu checkout (PayTR) rayıdır. Ücretli bir ürün, ödeme kanıtı (paymentRef) olmadan asla provize edilmez.

curl -X POST https://hummytummy.com/api/v1/checkout/intent \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": {
      "items": [
        { "type": "addon", "code": "license_annual", "qty": 1 },
        { "type": "addon", "code": "fiscal_hugin", "qty": 1 }
      ]
    },
    "buyer": {
      "email": "[email protected]",
      "name": "Ali Veli",
      "phone": "+905551112233",
      "address": "..."
    },
    "returnUrl": "https://app.hummytummy.com/checkout/done",
    "acceptedDocumentIds": ["<KVKK>", "<MESAFELI_SATIS>", "<IADE>"]
  }'

const res = await fetch("https://hummytummy.com/api/v1/checkout/intent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${jwt}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cart: {
      items: [
        { type: "addon", code: "license_annual", qty: 1 },
        { type: "addon", code: "fiscal_hugin", qty: 1 },
      ],
    },
    buyer: {
      email: "[email protected]",
      name: "Ali Veli",
      phone: "+905551112233",
      address: "...",
    },
    returnUrl: "https://app.hummytummy.com/checkout/done",
    acceptedDocumentIds: [kvkkId, mesafeliSatisId, iadeId],
  }),
});
const { paymentRef, iframeToken, paymentLink } = await res.json();

Satın alınabilirlik ve bağımlılıklar (deps)

Her addon satırı, ödeme alınmadan önce satın alınabilirlik kapısından geçer. Reddedilen satır 409 ile döner ve sepetin tamamı durur:

deps dizisindeki her giriş bir katalog ürün kodudur ve satın alma anında aktif bir sahiplik satırıyla ya da aynı sepetteki bir kardeş satırla karşılanmalıdır. Bugün deps taşıyan ürünler dört kontör paketidir (credit_ai_* → module_ai_studio, credit_sms_500 → sms_integration).

Çift-satın-alma koruması

Aynı ürünü iki kez alıp hiçbir şey kazanmamak engellenir: aynı (tenantId, addOnId, branchId) için aktif bir satır varsa ikinci satın alma ADDON_ALREADY_OWNED ile reddedilir. Kapasite ürünleri adetle alınır, bu yüzden onlarda tavan maxQuantity’dir. Kontör paketleri tüketilir, bu yüzden hiç engellenmez. Eş zamanlı iki satın alma Serializable transaction ile yakalanır; kaybeden işlem yeniden denenebilir bir 409 alır (kart çift çekilmez).

İdempotensi

PayTR retry’leri agresiftir (200 OK dönse bile gövde “OK”/“FAIL” değilse tekrar dener). Çift provizyona karşı çok katmanlı koruma vardır:

Mevcut ürünlerim

Tenant’ın elindeki satırları listeler.

curl https://hummytummy.com/api/v1/marketplace/addons/mine \
  -H "Authorization: Bearer $JWT"

const res = await fetch(
  "https://hummytummy.com/api/v1/marketplace/addons/mine",
  { headers: { Authorization: `Bearer ${jwt}` } },
);
const mine = await res.json();

Her satır ürün kataloğunu (addOn) ve durum/dönem alanlarını taşır:

[
  {
    "id": "ta_01J...",
    "tenantId": "t_01J...",
    "addOnId": "ao_01J...",
    "branchId": null,
    "quantity": 2,
    "pendingQuantity": null,
    "status": "active",
    "activatedAt": "2026-08-13T10:00:00.000Z",
    "currentPeriodStart": "2026-08-13T00:00:00.000Z",
    "currentPeriodEnd": "2027-03-10T00:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "paymentRef": "CK-018f...",
    "chargedCents": 434300,
    "currency": "TRY",
    "origin": "purchase",
    "addOn": { "code": "extra_branch", "name": "Ek Şube", "...": "..." }
  }
]

Ürün iptali

İptal yalnızca ADMIN’e açıktır (faturalandırma kararı). Varsayılan olarak satır dönem sonunda iptal edilir; hemen geri almak için ?immediate=true geçin.

curl -X DELETE \
  https://hummytummy.com/api/v1/marketplace/addons/$TENANT_ADDON_ID \
  -H "Authorization: Bearer $JWT"

curl -X DELETE \
  "https://hummytummy.com/api/v1/marketplace/addons/$TENANT_ADDON_ID?immediate=true" \
  -H "Authorization: Bearer $JWT"

Yalnızca active ve past_due satırlar iptal edilebilir; başka bir durumda istek 400 alır. past_due bir satırda iptal her zaman anında uygulanır — ödenmiş dönemi zaten bitmiştir, dönem sonuna bırakmak grace hakkını canlı tutmaktan başka işe yaramazdı.

İlgili

• Yetki Matrisi — ücretsiz taban, ürün grant’ları, lisans karartması ve ENTITLEMENT_REQUIRED zarfı.
• Lisans & Ödeme API — checkout rayı, orantılı fiyatlama, yıl dönümü, faturalar ve yenileme.
• API Temelleri — taban URL, kimlik realm’leri, hata zarfı, rate-limit katmanları.
• Webhook’lar — giden olayları alın (api_access modülü feature.apiAccess’i açar).
• Operatör deneyimi (panelde ürünlere göz atma, satın alma ve takip): Marketplace yardımı.