İade almak ve para iadesi

İstekler https://api.siparis.app/v1 adresine gönderilir. Teslim edilmiş siparişte panelin İade et işlemiyle aynı hesap, stok hareketleri ve para defteri kullanılır. Önce önizleyin, görülen tutarı onaylayın, ardından sonucu izleyin. İptal edilmesi gereken açık sipariş ve pazaryeri siparişi için panelin mevcut kısıtları geçerlidir.

Yetki ve hazırlık

money_out:write hassas bir kapsamdır (anahtara verilen para çıkışı izni). Kodsuz talep onayı para çıkışı oluşturmaz. Yazma yetkisi okuma yetkisi vermez: aşağıdaki örneklerde orders:read, returns:read, payments:read ve olayları izlemek için events:read de gerekir. Kişisel açıklamalar yalnız personal_data:read ile görünür. Marka sınırlı anahtar başka markanın kaydında 404 not_found alır.

Anahtarı sunucunuzdaki SIPARIS_API_KEY ortam değişkeninde tutun; sohbete veya kaynak koduna yazmayın. SIPARIS_ORDER_ID değişkenine sipariş listesinden aldığınız ord_ kimliğini yazın. Örnekler curl, jq ve Python 3 kullanır.

1. İade talebini okuyun ve karar verin

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID/returns" \
  -H "Authorization: Bearer $SIPARIS_API_KEY"

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "data": [
    {
      "created_at": "2026-10-16T09:00:00Z",
      "currency": "TRY",
      "id": "ret_1234567890abcdef1234567890abcdef",
      "kind": "return",
      "refund_amount": null,
      "requested_at": "2026-10-16T09:00:00Z",
      "source": "customer",
      "status": "requested",
      "updated_at": "2026-10-16T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Listede seçtiğiniz müşteri talebinin ret_ kimliğini SIPARIS_RETURN_ID olarak tutun. Ayrıntı, istenen kalemlerin lin_ kimliklerini ve miktarlarını verir. Değişim talebini onaylamak yeni ürün siparişi açmaz; ürünle değişim panelin veya paneldeki AI'ın aynı değişim akışıyla tamamlanır.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/returns/$SIPARIS_RETURN_ID" \
  -H "Authorization: Bearer $SIPARIS_API_KEY"

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "created_at": "2026-10-16T09:00:00Z",
  "id": "ret_1234567890abcdef1234567890abcdef",
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1.000",
      "unit": "adet"
    }
  ],
  "kind": "return",
  "order": "ord_1234567890abcdef1234567890abcdef",
  "refund_amount": "120.00",
  "requested_at": "2026-10-16T09:00:00Z",
  "source": "panel",
  "status": "requested",
  "updated_at": "2026-10-16T09:00:00Z"
}

Onayda return_code varsayılan olarak false değerindedir: müşteri ürünü getirir veya satıcıyla kodsuz teslimde anlaşır. Açıkça return_code=true seçilirse kargolu sipariş için geri gönderim kodu açılır; BasitKargo bakiyenizden ücretlidir ve shipments:write gerekir. notify_customer=false karar e-postasını göndermez; not müşteri sayfasında görünür. Kod hemen açılamazsa talep paneldeki aynı bekleyen süreçte kalır.

export SIPARIS_DECISION_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body --silent --show-error -X POST \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/returns/$SIPARIS_RETURN_ID/approve" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_DECISION_KEY" -H 'Content-Type: application/json' \
  --data '{"return_code":false,"note":"Ürünü teslim aldığınız yere getirebilirsiniz.","notify_customer":true}'

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "created_at": "2026-10-16T09:00:00Z",
  "id": "ret_1234567890abcdef1234567890abcdef",
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1.000",
      "unit": "adet"
    }
  ],
  "kind": "return",
  "order": "ord_1234567890abcdef1234567890abcdef",
  "refund_amount": "120.00",
  "requested_at": "2026-10-16T09:00:00Z",
  "source": "panel",
  "status": "requested",
  "updated_at": "2026-10-16T09:00:00Z"
}

Idempotency-Key tekrar anahtarıdır: aynı isteği güvenle yeniden göndermek için sizin ürettiğiniz benzersiz metin. Reddetmek için İade talebini reddet ucuna yeni tekrar anahtarıyla {"note":"Ret nedeniniz","notify_customer":true} gönderin. Aynı kararı ağ hatası nedeniyle tekrarlarken aynı gövde ve anahtarı koruyun.

2. Önizleyin

Siparişin /lines listesinden iade edilecek lin_ kimliğini SIPARIS_LINE_ID olarak alın. Aşağıdaki örnek bir birim sağlam ürünü geri alır. Birden fazla kalem için items listesine ekleyin. quantity ürünün birimindedir; adetle satılan üründe kesir kullanmayın.

jq -n --arg item "$SIPARIS_LINE_ID" \
  '{items:[{item:$item,quantity:"1"}],restock:true,received_condition:"sound",money_returned:false,notify_customer:true}' \
  > iade-secimi.json
curl --fail-with-body --silent --show-error -X POST \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID/refunds/preview" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" -H 'Content-Type: application/json' \
  --data-binary @iade-secimi.json > iade-onizleme.json
jq . iade-onizleme.json

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "amount": "120.00",
  "completes": true,
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1.000",
      "restock": true,
      "unit": "adet"
    }
  ],
  "order": "ord_1234567890abcdef1234567890abcdef",
  "refund_distribution": {
    "card": "100.00",
    "manual": "20.00",
    "provider": "PayTR"
  },
  "refund_method": "iban",
  "remaining": "120.00",
  "shipping_included": true,
  "suggested_amount": "120.00",
  "warnings": []
}

Önizleme para, stok veya bildirim yazmaz; tekrar anahtarı gerekmez. amount geri ödenecek tutardır; yanıtın diğer alanları İadeyi önizle sayfasındadır. Tutarlar TRY cinsinden ondalık metindir. Kısmi iadede indirim sonrası ürün payı, son ürünlerin iadesinde kalan tahsilat ve kargo bedeli panelin kuralıyla hesaplanır.

Yalnız para iadesinde items:[] ve açık amount gönderin; stok değişmez. Tutarı değiştirmek için amount ekleyip yeniden önizleyin. Hasarlı ürünü fiziksel olarak teslim aldıysanız restock:false, received_condition:"damaged" fire yazar; yalnız restock:false fire yazmaz. warnings listesini kontrol edin.

restock verilmezse panel/AI varsayılanı uygulanır: iade edilemez işaretli, hasar nedenli veya received_condition=damaged ürün stoğa eklenmez; önizlemenin her items[] satırı uygulanacak seçimi gösterir. Ürün gerçekten yeniden satılabilecekse açıkça restock:true seçin.

3. Gördüğünüz tutarla iadeyi oluşturun

Para iadesi geri alınamaz. Yanlış para veya stok kaydı geçmişi silerek düzeltilmez; platformun kayıtlı düzeltme yolları kullanılır. İstekten önce tutarı, kalemleri, stok seçimini ve paranın yolunu onaylayın.

İlk örnek için zorunlu alanlar (POST /v1/orders/{id}/refunds):

Bütün alanlar: İade başlat.

jq --slurpfile preview iade-onizleme.json \
  '. + {expected_amount:$preview[0].amount,refund_distribution:$preview[0].refund_distribution}' \
  iade-secimi.json > iade-istegi.json
export SIPARIS_REFUND_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body --silent --show-error -X POST \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID/refunds" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_REFUND_KEY" -H 'Content-Type: application/json' \
  --data-binary @iade-istegi.json > iade-sonucu.json
jq . iade-sonucu.json
export SIPARIS_REFUND_ID="$(jq -er .id iade-sonucu.json)"

Örnek HTTP 201 yanıtı (uydurma veri):

{
  "amount": "120.00",
  "card_status": "pending",
  "id": "ret_1234567890abcdef1234567890abcdef",
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1.000",
      "unit": "adet"
    }
  ],
  "money_returned": false,
  "order": "ord_1234567890abcdef1234567890abcdef",
  "remaining_amount": "120.00",
  "restock": true
}

expected_amount zorunludur: önizlemede gördüğünüz tutardır. Sunucu işlemin kilitleri alındıktan sonra tutarı yeniden doğrular; uyuşmazsa 409 amount_changed ve current_amount döner, iade yapılmaz. Yeniden önizleyip yeni anahtarla onaylayın. Değişim veya ayrılan siparişte refund_distribution kart ve elle ödeme paylarını taşır; önizlemeden aynen gönderin.

Ağ hatasında aynı dosya ve SIPARIS_REFUND_KEY ile yalnız son curl komutunu tekrarlayın; anahtar üretme satırını yeniden çalıştırmayın. Idempotent-Replayed:true önceki işlemin güncel kaydını verdiğini gösterir. Aynı anahtarla eş zamanlı istek ikinci iade açmaz.

4. Para yoluna göre sonucu izleyin

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/refunds/$SIPARIS_REFUND_ID" \
  -H "Authorization: Bearer $SIPARIS_API_KEY"

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "amount": "120.00",
  "card_status": "pending",
  "id": "ret_1234567890abcdef1234567890abcdef",
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1.000",
      "unit": "adet"
    }
  ],
  "money_returned": false,
  "order": "ord_1234567890abcdef1234567890abcdef",
  "remaining_amount": "120.00",
  "restock": true
}

İade kaydının kimliği ret_, başarılı para hareketinin kimliği rfd_ öneklidir. payments aynı siparişin ödeme listesi ve güncel para özetidir; yazma ve tekrar yanıtlarında payments:read yoksa alan atlanır. GET /refunds/{id} için returns:read ve payments:read birlikte gerekir. remaining_amount yalnız seçilen iadenin henüz dönmemiş tutarıdır. Kısmen karttan dönen değişim iadesinde kalan elle ödeme ayrı durur. card_status değerlerinin anlamı Kodlar ve durumlar sayfasındadır.

Havaleyi gerçekten yaptıktan sonra seçilen iadenin kalan tutarıyla kaydedin (cash: nakit, bank: havale, pos: POS). Bekleyen kart denemesi kapatılamaz. Sonucu belirsiz kart iadesinde bu işlem yalnız sağlayıcı panelinde doğruladığınız ödeme içindir; yeniden havale göndermek için değildir.

export SIPARIS_RETURNED_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body --silent --show-error -X POST \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/refunds/$SIPARIS_REFUND_ID/money-returned" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_RETURNED_KEY" -H 'Content-Type: application/json' \
  --data "$(jq -n --arg amount "$SIPARIS_RETURNED_AMOUNT" '{expected_amount:$amount,method:"bank"}')"

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "amount": "120.00",
  "card_status": "pending",
  "id": "ret_1234567890abcdef1234567890abcdef",
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1.000",
      "unit": "adet"
    }
  ],
  "money_returned": false,
  "order": "ord_1234567890abcdef1234567890abcdef",
  "remaining_amount": "120.00",
  "restock": true
}

SIPARIS_RETURNED_AMOUNT gerçekten geri verdiğiniz ve son okumada görünen tutardır. Sonradan alınan iadeyi kapatmak için yeni ürün iadesi açmayın.

Olaylar ve sık hatalar

Olay akışını veya webhook kullanın. refund.succeeded gerçek başarılı para iadesini, order.updated / order.status_changed sipariş değişimini bildirir. Olay geldikten sonra ilgili siparişin iadelerini ve ödeme özetini okuyun. return.requested, return.approved, return.rejected, return.received, return.closed olayları returns:read kapsamıyla talebin yaşam döngüsünü bildirir. Kapanış para ödendiği anlamına gelmez; talebin güncel kararını /returns/{id} üzerinden okuyun. Geçmiş ve tekrar makbuzları korunur.

notify_customer=false yalnız bu iadenin e-postasını atlar. Para ve stok kayıtları, müşteri sayfasındaki durum ve olaylar korunur.