> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# e-Fatura

> Nilvera ve NES entegratör hesaplarını API ile eklemeyi, serileri, kontör bilgisini ve fatura gönderim akışını anlatır.

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](/api/klinikler-ve-x-tenant) sayfasına bakın.

<Warning>
  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.
</Warning>

## 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.

<Note>
  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.
</Note>

## 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.

<CodeGroup>
  ```bash curl theme={null}
  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>" }
    }'
  ```
</CodeGroup>

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.

<Info>
  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](/panel/baglantilar/entegrasyonlar) sayfasına bakın.
</Info>

## 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.

```json Yanıt örneği theme={null}
{
  "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.

```bash theme={null}
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.

<Note>
  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.
</Note>

## Fatura gönderimi

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Ö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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Taslağı kesinleştirin">
    Taslak için `POST /invoices/{id}/send` çağırın. Belge bu noktada resmen kesilir ve geri alınamaz.
  </Step>

  <Step title="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.
  </Step>
</Steps>

`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. |

```bash theme={null}
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
  }'
```

<Note>
  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.
</Note>

<Warning>
  `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.
</Warning>

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](/api/kaynaklar/faturalar) sayfasına, uçtan uca akış için [Satış, tahsilat ve fatura](/api/rehberler/satis-tahsilat-fatura) rehberine bakın.

## Hatalar

Hata yanıtlarının genel yapısı [Hata kodları](/api/istekler/hata-kodlari) 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

<CardGroup cols={2}>
  <Card title="Faturalar" icon="file-text" href="/api/kaynaklar/faturalar">
    Fatura nesnesi, filtreler, PDF, XML ve e-posta uçları.
  </Card>

  <Card title="Satış, tahsilat ve fatura" icon="receipt" href="/api/rehberler/satis-tahsilat-fatura">
    Satıştan faturaya uçtan uca akış.
  </Card>

  <Card title="Entegrasyonlar genel bakış" icon="plug" href="/api/entegrasyonlar/genel-bakis">
    Diğer entegrasyonlar ve bağlantı kavramları.
  </Card>

  <Card title="Scope'lar" icon="key" href="/api/kimlik-dogrulama/scopelar">
    `invoices:read` ve `invoices:write` scope'ları.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.