# Fatura kesmek ve iptal etmek > **Ne yaparsınız:** Siparişin faturasını önizler ve keser, sonucu ve yazdırılabilir görünümü alır, gerekirse faturayı iptal edersiniz. > **Hangi uçlar:** [Faturayı önizle](https://developer.siparis.app/uc/faturayi-onizle), [Fatura kes](https://developer.siparis.app/uc/fatura-kes), [Faturayı getir](https://developer.siparis.app/uc/faturayi-getir), [Fatura belgesini indir](https://developer.siparis.app/uc/fatura-belgesini-indir), [Fatura iptalini önizle](https://developer.siparis.app/uc/fatura-iptalini-onizle), [Faturayı iptal et](https://developer.siparis.app/uc/faturayi-iptal-et) > **Gereken izin:** Kesme ve önizleme için `invoices:write`, okuma için `invoices:read`; iptalde ayrıca `money_out:write`, alıcı ve belge için `personal_data:read`. API adresi `https://api.siparis.app/v1`. Panelle aynı fatura servisi kullanılır. Önce işletme sahibi **İşletme > Entegrasyonlar** bölümünden e-Fatura sağlayıcısını bağlar. Sağlayıcı anahtarı bu API’ye gönderilmez. Yazma kapsamı (izni) okumayı vermez. Markayla sınırlı anahtar başka markanın siparişini veya faturasını `404` olarak görür. Alıcı bilgileri paneldeki gibi siparişin fatura bilgilerinden ve adresinden seçilir; kesme isteğinde yeni alıcı girilmez. Bilgiyi düzeltmek için önce [Siparişi düzelt](https://developer.siparis.app/uc/siparisi-duzelt) kullanın (`orders:write` ve `personal_data:write`). ## 1. Önizleyin `SIPARIS_API_KEY` ortam değişkenine API anahtarınızı, `SIPARIS_ORDER_ID` değişkenine `ord_` kimliğini koyun. Bu istek sipariş, fatura, bağlantı veya iş kaydı yazmaz; `Idempotency-Key` (tekrar anahtarı) istemez. Ödeme kanıtı, sipariş durumu ve eksik fatura bilgisi panelin aynı kurallarıyla denetlenir. ```bash curl --fail-with-body --silent --show-error -X POST \ "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID/invoices/preview" \ -H "Authorization: Bearer $SIPARIS_API_KEY" \ -H 'Content-Type: application/json' \ --data '{}' ``` Örnek HTTP 200 yanıtı (uydurma veri): ```json { "kind": "e_arsiv", "lines": [ { "discount": "0.00", "name": "Örnek ürün", "net": "100.00", "quantity": "2", "tax_amount": "20.00", "tax_rate": "20", "total": "120.00", "unit": "adet", "unit_price": "50.0000" } ], "order": "ord_1234567890abcdef1234567890abcdef", "tax_total": "20.00", "total": "120.00", "warnings": [ { "code": "invoice_kind_unknown", "detail": "Belge türü sağlayıcı yanıt verdiğinde kesinleşir." } ] } ``` Bireysel alıcıya **e-Arşiv** kesilir. Şirket adına faturada sağlayıcı mükellef kaydını sorgular: kayıtlı alıcıya **e-Fatura**, diğerine **e-Arşiv**. `kind=null` ve `invoice_kind_unknown` uyarısı sorgunun yanıtsız kaldığını belirtir; tür kesimde yeniden sorgulanır. `invoice_buyer_title_differs` vergi numarasıyla unvanı kontrol etmenizi ister. Kalemler ve tutarlar paneldeki KDV ve indirim hesabıdır. ## 2. Fatura kesin `SIPARIS_INVOICE_KEY` değişkenine bu işlem için bir kez ürettiğiniz benzersiz tekrar anahtarını koyun: aynı isteği güvenle yeniden göndermenizi sağlayan metindir. Ağ hatasında aynı anahtar ve aynı gövdeyle yineleyin; her denemede yeni anahtar üretmeyin. ```bash curl --fail-with-body --silent --show-error -X POST \ "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID/invoices" \ -H "Authorization: Bearer $SIPARIS_API_KEY" \ -H "Idempotency-Key: $SIPARIS_INVOICE_KEY" \ -H 'Content-Type: application/json' \ --data '{}' ``` Örnek HTTP 202 yanıtı (uydurma veri): ```json { "cancelled_at": null, "created_at": "2026-10-16T09:00:00Z", "currency": "TRY", "id": "inv_1234567890abcdef1234567890abcdef", "issued_at": "2026-10-16T09:00:00Z", "kind": "e_arsiv", "status": "pending", "tax_total": "20.00", "total": "120.00", "updated_at": "2026-10-16T09:00:00Z" } ``` `202` ve `status=pending` isteğin kalıcı olarak alındığını gösterir. Yanıttaki `inv_` kimliğini `SIPARIS_INVOICE_ID` değişkenine koyun; `Location` aynı kaydın okuma yoludur. İsteğe bağlı `If-Match` başlığına siparişin güncel `ETag` değerini (sürüm etiketi) yazarsanız sipariş bu arada değiştiyse fatura kesilmez. Sağlayıcı isteği kabul edip yanıtı kaybolsa bile ikinci fatura kesilmez; sonuç aynı ETTN üzerinden sorgulanır. Paraşüt’te e-belge hazırlanması zaman alabilir. Bekleyen faturaya yeni istek açmayın. ## 3. Sonucu ve belgeyi alın ```bash curl --fail-with-body --silent --show-error \ "${SIPARIS_API_URL:-https://api.siparis.app/v1}/invoices/$SIPARIS_INVOICE_ID" \ -H "Authorization: Bearer $SIPARIS_API_KEY" ``` Örnek HTTP 200 yanıtı (uydurma veri): ```json { "cancelled_at": null, "created_at": "2026-10-16T09:00:00Z", "currency": "TRY", "id": "inv_1234567890abcdef1234567890abcdef", "issued_at": "2026-10-16T09:00:00Z", "kind": "e_arsiv", "status": "issued", "tax_total": "20.00", "total": "120.00", "updated_at": "2026-10-16T09:00:00Z" } ``` `pending` ise aralıklı okuyun; `issued` numaranın kesinleştiğini gösterir. `failed` veya `error_code` varsa paneldeki fatura ve sağlayıcı bağlantısını kontrol edin. Durumların anlamı [Kodlar ve durumlar](https://developer.siparis.app/referans#fatura-durumlari) sayfasındadır. `invoice.*` webhook olayları bu sürümde henüz yoktur; izlemek için bu okuma ucunu kullanın. Panelin sipariş geçmişi kesme/iptali kaydetmeye devam eder. ```bash curl --fail-with-body --silent --show-error \ "${SIPARIS_API_URL:-https://api.siparis.app/v1}/invoices/$SIPARIS_INVOICE_ID/document" \ -H "Authorization: Bearer $SIPARIS_API_KEY" \ --output fatura.html ``` Yanıt `200 text/html`: panelle aynı yazdırılabilir **fatura görünümü**. Resmî e-belge sağlayıcı portalındadır; bu uç PDF döndürmez. İptal edilmiş faturanın belgesi iptal damgasıyla alınabilir, kayıt silinmez. ## 4. İptali önizleyip uygulayın ```bash curl --fail-with-body --silent --show-error -X POST \ "${SIPARIS_API_URL:-https://api.siparis.app/v1}/invoices/$SIPARIS_INVOICE_ID/cancel/preview" \ -H "Authorization: Bearer $SIPARIS_API_KEY" \ -H 'Content-Type: application/json' \ --data '{}' ``` Örnek HTTP 200 yanıtı (uydurma veri): ```json { "code": null, "detail": null, "invoice": "inv_1234567890abcdef1234567890abcdef", "portal_required": false, "via_api": true } ``` Önizleme yan etkisizdir. `portal_required=true` ise önce sağlayıcının açıklamasına göre portalından iptal edin. e-Fatura ve Paraşüt e-belgelerinde bu yol kullanılır. Tamamlandığında aşağıdaki gövdeye `"portal_done":true` ekleyin. `SIPARIS_CANCEL_KEY` bu iptal için oluşturulan ayrı ve sabit tekrar anahtarıdır. ```bash curl --fail-with-body --silent --show-error -X POST \ "${SIPARIS_API_URL:-https://api.siparis.app/v1}/invoices/$SIPARIS_INVOICE_ID/cancel" \ -H "Authorization: Bearer $SIPARIS_API_KEY" \ -H "Idempotency-Key: $SIPARIS_CANCEL_KEY" \ -H 'Content-Type: application/json' \ --data '{"reason":"Yanlış fatura düzenlendi."}' ``` Örnek HTTP 202 yanıtı (uydurma veri): ```json { "cancellation_status": "pending", "cancelled_at": null, "created_at": "2026-10-16T09:00:00Z", "currency": "TRY", "id": "inv_1234567890abcdef1234567890abcdef", "issued_at": "2026-10-16T09:00:00Z", "kind": "e_arsiv", "status": "issued", "tax_total": "20.00", "total": "120.00", "updated_at": "2026-10-16T09:00:00Z" } ``` API ile iptalde `202` ve `cancellation_status=pending`; portal onayıyla veya zaten iptal edilmiş faturada `200` gelir. Kesinleşene kadar fatura `issued` kalabilir. İptal çağrısının sonucu bilinmiyorsa `cancellation_status=unknown` ve `invoice_cancel_uncertain` gelir: dış iptal otomatik yinelenmez. Portalda kontrol edip gerçekten iptal edildiğinde **yeni tekrar anahtarıyla** `portal_done=true` gönderin. Fatura iptali siparişi iptal etmez ve para iadesi yapmaz; muhasebe kaydı korunur. Bağlantı değiştiği veya sağlayıcı kesin olarak reddettiği için `cancellation_status=failed` geldiyse bağlantıyı panelde düzeltip **yeni tekrar anahtarıyla** iptali yeniden isteyin; aynı iptal kaydı kullanılır. İstek sağlayıcıya hiç gitmediyse geçici ağ hatasında beş dakika sonra kendiliğinden denenir. Platformun durdurduğu sağlayıcı açılana kadar kuyruk korunur. Henüz gönderilmemiş bekleyen iptal de, portalda tamamlandıysa `portal_done=true` ile kapatılabilir; aktif sağlayıcı çağrısı sürerken bu onay sonucu bekler. ## Sık hatalar | Kod | Ne yapmalı? | | --- | --- | | `invoice_not_connected` | İşletme > Entegrasyonlar’dan sağlayıcıyı bağlayın. | | `invoice_provider_auth` | Bağlantı bilgilerini panelde düzeltin; bekleyen faturayı aynı kimlikle izleyin. | | `invoice_payment_required` | Ödeme kaydını tamamlayın; onaylı sipariş tek başına ödeme kanıtı değildir. | | `invoice_billing_invalid` | Siparişin vergi no, vergi dairesi ve fatura adresini kontrol edin. | | `invoice_order_not_allowed`, `invoice_zero_total` | İptal/iade edilmiş veya 0 TL siparişe fatura kesilmez. | | `invoice_exists` | Siparişin mevcut faturasını okuyun; yeni bir fatura açmayın. | | `invoice_not_ready` | Numara kesinleşmeden belge indirmeyin veya iptal etmeyin. | | `invoice_portal_required` | Açıklamadaki sağlayıcı portalında iptal edip `portal_done=true` ile bildirin. | | `insufficient_scope` | Sahipten gereken kapsamlarla yeni bağlantı isteyin; belge ayrıca `personal_data:read` ister. | Kargo şartı ve taşıyıcı bilgileri panelle aynıdır: otomatik internet satışı faturası gerektiğinde gönderiyi bekler; taşıyıcının unvanı, VKN’si ve gönderim tarihi ortak servisten gelir. API farklı bir fatura kuralı uygulamaz. Faturanın kesin sonucu [olay akışı](https://developer.siparis.app/olaylar) ve [webhook](https://developer.siparis.app/webhook) üzerinden `invoice.issued`, `invoice.failed`, `invoice.cancelled` olarak gelir (`invoices:read`). Bekleyen veya belirsiz kesim hata olayı üretmez. Yükte fatura/sipariş kimliği, belge türü, durum ve tutar vardır; vergi numarası, unvan ve sağlayıcının hata metni yoktur.