Uygulama ücretlendirme

/apps/billing/charges — herhangi bir kurulum (installation) token’ı, scope gerekmez. Ücretlendirme mağazadan hiçbir veri okumaz, bu yüzden verilecek bir izin yoktur; bunun yerine mağaza sahibi her ücreti faturalanmadan önce CIQRA yönetim panelinde onaylar.

Akış

POST /apps/billing/charges — ücreti tanımlarsınız; CIQRA onu pending olarak kaydeder ve bir confirmationUrl döndürür.
Mağaza sahibini confirmationUrl adresine yönlendirin. Uygulamanızı, fiyatı, deneme süresini ve tavanı görür; onaylar veya reddeder. Bağlantı 48 saat geçerlidir; sonra ücret expired olur.
Kararı aşağıdaki webhook’tan ya da GET /apps/billing/charges/{id} ile öğrenirsiniz.
adımdan önce hiçbir şey faturalanmaz. Deneme süreli yinelenen bir ücret, deneme bittiğinde faturalanmaya başlar.

Ücret oluşturma

{ "kind": "recurring", "name": "Pro plan", "amount": 1900, "currency": "usd", "interval": "month", "trialDays": 14 }

Alan	Ayrıntı
`kind`	`one_time`, `recurring` veya `usage_capped`
`name`	mağaza sahibinin gördüğü ad, en fazla 120 karakter
`amount`	küçük birim (kuruş/cent), pozitif, en fazla 10.000.000; `usage_capped` için `0` olmalı (sabit tutarı yoktur)
`currency`	`usd`, `eur` veya `try`
`interval`	yalnız `recurring`: `month` veya `year`
`trialDays`	yalnız `recurring`: 0 ile 365 arası
`cappedAmount`, `terms`	yalnız `usage_capped`: mağaza sahibinin onayladığı tavan (küçük birim) ve kullanımın neye göre ücretlendiği
`returnUrl`	isteğe bağlı; mağaza sahibinin karardan sonra döneceği `https` adresi
`test`	test ücreti için `true`

201 ücreti döndürür: id, kind, status, tutarlar, test, confirmationUrl (beklemedeyken), confirmationExpiresAt, approvedAt, billingOn (deneme bittiğinde) ve createdAt. Stripe referansı asla döndürülmez.

Kullanım kayıtları

POST /apps/billing/charges/{id}/usage-records — Idempotency-Key zorunlu.

{ "description": "1.200 SMS gönderildi", "amount": 2400 }

Ücret onaylanmış bir usage_capped ücreti olmalıdır. Bakiyeyi onaylanan cappedAmount üstüne taşıyacak kayıt 422 cap_exceeded ile reddedilir; bunun yerine daha yüksek tavanlı yeni bir ücret isteyin. Aynı Idempotency-Key ile tekrar gönderim ilk sonucu Ciqra-Idempotent-Replay: true ile döndürür ve hiçbir şey kaydetmez.

İptal

DELETE /apps/billing/charges/{id} bekleyen, yinelenen veya kullanım ücretini durdurur. Uygulamanın kaldırılması tuttuğu tüm ücretleri iptal eder.

Webhook’lar

Kurulumunuzu app_subscriptions.update (yinelenen ve kullanım ücretleri) ve app_purchases_one_time.update (tek seferlik ücretler) olaylarına abone edin. Scope gerektirmezler ve yalnızca ücretin sahibi olan kuruluma gönderilirler — başka bir uygulamaya ya da mağaza sahibinin kendi aboneliklerine asla. Her biri bir ücret oluşturulduğunda, onaylandığında, reddedildiğinde veya iptal edildiğinde gönderilir:

{ "chargeId": "…", "status": "active", "kind": "recurring", "name": "Pro plan", "test": true }

Hatalar

Her ret şu gövdeyle döner: { "error": "…", "code": "…", "fields": { … } } (fields yalnız doğrulamada).

Durum	`code`	Anlamı
`400`	`idempotency_key_required`	kullanım kaydı `Idempotency-Key` olmadan gönderildi
`404`	`not_found`	bu kurulumda böyle bir ücret yok
`409`	`currency_mismatch`	ücretin para birimi, mağazanın faturalandığı para birimi değil
`409`	`billing_not_live`	ücretli talepler canlı değilken test olmayan ücret
`409`	`charge_not_active`	onaylanmamış veya çalışmayan bir ücrete kullanım
`409`	`not_cancellable`	ücret zaten sona erdi
`409`	`idempotency_conflict`	aynı `Idempotency-Key` işleniyor ya da farklı bir kayıt için kullanıldı
`422`	`validation_failed`	reddedilen her alan için `fields`’a bakın
`422`	`cap_exceeded`	kullanım kaydı onaylanan tavanı aşacak
`422`	`not_a_usage_charge`	tek seferlik veya yinelenen ücrete kullanım gönderildi
`503`	`provider_unavailable`	ödeme sağlayıcısı yanıt vermedi; hiçbir şey kaydedilmedi, aynı anahtarla tekrar deneyin