# İade almak ve para iadesi

> **Ne yaparsınız:** Müşterinin iade talebini onaylar veya reddeder, iade tutarını önizler, gördüğünüz tutarla iadeyi yapar ve paranın müşteriye dönüşünü izlersiniz.
> **Hangi uçlar:** [Siparişin iadelerini listele](https://developer.siparis.app/uc/siparisin-iadelerini-listele), [İade talebini getir](https://developer.siparis.app/uc/iade-talebini-getir), [İade talebini onayla](https://developer.siparis.app/uc/iade-talebini-onayla), [İade talebini reddet](https://developer.siparis.app/uc/iade-talebini-reddet), [İadeyi önizle](https://developer.siparis.app/uc/iadeyi-onizle), [İade başlat](https://developer.siparis.app/uc/iade-baslat), [Para iadesini getir](https://developer.siparis.app/uc/para-iadesini-getir), [Elle verilen iadeyi kaydet](https://developer.siparis.app/uc/elle-verilen-iadeyi-kaydet)
> **Gereken izin:** `returns:write`; para iadesinde ayrıca `money_out:write`, geri gönderim kodunda `shipments:write`.

İ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](https://developer.siparis.app/siparisleri-listelemek) aldığınız `ord_` kimliğini yazın. Örnekler `curl`, `jq` ve Python 3 kullanır.

## 1. İade talebini okuyun ve karar verin

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

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

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

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

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

```json
{
  "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](https://developer.siparis.app/uc/iade-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.

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

```json
{
  "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](https://developer.siparis.app/uc/iadeyi-onizle) 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):

| Alan | Tür | Açıklama | Örnek |
| --- | --- | --- | --- |
| `expected_amount` | sayı (en az 0; en çok 10000000) veya metin | Son önizlemenin amount değeri, TRY; değişmişse 409 amount_changed döner. | `"120.00"` |

Bütün alanlar: [İade başlat](https://developer.siparis.app/uc/iade-baslat).

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

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

| Ödeme | İadenin davranışı |
|---|---|
| Çevrimiçi kart | PayTR/iyzico yoluyla iade işi kaydedilir. `201` başarılı kart iadesi değildir. `card_status=pending` bekler, `unknown` sonucu belirsizdir; ikinci kez para göndermeyin. |
| Havale veya nakit | Parayı siz geri verirsiniz. Başta `money_returned=false` borcu açık bırakır; gerçekten verdiğinizde aşağıdaki kayıt yapılır. |
| Kart (POS) veya parçalı ödeme | Panelin izin verdiği nakit, havale, POS veya `refund_parts` seçilir. Parçaların toplamı iade tutarına eşit olmalı; gerçekten verilmiş ödeme kaydedilir. |
| Kapıda ödeme | Kurye tahsilatı kanıtı esas alınır; teslim durumu para alındığı anlamına gelmez. Tahsil edilmemiş bedel müşteriye yeniden ödenmez. BasitKargo'daki para siparis.app'e gelmez. |
| Değişim siparişi | Devreden ürün bedeli ve alınmış fark ortak servisle asıl tahsilatlara bağlanır. Asıl siparişte ayrıca iade açmayın. Kart/elle ödeme dağılımını onaylayın. |

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

```json
{
  "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](https://developer.siparis.app/referans#kart-iadesi-durumlari) 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.

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

```json
{
  "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ı](https://developer.siparis.app/olaylar) veya [webhook](https://developer.siparis.app/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.

| Hata | Yapılacak işlem |
|---|---|
| `409 amount_changed` | `current_amount` güncel tutardır; önizleyip yeni anahtarla onaylayın. Aynı anahtarla hata tekrarı sabit hata kodunu taşır; tutarı yeniden okuyun. |
| `409 refund_distribution_confirm` | Kart/elle ödeme dağılımını yeniden önizleyin ve aynen gönderin. |
| `403 insufficient_scope` | Para iadesinde `returns:write` ve `money_out:write` birlikte gerekir. |
| `422 validation_error` | `expected_amount`, kalem kimliği, miktar ve ondalık basamakları kontrol edin. |
| `400 invalid_request` | Panelin kuralı işlemi reddetmiştir; teslim durumu, kalan miktar, ödeme ve yöntemi kontrol edin. |

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