Krediler

Kredi, kliniğin plan kotasının üstünde sahip olduğu ek kullanım hakkıdır: SMS ve WhatsApp mesaj adedi, depolama alanı ve AI kullanımı. Bu kaynak yalnızca okunur. Kredi oluşturan, değiştiren veya silen bir endpoint yoktur. Krediler ek paket satın alındığında oluşur; satın alma akışı için Abonelik ve faturalama sayfasına bakın. Panelde aynı veriyi Krediler sayfasında görürsünüz. Tüm istekler Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıklarını taşır. Başlığın nasıl çalıştığı için Klinikler ve X-Tenant sayfasına bakın.

Endpoint özeti

Beş endpoint de aynı scope’u kullanır: credits:read. Scope’ların anlamı için Scope’lar sayfasına bakın.

Metot	Endpoint	Açıklama	İzin
GET	`/v1/credits/balance`	Kalan SMS, WhatsApp ve depolama bakiyesinin özetini getirir.	`View:Credit`
GET	`/v1/credits`	Kredileri sayfalı listeler.	`View:Credit`
GET	`/v1/credits/{id}`	Tek bir krediyi getirir. `{id}` yalnızca sayı olabilir.	`View:Credit`
GET	`/v1/credit-usages`	Kredi kullanım geçmişini sayfalı listeler.	`View:CreditUsage`
GET	`/v1/credit-usages/statistics`	Kliniğin depolama kotasını ve kullanımını getirir.	`View:CreditUsage`

Token credits:read scope’unu taşısa bile kullanıcının ilgili izni yoksa istek 403 FORBIDDEN ile döner. Tersi de geçerlidir: izin olsa da scope yoksa 403 alırsınız. Kredilerde “yalnızca kendi kayıtlarım” ayrımı yoktur; izni olan her kullanıcı kliniğin tüm kredilerini görür. İzin modeli için İzinler ve görünürlük sayfasına bakın.

Tarih alanları klinik saat diliminde, saat farkıyla birlikte ISO 8601 biçiminde döner (2026-10-12T14:30:00+03:00). Her yanıtta meta.timezone alanı bulunur.

Bakiye özeti

GET /v1/credits/balance parametre almaz.

{
  "success": true,
  "data": {
    "active_credits": 3,
    "sms": { "remaining": 400, "unit": "count" },
    "whatsapp": { "remaining": 1500, "unit": "count" },
    "storage": { "remaining_bytes": 1073741824, "remaining_human": "1,00 GB" }
  },
  "meta": { "timezone": "Europe/Istanbul" }
}

Alan	Tür	Açıklama
`active_credits`	sayı	Aktif kredi kayıtlarının sayısı. AI kredileri de sayıya girer.
`sms.remaining`, `whatsapp.remaining`	sayı	Kalan mesaj adedi.
`sms.unit`, `whatsapp.unit`	metin	Her zaman `count`.
`storage.remaining_bytes`	sayı	Kalan depolama, bayt olarak.
`storage.remaining_human`	metin	Okunabilir biçim, örneğin `1,00 GB`.

Kalan değer, aktif kredilerin toplamından kullanımların çıkarılmasıyla hesaplanır. Süresi dolmuş bir krediye yazılmış kullanım da aktif kredilerin kalanından düşer.

Bakiye yanıtında AI satırı yoktur; AI kredilerini GET /v1/credits ile okuyun. remaining ve storage.remaining_bytes eksi değer alabilir (kullanım aktif toplamı aştığında). remaining_human ise 0 B altına inmez.

Kredi nesnesi

GET /v1/credits ve GET /v1/credits/{id} aynı nesneyi döner.

Alan	Tür	Açıklama
`id`	sayı	Kredi kimliği.
`tenant_id`	sayı	Klinik kimliği.
`type`	metin	`llm_token`, `sms`, `storage` veya `whatsapp`.
`type_label`	metin	Yerelleştirilmiş ad: `AI Kullanımı`, `SMS`, `Depolama`, `WhatsApp`.
`amount`	sayı	Tanımlanan miktar. Birimi türe bağlıdır (Tutar biçimi).
`formatted_amount`	metin	Okunabilir miktar, örneğin `1.500 adet`.
`start_date`	tarih veya `null`	Geçerlilik başlangıcı.
`end_date`	tarih veya `null`	Geçerlilik bitişi.
`is_active`	boolean	Kredinin şu an geçerli olup olmadığı.
`created_at`	tarih	Oluşturulma zamanı.

Nesnede kredinin ne kadarının harcandığını gösteren bir alan yoktur. Kalan miktarı bakiye özetinden, harcamaları kullanım geçmişinden okuyun.

Aktif kredi

Kredinin durumu saklanmaz, start_date ve end_date alanlarından hesaplanır. Sınırlar dahildir: tam şimdi başlayan kredi aktiftir, tam şimdi biten kredi hâlâ aktiftir.

`start_date`	`end_date`	`is_active`
`null`	`null`	`true` (süresiz)
geçmişte veya `null`	gelecekte veya `null`	`true`
gelecekte	herhangi	`false` (henüz başlamadı)
herhangi	geçmişte	`false` (süresi doldu)

Başka bir kliniğe ait, silinmiş veya var olmayan bir kredi için GET /v1/credits/{id} aynı yanıtı verir: 404 RESOURCE_NOT_FOUND (Kredi bulunamadı). Sayı olmayan bir {id} düz 404 döner.

Kullanımlar

GET /v1/credit-usages her kredi için faturalama döneminde harcanan miktarı listeler. Kayıtları siz oluşturmazsınız; faturalama dönemi kapanırken sistem yazar. Kullanım, mesaj gönderildiği anda değil dönem sonunda işlenir.

Alan	Tür	Açıklama
`id`	sayı	Kullanım kaydı kimliği.
`description`	metin veya `null`	Açıklama, örneğin `WhatsApp mesajı — 2026-01 dönemi kota tüketimi`. Metin her zaman Türkçedir.
`amount`	sayı	Krediden düşen miktar. Birimi kredinin birimidir.
`credit`	nesne	Kullanımın düştüğü kredi: `id`, `type`, `type_label`.
`created_at`	tarih	Kullanım tarihi.

{
  "success": true,
  "data": [
    {
      "id": 123,
      "description": "WhatsApp mesajı — 2026-01 dönemi kota tüketimi",
      "amount": 250,
      "credit": { "id": 123, "type": "whatsapp", "type_label": "WhatsApp" },
      "created_at": "2026-02-01T03:00:00+03:00"
    }
  ],
  "links": {},
  "meta": { "current_page": 1, "per_page": 15, "total": 1, "timezone": "Europe/Istanbul" }
}

type verilmezse liste SMS, WhatsApp ve AI kullanımlarını birlikte getirir. Depolama kullanım kaydı yazılmaz; bu yüzden depolama için kullanım geçmişi yoktur. Silinmiş bir krediye ait kullanımlar listede görünmez.

Depolama istatistikleri

Kliniğin gerçek depolama durumu için GET /v1/credit-usages/statistics endpoint’ini kullanın. Parametre almaz.

{
  "success": true,
  "data": {
    "total": { "bytes": 10737418240, "formatted": "10,00 GB" },
    "used": { "bytes": 2147483648, "formatted": "2,00 GB" },
    "remaining": { "bytes": 8589934592, "formatted": "8,00 GB" },
    "usage_percentage": 20.0,
    "breakdown": [
      { "category": "images", "bytes": 1610612736, "formatted": "1,50 GB" },
      { "category": "documents", "bytes": 536870912, "formatted": "512,00 MB" }
    ]
  }
}

Alan	Açıklama
`total`	Etkin depolama kotası: plan kotası ile aktif depolama kredilerinin toplamı. Yalnızca kredilerden oluşmaz.
`used`	Klinikte kullanılan alan. Silinmiş dosyalar ve diğer klinikler sayılmaz.
`remaining`	`total − used`, en az 0.
`usage_percentage`	`used / total` yüzdesi, iki ondalık. 100’ü aşabilir. `total` 0 ise kullanım varken `100.0`, yokken `0.0` döner.
`breakdown`	Her zaman iki öğe, bu sırayla: `images` (görseller), `documents` (belgeler). Görsel olmayan tüm aktif dosyalar `documents` sayılır.

Filtreler

Sayfalama ve sıralama kuralları tüm listelerde ortaktır; ayrıntı için Sayfalama ve Filtreleme ve sıralama sayfalarına bakın. Aşağıdaki parametreler bu kaynağa özgüdür. Filtreler birlikte kullanılabilir ve hepsi aynı anda uygulanır (VE).

Kredi listesi

Parametre	Değerler	Açıklama
`type`	`llm_token`, `sms`, `storage`, `whatsapp`	Türe göre süzer. Bilinmeyen değer `422` verir.
`is_active`	`true`, `false`	`true` yalnızca aktif, `false` yalnızca aktif olmayan (başlamamış veya süresi dolmuş) kredileri getirir. Verilmezse hepsi gelir.
`created_at_from`, `created_at_to`	tarih	Oluşturulma zamanı aralığı.
`start_date_from`, `start_date_to`	tarih	Geçerlilik başlangıcı aralığı.
`end_date_from`, `end_date_to`	tarih	Geçerlilik bitişi aralığı.
`sort_by`	`created_at` (varsayılan), `start_date`, `end_date`, `amount`	Başka bir değer `422` verir.
`sort_order`	`asc`, `desc` (varsayılan)	Sıralama yönü.
`per_page`	1–100, varsayılan 15	Sayfa boyutu.
`page`	1 veya üstü	Sayfa numarası.

Her _to değeri, eşlenik _from değerinden önce olamaz; aksi hâlde 422 alırsınız. Yalnızca tarih içeren bir sınır, klinik saat diliminde gün başı ve gün sonu olarak yorumlanır: _from o günün başlangıcı, _to o günün sonu dahil. start_date veya end_date değeri null olan krediler, o sütundaki aralık filtresiyle hiçbir zaman eşleşmez.

curl "https://app.flextell.ai/api/v1/credits?type=whatsapp&is_active=true&sort_by=end_date&sort_order=asc" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Kullanım listesi

Parametre	Değerler	Açıklama
`type`	`sms`, `whatsapp`	Yalnızca bu iki değer kabul edilir. `storage` ve `llm_token` `422` verir.
`search`	en çok 255 karakter	Yalnızca `description` alanında arar.
`sort_by`	`created_at` (varsayılan), `amount`	Başka bir değer `422` verir.
`sort_order`	`asc`, `desc` (varsayılan)	Sıralama yönü.
`per_page`	1–100, varsayılan 15	Sayfa boyutu.
`page`	1 veya üstü	Sayfa numarası.

Kullanım listesinde tarih aralığı filtresi yoktur.

Hatalar

Geçersiz parametre 422 VALIDATION_FAILED döner. Bu kaynağa özgü iş hataları aşağıdadır; tüm kodlar için Hata kodları sayfasına bakın.

Kod	HTTP	Ne zaman
`FORBIDDEN`	403	Token `credits:read` taşımıyor veya kullanıcıda `View:Credit` / `View:CreditUsage` izni yok.
`TENANT_HEADER_REQUIRED`	400	`X-Tenant` başlığı yok.
`RESOURCE_NOT_FOUND`	404	Kredi yok, başka kliniğe ait veya silinmiş.
`VALIDATION_FAILED`	422	Geçersiz `type`, `sort_by`, `per_page`, `search` veya tarih aralığı.

Tutar biçimi

amount alanı sayıdır; birimi kredinin türüne bağlıdır. formatted_amount ise Türkçe ayraçlarla (binlik nokta, ondalık virgül) hazır metindir.

`type`	`amount` birimi	`formatted_amount` örneği
`llm_token`	Türk lirası (₺)	`1.234,50 ₺`
`sms`	Mesaj adedi	`1.500 adet`
`whatsapp`	Mesaj adedi	`1.500 adet`
`storage`	Bayt	`1,00 MB`

AI kullanımı için miktar mesaj değil, harcama tutarıdır ve iki ondalıkla gelir.
SMS ve WhatsApp miktarları ondalıksız gösterilir.
Depolama miktarları bayttır. formatted_amount uygun birimi seçer: B, KB, MB, GB, TB.
Birim sözcüğü isteğin dil başlığına göre yerelleşir. Sayısal alanları işlemek için formatted_amount yerine amount alanını kullanın.

Sayısal karşılaştırma ve toplama için amount alanını kullanın. formatted_amount yalnızca görüntüleme içindir ve biçimi dile göre değişebilir. Tarih ve sayı biçimleri için Veri biçimleri sayfasına bakı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

Endpoint özeti

Bakiye özeti

Kredi nesnesi

Aktif kredi

Kullanımlar

Depolama istatistikleri

Filtreler

Kredi listesi

Kullanım listesi

Hatalar

Tutar biçimi

​Endpoint özeti

​Bakiye özeti

​Kredi nesnesi

​Aktif kredi

​Kullanımlar

​Depolama istatistikleri

​Filtreler

​Kredi listesi

​Kullanım listesi

​Hatalar

​Tutar biçimi

Endpoint özeti

Bakiye özeti

Kredi nesnesi

Aktif kredi

Kullanımlar

Depolama istatistikleri

Filtreler

Kredi listesi

Kullanım listesi

Hatalar

Tutar biçimi