Teklifler

/v1/offers kaynağı, bir hasta veya lead için hazırlanan fiyat teklifini yönetir. Teklif; tedavi ve ürün kalemlerinden, para biriminden, geçerlilik tarihinden ve bir durumdan oluşur. Kabul edilen teklifi tek çağrıyla taslak satışa dönüştürebilir, teklifin PDF’ini üretebilirsiniz. Tüm istekler https://app.flextell.ai/api/v1 altındadır ve Authorization: Bearer <access_token> ile X-Tenant: <tenant_id> başlıklarını gerektirir. Bkz. Klinikler ve X-Tenant.

Bu modül teklifi hastaya e-posta, WhatsApp veya SMS ile göndermez. sent durumu yalnızca elle işaretlenen bir bayraktır. Teklif şablonlarını yöneten bir API de yoktur; PDF her zaman kliniğin şablonuyla üretilir.

Endpoint özeti

Metot	Endpoint	Açıklama	Scope	İzin
`GET`	`/v1/offers`	Teklifleri listeler.	`offers:read`	`View:Offer`
`POST`	`/v1/offers`	Teklif oluşturur.	`offers:write`	`Create:Offer`
`GET`	`/v1/offers/options/products`	Kalem seçimi için ürünleri listeler.	`offers:read`	`Create:Offer` veya `Update:Offer`
`GET`	`/v1/offers/options/treatments`	Kalem seçimi için tedavileri listeler.	`offers:read`	`Create:Offer` veya `Update:Offer`
`GET`	`/v1/offers/{id}`	Teklifi kalemleriyle getirir.	`offers:read`	`View:Offer`
`PUT`	`/v1/offers/{id}`	Teklifi günceller.	`offers:write`	`Update:Offer`
`DELETE`	`/v1/offers/{id}`	Teklifi siler.	`offers:write`	`Delete:Offer`
`POST`	`/v1/offers/{id}/convert`	Teklifi taslak satışa dönüştürür.	`offers:write` ve `sales:write`	`Convert:Offer`
`POST`	`/v1/offers/{id}/generate-pdf`	PDF üretimini kuyruğa alır.	`offers:read`	`View:Offer`
`GET`	`/v1/offers/{id}/pdfs`	Üretilmiş PDF’leri listeler.	`offers:read`	`View:Offer`
`GET`	`/v1/offers/{id}/pdfs/{fileId}/download-url`	Kısa ömürlü indirme bağlantısı üretir.	`offers:read`	`View:Offer`
`DELETE`	`/v1/offers/{id}/pdfs/{fileId}`	PDF’i siler.	`offers:write`	`Delete:Offer`

Her endpoint için scope ve izin birlikte gerekir. Kalıcı silme (force) endpoint’i yoktur. İzin modeli için İzinler ve görünürlük sayfasına bakın.

Görünürlük

ViewAllOffers:Offer iznine sahip kullanıcı kliniğin tüm tekliflerini görür. İzni olmayan kullanıcı yalnızca sahibi olduğu teklifleri ve kendisine atanmış lead’lerin tekliflerini görür. salesperson rolündeki kullanıcı ayrıca lead aşamasını geçmiş hastaların tüm tekliflerini görür. Görünmeyen teklif için 404 RESOURCE_NOT_FOUND döner, 403 dönmez.

Listeleme

GET /v1/offers sayfalı döner. Liste yanıtında items yer almaz, yalnızca total_price gelir. Sayfalama için Sayfalama, genel sıralama kuralları için Filtreleme ve sıralama sayfasına bakın.

Parametre	Açıklama
`search`	En fazla 255 karakter. Hastanın tam metin aramasında eşleşir.
`customer_id`, `lead_id`	Hasta veya lead’e göre süzer. `lead_id`, görebildiğiniz bir lead olmalıdır; aksi hâlde `422` döner.
`user_id`	Teklif sahibine göre süzer.
`status`	`draft`, `sent`, `accepted`, `rejected` veya `converted`.
`created_at_from`, `created_at_to`	Oluşturulma aralığı. Bitiş, başlangıçtan önce olamaz.
`sort_by`, `sort_order`	`created_at` (varsayılan), `updated_at`, `status`. Yön `asc` veya `desc` (varsayılan `desc`).
`per_page`, `page`	`per_page` 1 ile 100 arası, varsayılan 15.

Teklif nesnesi

Alan	Tür	Açıklama
`id`	integer	Teklif kimliği.
`user_id`	integer	Teklif sahibi. Göndermezseniz isteği yapan kullanıcıdır.
`customer_id`	integer veya `null`	Hasta. Hasta kalıcı olarak silinirse teklif kalır ve alan `null` olur.
`sale_id`	integer veya `null`	Dönüştürülünce oluşan satış. Yazılamaz.
`currency_id`, `exchange_rate`	integer, number	Para birimi ve kur.
`valid_until`	string	Geçerlilik zamanı. Yalnızca bilgi amaçlıdır; süresi dolan teklif otomatik kapanmaz.
`notes`	string	Serbest not.
`status`	string	Değerler için aşağıdaki Durum akışı bölümüne bakın.
`is_locked`	boolean	`true` ise teklif güncellenemez ve silinemez.
`can_convert`	boolean	`true` ise teklif satışa dönüştürülebilir.
`total_price`	number	Kalem toplamlarının toplamı.
`record_state`	object	`is_read_only` ve `reason_code` (`CUSTOMER_ERASED`, `LEAD_NOT_ASSIGNED` veya `null`).
`customer`	object veya `null`	`id`, `first_name`, `last_name`, `phone_number`, `email`, `is_masked`, `is_lead_stage`, `lead_id`. Başka bir temsilcinin lead aşamasındaki hastası için kimlik alanları maskelenir.
`user`, `currency`	object	`user`: `id`, `name`. `currency`: `id`, `code`, `symbol`, `name`.
`items`	array	Yalnızca tek teklif yanıtlarında (oluşturma, getirme, güncelleme) bulunur.
`created_at`, `updated_at`, `deleted_at`	string	Zaman damgaları.

Her kalemde (items[]) şu alanlar döner: id, offer_id, order, itemable_type (Treatment veya Product), itemable_id, quantity, tax_rate, unit_price, discount_amount, discount_percentage, sub_total, total_discount, total_tax, total_price ve itemable (id, name; kayıt silinmişse null).

Durum akışı

`status`	Etiket	Kilitli	Satışa dönüşür
`draft`	Taslak	Hayır	Evet
`sent`	Gönderildi	Hayır	Evet
`accepted`	Kabul Edildi	Evet	Evet
`rejected`	Reddedildi	Hayır	Hayır
`converted`	Satışa Dönüştü	Evet	Hayır

Tipik akış aşağıdadır. Zorunlu bir sıra yoktur.

Oluştururken ve güncellerken draft, sent, accepted, rejected değerlerini verebilirsiniz. converted değerini API’ye veremezsiniz; yalnızca dönüştürme işlemi bu duruma geçirir.
Geçişler arasında bir doğrulama yoktur. Kilitli değilken rejected durumundan draft durumuna da dönebilirsiniz.
accepted ve converted teklifler kilitlidir. PUT ve DELETE istekleri 422 OFFER_LOCKED döner. Kabul edilmiş bir teklifi API ile kilitten çıkaramazsınız.

Oluşturma

POST /v1/offers başarılı olunca 201 ve kalemleriyle birlikte teklifi döner.

integer

Hasta. lead_id göndermiyorsanız zorunludur ve lead_id ile birlikte gönderilemez. Hasta kliniğe ait olmalıdır.

integer

Lead. customer_id göndermiyorsanız zorunludur. Görebildiğiniz bir lead olmalıdır. Lead dönüştürülmez; gerekirse lead aşamasında bir kişi kaydı oluşturulur ya da telefon numarasıyla mevcut kayıt kullanılır.

integer

gerekli

Para birimi.

number

gerekli

Kur. 0 veya daha büyük olmalıdır.

string

gerekli

Geçerlilik tarihi. Saat dilimi vermezseniz kliniğin saat dilimi kabul edilir; yalnızca tarih verirseniz gün başlangıcı (00:00) alınır.

string

gerekli

draft, sent, accepted veya rejected.

integer

Teklif sahibi. Kliniğin bir kullanıcısı olmalıdır.

string

Serbest not.

array

gerekli

En az bir kalem.

Kalemler

Alan	Zorunlu	Kural
`itemable_type`	Evet	`Treatment` veya `Product`.
`itemable_id`	Evet	Kliniğinizde var olan tedavi veya ürün. Pasif kayıtlar da kabul edilir.
`quantity`	Evet	0.0001 veya daha büyük sayı.
`unit_price`	Evet	Vergi hariç (net) birim fiyat, 0 veya daha büyük.
`tax_rate`	Evet	`0`, `1`, `10` veya `20`.
`discount_amount`	Evet	Tutar olarak indirim, 0 veya daha büyük.
`discount_percentage`	Evet	Yüzde olarak indirim, 0 ile 100 arası.

order, sub_total, total_discount, total_tax ve total_price alanlarını göndermeniz gerekmez. Gönderirseniz yok sayılır; sıra, istekteki kalem sırasına göre 0’dan başlar.

Toplamlar

Sunucu toplamları her yazmada yeniden hesaplar:

sub_total = quantity × unit_price
total_discount = discount_amount + sub_total × discount_percentage / 100
total_tax = (sub_total − total_discount) × tax_rate / 100. İndirim ara toplamı aşarsa vergi tabanı 0 olur.
total_price = (sub_total − total_discount) + total_tax

discount_amount ve discount_percentage birbirine eklenir; ikisi de uygulanır. İndirimi tek biçimde vermek istiyorsanız diğer alanı 0 gönderin.

Kliniğin muhasebe ayarlarında “satış vergi oranını geçersiz kıl” seçeneği açıksa her kaleme kliniğin varsayılan vergi oranı uygulanır.

Kalem seçenekleri

GET /v1/offers/options/products ve GET /v1/offers/options/treatments, teklif formundaki seçim listelerini besler. Yalnızca aktif kayıtları döndürür. Bu endpoint’ler View:Product veya View:Treatment izni gerektirmez; Create:Offer ya da Update:Offer yeterlidir. Parametreler: search, per_page (1–100, varsayılan 15), page ve ids[] (en fazla 100). ids[] verdiğinizde arama ve aktiflik süzgeci uygulanmaz; kayıtlı kalemleri etiketlemek için pasif kayıtlar da döner. Katalog fiyatları vergi dahildir. Yanıttaki unit_price_excl_tax ve tax_rate değerlerini kalemde unit_price ve tax_rate olarak gönderin.

curl -X POST "https://app.flextell.ai/api/v1/offers" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 123,
    "currency_id": 1,
    "exchange_rate": 1,
    "valid_until": "2026-11-15T23:59:00+03:00",
    "status": "draft",
    "notes": "Örnek teklif",
    "items": [
      {
        "itemable_type": "Treatment",
        "itemable_id": 123,
        "quantity": 1,
        "unit_price": 1000,
        "tax_rate": 20,
        "discount_amount": 0,
        "discount_percentage": 10
      }
    ]
  }'

const res = await fetch("https://app.flextell.ai/api/v1/offers", {
  method: "POST",
  headers: {
    Authorization: "Bearer <access_token>",
    "X-Tenant": "<tenant_id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: 123,
    currency_id: 1,
    exchange_rate: 1,
    valid_until: "2026-11-15T23:59:00+03:00",
    status: "draft",
    items: [
      {
        itemable_type: "Treatment",
        itemable_id: 123,
        quantity: 1,
        unit_price: 1000,
        tax_rate: 20,
        discount_amount: 0,
        discount_percentage: 10,
      },
    ],
  }),
});

Bu örnekte sub_total 1000, total_discount 100, total_tax 180 ve total_price 1080 olur.

Güncelleme

PUT /v1/offers/{id} kısmi güncellemedir; göndermediğiniz alanlar değişmez. items gönderirseniz mevcut kalemlerin tamamı yeni listeyle değiştirilir ve liste en az bir kalem içermelidir. items göndermezseniz kalemler korunur. notes ve user_id alanlarını null göndererek temizleyemezsiniz.

Teklifi çoğaltma

Çoğaltma için ayrı bir endpoint yoktur. Kopyayı kendiniz oluşturun: kaynak teklifi GET /v1/offers/{id} ile okuyun, kalemleri ve alanları POST /v1/offers gövdesine taşıyın ve status değerini draft yapın. Kopyaya valid_until için yeni bir tarih vermeniz iyi olur. Kaynak teklifi okumak için View:Offer, kopyayı oluşturmak için Create:Offer izni gerekir.

Silme

DELETE /v1/offers/{id} teklifi ve kalemlerini Geri Dönüşüm Kutusu’na taşır. Kilitli (accepted, converted) teklif silinemez. Bekleme süresi ve geri yükleme için Silme yaşam döngüsü sayfasına bakın.

PDF

PDF üretimi eşzamansızdır. POST /v1/offers/{id}/generate-pdf isteği işi kuyruğa alır ve hemen 202 döner. PDF A4 boyutundadır.

integer

İsteğe bağlı teklif şablonu kimliği. Vermezseniz kliniğin aktif şablonlarından varsayılan olanı kullanılır. Her yeni klinikte Varsayılan Teklif Şablonu hazır gelir.

curl

curl -X POST "https://app.flextell.ai/api/v1/offers/123/generate-pdf" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Yanıt: {"message": "Teklif PDF dosyası oluşturma işi kuyruğa alındı."} Her üretim yeni bir dosya kaydı ekler; eski PDF’ler silinmez. Dosya adı offer - <hasta adı> - <teklif id> - <tarih_saat>.pdf biçimindedir. İş bitince isteği yapan kullanıcıya Dosya Yüklendi bildirimi gider. Üretim başarısız olursa bildirim gelmez, bu yüzden sonucu GET /v1/offers/{id}/pdfs ile kontrol edin. GET /v1/offers/{id}/pdfs sayfalı döner (per_page 1–100, varsayılan 15; sort_order, created_at_from, created_at_to). Her kayıtta id, name, description, mime_type, size, source, created_at ve updated_at bulunur. GET /v1/offers/{id}/pdfs/{fileId}/download-url kısa ömürlü bir bağlantı üretir.

Parametre	Varsayılan	Açıklama
`disposition`	`attachment`	`attachment` indirir, `inline` tarayıcıda açar.
`expires_in`	15	Bağlantı ömrü, dakika (1–60).

Yanıt url, expires_at (ISO 8601), disposition ve file alanlarını içerir. Dosya depolamadan kaybolmuşsa 404 OFFER_PDF_FILE_MISSING döner. DELETE /v1/offers/{id}/pdfs/{fileId} PDF’i kalıcı siler; teklif kilitli olsa bile çalışır.

Satışa dönüştürme

POST /v1/offers/{id}/convert teklifi, aynı kalemlerle yeni bir taslak satışa çevirir. İsteğin gövdesi yoktur. Token’ınızda hem offers:write hem sales:write scope’u, rolünüzde Convert:Offer izni olmalıdır. Update:Offer bu işlem için yeterli değildir. Dönüştürme draft, sent ve accepted tekliflerde çalışır. Başarılı olunca 201 ve satış nesnesi döner; satışın status değeri draft olur. Teklif converted durumuna geçer ve sale_id alanı dolar.

Satışa hasta, para birimi, kur ve notlar taşınır. Satışın sahibi, isteği yapan kullanıcı değil teklifin sahibidir.
Her kalem sırası, miktarı, vergi oranı, fiyatı, indirimleri ve toplamlarıyla birebir kopyalanır. Ürün kalemlerinin maliyet fiyatı üründen alınır; tedavi kalemlerinde 0’dır.
İkinci çağrı 422 döner. Satış nesnesi için Satışlar sayfasına bakın.

curl

curl -X POST "https://app.flextell.ai/api/v1/offers/123/convert" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Hata kodları

Kod	HTTP	Ne zaman
`OFFER_LOCKED`	422	Kabul edilmiş veya satışa dönüştürülmüş teklifi güncelleme ya da silme.
`OFFER_NOT_CONVERTIBLE`	422	`rejected` veya `converted` teklifi dönüştürme.
`OFFER_ALREADY_CONVERTED`	422	Teklif eşzamanlı bir istekle zaten dönüştürülmüş.
`OFFER_TEMPLATE_MISSING`	422	`template_id` yok ve kliniğin aktif şablonu yok.
`OFFER_TEMPLATE_INVALID`	422	`template_id` başka bir klinikteki şablona ait. Var olmayan bir kimlik `422 VALIDATION_FAILED` döner.
`OFFER_PDF_FILE_MISSING`	404	Bağlantısı istenen PDF dosyası depolamada yok.
`CUSTOMER_ERASED`	409	Hastanın verileri imha edilmiş; teklif üzerinde her yazma işlemi (güncelleme, silme, dönüştürme, PDF) reddedilir. Okuma çalışır, `record_state.is_read_only` `true` olur.
`LEAD_NOT_ASSIGNED`	403	Satış temsilcisi, başka bir temsilcinin ya da kimseye atanmamış lead’in teklifine yazmaya çalışıyor. `data.assigned_user` sahibi gösterir.
`RESOURCE_NOT_FOUND`	404	Teklif veya PDF yok ya da size görünmüyor.
`FORBIDDEN`	403	Scope veya izin eksik.
`VALIDATION_FAILED`	422	Doğrulama hatası; ayrıntılar `errors` içindedir.

Ortak kodlar için Hata kodları 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

Görünürlük

Listeleme

Teklif nesnesi

Durum akışı

Oluşturma

Kalemler

Toplamlar

Kalem seçenekleri

Güncelleme

Teklifi çoğaltma

Silme

PDF

Satışa dönüştürme

Hata kodları

​Endpoint özeti

​Görünürlük

​Listeleme

​Teklif nesnesi

​Durum akışı

​Oluşturma

​Kalemler

​Toplamlar

​Kalem seçenekleri

​Güncelleme

​Teklifi çoğaltma

​Silme

​PDF

​Satışa dönüştürme

​Hata kodları

Endpoint özeti

Görünürlük

Listeleme

Teklif nesnesi

Durum akışı

Oluşturma

Kalemler

Toplamlar

Kalem seçenekleri

Güncelleme

Teklifi çoğaltma

Silme

PDF

Satışa dönüştürme

Hata kodları