> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/metering-ve-billing/entitlements-metering.md). # Entitlement, quota ve kullanım Kangal, ticari özellik erişimini sunucu tarafında uygular. Konsolda bir düğmenin gizlenmesi hiçbir zaman güvenlik veya faturalandırma sınırı değildir. ## Entitlement kataloğu Katalog sürümü `2026-07-15.1` değeridir. Her tenant için açıkça atanmış ve o anda etkin bir plan bulunmalıdır. Kullanılabilir plan ataması yoksa korunan işlemler `402 Payment Required` ve kararlı `plan_required` koduyla başarısız olur. Başlangıç zamanı gelmemiş, süresi dolmuş, bilinmeyen bir plana başvuran veya kullanılamayan katalog sürümü kullanan atama kullanılamaz. ### Özellik anahtarları ve dönemler | Özellik | Anahtar | Dönem | | ------------------- | ------------------------------- | ------------------------ | | Ağ geçitleri | `gateway.manage` | Yaşam boyu kaynak sayısı | | Rotalar | `route.manage` | Yaşam boyu kaynak sayısı | | Eklentiler | `plugin.manage` | Yaşam boyu kaynak sayısı | | AI yapılandırması | `ai_gateway.manage` | Yaşam boyu kaynak sayısı | | AI istekleri | `ai_gateway.runtime` | Takvim ayı, UTC | | Entegrasyonlar | `integration.manage` | Yaşam boyu kaynak sayısı | | Geliştirici portalı | `developer_portal.manage` | Yaşam boyu kaynak sayısı | | Portal uygulamaları | `developer_portal.applications` | Takvim ayı, UTC | ### Plan sınırları `Sınırsız`, özelliğin sayısal bir sınır olmadan etkin olduğu anlamına gelir. | Özellik | Starter | Team | Dedicated Cloud | Self-managed Hybrid | | ------------------------ | -------------------: | ----------------------: | -----------------------: | ------------------: | | Ağ geçitleri | 2 katı/engelleyici | 10 katı/engelleyici | 100 yumuşak/uyarı | Sınırsız | | Rotalar | 100 yumuşak/uyarı | 1.000 yumuşak/uyarı | Sınırsız | Sınırsız | | Eklentiler | 25 katı/engelleyici | 250 katı/engelleyici | Sınırsız | Sınırsız | | AI yapılandırmaları | 10 katı/engelleyici | 100 katı/engelleyici | Sınırsız | Sınırsız | | AI istekleri / ay | 10.000 yumuşak/uyarı | 1.000.000 yumuşak/uyarı | 10.000.000 yumuşak/uyarı | Sınırsız | | Entegrasyonlar | 5 katı/engelleyici | 50 katı/engelleyici | Sınırsız | Sınırsız | | Geliştirici portalı | 1 katı/engelleyici | 1 katı/engelleyici | Sınırsız | Sınırsız | | Portal uygulamaları / ay | 100 yumuşak/uyarı | 10.000 yumuşak/uyarı | Sınırsız | Sınırsız | Plan kodları `serverless_starter`, `serverless_team`, `dedicated_cloud` ve `self_managed_hybrid` değerleridir. ## Uygulama sonuçları | HTTP durumu | Kararlı kod | Anlamı | | ----------------------- | ---------------------- | ------------------------------------------------------------ | | `402 Payment Required` | `plan_required` | Şu anda kullanılabilir bir plan ataması yoktur. | | `403 Forbidden` | `feature_not_entitled` | Plan veya geçersiz kılma, özelliği devre dışı bırakmıştır. | | `429 Too Many Requests` | `quota_exceeded` | Katı/engelleyici kotada kullanılabilir kapasite kalmamıştır. | Günlük veya aylık katı/engelleyici kota yanıtları `Retry-After` içerir. Yaşam boyu kotaların otomatik sıfırlama tarihi yoktur. Yumuşak/uyarı kotaları işleme izin verir ve durumda `warning: true` gösterir. Sınırı olan işlemler yazmadan önce kapasite ayırır; başarılı yazmadan sonra bunu kesinleştirir, hata sonrasında serbest bırakır. Ayırmalar varsayılan olarak beş dakika sonra zaman aşımına uğrar. Eş zamanlı yazmalar aynı son katı/engelleyici kota birimini tüketemez. Bu nedenle `used + reserved`, güncel kullanılabilirliği temsil eder. Kapsanan yaşam boyu kaynağın silinmesi birimi serbest bırakır. Aylık istek ve uygulama sayaçları azaltılmaz. Sınırlı plan atandığında yeni ayırma kabul edilmeden önce mevcut ağ geçitleri, rotalar, eklentiler, AI yapılandırmaları ve entegrasyonlar yaşam boyu kullanıma dahil edilir. ## Yönetici iş akışı Tenant yöneticileri kataloğu, durumu ve kendi tenant geçmişini okuyabilir. Plan atama, geçersiz kılma ekleme veya silme ve kullanım sıfırlama işlemlerini yalnızca super-admin gerçekleştirebilir. ```bash export KANGAL_URL='https://api.example.com' export KANGAL_SUPER_ADMIN_TOKEN='' curl --request PUT "$KANGAL_URL/api/v1/admin/entitlements/assignments/acme" \ --header "Authorization: Bearer $KANGAL_SUPER_ADMIN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "plan_code": "serverless_team", "reason": "Approved order form" }' ``` Atamalar `starts_at` ve `expires_at` içerebilir; bitiş, başlangıçtan sonra olmalıdır. Belgelenmiş bir nedenle geçici özellik geçersiz kılması tanımlayın: ```bash curl --request PUT "$KANGAL_URL/api/v1/admin/entitlements/overrides/acme/plugin.manage" \ --header "Authorization: Bearer $KANGAL_SUPER_ADMIN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "limit": 50, "mode": "hard", "reason": "Temporary migration capacity", "expires_at": "2026-08-01T00:00:00Z" }' ``` Sayısal sınırı kaldırmak için `limit` yerine `unlimited: true` kullanın. Her atama, geçersiz kılma, silme ve kullanım sıfırlama işlemi denetim günlüğüne yazılır. ## Uygulanan işlemler Entitlement kataloğu; ağ geçidi oluşturma, rota oluşturma, eklenti oluşturma ve paket yayımlama veya kurma, AI yapılandırması oluşturma, AI istek çalışma zamanı, entegrasyon kurma, geliştirici portalı yönetimi ve portal uygulaması kaydına uygulanır. Kapsanan yaşam boyu kaynakların silme işlemleri kullanım birimini serbest bırakır. ## Ölçüm veri kalitesi | Kalite | Nasıl üretilir? | Kesinleştirilebilir mi? | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | Kesin | Kanıtlanmış veritabanı snapshot'ından okunan, açık dönem trafik günlükleri ve faturalandırılmış maliyet içeren kesin başarılı AI olayları | Evet | | Tahmini | İstenen aralığa ölçeklenen yedi günlük toplamlar veya faturalandırılmış maliyet yerine tahmini maliyet içeren AI olayları | Hayır | | Kullanılamıyor | Gerekli kaynak okunamıyor veya kesin AI kanıtı eksik | Hayır | Açıkça belirtilen dönemlerde istekler trafik günlüklerinden gelir. AI cache hit, hata, bağlantı kopması ve hata durumlu yanıtlar token veya maliyet eklemez. Başarılı bir AI olayının kesin sayılması için token kullanımı ve negatif olmayan faturalandırılmış maliyet gerekir. ## Kalıcı faturalandırma iş akışları ### Ledger snapshot'ı 1. Tenant, isteğe bağlı ağ geçidi ve `days` ya da açık dönem sınırlarıyla `POST /api/v1/admin/metering-billing/ledger/snapshots` çağrısı yapın. 2. `data_quality`, `billing_eligible`, özet, digest ve sunucunun ürettiği `source_watermark` değerlerini inceleyin. 3. Yalnızca kesin ve uygun taslağı `POST /api/v1/admin/metering-billing/ledger/snapshots/{ledger_id}/finalize` ile kesinleştirin. 4. Kesinleştirilmiş `ledger_id` ile dışa aktarın. ### Faturalandırma dönemini kapatma `POST /api/v1/admin/metering-billing/periods/close`, kesin kullanım dönemini, kesinleştirilmiş faturayı ve reconciliation kanıtını atomik olarak kalıcılaştırır. İstekte açık `period_start` ve `period_end` değerleri zorunludur. ```bash curl --request POST "$KANGAL_URL/api/v1/admin/metering-billing/periods/close" \ --header "Authorization: Bearer $KANGAL_SUPER_ADMIN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "tenant_id": "acme", "period_start": "2026-06-01T00:00:00Z", "period_end": "2026-07-01T00:00:00Z" }' ``` Sunucu kullanım sınırını yakalar. İstemciler normalde `source_watermark` alanını göndermemelidir; yeniden denemeyi doğrulamak için gönderilirse önceki yanıttaki sunucu değerine tam olarak eşit olmalıdır. Aynı kapsam, dönem ve watermark idempotent davranır. Yeniden deneme, ikinci bir aylık slot kullanmadan kısmen kalıcılaşmış kapatmayı tamamlayabilir. ### Faturalandırma dönemi kapatma yetkisi Bir dönemi kapatmadan önce her tenant için faturalandırma etkinliğini, `period_close_enabled` değerini ve `monthly_period_close_quota` kotasını yapılandırın. İşlem durumu endpoint'i dönem kapatmanın etkin olup olmadığını, kapatılmış ve kalan slotları raporlar. Eş zamanlı farklı kapatmalar aynı kota slotunu tüketemez. ## Bütünlük gereksinimleri Kesin snapshot ve dönem kapatma, veritabanı snapshot transaction desteği ister. Kangal tutarlı kullanım sınırını kanıtlayamazsa belirsiz faturayı kesinleştirmek yerine `409` ile işlemi durdurur. Kesinleştirilmiş snapshot'lar değiştirilemez ve canlı olarak yeniden hesaplanmak yerine kalıcı içerikten dışa aktarılır. Digest veya watermark manipülasyonu da erişime kapalı davranır. ## API referansı | İşlem | Endpoint | | --------------------------------- | --------------------------------------------------------------------------- | | Katalog | `GET /api/v1/admin/entitlements/catalog` | | Tenant durumu | `GET /api/v1/admin/entitlements/status?tenant_id={tenant_id}` | | Entitlement geçmişi | `GET /api/v1/admin/entitlements/history?tenant_id={tenant_id}` | | Plan atama | `PUT /api/v1/admin/entitlements/assignments/{tenant_id}` | | Geçersiz kılma tanımlama | `PUT /api/v1/admin/entitlements/overrides/{tenant_id}/{feature_key}` | | Geçersiz kılmayı silme | `DELETE /api/v1/admin/entitlements/overrides/{tenant_id}/{feature_key}` | | Kullanımı sıfırlama | `POST /api/v1/admin/entitlements/usage/{tenant_id}/{feature_key}/reset` | | Ölçüm önizlemesi | `GET /api/v1/admin/metering-billing/summary` | | Ledger snapshot'ı oluşturma | `POST /api/v1/admin/metering-billing/ledger/snapshots` | | Ledger snapshot'ını getirme | `GET /api/v1/admin/metering-billing/ledger/snapshots/{ledger_id}` | | Ledger snapshot'ını kesinleştirme | `POST /api/v1/admin/metering-billing/ledger/snapshots/{ledger_id}/finalize` | | Faturalandırma dönemini kapatma | `POST /api/v1/admin/metering-billing/periods/close` | | Faturalandırma dönemini getirme | `GET /api/v1/admin/metering-billing/periods/{period_id}` | | İşlem durumu | `GET /api/v1/admin/metering-billing/operations/status` | | Fatura dışa aktarma | `GET /api/v1/admin/metering-billing/invoice/export` | ## Sorun giderme | Belirti | Kontrol | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `402 plan_required` | Geçerli bir plan atayın; ardından katalog sürümünü ve atamanın başlangıç/bitiş zamanını doğrulayın. | | `403 feature_not_entitled` | Etkin özelliği ve geçerli geçersiz kılmayı inceleyin. | | `429 quota_exceeded` | Kullanılan ve ayrılmış birimlerin toplamını ve sıfırlama dönemini kontrol edin. | | Plan atandıktan sonra durum zaten sınırın üzerinde | Mevcut yaşam boyu kaynaklar hesaba katılmıştır; kaynak kaldırın veya sözleşme sınırını değiştirin. | | Yumuşak/uyarı kotası işlemi engellemedi | Yumuşak/uyarı modu tasarım gereği uyarır ve aşıma izin verir. | | Ledger kesinleştirme `409` döndürüyor | Veri tahmini veya kullanılamazdır, snapshot kanıtı yoktur, taslak değiştirilmiştir ya da watermark yanlıştır. | | Dönem kapatma `403` döndürüyor | Faturalandırma veya dönem kapatma entitlement'ı devre dışıdır. | | Dönem kapatma aylık kotanın tükendiğini söylüyor | Sonraki UTC ayını bekleyin veya operatörden tenant faturalandırma entitlement'ını değiştirmesini isteyin. | | Önizleme ve entitlement planları farklı | Entitlement ataması tenant düzeyindedir; faturalandırma her ağ geçidinin `plan_code` değerini okur. İki yapılandırmayı uzlaştırın. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/metering-ve-billing/entitlements-metering.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.