Abonelik ve faturalama

​

Endpoint özeti

​

Ortak kurallar

• Tutarlar metin olarak döner ("9900.00"). Tek kayıt yanıtları {"success": true, "data": ..., "meta": {...}} biçimindedir. Liste yanıtlarında success alanı yoktur. Genel yapı için Yanıt yapısı sayfasına bakın.
• Takvim alanları (issue_date, due_date, period_start, period_end) YYYY-MM-DD biçimindedir. period_end dönemin dışında kalan ilk gündür; son dahil gün period_end eksi 1 gündür.
• Dönem sınırları, satın alma son ödeme günleri ve yenileme tarihleri klinik saat diliminize göre değil, Europe/Istanbul muhasebe saatine göre hesaplanır. Zaman damgası filtreleri (created_at_*, completed_at_*, applied_at_*, assigned_at_*) ise klinik saat diliminin gün sınırlarıyla okunur. is_overdue ve gecikmiş ödeme kilidi UTC tarihine göre değerlendirilir.
• Plan ve paket fiyatları KDV hariçtir. KDV her satırda tax_rate oranıyla ayrıca eklenir.
• Abonelik veya ödeme kilidi varken subscription, plans, fatura, ödeme, overview, settings ve payments uç noktaları açık kalır; böylece klinik plan alıp borcunu ödeyebilir. current-usage, usage-history, quota-packages, seats, discount-codes ve plan-change uç noktaları kilitliyken 402 döner.
• billing uç noktaları kurulum kilidine (428 SETUP_REQUIRED) takılmaz. Abonelik ve ödeme kilitleri için Erişim kilitleri sayfasına bakın.
• Listelerde sayfalama için Sayfalama sayfasına bakın. per_page 1-100 arasındadır, varsayılan 15’tir.

​

Abonelik durumu

​

Planlar ve plan değişikliği

• Yükseltme purchase uç noktasıyla yapılır ve ödeme tamamlanınca plan hemen değişir. Yükseltme teklifi yalnızca plan ve paid_until değişmediği sürece geçerlidir.
• Daha ucuz plana geçiş POST /v1/billing/subscription/plan-change ile yapılır. Yalnızca active durumunda çalışır. Ödeme sonrası yeni plan mevcut dönem bitince başlar.
• Ödenmiş bir sonraki dönem değişikliği (pending_plan_paid) varken yeni teklif, satın alma, ödeme veya iptal yapılamaz.
• DELETE /v1/billing/subscription/plan-change ödenmemiş plan seçimlerini iptal eder.
• Hedef planın kullanıcı sınırı aktif kullanıcı sayısından düşükse PLAN_DOWNGRADE_BLOCKED_BY_ACTIVE_USERS döner.
• Abonelikler iade edilmez. Kullanılmamış ödeme sonraki abonelik faturasında mahsup edilir (Abonelik mahsubu satırı).
• Kart ile otomatik tahsilat yoktur. Yenileme için fatura oluşur; ödemeyi siz başlatırsınız.

​

Proforma faturalar

​

Fatura türleri ve durumları

​

Listeleme

​

Fatura nesnesi

​

Ödeme

curl -X POST https://app.flextell.ai/api/v1/billing/proforma-invoices/123/pay \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://panel.ornek-klinik.com/odeme-sonucu"}'

const res = await fetch("https://app.flextell.ai/api/v1/billing/proforma-invoices/123/pay", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "X-Tenant": tenantId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ return_url: "https://panel.ornek-klinik.com/odeme-sonucu" }),
});
const { data } = await res.json();
window.location.href = data.initiation.redirect_url;

• Kart ödemesi her zaman faturanın kalan tutarının tamamı içindir; tek taksit ve TL ile çalışır. Kısmi ödeme yoktur.
• Bir faturada aynı anda tek ödeme denemesi olur. 60 dakikadan yeni bir deneme varken yeni istek 409 PAYMENT_ALREADY_PROCESSED döner (data.payment_id, data.status). 60 dakikadan eski deneme başarısız sayılır.
• Sağlayıcı sayfasından dönüşte tarayıcı return_url adresine tenant, proforma_invoice_id ve payment_attempt sorgu parametreleriyle yönlendirilir. Doğrulama başarısız olursa payment_issue=verification_failed eklenir; bu durumda sonucu GET /v1/billing/proforma-invoices/{id} ile faturadan okuyun.
• Süresi dolmuş oturumda gelen başarılı geri dönüş 409 PAYMENT_SESSION_EXPIRED ile reddedilir ve fatura ödenmemiş kalır.
• Tutar veya para birimi uyuşmazsa deneme başarısız olur (PAYMENT_AMOUNT_MISMATCH, PAYMENT_CURRENCY_MISMATCH).

​

İndirim kodu ve ödemesiz tamamlama

​

Satın almayı iptal etme

​

Ödemeleri listeleme

​

Kullanım ve kotalar

​

Kota aşımı davranışı

​

Ek paketler

curl -X POST https://app.flextell.ai/api/v1/billing/quota-packages/123/purchase \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Idempotency-Key: ek-paket-2026-10-13-001"

• Aynı anahtar ve aynı paket aynı faturayı (201) döner. Aynı anahtar başka pakette 409 PURCHASE_IDEMPOTENCY_CONFLICT verir. Yeni anahtar her zaman yeni bir satın alma oluşturur.
• Paket kliniğin planında sunulmuyorsa QUOTA_PACKAGE_NOT_AVAILABLE_FOR_PLAN; paket bulunamazsa veya kredi havuzuna çevrilemezse QUOTA_PACKAGE_NOT_FOUND döner.
• Vade, düzenlenme tarihine ödeme süresi (varsayılan 14 gün) eklenerek belirlenir. Vadeyi geçen ödenmemiş satın alma Süresi doldu olur, ödenemez (PROFORMA_NOT_PAYABLE) ve otomatik iptal edilir.
• Ödeme tamamlanınca kredi bir kez tanımlanır. Kredi, ödeme anından validity_days süresince geçerlidir. AI paketleri satın alınan türe (ai_chat veya ai_report) bağlıdır. Krediler yalnızca plan kotasını aşan kullanımda, en eski kredi önce olmak üzere tüketilir; depolama kredisi günlük sınırı yükseltir.
• Ödenmemiş ek paket satın almaları borç sayılmaz, hatırlatılmaz ve erişimi kilitlemez.

​

Fatura ayarları

​

Ek kullanıcılar

• Değer değişmiyorsa işlem hata vermez; deneme kliniğinde bile kabul edilir.
• Değişiklik için abonelik active veya legacy olmalı ve gecikmiş ödeme kilidi olmamalıdır. Aksi hâlde SUBSCRIPTION_REQUIRED (422) veya ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT (402) alırsınız.
• Sayıyı aktif kullanıcı sayısının altına indirirseniz 422 SEAT_REDUCTION_BLOCKED_BY_ACTIVE_USERS döner (data.active_users, data.limit).
• Ücretlendirme charged_from tarihinden başlar (sonraki yenileme ya da mevcut fatura döneminin sonu). Önceden ödemeli kliniklerde yenileme, ödenen dönemde ulaşılan en yüksek ek kullanıcı sayısını faturalar.

​

İndirim kodları

​

Hata kodları

​

Yetki