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

> Flextell'in e-fatura entegratörleri (Nilvera ve NES) — belge türleri, hesap kurulumu ve fatura yaşam döngüsü.

Flextell, Türkiye'de **e-Fatura**, **e-Arşiv Fatura** ve **e-SMM** (Serbest Meslek Makbuzu) belgelerini iki farklı entegratör üzerinden kesmenize imkân verir: **Nilvera E-Fatura** ve **NES Bilgi E-Fatura**. Kurumunuz için hangisini kullanacağınızı seçip ilgili entegratörden aldığınız **API anahtarını** panelde tanıtarak kurulumu tamamlarsınız.

<Note>
  **E-Fatura entegrasyonları şu an yalnızca panel üzerinden** kullanılabilir. Public API'de (`/api/v1/*`) fatura kesme, taslak oluşturma, iptal veya sorgulama uçları henüz yayında değildir. Bu sayfa, entegrasyonun nasıl kurulduğunu ve satış kayıtlarının panelden nasıl faturalandığını açıklar.
</Note>

## Desteklenen entegratörler

| Entegratör         | `system_name`     | Şirket                                |
| ------------------ | ----------------- | ------------------------------------- |
| Nilvera E-Fatura   | `invoice.nilvera` | Nilvera Yazılım ve Bilişim Hizmetleri |
| NES Bilgi E-Fatura | `invoice.nes`     | NES Bilgi Teknolojileri A.Ş.          |

Aynı tenant için **birden fazla fatura hesabı** tanımlayabilirsiniz — örneğin biri e-Fatura için Nilvera, diğeri e-SMM için NES şeklinde. Her fatura hesabı bir entegratöre bağlıdır ve kendi API anahtarı ile ayrı ayrı çalışır.

## Belge türleri

Flextell'in kestiği belgeler `document_class` alanı ile ayrılır:

| `document_class` | Etiket   | Kullanım                                                               |
| ---------------- | -------- | ---------------------------------------------------------------------- |
| `EFATURA`        | E-Fatura | Alıcı **e-Fatura mükellefi** olduğunda (GİB kayıtlı)                   |
| `EARSIV`         | E-Arşiv  | Alıcı e-Fatura mükellefi **değilse** (son tüketici veya küçük işletme) |
| `SMM`            | E-SMM    | Serbest meslek makbuzu (hekim, danışman vb. hizmet gelirleri)          |

Fatura hesabı oluşturulurken `document_type` alanıyla bu hesabın `einvoice` mi yoksa `evoucher` (e-SMM) mi keseceği belirlenir.

## Kurulum akışı

```mermaid theme={null}
flowchart LR
    Tenant[Tenant Yöneticisi]
    Panel((Flextell Panel))
    Flextell[Flextell API]
    Provider[Entegratör Nilvera veya NES]

    Tenant -->|Panelden ekle| Panel
    Panel -->|API anahtarı test| Provider
    Panel -->|Fatura hesabı kaydet| Flextell
    Panel -->|Faturalandır| Flextell
    Flextell -->|UBL-TR XML gönder| Provider
    Provider -->|Belge numarası ve UUID| Flextell
```

1. Entegratörde hesap açın ve bir **API anahtarı** alın (test ortamı için entegratörün sandbox'ını kullanmanızı öneririz).
2. Flextell panelinde `Entegrasyonlar → E-Fatura → Yeni Hesap` altından Nilvera veya NES'i seçin.
3. **VKN/TCKN**, **vergi dairesi**, **unvan** ve **API anahtarı** gibi bilgileri girin. Gerekirse varsayılan seri adı ve stopaj oranı da burada tanımlanır.
4. Fatura kesmek istediğiniz satış kaydını (`sale`) panelden faturalandırın; Flextell, satışı **UBL-TR XML**'e dönüştürüp entegratöre iletir.

## Fatura durumları

Her faturanın yaşam döngüsünde `InvoiceStatus` alanı şu değerlerden birini alır:

| `status`    | Anlamı                                                                         |
| ----------- | ------------------------------------------------------------------------------ |
| `draft`     | Taslak — entegratöre gönderilmiş ama henüz kesinleşmemiş                       |
| `waiting`   | Entegratör tarafından kuyruğa alındı; GİB yanıtı bekleniyor                    |
| `sent`      | Entegratöre gönderildi                                                         |
| `success`   | GİB tarafından onaylandı                                                       |
| `error`     | Entegratör veya GİB tarafında hata oluştu (`original_status_detail` incelenir) |
| `cancelled` | İptal edildi                                                                   |

Belge sınıfına göre iptal davranışı değişir:

<Warning>
  **E-Fatura iptali GİB kuralları gereği 8 gün içinde yalnızca alıcı tarafından yapılabilir.** Flextell panelinden e-Fatura iptal aksiyonu kapalıdır; yalnızca **e-Arşiv** ve **e-SMM** belgeleri panelden iptal edilebilir.
</Warning>

## XML arşivi

Kesilen her belgenin **UBL-TR XML** çıktısı Flextell tarafında S3'te saklanır (`{tenant_id}/invoices/{yıl}/{ay}/{invoice_id}.xml`). Taslak fatura kesinleştirildiğinde veya iptal edildiğinde bu XML dosyası korunur; denetim ve arşiv gereksinimleri için panelden indirilebilir.

## Stok davranışı

Fatura oluşturulurken satışa bağlı ürünler için stok hareketi otomatik yazılır. Bunun zamanlaması tenant ayarındaki **stok düşüm modu** (`stock_deduction_mode`) ile belirlenir:

* **`on_invoice`** (varsayılan) — stok, fatura kesildiğinde düşer.
* **`on_sale`** — stok, satış oluşturulduğunda düşer; fatura yalnızca belgeleme adımıdır.

Fatura iptal edildiğinde (`on_invoice` modunda) ilgili stok hareketleri geri alınır.

## Kredi ve seri sorgulama

Panel, fatura hesabı kurulduktan sonra entegratörden gelen bilgileri periyodik olarak tazeler:

* **Kredi bakiyesi** — entegratörünüzde kalan kontör. Düşük bakiye bildirimi panelden gösterilir.
* **Seri listesi** — entegratörde tanımlı fatura serileri. Fatura keserken bu listeden bir seri seçilir.

<Tip>
  Hem Nilvera hem NES, test ortamlarında ücretsiz kontör tanımlar — canlıya almadan önce uçtan uca bir fatura akışını test ortamında denemenizi öneririz.
</Tip>

## E-Posta gönderimi

Kesilen bir e-Arşiv veya e-SMM belgesi, panel üzerinden hastaya e-posta ile iletilebilir. E-posta geçmişi (teslim durumu dahil) fatura kaydında tutulur; aynı faturayı birden fazla adrese iletebilirsiniz.

## Yol haritası

Aşağıdaki başlıklar yol haritasında yer almakla birlikte **şu an public API'de yayında değildir**:

* `POST /v1/invoices` — bir satıştan fatura kesme
* `POST /v1/invoices/{id}/cancel` — iptal
* `GET /v1/invoices/{id}/status` — entegratör durumunu sorgulama
* `GET /v1/invoices/{id}/pdf` — PDF çıktı indirme

Bu uçlar public API'ye eklendiğinde [Changelog](/resources/changelog) sayfasından duyurulacaktır.

## Sık sorulanlar

<AccordionGroup>
  <Accordion title="Her iki entegratörü aynı anda kullanabilir miyim?">
    Evet. Aynı tenant altında farklı entegratörlere bağlı birden fazla fatura hesabı tanımlayabilirsiniz. Örneğin kurumsal müşteriler için Nilvera, bireysel müşteriler için NES gibi bir bölünme mümkündür.
  </Accordion>

  <Accordion title="Stopaj ve KDV istisna senaryoları destekleniyor mu?">
    Evet. Fatura hesabında varsayılan **stopaj oranı** ve **KDV istisna kullanımı** tanımlanabilir; fatura keserken bu varsayılanlar satır bazında geçersiz kılınabilir.
  </Accordion>

  <Accordion title="Alıcının e-Fatura mükellefi olup olmadığını nasıl anlarım?">
    Entegratörler VKN/TCKN ile GİB mükellef sorgusu yapar; Flextell, fatura kesilirken alıcının e-Fatura mükellefi olup olmadığını bu sorguya göre otomatik `EFATURA` veya `EARSIV` sınıfına yönlendirir.
  </Accordion>

  <Accordion title="Yabancı uyruklu hasta için pasaport numarası ile fatura kesilebilir mi?">
    Evet. Bir sefere mahsus olarak `use_passport_number` bayrağı ile faturayı `11111111111` (yabancı uyruklu için rezervli TCKN) üzerinden keser ve hastanın pasaport bilgisini belge notlarına ekler. Bu akış e-Arşiv için tipiktir.
  </Accordion>
</AccordionGroup>

## Sonraki adımlar

<CardGroup cols={2}>
  <Card title="Satış kaydetme" icon="receipt" href="/guides/record-sale">
    Fatura kesilecek bir satış kaydını nasıl oluşturursunuz.
  </Card>

  <Card title="Entegrasyonlar - Genel Bakış" icon="plug" href="/integrations/overview">
    Kanal entegrasyonları ile e-fatura entegrasyonları arasındaki fark.
  </Card>
</CardGroup>