Lisans & Ödeme API

Bu sayfa, para ile ilgili her şeyin entegratör referansıdır: katalog fiyatlarını okuma, işletmenin lisans ve ürün durumunu sorgulama, checkout rayından ödeme alma, faturaları okuma ve yenileme döngüsünü izleme. API Temelleri sayfasındaki ortak kuralların (taban URL, auth realm’leri, şube kapsamı, hata zarfı, idempotency, rate-limit’ler) üzerine kurulur.

Kimlik & roller

Bu uçlar Personel JWT realm’ini kullanır (Authorization: Bearer <jwt> — bkz. API Temelleri). Rol gereksinimleri uca göre değişir:

Uç özeti

Fiyat listesini okuma

Katalog herkese açıktır; pazarlama sayfaları da bunu okur, böylece süperadmin panelinden yapılan bir fiyat değişikliği sitede eski fiyatın kalmasına yol açamaz.

curl "https://app.hummytummy.com/api/v1/catalog/pricing?locale=tr"

Her ürün için dönen alanlar:

Ürün kodlarının verdiği yetkiler için Yetki Matrisi’ne bakın.

Lisans durumu ve sahip olunanlar

GET /v1/me/licensing, SPA’nın lisans ekranını tek istekte çizmesini sağlar:

curl https://app.hummytummy.com/api/v1/me/licensing \
  -H "Authorization: Bearer $JWT"

license.status dört değerden biridir:

Yıl dönümü ve orantılı fiyatlama

Lisansın alındığı gün, hesabın değişmez yıl dönümü olur (tenant yerel takvim tarihi; varsayılan Europe/Istanbul). Sonradan alınan her yıllık kalem, yıl dönümüne kalan gün kadar orantılanır — böylece tüm hesap tek tarihte, tek kalemli faturayla yenilenir.

• Yuvarlama birim başına yapılır, sonra adetle çarpılır: unitCents × qty === subtotalCents daima birebir tutar.
• Hiçbir ücretli satır ₺1’in altına inmez (MIN_LINE_CENTS = 100); gerçekten ücretsiz bir kalem ise 0 kalır.
• Döngü uzunluğu 365 veya 366 olarak hesaplanır, sabit değildir; 29 Şubat yıl dönümü artık olmayan yıllarda 28 Şubat’a sıkıştırılır.

KDV dahil fiyatlandırma içi

Katalogdaki tüm fiyatlar brüt (KDV dahil) tutarlardır ve müşteriden tam olarak bu tutar tahsil edilir. Quote, KDV’yi brütün içinden çıkarır; asla üzerine eklemez:

netCents = round(brütSatırToplamı / (1 + oran))
taxCents = brütSatırToplamı - netCents

TRY sepetlerde oran %20’dir. Quote yanıtında subtotalCents net, taxCents içerideki KDV, totalCents ise tahsil edilecek brüt tutardır (donanım varsa kargo dahil).

Checkout rayı

Bir ürünü satın almanın tek yolu checkout (PayTR) rayıdır. Ücretli hiçbir kalem ödeme kanıtı (paymentRef) olmadan provizyonlanmaz.

curl -X POST https://app.hummytummy.com/api/v1/checkout/quote \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "addon", "code": "license_annual", "qty": 1 },
      { "type": "addon", "code": "module_inventory", "qty": 1 },
      { "type": "addon", "code": "extra_branch", "qty": 2 }
    ]
  }'

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

Satın alınabilirlik kapısı (tahsilat öncesi)

Her addon satırı, ödeme alınmadan önce kontrol edilir. Reddedilen satır 409 ile döner ve sepetin tamamı durur — hiçbir intent satırı yazılmaz, PayTR çağrılmaz. Zarf { code, message, addOnCode } taşır:

Diğer tahsilat öncesi retler:

• 409 HARDWARE_OUT_OF_STOCK — donanım satırında yeterli gerçek stok yok (aynı ürünün birden çok satırı toplanarak kontrol edilir).
• 400 — sepet toplamı 0; PayTR sıfır tutarlı sepeti reddeder, ücretsiz provizyon süperadmin comp yolundan yapılır.

İdempotensi

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

Faturalar

Yenileme (manuel)

Kayıtlı kart ve otomatik tahsilat yoktur. Yenileme, aynı checkout rayından elle ödenir.

Yenileme sepeti tam liste fiyatındandır: yıl dönümü anına quote edildiği için kalan gün = döngü günü olur ve orantılama tam fiyatı döndürür. Ödenince aynı TenantAddOn satırı yerinde yeniden etkinleşir — yeni satır açılmaz, sahiplik kimliği ve varsa planlanmış kapasite düşüşü (pendingQuantity) korunur.

İptal

Ürün iptali marketplace rayındadır ve yalnız ADMIN’e açıktır: DELETE /api/v1/marketplace/addons/:id (varsayılan dönem sonu, ?immediate=true ile anında). Ayrıntılar için Marketplace API.

Kaldırılan raylar

Aşağıdaki uçlar v3.3.0’da kaldırıldı; eski entegrasyonlar bunları çağırıyorsa 404 alır:

İlgili

• Yetki Matrisi — ücretsiz taban, ürün grant’ları, katlama kuralları ve ENTITLEMENT_REQUIRED zarfı.
• Marketplace API — katalog listeleme, sahip olunanlar ve iptal.
• API Temelleri — taban URL, auth realm’leri, şube kapsamı, hata zarfı, rate-limit katmanları.
• Webhook’lar — bu raylar onaylandığında tetiklenen ödeme ve checkout olayları.