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

# Faturalar ve e-Fatura hesapları

> Satıştan fatura oluşturmayı, fatura durumlarını, iptali, PDF/XML indirmeyi ve e-Fatura entegratör hesaplarını anlatır.

Fatura, bir satıştan e-belge entegratörü (**Nilvera** veya **NES**) üzerinden kestiğiniz resmî belgedir. Fatura her zaman bir satıştan doğar; taslak olarak kaydedebilir ya da hemen gönderebilirsiniz. Belgeyi hangi vergi kimliğiyle kesecekleri ise **fatura hesabı** belirler: kliniğin ya da doktorun entegratördeki kimliği ve API anahtarı.

<Warning>
  Şu an yalnızca **e-SMM** (Serbest Meslek Makbuzu) kesilir. Hesap türü olarak `einvoice` (E-Fatura) seçilebilir, ancak bu türdeki bir hesapla fatura, seri veya kontör çağrıları `*_FAILED` hata koduyla sonuçlanır. API ile oluşturduğunuz her faturanın `document_class` değeri `SMM`'dir. `EFATURA` ve `EARSIV` kayıtları yalnızca içe aktarılan verilerde görünür.
</Warning>

<Info>
  Tüm istekler `Authorization: Bearer <access_token>` ve `X-Tenant: <tenant_id>` başlıklarını taşır. Okuma endpoint'leri `invoices:read`, yazma endpoint'leri `invoices:write` scope'unu ister. Bkz. [Scope'lar](/api/kimlik-dogrulama/scopelar). Satış tarafı için [Satışlar](/api/kaynaklar/satislar) sayfasına, uçtan uca akış için [Satış, tahsilat ve fatura rehberi](/api/rehberler/satis-tahsilat-fatura) sayfasına bakın.
</Info>

## Endpoint özeti

İzinler istek doğrulanmadan önce denetlenir. Eksik scope veya izin `403 FORBIDDEN` döner.

| Metot | Endpoint | Açıklama | Scope | İzin |
| - | - | - | - | - |
| `GET` | `/api/v1/invoices` | Faturaları listeler. | `invoices:read` | `View:Invoice` |
| `GET` | `/api/v1/invoices/{id}` | Fatura detayını getirir. | `invoices:read` | `View:Invoice` |
| `POST` | `/api/v1/invoices` | Satıştan fatura oluşturur (taslak veya gönderilmiş). | `invoices:write` | `Create:Invoice` ve `CreateDocument:Sale` |
| `POST` | `/api/v1/invoices/preview` | Satıştan kaydetmeden HTML önizleme üretir. | `invoices:write` | `Create:Invoice` ve `CreateDocument:Sale` |
| `GET` | `/api/v1/invoices/{id}/preview` | Mevcut faturanın HTML önizlemesini getirir. | `invoices:read` | `Download:Invoice` |
| `POST` | `/api/v1/invoices/{id}/send` | Taslağı kesinleştirir ve entegratöre gönderir. | `invoices:write` | `Send:Invoice` |
| `POST` | `/api/v1/invoices/{id}/email` | Faturayı e-posta ile gönderir. | `invoices:write` | `SendEmail:Invoice` |
| `GET` | `/api/v1/invoices/{id}/email-history` | E-posta gönderim geçmişini döner. | `invoices:read` | `View:Invoice` |
| `POST` | `/api/v1/invoices/{id}/query-status` | Tek faturanın durumunu entegratörden sorgular. | `invoices:write` | `QueryStatus:Invoice` |
| `POST` | `/api/v1/invoices/query-status` | En çok 100 faturanın durumunu toplu sorgular. | `invoices:write` | `QueryStatus:Invoice` |
| `POST` | `/api/v1/invoices/{id}/cancel` | Faturayı iptal eder. | `invoices:write` | `Cancel:Invoice` |
| `POST` | `/api/v1/invoices/{id}/revert-cancel` | İptali geri alır. | `invoices:write` | `RevertCancel:Invoice` |
| `POST` | `/api/v1/invoices/{id}/archive` | Faturayı arşivler. | `invoices:write` | `Archive:Invoice` |
| `DELETE` | `/api/v1/invoices/{id}/archive` | Arşivden çıkarır. | `invoices:write` | `Archive:Invoice` |
| `GET` | `/api/v1/invoices/{id}/pdf/download` | PDF indirir. | `invoices:read` | `Download:Invoice` |
| `GET` | `/api/v1/invoices/{id}/xml` | XML içeriğini JSON içinde döner. | `invoices:read` | `Download:Invoice` |
| `GET` | `/api/v1/invoices/{id}/xml/download` | XML dosyasını indirir. | `invoices:read` | `Download:Invoice` |
| `GET` | `/api/v1/invoices/accounts` | Fatura hesaplarını listeler. | `invoices:read` | `View:Invoice`, `Create:Invoice` veya `View:InvoiceAccount` |
| `POST` | `/api/v1/invoices/accounts` | Fatura hesabı oluşturur. | `invoices:write` | `Create:InvoiceAccount` |
| `GET` | `/api/v1/invoices/accounts/{id}` | Fatura hesabı detayını getirir. | `invoices:read` | Liste ile aynı |
| `PUT` | `/api/v1/invoices/accounts/{id}` | Fatura hesabını günceller. | `invoices:write` | `Update:InvoiceAccount` |
| `PATCH` | `/api/v1/invoices/accounts/{id}/default-series` | Hesabın varsayılan serisini ayarlar. | `invoices:write` | `Update:InvoiceAccount` |
| `DELETE` | `/api/v1/invoices/accounts/{id}` | Fatura hesabını siler. | `invoices:write` | `Delete:InvoiceAccount` |
| `GET` | `/api/v1/invoices/series` | Hesabın entegratördeki aktif serilerini listeler. | `invoices:read` | `View:Invoice` veya `Create:Invoice` |
| `GET` | `/api/v1/invoices/credit` | Entegratördeki kontör bakiyesini döner. | `invoices:read` | `View:Invoice` |

Faturalar değiştirilemez: `PUT`/`PATCH /invoices/{id}` ve `DELETE /invoices/{id}` yoktur. Başka klinikteki bir kimlik her zaman `404 RESOURCE_NOT_FOUND` döner.

## Fatura nesnesi

| Alan | Tür | Açıklama |
| - | - | - |
| `id` | integer | Fatura kimliği. |
| `document_number` | string | Entegratörün verdiği belge numarası (ör. `SMM2026000000940`). Numara vermeyen entegratörde taslakta `{seri}-{8 rastgele karakter}` biçiminde geçici bir değer olur. |
| `document_class` | string | `SMM` (e-SMM). İçe aktarılan kayıtlarda `EFATURA` veya `EARSIV` olabilir. |
| `ettn` | string \| null | Entegratörün belge UUID'si. Gönderilmemiş taslakta `null`. |
| `issue_date` | string | Belge tarihi, yalnızca `YYYY-MM-DD`. |
| `sent_at` | string \| null | Gönderim zamanı. Her başarılı e-posta gönderiminde güncellenir. |
| `sender_tax_number` | string | Fatura hesabındaki vergi numarası. |
| `receiver_name`, `receiver_tax_number`, `receiver_email` | string | Kesim anındaki Hasta bilgisi (anlık görüntü). Pasaport modunda vergi numarası `11111111111` olur. |
| `exchange_rate` | string | Satışın döviz kuru, ondalık metin (`"1.00000000"`). |
| `amount_payable` | string | Hastadan tahsil edilen toplam (`"1500.00"`). |
| `invoice_amount` | string | Uygulamayla kesilen faturalarda `amount_payable` ile aynıdır. |
| `amount_tax_exclusive`, `amount_tax_total` | string \| null | Yalnızca içe aktarılan kayıtlarda dolu; uygulamayla kesilen e-SMM'de `null`. |
| `status`, `status_label` | string | Durum ve yerelleştirilmiş etiketi (bkz. [Durum akışı](#durum-akışı)). |
| `is_draft`, `is_cancelled`, `is_archived` | boolean | Taslak, iptal ve arşiv bayrakları. İptal için tek doğru kaynak `is_cancelled`'dır. |
| `is_printed`, `is_read` | boolean | Uygulama tarafından yönetilmez; bilgi amaçlıdır. |
| `series_name` | string \| null | Kullanılan seri. |
| `notes` | string \| null | Fatura notu. |
| `customer`, `currency` | object | Hasta ve para birimi ayrıntıları. |
| `record_state` | object | `is_read_only` ve `reason_code`. |
| `created_at`, `updated_at` | string | Klinik saat diliminde, ofsetli ISO 8601. |

Yanıt `sale_id`, `customer_id` ve `invoice_account_id` alanlarını döndürmez.

Satış temsilcisi izolasyonu açıksa ve Hasta başka bir temsilciye atanmış bir lead ise `record_state` değeri `{"is_read_only": true, "reason_code": "LEAD_NOT_ASSIGNED"}` olur. Bu durumda alıcı adı, vergi numarası, e-posta ve Hasta kimlik alanları maskelenir. Bkz. [İzinler ve görünürlük](/api/izinler-ve-gorunurluk).

### Listeleme

`GET /invoices` yalnızca bu kaynağa özgü filtreleri destekler. Genel kurallar için [Sayfalama](/api/istekler/sayfalama) ve [Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama) sayfalarına bakın.

| Parametre | Açıklama |
| - | - |
| `search` | En çok 255 karakter. Belge numarası, alıcı adı ve vergi numaralarında arar; her sözcük ön ek eşleşmesidir ve hepsi eşleşmelidir. |
| `status` | `draft`, `sent`, `waiting`, `success`, `error`, `cancelled`. |
| `is_archived`, `is_draft`, `is_cancelled` | Boolean. Anahtar varsa uygulanır (`is_archived=0` yalnızca arşivlenmemişleri getirir). Arşivliler filtrelemezseniz dahildir. |
| `document_class` | `EFATURA`, `EARSIV` veya `SMM`. |
| `sale_id`, `customer_id` | Tam sayı, en az 1. |
| `issue_date_from`, `issue_date_to` | Uçlar dahil takvim günü. `_to`, `_from`'dan önce olamaz. |
| `sort_by` | `created_at` (varsayılan), `issue_date`, `document_number`, `amount_payable`, `status`. |
| `sort_order` | `asc` veya `desc` (varsayılan). |
| `per_page` | 1–100, varsayılan 15. |

`View:Invoice` iznine sahip herkes klinikteki tüm faturaları görür; faturalar için "tümünü görme" izni ayrıca yoktur.

## Durum akışı

| `status` | Etiket | Anlamı |
| - | - | - |
| `draft` | Taslak | `mode=draft` ile oluşturuldu, kesinleştirilmedi. |
| `sent` | Gönderildi | Flextell entegratöre gönderdi (oluşturma, kesinleştirme veya iptal geri alma sonrası). |
| `waiting` | Bekliyor | Entegratör durumu bilinmiyor veya bekliyor. |
| `success` | Başarılı | Entegratör işlemi tamamladı. |
| `error` | Hata | Entegratör hata bildirdi. |
| `cancelled` | İptal Edildi | Flextell üzerinden veya NES tarafında iptal edildi. |

```mermaid theme={null}
flowchart LR
  A[Taslak] -->|send| B[Gönderildi]
  C[mode=send] --> B
  B -->|query-status| D[Bekliyor / Başarılı / Hata]
  B -->|cancel| E[İptal Edildi]
  E -->|revert-cancel| B
```

`query-status` yerel durumu entegratörün durumuyla değiştirir. Entegratör kodları şöyle eşlenir: bilinmiyor, bekliyor veya beklemede `waiting`; başarılı veya tamamlandı `success`; hata veya başarısız `error`; iptal `cancelled`. Tanınmayan kodlar `waiting` olur.

<Warning>
  Durum sorgusu `cancelled` ya da `draft` durumunu entegratörün işlem durumuyla ezebilir. Nilvera hiçbir zaman `cancelled` döndürmez; iptal edilmiş bir Nilvera e-SMM'sini yeniden sorguladığınızda `status=success` ve `is_cancelled=true` görürsünüz. İptal bilgisi için her zaman `is_cancelled` alanına güvenin.
</Warning>

Toplu sorgu (`POST /invoices/query-status`) `ids` dizisinde 1–100 kimlik alır ve her zaman `200` döner. Başarısız kayıtlar `results[].message` alanında bildirilir, HTTP hatası olarak değil:

```json theme={null}
{
  "success_count": 1,
  "failed_count": 1,
  "results": [
    { "invoice_id": 123, "success": true, "message": "Durum güncellendi." },
    { "invoice_id": 999, "success": false, "message": "Fatura bulunamadı" }
  ]
}
```

## Fatura oluşturma

`POST /api/v1/invoices` bir satıştan fatura keser. Flextell önce entegratörü çağırır, ardından yerel kaydı yazar.

| Alan | Zorunlu | Açıklama |
| - | - | - |
| `sale_id` | Evet | Satış kimliği. Satışı görebiliyor olmanız gerekir; aksi halde `404`. |
| `invoice_account_id` | Evet | Belgeyi kesecek fatura hesabı. |
| `mode` | Evet | `draft` veya `send`. |
| `series_name` | Evet | En çok 50 karakter. `GET /invoices/series` listesinden seçin. |
| `issue_date` | Evet | Tarih ya da tarih-saat. Saat kısmı belge saati olur; saat dilimi dönüştürülmez. |
| `custom_line_items[]` | Hayır | Özel satırlar: `name` (en çok 255), `quantity` (en az 0,01), `unit_price` (0 veya üstü), `tax_rate` (`0`, `1`, `10` veya `20`). |
| `global_withholding_rate` | Hayır | Stopaj oranı, **0–1 arası kesir** (`0.20` = %20). Her satıra uygulanır. |
| `use_passport_number` | Hayır | `true` ise alıcı kimliği `11111111111` olur ve nota `Pasaport Numarası: ...` eklenir. |
| `notes` | Hayır | En çok 2000 karakter. |

Satış görünürlüğü için `ViewAllSales:Sale` iznine sahip değilseniz satışın size ait olması ya da Hastanın lead'inin size atanmış olması gerekir.

<CodeGroup>
  ```bash curl 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": 7,
      "mode": "send",
      "series_name": "SMM",
      "issue_date": "2026-10-12T14:30:00",
      "global_withholding_rate": 0.20
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://app.flextell.ai/api/v1/invoices", {
    method: "POST",
    headers: {
      Authorization: "Bearer <access_token>",
      "X-Tenant": "<tenant_id>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sale_id: 123,
      invoice_account_id: 7,
      mode: "send",
      series_name: "SMM",
      issue_date: "2026-10-12T14:30:00",
    }),
  });
  ```
</CodeGroup>

Başarılı yanıt `201` ve fatura nesnesidir.

### Satır ve tutar kuralları

* `custom_line_items` göndermezseniz her satış kalemi bir satır olur. Gönderirseniz her satır `quantity × unit_price` olarak hesaplanır.
* Tutarı 0 veya altındaki satırlar atılır. Hiç satır kalmazsa fatura oluşmaz; bu yüzden 0 TL'lik satışa e-SMM kesilemez.
* Satır tutarı, Hastadan **KDV dahil ve stopaj düşülmüş olarak tahsil edilen** tutar sayılır. Brüt ücret `tutar / (1 − stopaj + KDV)` ile bulunur; KDV ve stopaj brüt ücretten hesaplanır. Stopaj uygulamak Hastanın ödediği tutarı değiştirmez, vergi matrahını büyütür.
* Örnek: %10 KDV ile 50.000 TL için brüt 45.454,55, KDV 4.545,46, ödenecek 50.000,00. %20 stopajla brüt 55.555,56, KDV 5.555,56, stopaj 11.111,11, ödenecek yine 50.000,00.
* Yabancı para birimli satışta satışın `exchange_rate` değeri 0'dan büyük olmalıdır. Aksi halde istek `INVOICE_CREATE_FAILED` ile döner.
* Eksik Hasta bilgisi (ad, kimlik, adres) için XML'de varsayılanlar kullanılır: şehir `İstanbul`, ülke `Türkiye`, ilçe `Merkez`, Hasta adı `Hasta`. Kimlik numarası olmayan Hastada entegratör belgeyi reddedebilir; faturalamadan önce bilgileri tamamlayın.
* Kimlik numarası 11 haneliyse TCKN, diğer durumlarda VKN sayılır.

### Önizleme

`POST /invoices/preview` oluşturma ile aynı gövdeyi alır (`mode` hariç) ve hiçbir şey kaydetmeden `{ "sale_id", "invoice_account_id", "html" }` döner. Kesmeden önce kontrol etmek için kullanın.

<Warning>
  Nilvera'nın ayrı bir taslak uç noktası yoktur; `mode=draft` isteği Nilvera hesabında da entegratöre gönderim çağrısı yapar ve belgenin bu durumda kesinleşip kesinleşmediği doğrulanmamıştır. Nilvera hesabıyla kesim yapacaksanız önce `/invoices/preview` ile önizleyin ve `draft` modunu kesin gönderim gibi ele alın.
</Warning>

### Taslağı kesinleştirme

`POST /invoices/{id}/send` taslağı gönderir. Taslak oluşturulduğu andaki XML ile gönderilir; satışta sonradan yaptığınız değişiklikler yansımaz. Zaten kesinleştirilmiş bir faturada `INVOICE_SEND_FAILED` ve `Bu fatura zaten kesinleştirilmiş.` mesajını alırsınız. Entegratör "zaten kayıtlı" derse mesaj, durumu `query-status` ile kontrol etmenizi söyler.

### Yan etkiler

* **Satış durumu.** Gönderilmiş bir fatura (oluşturma, kesinleştirme veya iptal geri alma sonrası) kalan faturalanabilir tutarı sıfıra indirirse satış `invoiced` (**Faturalandırıldı**) olur. Taslaklar satışı değiştirmez. Faturalanmış satış silinemez.
* **Stok.** Klinik ayarı **Stok Düşürme Modu** `Fatura Kesildiğinde` ise gönderilmiş fatura, satıştaki **tüm ürün kalemlerini** stoktan düşer (yalnızca özel satırları değil). Stok yetersizse işlem başarısız olur. Bkz. [Depolar ve stok](/api/kaynaklar/depolar-ve-stok).
* **Lead kuralı.** Lead aşamasındaki Hasta için fatura kesilemez; istek `INVOICE_CREATE_FAILED` döner.

## İptal ve geri alma

**İptal.** `POST /invoices/{id}/cancel` gönderilmiş faturayı iptal eder. Başarıda `status=cancelled`, `is_cancelled=true` olur ve satış `invoiced` idiyse `completed` durumuna döner (satışa ait başka geçerli fatura kalsa bile). İptal stoku geri yükler.

**Geri alma.** `POST /invoices/{id}/revert-cancel` iptali geri alır: `status=sent`, `is_cancelled=false`. Kalan faturalanabilir tutar sıfırsa satış yeniden `invoiced` olur. Stok yeniden düşülmez.

| Durum | Hata mesajı |
| - | - |
| Fatura henüz entegratöre gönderilmemiş | `Fatura henüz e-fatura sistemine gönderilmemiş.` |
| Taslak iptal edilmek isteniyor | `Taslak faturalar iptal edilemez.` |
| Zaten iptal edilmiş | `Bu fatura zaten iptal edilmiş.` |
| İptal edilmemiş bir fatura geri alınıyor | `Bu fatura iptal edilmemiş.` |
| `EFATURA` sınıfında | `E-Fatura iptal işlemi bu ekrandan yapılamaz.` |

Başarısızlıkta mesaj, hata zarfının `message` alanında gelir. Entegratör kaynaklı hatalar şöyle çevrilir: zaman aşımı `Bağlantı zaman aşımına uğradı. Lütfen tekrar deneyin.`, yetkilendirme hatası `API yetkilendirmesi başarısız. Fatura hesabı ayarlarını kontrol edin.`, bulunamadı `Belge bulunamadı.`; diğer durumlarda entegratörün ham metni döner.

`archive` ve `DELETE .../archive` yalnızca Flextell'deki arşiv bayrağını değiştirir, entegratörü çağırmaz ve tekrarlanabilir (idempotent). Fatura silme yoktur; faturalar yasal saklama kapsamındadır ve Hasta imha talebiyle silinmez.

## Belgeler

| İşlem | Endpoint | Yanıt |
| - | - | - |
| HTML önizleme | `GET /invoices/{id}/preview` | `{ "invoice_id", "document_number", "html" }`. Gönderilmemiş faturada `INVOICE_PREVIEW_FAILED` döner. |
| PDF indirme | `GET /invoices/{id}/pdf/download` | `application/pdf`, dosya adı `{document_number}.pdf`. |
| XML içeriği | `GET /invoices/{id}/xml` | `{ "invoice_id", "document_number", "xml" }`. Saklı XML yoksa `404`. |
| XML indirme | `GET /invoices/{id}/xml/download` | `application/xml`, dosya adı `{document_number}.xml`. |
| E-posta gönderme | `POST /invoices/{id}/email` | Gövde: `emails[]` (1–20 geçerli e-posta, her biri en çok 255 karakter). |
| E-posta geçmişi | `GET /invoices/{id}/email-history` | `data[]`: `id`, `email`, `status`, `status_label`, `sent_at`. Sayfalama yoktur. |

E-posta geçmişindeki `status` değerleri `sent`, `read`, `unread` ve `failed`'dir; `status_label` her zaman Türkçedir (`Gönderildi`, `Okundu`, `Okunmadı`, `Başarısız`, `Bilinmiyor`). Önizleme, PDF ve XML endpoint'leri `Download:Invoice`, e-posta gönderme `SendEmail:Invoice`, e-posta geçmişi `View:Invoice` iznini ister.

```bash theme={null}
curl -X POST "https://app.flextell.ai/api/v1/invoices/123/email" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["ayse@example.com"]}'
```

## Fatura hesapları ve seriler

Fatura hesabı, belgeyi kesen tarafın vergi kimliğini ve entegratör bağlantısını tutar. Hesap oluşturmadan önce entegratörü seçin: `integration_id`, tipi fatura olan ve aktif bir entegratöre (Nilvera veya NES) ait olmalıdır.

### Hesap nesnesi

| Alan | Tür | Açıklama |
| - | - | - |
| `id`, `integration_id` | integer | Hesap ve entegratör kimliği. Entegratör oluşturduktan sonra değişmez. |
| `integration` | object | `id`, `name`, `system_name`, `company_logo` (kısa ömürlü imzalı URL veya `null`). |
| `party_type`, `party_type_label` | string | `individual` (Bireysel) veya `company` (Kurumsal). |
| `document_type`, `document_type_label` | string | `evoucher` (E-SMM) veya `einvoice` (E-Fatura). Yalnızca `evoucher` çalışır. |
| `name`, `surname` | string \| null | Bireysel hesapta ad ve soyad. |
| `title` | string \| null | Kurumsal hesapta ticari unvan. |
| `tax_number` | string | VKN (10 hane) veya TCKN (11 hane); en çok 11 karakter, biçim denetimi yoktur. |
| `tax_office`, `address`, `phone`, `email` | string \| null | Belgede görünen satıcı bilgileri. |
| `country_id`, `city_id`, `district_id` | integer \| null | Adres (ülke, il, ilçe hiyerarşisi). |
| `default_series` | string \| null | Faturalarken ön seçilen seri. |
| `withholding_rate_percent` | number | Varsayılan stopaj oranı, 0–100. |
| `default_apply_withholding` | boolean | Stopajın varsayılan olarak işaretli gelip gelmeyeceği. |
| `use_vat_exemption` | boolean | Saklanır ve döner; belge üretiminde kullanılmaz. |
| `configured_extra_fields` | array | Değeri girilmiş kimlik bilgisi anahtarları (ör. `["API_KEY"]`). |

API anahtarı şifreli saklanır ve hiçbir yanıtta dönmez.

### Hesap oluşturma ve güncelleme

`POST /invoices/accounts` gövdesinde `integration_id`, `party_type`, `document_type`, `tax_number` ve `extra_fields` zorunludur. Bireysel hesapta `name` ve `surname`, kurumsal hesapta `title` zorunludur. `extra_fields`, entegratörün istediği **her anahtarı** içermelidir; Nilvera ve NES için bu `API_KEY` (**API Anahtarı**) alanıdır.

```bash 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": 1,
    "party_type": "individual",
    "name": "Ayşe",
    "surname": "Yılmaz",
    "tax_number": "11111111111",
    "document_type": "evoucher",
    "extra_fields": { "API_KEY": "<entegrator_api_anahtari>" }
  }'
```

`PUT /invoices/accounts/{id}` aynı gövdeyi alır, ancak `integration_id` göndermek `422` verir. Güncelleme tam değiştirme gibi davranır: göndermediğiniz isteğe bağlı alanlar (`tax_office`, adres, iletişim) `null`, boolean alanlar `false` ve `withholding_rate_percent` 0 olur. Yalnızca `extra_fields` birleştirilir; göndermediğiniz anahtar mevcut değerini korur. `party_type` değiştirirseniz diğer türün ad alanları temizlenir.

`PATCH /invoices/accounts/{id}/default-series` yalnızca `default_series` alır (zorunlu, en çok 255 karakter). Değer entegratörde doğrulanmaz; `GET /invoices/series` listesinden seçin.

`DELETE /invoices/accounts/{id}` hesabı kalıcı siler. Hesaptan kesilmiş fatura varsa `422 INVOICE_ACCOUNT_HAS_INVOICES` döner. Doktorların `preferred_invoice_account_id` değeri `null` olur.

### Seri ve kontör

`GET /invoices/series?invoice_account_id=7` entegratördeki **aktif** serileri döner:

```json theme={null}
{ "invoice_account_id": 7, "series": { "SMM": "SMM" } }
```

`GET /invoices/credit?invoice_account_id=7` entegratör kontörünü döner: `{ "total", "used", "remaining", "percentage" }`. Flextell kontörü kendisi saymaz, yalnızca entegratörün bakiyesini okur. Seriler 5 dakika, kontör bilgisi 1 dakika önbellekte tutulabilir; hesabı güncellediğinizde veya varsayılan seriyi değiştirdiğinizde önbellek temizlenir. Her iki çağrı da entegratöre bağlıdır; API anahtarı eksik ya da yanlışsa, entegratör yanıt vermezse veya hesap `einvoice` türündeyse `INVOICE_SERIES_LOOKUP_FAILED` / `INVOICE_CREDIT_LOOKUP_FAILED` döner.

### Varsayılan hesap

Satış detayındaki `default_invoice_account_id` alanı faturalarken önerilen hesabı verir. Sıra: satışı yapan kullanıcının tercih ettiği hesap; yoksa satış kalemlerindeki tüm doktorların ortak tercihi (doktorlar farklı hesap seçtiyse tahmin edilmez); yoksa klinik ayarı `default_invoice_account_id`; yoksa `null`. Aday hesabın kliniğe ait ve entegratörünün aktif olması gerekir. Doktor tercihi için [Doktorlar, asistanlar, odalar](/api/kaynaklar/doktorlar-asistanlar-odalar), klinik ayarı için [Ayarlar](/api/kaynaklar/ayarlar) sayfasına bakın.

## Hata kodları

Genel hata yapısı için [Hata kodları](/api/istekler/hata-kodlari) sayfasına bakın. Servis belirli bir neden döndürdüğünde, o Türkçe metin varsayılan mesajın yerine geçer.

| Kod | HTTP | Ne zaman |
| - | - | - |
| `INVOICE_CREATE_FAILED` | 422 | `POST /invoices` içinde satış ve hesap bulunduktan sonraki her hata (entegratör, eşleme, stok, Lead aşaması). Gerçek neden yanıtta verilmez. |
| `INVOICE_PREVIEW_FAILED` | 422 | Önizleme üretilemedi (gönderilmemiş fatura, entegratör hatası, eksik döviz kuru, pozitif satır yok). |
| `INVOICE_PDF_GENERATION_FAILED` | 422 | PDF alınamadı. |
| `INVOICE_SEND_FAILED` | 422 | Taslak kesinleştirilemedi. |
| `INVOICE_EMAIL_SEND_FAILED` | 422 | E-posta gönderilemedi. |
| `INVOICE_EMAIL_HISTORY_FAILED` | 422 | E-posta geçmişi alınamadı. |
| `INVOICE_STATUS_QUERY_FAILED` | 422 | Tek fatura durum sorgusu başarısız. |
| `INVOICE_CANCEL_FAILED` | 422 | İptal reddedildi veya entegratör hata verdi. |
| `INVOICE_CANCEL_REVERT_FAILED` | 422 | İptal geri alınamadı. |
| `INVOICE_ACCOUNT_MISSING` | 422 | Faturanın bağlı hesabı yok ya da silinmiş. |
| `INVOICE_ACCOUNT_HAS_INVOICES` | 422 | Faturası olan hesap silinmek istendi. |
| `INVOICE_SERIES_LOOKUP_FAILED` | 422 | Seri listesi alınamadı. |
| `INVOICE_CREDIT_LOOKUP_FAILED` | 422 | Kontör bilgisi alınamadı. |
| `LEAD_NOT_ASSIGNED` | 403 | İzole satış temsilcisi, başka birine atanmış lead'in faturasında `send`, `email`, `query-status`, `cancel`, `revert-cancel`, `archive` veya oluşturma yapıyor. `data.assigned_user` atanan kişiyi (`{id, name}`) ya da `null` verir. |
| `RESOURCE_NOT_FOUND` | 404 | Fatura, hesap, satış ya da saklı XML bulunamadı (`Fatura bulunamadı`, `Fatura hesabı bulunamadı`, `Satış bulunamadı`, `Fatura XML dosyası bulunamadı`). |
| `VALIDATION_FAILED` | 422 | Gövde veya sorgu parametresi geçersiz. |

Toplu durum sorgusu, önizleme ve okuma endpoint'leri `LEAD_NOT_ASSIGNED` denetimi yapmaz.

## İlgili sayfalar

<CardGroup cols={2}>
  <Card title="Satışlar" icon="receipt" href="/api/kaynaklar/satislar">
    Faturanın kaynağı olan satış kayıtları.
  </Card>

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

  <Card title="Faturalar (panel)" icon="file-text" href="/panel/finans/faturalar">
    Aynı kayıtların panel ekranı.
  </Card>

  <Card title="İzinler ve görünürlük" icon="shield" href="/api/izinler-ve-gorunurluk">
    Lead kısıtı ve maskeleme kuralları.
  </Card>
</CardGroup>


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