Fatura kesmek ve iptal etmek

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

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):

{
  "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.

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):

{
  "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

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):

{
  "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 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.

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

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):

{
  "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.

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):

{
  "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

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ışı ve 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.