Abonelik ve kurulum kilitleri

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 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:

400 TENANT_HEADER_REQUIRED veya 404 TENANT_NOT_FOUND
402 abonelik ya da gecikmiş ödeme kilidi
428 kurulum kilidi
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.

string

Abonelik durumu. Bu kilitte değer expired olur.

string

Kliniğin planı.

string

Deneme bitişi, ödenmiş dönemin sonu ve ek sürenin sonu.

string

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}.

{
  "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.

{
  "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ış

Yeniden denemeyin

402 ve 428 geçici hatalar değildir. Aynı isteği beklemek ya da tekrarlamak sonucu değiştirmez. Oran sınırlarındaki 429 gibi geri çekilme (backoff) uygulamayın; kilit kalkana kadar o klinik için istek göndermeyi durdurun.

Kodu error_code ile ayırt edin

message metni dile göre değişir. Dallanmayı error_code ve HTTP durum koduna göre yapın.

Kliniği askıya alın, diğerlerini sürdürü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.

Kullanıcıyı bilgilendirin

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 sayfasına yönlendirebilirsiniz.

Durumu kilitten etkilenmeyen endpoint'lerle yoklayın

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.

428 için kurulum akışını izleyin

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:

curl -i https://app.flextell.ai/api/v1/appointments \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json"
# HTTP/1.1 402 Payment Required  veya  428 Precondition Required

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

Hatalar

Hata zarfı ve durum kodları.

Hata kodları

Tüm error_code değerleri.

Abonelik ve faturalama

Plan, abonelik ve fatura endpoint’leri.

Klinikler ve X-Tenant

Klinik seçimi ve X-Tenant başlığı.

Başlarken

Kimlik Doğrulama

Çok Kiracılılık

İstek Kuralları

Kaynak Rehberleri

Gerçek Zamanlı

Webhook'lar ve Açık Uçlar

Entegrasyonlar

Rehberler

Kaynaklar

Abonelik ve kurulum kilitleri

Kilit türleri

Hangi istek hangi kontrole takılır

402 yanıtları

`SUBSCRIPTION_REQUIRED`

`ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT`

428 kurulum gerekli

Kimler etkilenir

Kilidi kaldırma

Kilitten etkilenmeyen endpoint’ler

Abonelik kilidinde (`402`) açık kalanlar

Kurulum kilidinde (`428`) açık kalanlar

Önerilen davranış

İlgili sayfalar

Hatalar

Hata kodları

Abonelik ve faturalama

Klinikler ve X-Tenant

​Kilit türleri

​Hangi istek hangi kontrole takılır

​402 yanıtları

​SUBSCRIPTION_REQUIRED

​ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT

​428 kurulum gerekli

​Kimler etkilenir

​Kilidi kaldırma

​Kilitten etkilenmeyen endpoint’ler

​Abonelik kilidinde (402) açık kalanlar

​Kurulum kilidinde (428) açık kalanlar

​Önerilen davranış

​İlgili sayfalar

Hatalar

Hata kodları

Abonelik ve faturalama

Klinikler ve X-Tenant

Kilit türleri

Hangi istek hangi kontrole takılır

402 yanıtları

`SUBSCRIPTION_REQUIRED`

`ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT`

428 kurulum gerekli

Kimler etkilenir

Kilidi kaldırma

Kilitten etkilenmeyen endpoint’ler

Abonelik kilidinde (`402`) açık kalanlar

Kurulum kilidinde (`428`) açık kalanlar

Önerilen davranış

İlgili sayfalar