e-Fatura

Flextell, satışlardan resmi belge kesmek için kliniğin kendi Nilvera veya NES hesabını kullanır. Bu sayfa, entegratör hesabını (Flextell’deki adıyla fatura hesabı) API ile nasıl ekleyeceğinizi, seri ve kontör bilgisini nasıl okuyacağınızı ve bir satıştan belge nasıl keseceğinizi anlatır. Tüm uçlar https://app.flextell.ai/api/v1/invoices altındadır ve X-Tenant başlığı gerektirir. Başlık için Klinikler ve X-Tenant sayfasına bakın.

Bugün yalnızca e-SMM (Serbest Meslek Makbuzu) kesilebilir. API’ye document_type: "einvoice" olan bir hesap eklenebilir, ancak bu hesapla seri sorgulama, kontör sorgulama, önizleme ve belge gönderme çağrılarının hepsi hata verir. Fatura hesabını document_type: "evoucher" ile oluşturun.

Desteklenen entegratörler

Entegratör, hesap oluştururken verdiğiniz integration_id ile seçilir. Katalog tüm klinikler için ortaktır.

Entegratör	Katalog adı	Gerekli kimlik bilgisi
Nilvera	`Nilvera E-Fatura`	`API_KEY` (`API Anahtarı`)
NES Bilgi	`NES Bilgi E-Fatura`	`API_KEY` (`API Anahtarı`)

Başlamadan önce şunlar hazır olmalı:

Entegratörde açılmış, e-SMM (serbest meslek) modülü etkin bir hesap, tanımlı seri ve satın alınmış kontör.
Entegratörün verdiği API anahtarı.
Vergi kimlik numarası (VKN) veya TCKN, vergi dairesi ve adres bilgisi.

Flextell kayıt sırasında API anahtarını entegratöre karşı denemez; yalnızca şifreleyip saklar. Yanlış bir anahtar ilk seri, kontör veya gönderim çağrısında INVOICE_SERIES_LOOKUP_FAILED, INVOICE_CREDIT_LOOKUP_FAILED veya INVOICE_SEND_FAILED hatasıyla ortaya çıkar. Anahtar yanıtlarda hiçbir zaman geri dönmez.

Fatura hesabı ekleme

Hesap uçları ve gereken izinler:

Metot	Endpoint	Açıklama	Scope	İzin
`GET`	`/invoices/accounts`	Hesapları listeler	`invoices:read`	`View:Invoice`, `Create:Invoice` veya `View:InvoiceAccount`
`POST`	`/invoices/accounts`	Hesap oluşturur	`invoices:write`	`Create:InvoiceAccount`
`GET`	`/invoices/accounts/{id}`	Hesap detayı	`invoices:read`	Liste ile aynı
`PUT`	`/invoices/accounts/{id}`	Hesabı günceller	`invoices:write`	`Update:InvoiceAccount`
`DELETE`	`/invoices/accounts/{id}`	Hesabı siler	`invoices:write`	`Delete:InvoiceAccount`

Gövde alanları

Alan	Zorunlu	Açıklama
`integration_id`	Evet	Aktif bir fatura entegratörünün kimliği. Oluşturduktan sonra değiştirilemez; `PUT` isteğinde göndermeyin (422).
`party_type`	Evet	`individual` (şahıs) veya `company` (şirket).
`name`, `surname`	Şahıs ise	Ad ve soyad.
`title`	Şirket ise	Ticari unvan.
`tax_number`	Evet	VKN veya TCKN, en çok 11 karakter.
`tax_office`	Hayır	Vergi dairesi.
`country_id`, `city_id`, `district_id`	Hayır	Aktif ve birbiriyle tutarlı ülke, il, ilçe zinciri.
`address`	Hayır	En çok 1000 karakter.
`phone`, `email`	Hayır	Belgede tedarikçi iletişim bilgisi olarak görünür.
`document_type`	Evet	`evoucher` (e-SMM) veya `einvoice`. Yukarıdaki uyarıya bakın.
`use_vat_exemption`	Hayır	Saklanır ve döner; belge üretiminde kullanılmaz.
`withholding_rate_percent`	Hayır	Varsayılan stopaj oranı, 0 ile 100 arası.
`default_apply_withholding`	Hayır	Stopajın varsayılan olarak işaretli olup olmadığı.
`extra_fields`	Evet	Entegratörün istediği tüm anahtarları içeren nesne, örneğin `{"API_KEY": "..."}`. Her değer en çok 1000 karakter.

PUT isteği tam değiştirme gibi çalışır. Göndermediğiniz isteğe bağlı alanlar boşalır, mantıksal alanlar false olur, withholding_rate_percent 0’a döner. Yalnızca extra_fields birleştirilir: göndermediğiniz anahtarın kayıtlı değeri korunur. default_series bu istekle değişmez; bunun için ayrı uç vardır.

curl -X POST "https://app.flextell.ai/api/v1/invoices/accounts" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": 123,
    "party_type": "individual",
    "name": "Ayşe",
    "surname": "Yılmaz",
    "tax_number": "11111111111",
    "tax_office": "Kadıköy",
    "document_type": "evoucher",
    "withholding_rate_percent": 20,
    "default_apply_withholding": false,
    "extra_fields": { "API_KEY": "<entegrator_api_anahtari>" }
  }'

Başarılı yanıt 201 ve hesap nesnesidir. Nesnede kimlik bilgisinin kendisi yerine, hangi anahtarların tanımlı olduğunu gösteren configured_extra_fields listesi döner. Hesabı silmek için DELETE /invoices/accounts/{id} çağırın. O hesapla kesilmiş en az bir fatura varsa istek 422 INVOICE_ACCOUNT_HAS_INVOICES ile reddedilir.

Panelde Bağlantılar → Entegrasyonlar altındaki Fatura Hesapları ekranı şu an salt okunurdur. Hesap ekleme, düzenleme, silme ve varsayılan seri değiştirme için API’yi kullanın. Ekran için Entegrasyonlar sayfasına bakın.

Seriler ve varsayılan seri

Bir belge kesmek için entegratördeki aktif serilerden birini seçersiniz.

Metot	Endpoint	Açıklama	Scope	İzin
`GET`	`/invoices/series?invoice_account_id=123`	Hesabın entegratördeki aktif serileri	`invoices:read`	`View:Invoice` veya `Create:Invoice`
`PATCH`	`/invoices/accounts/{id}/default-series`	Hesabın varsayılan serisini ayarlar	`invoices:write`	`Update:InvoiceAccount`

View:InvoiceAccount izni tek başına seri listesini açmaz.

Yanıt örneği

{
  "invoice_account_id": 123,
  "series": { "SMM": "SMM" }
}

series bir ad-ad eşlemesidir; seri yoksa boş döner. Yalnızca aktif seriler listelenir. default_series alanı zorunlu bir metindir (en çok 255 karakter). Flextell değeri entegratöre karşı doğrulamaz, bu yüzden GET /invoices/series yanıtındaki adlardan birini gönderin.

curl -X PATCH "https://app.flextell.ai/api/v1/invoices/accounts/123/default-series" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{ "default_series": "SMM" }'

Kontör bilgisi

GET /invoices/credit?invoice_account_id=123 entegratördeki kontör bakiyesini döndürür. Scope invoices:read, izin View:Invoice (yalnızca bu izin).

Alan	Tür	Açıklama
`total`	tamsayı	Toplam tanımlı kontör.
`used`	tamsayı	Kullanılan kontör.
`remaining`	tamsayı	Kalan kontör.
`percentage`	ondalık	Kullanım yüzdesi.

Flextell kontörü kendisi saymaz; yalnızca entegratörün bildirdiği bakiyeyi okur. Her belge entegratörün kontörünü tüketir.

Seri listesi 5 dakika, kontör bilgisi 1 dakika önbellekte tutulur. Başarısız sorgular önbelleğe alınmaz. Hesabı güncellediğinizde veya sildiğinizde ya da varsayılan seriyi değiştirdiğinizde ilgili önbellek temizlenir.

Fatura gönderimi

Belge her zaman bir satıştan kesilir. Akış şöyledir:

Hesabı ve seriyi belirleyin

GET /invoices/accounts ile hesabı, GET /invoices/series ile seriyi seçin. Satış detayındaki (GET /sales/{id}) default_invoice_account_id alanı önerilen hesabı verir.

Önizleyin (isteğe bağlı)

POST /invoices/preview aynı gövdeyi (mode hariç) alır ve kayıt oluşturmadan { "sale_id", "invoice_account_id", "html" } döndürür.

Belgeyi kesin

POST /invoices ile mode değerini seçin: send belgeyi hemen gönderir, draft taslak olarak kaydeder. Başarılı yanıt 201 ve fatura nesnesidir.

Taslağı kesinleştirin

Taslak için POST /invoices/{id}/send çağırın. Belge bu noktada resmen kesilir ve geri alınamaz.

Durumu sorgulayın

POST /invoices/{id}/query-status entegratördeki durumu okuyup kaydı günceller. En fazla 100 faturayı tek istekte sorgulamak için POST /invoices/query-status ve ids dizisini kullanın.

POST /invoices için Create:Invoice ve CreateDocument:Sale izinleri birlikte gerekir (scope invoices:write). Satışı görebiliyor olmanız da gerekir: ViewAllSales:Sale iznine sahip değilseniz yalnızca kendi satışlarınızı veya size atanmış lead’in hastasına ait satışları kesebilirsiniz. Diğer satışlar 404 döner. Taslağı gönderme için Send:Invoice, durum sorgulama için QueryStatus:Invoice izni gerekir.

Alan	Zorunlu	Açıklama
`sale_id`	Evet	Faturalanacak satış.
`invoice_account_id`	Evet	Kullanılacak fatura hesabı.
`mode`	Evet	`draft` veya `send`.
`series_name`	Evet	Seri adı, en çok 50 karakter.
`issue_date`	Evet	Tarih veya tarih-saat. Saat kısmı belge saati olur.
`custom_line_items`	Hayır	Satış kalemleri yerine kullanılacak satırlar: `name`, `quantity` (en az 0,01), `unit_price`, `tax_rate` (`0`, `1`, `10` veya `20`).
`global_withholding_rate`	Hayır	Tüm satırlara uygulanan stopaj oranı, 0 ile 1 arası kesir (örneğin `0.20`).
`use_passport_number`	Hayır	Yabancı hasta için pasaport modu.
`notes`	Hayır	Belge notu, en çok 2000 karakter.

curl -X POST "https://app.flextell.ai/api/v1/invoices" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "sale_id": 123,
    "invoice_account_id": 123,
    "mode": "draft",
    "series_name": "SMM",
    "issue_date": "2026-10-13T14:30:00",
    "global_withholding_rate": 0.20
  }'

Stopaj oranını API hesabın withholding_rate_percent değerinden okumaz; her istekte global_withholding_rate göndermeniz gerekir. Satış kaleminin tutarı, hastadan tahsil edilen KDV dahil ve stopaj sonrası tutar sayılır. Stopaj uygulamak hastanın ödeyeceği tutarı değiştirmez, yalnızca brüt ücret tabanını büyütür.

mode=draft da entegratörü çağırır. Nilvera’nın ayrı bir taslak ucu yoktur; bu entegratörde taslak modunda da gönderim ucu kullanılır. Taslağı kesinleştirirken taslak anında saklanan belge yeniden gönderilir, satışta sonradan yaptığınız değişiklikler belgeye yansımaz. Toplam tutarı sıfır olan satıştan e-SMM kesilemez.

Fatura kayıtları değiştirilemez ve API ile silinemez. İptal için POST /invoices/{id}/cancel (Cancel:Invoice), iptali geri almak için POST /invoices/{id}/revert-cancel (RevertCancel:Invoice) kullanın. Nilvera iptal sonrası durum sorgusunda is_cancelled alanını true olarak döndürür ama status değerini cancelled yapmaz; iptalin kesin göstergesi olarak is_cancelled alanına bakın. Ayrıntılı fatura nesnesi ve diğer uçlar (PDF, XML, e-posta, arşiv) için Faturalar sayfasına, uçtan uca akış için Satış, tahsilat ve fatura rehberine bakın.

Hatalar

Hata yanıtlarının genel yapısı Hata kodları sayfasındadır. Bu sayfadaki uçlara özgü kodlar:

Kod	HTTP	Ne zaman
`INVOICE_ACCOUNT_HAS_INVOICES`	422	Faturası olan hesabı silmeye çalıştığınızda.
`INVOICE_SERIES_LOOKUP_FAILED`	422	Seri alınamadığında: yanlış veya eksik API anahtarı, entegratör erişilemiyor, e-Fatura türü hesap.
`INVOICE_CREDIT_LOOKUP_FAILED`	422	Kontör bilgisi alınamadığında.
`INVOICE_CREATE_FAILED`	422	`POST /invoices` içinde herhangi bir hata olduğunda. Gerçek neden yanıtta yer almaz.
`INVOICE_PREVIEW_FAILED`	422	Önizleme oluşturulamadığında.
`INVOICE_SEND_FAILED`	422	Taslak kesinleştirilemediğinde. `message` alanı nedeni verir.
`INVOICE_STATUS_QUERY_FAILED`	422	Durum sorgulanamadığında, örneğin `Fatura henüz e-fatura sistemine gönderilmemiş.`
`INVOICE_CANCEL_FAILED`	422	Fatura iptal edilemediğinde.
`INVOICE_CANCEL_REVERT_FAILED`	422	İptal geri alınamadığında.
`LEAD_NOT_ASSIGNED`	403	Size atanmamış bir lead’in hastasına ait satış veya faturada yazma işlemi yaptığınızda.
`RESOURCE_NOT_FOUND`	404	Hesap, satış veya fatura yoksa ya da görmeye yetkiniz yoksa.
`VALIDATION_FAILED`	422	Gövde doğrulamayı geçmediğinde, örneğin `extra_fields` içinde entegratörün istediği bir anahtar eksikse.

Entegratörden gelen hata metni bazı durumlarda message alanına olduğu gibi taşınır. Zaman aşımı, yetkilendirme hatası ve bulunamayan belge için Türkçe karşılıklar döner, örneğin API yetkilendirmesi başarısız. Fatura hesabı ayarlarını kontrol edin. Bu mesaj hesabınızın API anahtarını kontrol etmeniz gerektiği anlamına gelir. Toplu durum sorgusu POST /invoices/query-status her zaman 200 döner; başarısız faturalar results[].message içinde bildirilir. Tek bir faturada gönderim “zaten kayıtlı” gibi bir çakışma bildirirse, belgeyi yeniden göndermeden önce query-status ile durumunu kontrol edin.

İlgili sayfalar

Faturalar

Fatura nesnesi, filtreler, PDF, XML ve e-posta uçları.

Satış, tahsilat ve fatura

Satıştan faturaya uçtan uca akış.

Entegrasyonlar genel bakış

Diğer entegrasyonlar ve bağlantı kavramları.

Scope'lar

invoices:read ve invoices:write scope’ları.

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

Desteklenen entegratörler

Fatura hesabı ekleme

Gövde alanları

Seriler ve varsayılan seri

Kontör bilgisi

Fatura gönderimi

Hatalar

İlgili sayfalar

Faturalar

Satış, tahsilat ve fatura

Entegrasyonlar genel bakış

Scope'lar

​Desteklenen entegratörler

​Fatura hesabı ekleme

​Gövde alanları

​Seriler ve varsayılan seri

​Kontör bilgisi

​Fatura gönderimi

​Hatalar

​İlgili sayfalar

Faturalar

Satış, tahsilat ve fatura

Entegrasyonlar genel bakış

Scope'lar

Desteklenen entegratörler

Fatura hesabı ekleme

Gövde alanları

Seriler ve varsayılan seri

Kontör bilgisi

Fatura gönderimi

Hatalar

İlgili sayfalar