Scope kataloğu

Bir scope, access token’ın hangi endpoint ailelerini çağırabileceğini belirler. Bu sayfa, uygulamanızı oluştururken ve yetkilendirme isteğinde scope parametresini doldururken kullanacağınız tüm scope’ları, her birinin açtığı endpoint’leri ve çağrının başarılı olması için kullanıcıda bulunması gereken izinleri listeler.

Tablolardaki izinler istek doğrulamasından ve politikalardan çıkarılmıştır. Bir endpoint’in kesin izin ve görünürlük kuralı için ilgili kaynak sayfasına bakın. Aksi belirtilmedikçe endpoint yolları https://app.flextell.ai/api/v1 altındadır.

Scope adlandırması

Scope’lar kaynak:eylem biçimindedir.

Parça	Değerler	Not
Kaynak	`customers`, `appointments`, `invoices` …	Çoğu çok kelimeli kaynak alt çizgi kullanır: `customer_forms`, `bank_accounts`. Üç scope tire kullanır: `agent-prompts`, `ai-reports`, `ai-report-schedules`.
Eylem	`read`, `write`	`read` listeleme ve detay okuma, `write` oluşturma, güncelleme ve silme içindir.
Özel eylem	`delete`	Yalnızca `holidays:delete` ve `account:delete`.

Kimlik scope’ları (openid, profile, email, phone) bu biçimi izlemez. Bir endpoint yalnızca kendi eyleminin scope’unu ister. GET çağrıları :read, POST, PUT ve DELETE çağrıları :write ister. Bu yüzden :write tek başına okuma yetkisi vermez.

Scope seçme önerileri

Gerçekten çağıracağınız kaynaklarla başlayın

Entegrasyonunuzun kullandığı kaynakların scope’larını isteyin. Kullanıcı yetkilendirme ekranında istediğiniz scope’ları kaynak adına göre gruplanmış, okuma ve yazma rozetiyle görür. Gereksiz scope istemeyin.

Birlikte gereken scope'ları atlamayın

Bazı endpoint’ler iki scope’u birden ister. Aşağıdaki “Birlikte gereken scope’lar” tablosuna bakın.

Okuma ve yazmayı ayrı düşünün

Yalnızca rapor çeken bir entegrasyon :write scope’u istememelidir. Veri yazan bir entegrasyon genellikle aynı kaynağın :read scope’una da ihtiyaç duyar.

Geçerli scope listesini sorgulayın

Uygulamanızın isteyebileceği scope’ları GET /oauth/scopes ile alın. İstek oauth_clients:read scope’u, View:Client izni ve X-Tenant başlığı ister. Yanıt scope ve description alanlarından oluşur; kimlik scope’ları listede yer almaz.

curl "https://app.flextell.ai/api/v1/oauth/scopes" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Yetkilendirme isteğinde bilinmeyen, devre dışı veya uygulamanıza tanımlı olmayan tek bir scope bile varsa istek tümüyle invalid_scope hatasıyla reddedilir. Yetkilendirme isteğinde scope’lar sessizce düşürülmez.

Scope listesiyle ilgili diğer kurallar:

Uygulamayı oluştururken scopes alanına en az bir uygulama scope’u yazılır. Geçersiz değer 422 OAUTH_SCOPE_INVALID döndürür ve data.invalid_scopes içinde listelenir. Kimlik scope’larını listeye yazmazsınız.
Uygulamanın scope listesini PUT /oauth/clients/{id}/scopes ile değiştirirsiniz. Değişiklik yeni yetkilendirmelerde ve yenilemelerde hemen etkili olur. Verilmiş access token’lar süresi dolana kadar eski scope’larıyla çalışır.
Token yenilerken scope gönderirseniz değerler ilk yetkilendirmenin alt kümesi olmalıdır. Yenileme scope’ları yalnızca daraltır; yeni scope için kullanıcıyı yeniden yetkilendirmeye yönlendirin.
Scope eksikse API 403 FORBIDDEN ve İngilizce Invalid scope(s) provided. mesajını döndürür. Mesaj Accept-Language başlığından etkilenmez.

Birlikte gereken scope’lar

Endpoint	Gereken scope’lar
`/customers/{id}/notes*`	`customers:read` veya `customers:write`, ve `notes:read` veya `notes:write`
`/leads/{id}/notes*`	`leads:read` veya `leads:write`, ve `notes:read` veya `notes:write`
`/customers/{id}/transactions`, `/customer-balances`	`customers:` ve `customer_transactions:`
`/customers/{customerId}/form*`	`customer_forms:read` ve `customers:read`
`/leads/{id}/activities`	`leads:read` ve `activity_logs:read`
`POST /leads/{id}/convert`	`leads:write` ve `customers:write`
`POST /offers/{id}/convert`	`offers:write` ve `sales:write`
`GET /appointments/{id}/sale-items`	`appointments:read` ve `sales:write`
`/bank-accounts/{accountId}/transactions*`	`bank_accounts:` ve `account_transactions:`
`/conversations/{id}/open`	`conversations:read` ve `conversations:write`

Aşağıdaki endpoint’lerde listelenen scope’lardan biri yeterlidir:

Endpoint	Yeterli scope’lar
`GET /channels`, `GET /channels/whatsapp/history-syncs`	`conversations:read` veya `channels:read`
`GET /general/global-search`	`customers:read` veya `leads:read`
`GET /leads/assignable-users`, `GET /leads/reference-sources`	`leads:read` veya `conversations:read`

Kimlik scope’ları

Bu scope’lar kimlik bilgisi içindir ve hiçbir /api/v1 endpoint’ine erişim vermez. Her uygulama için her zaman kullanılabilir; uygulamanızın scope listesine eklemezsiniz.

Scope	Açıklama	Not
`openid`	Kimlik Doğrulama	Olmadan `id_token` dönmez. Yetkilendirme ekranında gösterilmez.
`profile`	Profil bilgileri
`email`	E-posta adresi
`phone`	Telefon numarası

Ayrıntılar için OpenID Connect sayfasına bakın. scope parametresi boş bırakılırsa token hiçbir scope taşımaz.

Kaynak scope’ları

Tablolarda okuma izni ve yazma izni sütunları, ilgili scope ile açılan endpoint’lerin kullanıcıda aradığı izinlerdir. — işareti, endpoint’in scope ve klinik üyeliği dışında izin kontrolü yapmadığını gösterir. Tabloların çoğundaki endpoint’ler X-Tenant başlığı ister; bkz. Klinikler ve X-Tenant. İstisnalar /account endpoint’leri (GET /account/roles hariç) ve bu sayfanın sonunda listelenen scope’suz çağrılardır.

Hasta, lead ve satış ekibi

Scope	Açtığı endpoint’ler	Okuma izni	Yazma izni
`customers:read` / `:write`	`/customers`, `/customer-merges`, `/customers/duplicates`; yazmada hasta kimlikleri ve birleştirme	`View:Customer`	`Create`, `Update`, `Delete`, `Merge:Customer`; kimlik için `*:CustomerIdentity`
`customer_forms:read`	`/customer-forms`, `/customers/{id}/form`	`View:CustomerForm`	—
`customer_transactions:read` / `:write`	`/customers/{id}/transactions`, `/customer-balances`	`View:CustomerTransaction`, `View:CustomerBalances`	`Create`, `Update`, `Delete:CustomerTransaction`
`notes:read` / `:write`	Hasta ve lead notları	`View:Note`	`Create`, `Update`, `Delete:Note`
`leads:read` / `:write`	`/leads`, `/leads/stats`, `/leads/pipeline-summary`, toplu atama ve aşama işlemleri	`View:Lead`	`Create`, `Update`, `Delete`, `Assign`, `Convert:Lead`
`pipelines:read` / `:write`	`/pipelines`, aşamalar	`View:Pipeline`	`Create`, `Update`, `Delete`, `Activate:Pipeline`
`salespeople:read` / `:write`	`/salespeople`, müsait olmama dönemleri	`View:Salesperson`	`Create`, `Update`, `Delete`, `CreateUnavailablePeriod:Salesperson`
`data_erasure_requests:read` / `:write`	`/data-erasure-requests`	`View:DataErasureRequests`	`Create`, `Cancel`, `Retry`, `CopyLink:DataErasureRequests`
`tags:read` / `:write`	`/tags`	`View:Tag`	`Create`, `Update`, `Delete:Tag`
`occupations:read` / `:write`	`/occupations`	`View:Occupation`	`Create`, `Update`, `Delete:Occupation`

Randevu ve klinik kadrosu

Scope	Açtığı endpoint’ler	Okuma izni	Yazma izni
`appointments:read` / `:write`	`/appointments`, `/appointments/calendar`, `/appointments/options/*`, `/appointments/available-slots`; yazmada oluşturma, güncelleme, `cancel`, `revert-cancel`, `complete`, `reschedule`	`View:Appointment`; `available-slots` için `Create` veya `Update:Appointment`; `reschedule/preview` için `BulkReschedule:Appointment`	`Create`, `Update`, `Delete`, `Cancel`, `RevertCancel`, `BulkReschedule:Appointment`
`appointment_reminders:read` / `:write`	`/appointment-reminders`	`View:AppointmentReminder`	`Approve`, `Reject`, `Send`, `Delete:AppointmentReminder`
`holidays:read` / `:write` / `:delete`	`/holidays`	`View:Holiday`	`Create`, `Update:Holiday`; silme için `holidays:delete` ve `Delete:Holiday`
`treatments:read` / `:write`	`/treatments`	`View:Treatment`	`Create`, `Update`, `Delete:Treatment`
`treatment_groups:read` / `:write`	`/treatment-groups`	`View:TreatmentGroup`	`Create`, `Update`, `Delete:TreatmentGroup`
`doctors:read` / `:write`	`/doctors`, doktor tedavileri	`View:Doctor`	`Create`, `Update`, `Delete:Doctor`
`assistants:read` / `:write`	`/assistants`	`View:Assistant`	`Create`, `Update`, `Delete:Assistant`
`rooms:read` / `:write`	`/rooms`	`View:Room`	`Create`, `Update`, `Delete:Room`

Sohbet, kanal ve bildirim

Scope	Açtığı endpoint’ler	Okuma izni	Yazma izni
`conversations:read` / `:write`	`/conversations`, mesajlar, AI önerisi, agent durumu; yazmada sohbet başlatma, arşivleme, mesaj gönderme	`View:Conversation`	`Create:Conversation`, `Archive:Conversation`, `Send:Message`, `ManageAiSuggestions:Conversation`, `ToggleAgent:Conversation`, `ManageTags:Conversation`
`channels:read` / `:write`	`/channels` ve alt kaynakları (WhatsApp, Telegram, widget)	`View:Channel`; bağlantı durumu için `QueryStatus` veya `Update:Channel`; gömme kodu için `CopyLink:Channel`	`Create`, `Update:Channel`; widget token yenileme için `GenerateLink:Channel`
`channel_blacklists:read` / `:write`	`/channel-blacklists`	`View:ChannelBlacklist`	`Create`, `Update`, `Unblock:ChannelBlacklist`
`quick_replies:read` / `:write`	`/quick-replies`, ekli medya	`View:QuickReply`	`Create`, `Update`, `Delete:QuickReply`
`message_templates:read` / `:write`	`/message-templates`	`View:MessageTemplate`	`Create`, `Update`, `Delete:MessageTemplate`
`message_notifications:read` / `:write`	`/message-notifications`	—	—
`notifications:read` / `:write`	`/notifications`	—	—
`announcements:read`	`/announcements`	`View:Announcement`	—
`tickets:read` / `:write`	`/tickets` (Destek Talepleri)	`View:Ticket`	`Create`, `Update`, `Delete:Ticket`
`panel_tickets:read` / `:write`	`/panel-tickets` (Sorun Bildirimleri)	`View:PanelTicket`	`Create:PanelTicket`
`flexy_chat:write`	`/flexy-chat/stream`	—	—

Satış, fatura ve finans

Scope	Açtığı endpoint’ler	Okuma izni	Yazma izni
`sales:read` / `:write`	`/sales`, `/sales/stats`, `/sales/export`; yazmada tahsilat ve stok düşümü	`View:Sale`; dışa aktarma için `Export:Sale`	`Create`, `Update`, `Delete`, `Pay`, `DeductStock:Sale`
`offers:read` / `:write`	`/offers`, `/offers/options/*`, PDF	`View:Offer`	`Create`, `Update`, `Delete`, `Convert:Offer`
`invoices:read` / `:write`	`/invoices`, fatura hesapları, seriler	`View:Invoice`, `Download:Invoice`, `View:InvoiceAccount`	`Create`, `Send`, `Cancel`, `Archive`, `RevertCancel`, `QueryStatus`, `SendEmail:Invoice`
`payment_methods:read`	`/payment-methods`	—	—
`bank_accounts:read` / `:write`	`/bank-accounts`	`View:Account`	`Create`, `Update`, `Delete:Account`
`account_transactions:read` / `:write`	`/bank-accounts/{accountId}/transactions`, `/account-transaction-types`	`View:AccountTransaction`	`Create`, `Update`, `Delete:AccountTransaction`
`billing:read` / `:write`	`/billing/*` (plan, kullanım, proforma, ödeme)	`View:ProformaInvoice`, `View:BillingPayment`, `View:BillingUsage` ve ilgili `View:*` izinleri	`Pay:ProformaInvoice`, `Purchase:BillingQuotaPackage`, `Update:TenantBillingSetting`
`credits:read`	`/credits`, `/credit-usages`	`View:Credit`, `View:CreditUsage`	—

Ürün ve stok

Scope	Açtığı endpoint’ler	Okuma izni	Yazma izni
`products:read` / `:write`	`/products`, `/catalog-products`, `/product-sets`	`View:Product`, `View:ProductSet`	`Create`, `Update`, `Delete:Product`; set için `*:ProductSet`
`product_brands:read` / `:write`	`/product-brands`	`View:ProductBrand`	`Create`, `Update`, `Delete:ProductBrand`
`product_categories:read` / `:write`	`/product-categories`	`View:ProductCategory`	`Create`, `Update`, `Delete:ProductCategory`
`warehouses:read` / `:write`	`/warehouses`	`View:Warehouse`	`Create`, `Update`, `Delete:Warehouse`
`stocks:read` / `:write`	`/stocks/overview`, `/stocks/movements`; yazmada giriş, transfer, sayım, düzeltme	`View:StockOverview`, `View:StockMovement`	`Create`, `Transfer`, `Count`, `Adjust:StockMovement`

AI, rapor ve istatistik

Scope	Açtığı endpoint’ler	Okuma izni	Yazma izni
`agent-prompts:read` / `:write`	`/agent-prompts`, sürümler	`View:AgentPrompt`	`Create`, `Update`, `Delete`, `PublishRevision:AgentPrompt`
`ai-reports:read` / `:write`	`/ai-reports`, PDF	`View:AIReport`, `Download:AIReport`	`Create`, `Delete:AIReport`
`ai-report-schedules:read` / `:write`	`/ai-report-schedules`	`View:AIReportSchedule`	`Create`, `Update`, `Delete:AIReportSchedule`
`statistics:read`	`/statistics/*`	Rapora göre `View:Conversation`, `View:Product`, `View:StockOverview`, `ViewAllAppointments`, `ViewAllCustomers`, `ViewAllLeads`, `ViewAllSales`	—

Hesap, klinik ve yönetim

Scope	Açtığı endpoint’ler	Okuma izni	Yazma izni
`account:read` / `:write` / `:delete`	`/account` ve alt kaynakları: oturumlar, iki adımlı doğrulama, bildirim tercihleri, davetler, `GET /account/roles`	—	—
`users:read` / `:write`	`/users`, `/users/{id}/roles`	`View:User`	`Create`, `Update`, `Delete:User`; rol atama için `Update:Role`
`roles:read` / `:write`	`/roles`, `/permissions`	`View:Role`	`Create`, `Update`, `Delete:Role`
`tenant:read` / `:write`	`/tenant`	`View:TenantInfo`	`Update:TenantInfo`
`settings:read` / `:write`	`/settings/{accounting, appointment, chat, general, notification, support}`	—	`Update:AccountingSettings`, `Update:AppointmentSettings` vb.
`oauth_clients:read` / `:write`	`/oauth/clients`, `/oauth/scopes`	`View:Client` ve uygulamanın sahibi olmak	`Create`, `Update`, `Delete`, `Activate`, `Revoke`, `UpdateScopes:Client` ve uygulamanın sahibi olmak
`files:read` / `:write`	`/files`, `/uploads`	`View:File`, `Download:File`	`Create`, `Delete`, `Reorder:File`
`form_templates:read` / `:write`	`/form-templates`	`View:FormTemplate`	`Create`, `Update`, `Delete`, `GenerateLink:FormTemplate`
`imports:read` / `:write`	`/import`	`View:Imports`, `View:ImportJobDetails`	`Install`, `Update`, `Uninstall`, `Start`, `Cancel:ImportSource`
`integrations:read` / `:write`	`/integrations`, `/integration-connections`	`View:Integrations`, `View:IntegrationConnection`	`Create`, `Update`, `Delete:IntegrationConnection`
`activity_logs:read`	`/activity-logs`, `/leads/{id}/activities`	`View:ActivityLog`	—
`authentication_logs:read`	`/authentication-logs`	`View:AuthenticationLog`	—
`recycle_bin:read` / `:write`	`/recycle-bin`	`View:RecycleBin`	`Restore`, `Purge:RecycleBin`

activity_logs:write katalogda bulunur ancak hiçbir endpoint onu kontrol etmez; bu scope’u istemenize gerek yoktur.

Scope gerektirmeyen çağrılar

Bearer token ister, ancak scope kontrolü yapmaz:

GET /general/cities, /countries, /currencies, /districts, /exchange-rates, /product-types, /unit-codes, /withholding-codes
GET ve POST /api/broadcasting/auth (özel gerçek zamanlı kanallar)

Scope ve izin ilişkisi

Scope ve izin iki ayrı denetimdir. Çağrının başarılı olması için ikisi de gerekir.

	Scope	İzin
Neye bağlı	Access token’a	Kullanıcının kliniğe bağlı rolüne
Kim belirler	Uygulamanız ve kullanıcı onayı	Klinik yöneticisi, rol düzenleyicide
Eksikse	`403 FORBIDDEN`, `Invalid scope(s) provided.`	`403`
Kapsamı	Token’ın tüm kliniklerinde aynı	Her klinikte ayrı

Scope kullanıcıya izin kazandırmaz; yalnızca uygulamanın kullanıcı adına neleri deneyebileceğini sınırlar. customers:write scope’una sahip bir token, Delete:Customer iznine sahip olmayan kullanıcı adına hasta silemez. Aynı scope birden çok izni kapsayabilir. Örneğin appointments:write ile POST /appointments/{id}/cancel çağrısı için kullanıcıda Cancel:Appointment, revert-cancel için RevertCancel:Appointment izni gerekir; PUT /appointments/{id} ile durumu cancelled yapmak için Update ve Cancel izinleri birlikte aranır. Benzer şekilde conversations:write ile bir sohbete mesaj göndermek Send:Message, sohbeti arşivlemek Archive:Conversation ister. Kullanıcı kliniği değiştirdiğinde aynı token kullanılmaya devam eder. Scope’lar değişmez, izinler seçilen kliniğe göre değişir. Bu yüzden aynı token bir klinikte çalışıp diğerinde 403 alabilir. İzinlerin çağrıları kayıt düzeyinde nasıl sınırladığı (örneğin yalnızca kendi leadleri) için İzinler ve görünürlük sayfasına bakın.

İlgili sayfalar

Uygulama oluşturma

scopes listesiyle OAuth uygulaması kaydedin.

Yetkilendirme kodu ve PKCE

scope parametresiyle yetkilendirme isteği gönderin.

Tokenlar

Token yenilerken scope’ları daraltın.

İzinler ve görünürlük

İzinlerin kayıt görünürlüğünü nasıl etkilediğini görün.

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

Scope adlandırması

Scope seçme önerileri

Birlikte gereken scope’lar

Kimlik scope’ları

Kaynak scope’ları

Hasta, lead ve satış ekibi

Randevu ve klinik kadrosu

Sohbet, kanal ve bildirim

Satış, fatura ve finans

Ürün ve stok

AI, rapor ve istatistik

Hesap, klinik ve yönetim

Scope gerektirmeyen çağrılar

Scope ve izin ilişkisi

İlgili sayfalar

Uygulama oluşturma

Yetkilendirme kodu ve PKCE

Tokenlar

İzinler ve görünürlük

​Scope adlandırması

​Scope seçme önerileri

​Birlikte gereken scope’lar

​Kimlik scope’ları

​Kaynak scope’ları

​Hasta, lead ve satış ekibi

​Randevu ve klinik kadrosu

​Sohbet, kanal ve bildirim

​Satış, fatura ve finans

​Ürün ve stok

​AI, rapor ve istatistik

​Hesap, klinik ve yönetim

​Scope gerektirmeyen çağrılar

​Scope ve izin ilişkisi

​İlgili sayfalar

Uygulama oluşturma

Yetkilendirme kodu ve PKCE

Tokenlar

İzinler ve görünürlük

Scope adlandırması

Scope seçme önerileri

Birlikte gereken scope’lar

Kimlik scope’ları

Kaynak scope’ları

Hasta, lead ve satış ekibi

Randevu ve klinik kadrosu

Sohbet, kanal ve bildirim

Satış, fatura ve finans

Ürün ve stok

AI, rapor ve istatistik

Hesap, klinik ve yönetim

Scope gerektirmeyen çağrılar

Scope ve izin ilişkisi

İlgili sayfalar