> ## Documentation Index > Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt > Use this file to discover all available pages before exploring further. # Abonelik ve kurulum kilitleri > Kliniğin aboneliği ya da kurulumu nedeniyle dönen 402 ve 428 yanıtlarını ve entegrasyonunuzun bunlara nasıl tepki vermesi gerektiğini anlatır. Bir klinik aboneliğini yenilemediğinde, ödemesi gecikmiş olduğunda ya da kurulum sihirbazını bitirmediğinde API, o kliniğin verilerine erişen endpoint'lerde işlemi reddeder. Bu sayfa, bu reddin üç biçimini (`402` ve `428`), hangi endpoint'lerin etkilenmediğini ve entegrasyonunuzun nasıl davranması gerektiğini anlatır. Kilit klinik düzeyindedir. Token'ınız ve scope'larınız doğru olsa bile aynı istek, kliniğin durumuna göre `402` ya da `428` ile dönebilir. ## Kilit türleri | HTTP | `error_code` | Neden | `data` içeriği | | - | - | - | - | | `402` | `SUBSCRIPTION_REQUIRED` | Deneme süresi bitti ya da abonelik bitip 14 günlük ek süre de doldu. | Aboneliğin tam özeti | | `402` | `ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT` | Abonelik dönemine ait bir fatura vadesini geçti ve ödenmedi. | `proforma_invoice_id`, `due_date` | | `428` | `SETUP_REQUIRED` | Klinik, zorunlu kurulum adımlarını henüz tamamlamadı. | `next_step` | Hata gövdesi her zaman standart hata zarfıdır: `success: false`, `error_code`, `message` ve `data`. Zarfın ayrıntıları için [Hatalar](/api/istekler/hatalar) sayfasına bakın. Abonelik süresi bittikten sonraki 14 günlük ek sürede ürün erişimi devam eder; bu dönemde kilit yoktur. Yalnızca fazla kullanım kapanır ve kotalar sert sınır olur. Kilit, ek süre de bitince başlar. ### Hangi istek hangi kontrole takılır Kontroller sırayla çalışır ve ilk başarısız olan yanıt döner: 1. `400` `TENANT_HEADER_REQUIRED` veya `404` `TENANT_NOT_FOUND` 2. `402` abonelik ya da gecikmiş ödeme kilidi 3. `428` kurulum kilidi 4. `403` scope veya izin hatası Yani kliniğin aboneliği bitmişse ve kurulumu da eksikse `428` değil `402` alırsınız. `402` çözülmeden `428` görünmez. ## 402 yanıtları ### `SUBSCRIPTION_REQUIRED` Kliniğin deneme süresi ya da aboneliği bittiğinde döner. Mesaj: `Devam etmek için ücretli plan seçin veya aboneliğinizi yenileyin.` `data` alanı, `GET /api/v1/billing/subscription` yanıtıyla aynı abonelik özetidir. Böylece ek bir istek yapmadan durumu okursunuz. Abonelik durumu. Bu kilitte değer `expired` olur. Kliniğin planı. Deneme bitişi, ödenmiş dönemin sonu ve ek sürenin sonu. Sıradaki plan değişikliği varsa onun kodu. `pending_plan_starts_at` ve `pending_plan_paid` alanları eşlik eder. Özetin tamamında ayrıca `renewal_period`, `renewal_notice_days`, `overage_allowed` ve `can_purchase_extras` alanları bulunur. ### `ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT` Yalnızca abonelik dönemine ait faturalarda ve yalnızca ön ödemeli abonelerde döner. Mesaj: `Gecikmiş ödeme tamamlanana kadar erişim kısıtlanmıştır.` * Kilit, vade gününden **ertesi gün** başlar. Vadesi bugün olan fatura kilitlemez. * Fatura ödendiği anda kilit kalkar. * Abonelik başlamadan önceki borçlar, ek paket satın alımları ve deneme klinikleri bu kilide takılmaz. `data.proforma_invoice_id` ile ilgili faturayı okuyabilirsiniz: `GET /api/v1/billing/proforma-invoices/{id}`. ```json theme={null} { "success": false, "error_code": "ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT", "message": "Gecikmiş ödeme tamamlanana kadar erişim kısıtlanmıştır.", "data": { "proforma_invoice_id": 123, "due_date": "2026-10-01" } } ``` `422` ile dönen `SUBSCRIPTION_REQUIRED` bir kilit değildir. Ek paket satın alma ya da kullanıcı sayısı (seat) değiştirme gibi bir işlemin, deneme, ek süre veya bitmiş abonelik nedeniyle reddedildiğini gösterir. Yalnızca o işlem başarısız olur; diğer endpoint'ler çalışmaya devam eder. Kilidi ayırt etmek için HTTP durum kodunu da kontrol edin. Yapay zekâ yanıtı, transkripsiyon, giden WhatsApp mesajı ve dosya depolama gibi kota kontrolü olan işlemler de abonelik bittiğinde ya da ödeme gecikmesi kilidi varken `402` `SUBSCRIPTION_REQUIRED` ile reddedilebilir. Bu yanıtta `data` alanı olmayabilir; dallanmayı `error_code` ve HTTP koduna göre yapın. ## 428 kurulum gerekli Yeni bir klinik, zorunlu kurulum adımlarını bitirene kadar `428` `SETUP_REQUIRED` ile korunur. Mesaj: `Devam etmek için gerekli kurulum adımlarını tamamlayın.` ```json theme={null} { "success": false, "error_code": "SETUP_REQUIRED", "message": "Devam etmek için gerekli kurulum adımlarını tamamlayın.", "data": { "next_step": "clinic_info" } } ``` `data.next_step`, sıradaki tamamlanmamış adımın kimliğidir. Zorunlu adımlar: | Adım | `next_step` değeri | | - | - | | Klinik Bilgileri | `clinic_info` | | İletişim Kanalları | `communication_channels` | | Çalışma Modu | `work_mode` | | Doktor, Ürün ve Tedavi Tanımlama (mod 1) | `doctor_setup` | | Tedavi-Doktor Atama (mod 1) | `treatment_doctor_assign` | | Tedavi Grupları (mod 2) | `treatment_groups` | `room_assistant`, `invoice_integration` ve `bank_accounts` adımları isteğe bağlıdır ve kilidi açmak için gerekmez. ### Kimler etkilenir * Kurulum sihirbazı devreye girdiğinde var olan klinikler tamamlanmış sayıldı. Yalnızca sonradan oluşturulan klinikler `428` görür. * `POST /api/v1/account/tenants` ile oluşturduğunuz her yeni klinik, `GET /api/v1/account/tenants` yanıtında `setup_required: true` ile gelir. Kliniğe istek atmadan önce bu alana bakın. * Kurulum bittikten sonra bir doktoru veya kanalı silmek `428`'i geri getirmez; kilit ilerleme bayrağına bağlıdır. ### Kilidi kaldırma Kurulum, `setup-wizard` endpoint'leriyle ilerler. Bunların hepsi `Manage:SetupWizard` izni ister; okuma için `setup_wizard:read`, yazma için `setup_wizard:write` scope'u gerekir. | Metot | Endpoint | Ne yapar | | - | - | - | | `GET` | `/api/v1/setup-wizard` | İlerlemeyi, adımları, `next_step` ve `setup_required` değerini döndürür. | | `PUT` | `/api/v1/setup-wizard/clinic-info` | Klinik bilgilerini kaydeder ve adımı tamamlar. | | `PUT` | `/api/v1/setup-wizard/work-mode` | Çalışma modunu (1: randevu, 2: ön kayıt formu) kaydeder. | | `POST` | `/api/v1/setup-wizard/doctor/self` | Oturumdaki kullanıcıya doktor rolü verir. | | `POST` | `/api/v1/setup-wizard/steps/{step}/complete` | Kayıtları doğrular ve adımı tamamlar. | | `POST` | `/api/v1/setup-wizard/steps/{step}/skip` | İsteğe bağlı bir adımı atlar. | | `POST` | `/api/v1/setup-wizard/complete` | Kurulumu bitirir. | Kanal, doktor, tedavi ve tedavi grubu gibi kayıtları normal endpoint'lerle oluşturur, sonra ilgili adımı `complete` ile onaylarsınız. Sihirbaz bu kayıtlar için ayrı bir endpoint sunmaz. ## Kilitten etkilenmeyen endpoint'ler Kilit, `X-Tenant` başlığı isteyen klinik endpoint'lerinde uygulanır. Aşağıdakiler kilit sırasında da çalışır. ### Abonelik kilidinde (`402`) açık kalanlar Aboneliği okumak, plan seçmek ve ödemek için gereken `/api/v1/billing/*` endpoint'leri açık kalır: * `GET /billing/subscription`, `/billing/plans`, `/billing/overview`, `/billing/payment-providers`, `/billing/payments`, `/billing/settings` * `POST /billing/subscription/quote` ve `POST /billing/subscription/purchase` * `GET /billing/proforma-invoices` ve fatura altındaki `{id}`, `pdf`, `pay`, `discount-code`, `complete`, `cancel-purchase` işlemleri * `PUT /billing/settings` Şunlar açık kalmaz ve kilitliyken `402` döner: `current-usage`, `usage-history`, `quota-packages`, `seats`, `discount-codes` ve `subscription/plan-change`. ### Kurulum kilidinde (`428`) açık kalanlar Kurulum sırasında şu yol önekleri (alt yollarıyla birlikte) `/api/v1/` altında erişilebilir kalır: `setup-wizard`, `billing`, `tenant`, `account`, `notifications`, `general`, `settings`, `files`, `uploads`, `permissions`, `roles`, `users`, `invitations`, `occupations`, `channels`, `integrations`, `integration-connections`, `doctors`, `assistants`, `rooms`, `treatments`, `treatment-groups`, `form-templates`, `products`, `catalog-products`, `product-brands`, `product-categories`, `warehouses`, `invoices/accounts`, `invoices/series`, `bank-accounts`, `payment-methods`, `tickets`, `panel-tickets`. Bunun dışındaki her klinik endpoint'i kurulum bitene kadar `428` döner. Örneğin `/appointments`, `/customers`, `/leads`, `/conversations`, `/invoices`, `/sales` ve `/tags` bunlar arasındadır. `billing` önekli endpoint'ler hiçbir zaman `428` döndürmez. ## Önerilen davranış `402` ve `428` geçici hatalar değildir. Aynı isteği beklemek ya da tekrarlamak sonucu değiştirmez. [Oran sınırlarındaki](/api/istekler/oran-sinirlari) `429` gibi geri çekilme (backoff) uygulamayın; kilit kalkana kadar o klinik için istek göndermeyi durdurun. `message` metni dile göre değişir. Dallanmayı `error_code` ve HTTP durum koduna göre yapın. Kilit klinik başınadır. Birden çok klinik yönetiyorsanız yalnızca kilitli kliniğin eşitleme ve zamanlanmış işlerini durdurun. İşleri kuyrukta kaybetmeyin; kilit kalktığında kaldığınız yerden devam edin. Kliniğin yöneticisine nedeni gösterin. `SUBSCRIPTION_REQUIRED` için aboneliğin yenilenmesi gerektiğini, `ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT` için gecikmiş faturayı (`due_date`), `SETUP_REQUIRED` için kurulumun tamamlanması gerektiğini söyleyin. Klinik tarafında yapılacaklar için [Abonelik ve kurulum kilidi](/panel/sorun-giderme/abonelik-ve-kurulum-kilidi) sayfasına yönlendirebilirsiniz. `SUBSCRIPTION_REQUIRED` sonrasında `GET /api/v1/billing/subscription` ile durumu sorgulayın; bu endpoint kilit sırasında da açıktır. Durum `expired` olmaktan çıktığında işleri yeniden başlatın. `ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT` için abonelik durumu değişmez; `data.proforma_invoice_id` ile `GET /api/v1/billing/proforma-invoices/{id}` çağırıp faturanın ödendiğini doğrulayın. Başka bir fatura da gecikmişse yeniden `402` alabilirsiniz. Sık yoklamayın, makul aralıklarla sorgulayın. `data.next_step` değerini okuyun, kurulumu o adımdan sürdürün ve `GET /api/v1/setup-wizard` ile ilerlemeyi doğrulayın. Kliniği siz oluşturmadıysanız kurulumu kullanıcıya bırakın; yalnızca `Manage:SetupWizard` iznine sahip kullanıcılar sihirbazı kullanabilir. Örnek bir istemci işleyicisi: ```bash curl theme={null} curl -i https://app.flextell.ai/api/v1/appointments \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Accept: application/json" # HTTP/1.1 402 Payment Required veya 428 Precondition Required ``` ```javascript JavaScript theme={null} async function flextellFetch(path, { token, tenantId }) { const res = await fetch(`https://app.flextell.ai/api/v1${path}`, { headers: { Authorization: `Bearer ${token}`, "X-Tenant": String(tenantId), Accept: "application/json", }, }); if (res.status === 402 || res.status === 428) { const body = await res.json(); // Bu klinik için işleri durdur, kullanıcıyı bilgilendir. throw Object.assign(new Error(body.error_code), { kind: "tenant_locked", code: body.error_code, // SUBSCRIPTION_REQUIRED | ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT | SETUP_REQUIRED data: body.data, }); } return res.json(); } ``` ## İlgili sayfalar Hata zarfı ve durum kodları. Tüm `error_code` değerleri. Plan, abonelik ve fatura endpoint'leri. Klinik seçimi ve `X-Tenant` başlığı. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.