İçeriğe geç
siparis.app geliştiriciAnahtarları yönet ↗

İade

İade başlat

POST/v1/orders/{id}/refunds

Ürünü geri alın ve parayı müşteriye iade edin.

Gereken izin

Bearer anahtarı ve returns:write, money_out:write

Yanıtı genişleten izin

payments:read: yanıttaki ilgili alanları açar; izin yoksa bu alanlar atlanır, istek reddedilmez.

Maliyet

1 puan (bağlantı başına 60 saniyede 600 puan)

Tekrar anahtarı

Gerekir: Idempotency-Key başlığı.

İstek

Temel adres: https://api.siparis.app/v1

Yol parametreleri

AlanTürZorunluAçıklamaÖrnek
idmetinEvetOkunacak kaynağın ord_ önekli dış kimliği."ord_1234567890abcdef1234567890abcdef"

Başlıklar

AlanTürZorunluAçıklamaÖrnek
Idempotency-Keymetin · null olabilirEvetZorunlu tekrar anahtarı; en çok 200 karakter. Yeni işte yeni değer; ağ tekrarında aynı gövde ve aynı değer."ilk-esitleme-20261016-001"

Gövde (application/json)

AlanTürZorunluAçıklamaÖrnek
expected_amountsayı (en az 0; en çok 10000000) veya metinEvetSon önizlemenin amount değeri, TRY; değişmişse 409 amount_changed döner."120.00"
amountsayı (en az 0; en çok 10000000) veya metin · null olabilirHayırİsteğe bağlı TRY tutarı; boşsa panelin önerisi. Kalan tahsilatı aşamaz."120.00"
itemsliste: nesne (en çok 200 öğe)Hayırİade kalemleri; boşsa yalnız para iadesidir ve amount zorunludur.
itemmetinEvetSipariş kaleminin lin_ dış kimliği."lin_1234567890abcdef1234567890abcdef"
quantitysayı (en çok 100000) veya metinEvetİade miktarı; kalemin biriminde, en çok üç ondalık hane."1"
money_returnedtrue/falseHayırParayı gerçekten elle geri verdiyseniz true. Çevrimiçi kartta false bırakın; sağlayıcı sonucu beklenir.false
notify_customertrue/falseHayırİade e-postasını müşteriye gönder.true
reasonmetin (en çok 200 karakter)Hayırİade nedeni; kişisel bilgi yazmayın."Müşteri ürünü iade etti"
received_conditionmetin (seçenekler: sound, damaged) · null olabilirHayırFiziksel teslim onayı. Fire için damaged ve restock=false birlikte gerekir."sound"
refund_distributionnesne · null olabilirHayırDeğişim/ayrılan siparişte önizlemenin kart ve elle ödeme dağılımı; oluştururken aynen gönderin.
cardsayı (en az 0; en çok 10000000) veya metinEvetKaynak karta gönderilecek TRY tutarı."100.00"
manualsayı (en az 0; en çok 10000000) veya metinEvetElle iade edilecek TRY tutarı."20.00"
providermetin (en çok 100 karakter)EvetÖnizlemede görünen ödeme kuruluşu adı; aynen gönderin."PayTR"
refund_methodmetin (seçenekler: cash, pos, iban) · null olabilirHayırPanelin izin verdiği elle iade yolu; çevrimiçi karta iade otomatik belirlenir.null
refund_partsliste: nesne (en çok 20 öğe) · null olabilirHayırElle geri verilen parçalar; toplam iade tutarına eşit, money_returned=true olmalı.null
amountsayı (en az 0; en çok 10000000) veya metinEvetGerçekten geri verilen tutar, TRY; ondalık metin."120.00"
methodmetin (seçenekler: cash, pos, bank)Evetcash: nakit; pos: POS cihazından kart iadesi; bank: havale."cash"
restocktrue/false · null olabilirHayırStoğa geri ekleme seçimi. Boşsa panel/AI varsayılanı: iade edilemez veya hasarlı ürün eklenmez. false tek başına fire yazmaz.null

Örnek istek

curl --fail-with-body --silent --show-error --request POST \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/ord_1234567890abcdef1234567890abcdef/refunds" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ornek-post-v1-orders-ord-1234567890abcdef1234567890abcdef-refunds-001' \
  --data-binary @- <<'JSON'
{
  "expected_amount": "120.00",
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1"
    }
  ]
}
JSON
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
from urllib.error import HTTPError

# İmzalı indirme hedefine Bearer taşımamak için yönlendirme kendiliğinden izlenmez.
class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

base = os.environ.get("SIPARIS_API_URL", "https://api.siparis.app/v1")
headers = {
    "Authorization": "Bearer " + os.environ["SIPARIS_API_KEY"],
    "Content-Type": "application/json",
    "Idempotency-Key": "ornek-post-v1-orders-ord-1234567890abcdef1234567890abcdef-refunds-001",
}
request = Request(base + "/orders/ord_1234567890abcdef1234567890abcdef/refunds", headers=headers, method="POST",
    data="{\"expected_amount\":\"120.00\",\"items\":[{\"item\":\"lin_1234567890abcdef1234567890abcdef\",\"quantity\":\"1\"}]}".encode("utf-8"))
try:
    with build_opener(NoRedirect).open(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except HTTPError as error:
    print(error.code, error.read().decode("utf-8"))
    raise
// Node.js 22+; anahtar yalnız sunucunun ortam değişkenindedir.
const base = process.env.SIPARIS_API_URL ?? "https://api.siparis.app/v1";
if (!process.env.SIPARIS_API_KEY) throw new Error("SIPARIS_API_KEY gerekli");
const response = await fetch(base + "/orders/ord_1234567890abcdef1234567890abcdef/refunds", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SIPARIS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "ornek-post-v1-orders-ord-1234567890abcdef1234567890abcdef-refunds-001",
  },
  redirect: "manual", // 307 hedefini Bearer olmadan ayrı istekte okuyun.
  signal: AbortSignal.timeout(30_000),
  body: JSON.stringify({
  "expected_amount": "120.00",
  "items": [
    {
      "item": "lin_1234567890abcdef1234567890abcdef",
      "quantity": "1"
    }
  ]
}),
});
const text = await response.text();
if (!response.ok) throw new Error(`${response.status}: ${text}`);
console.log(text);

Kimlik içeren yollarda örnek kimliği kendi liste yanıtınızdan alın. SIPARIS_API_KEY sunucu ortamında tanımlı olmalı; yerelde SIPARIS_API_URL ile /v1 içeren adresi değiştirin. Üretimde tekrar kurallarını uygulayın.

Yanıt

201 İstek başarıyla tamamlandı.

İçerik türü: application/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
}
Yanıt alanları (17)
AlanTürZorunluAçıklamaÖrnek
amountmetinEvetİadenin TRY tutarı; tamamı ödenmiş anlamına gelmez."120.00"
card_statusmetin (seçenekler: pending, blocked, unknown, failed) · null olabilirEvetKart iadesinin bekleyen/belirsiz/hatalı durumu; sorun yoksa null."pending"
idmetinEvetİade işleminin ret_ kimliği; ödeme hareketinin rfd_ kimliğinden ayrıdır."ret_1234567890abcdef1234567890abcdef"
itemsliste: nesneEvetİade kalemleri; yalnız para iadesinde boş.
itemmetinEvetİade edilecek lin_ kalemi."lin_1234567890abcdef1234567890abcdef"
quantitymetinEvetİade miktarı; kalemin biriminde ondalık metin."1.000"
unitmetinEvetMiktarın birimi."adet"
money_returnedtrue/falseEvetBu iadenin parası geri verilmişse true.false
ordermetinEvetÜrünlerin ait olduğu ord_ siparişi."ord_1234567890abcdef1234567890abcdef"
remaining_amountmetinEvetBu iadenin henüz geri verilmemiş TRY tutarı; kart bekliyorsa elle ödeme yapmayın."120.00"
restocktrue/falseEvetBu iadede stoğa geri ekleme seçilmişse true.true
currencysabit "TRY"Hayırİadenin para birimi."TRY"
paymentsnesne · null olabilirHayırÖdeme listesi ve güncel para özeti; yalnız payments:read ile görünür. Değişimden devreden bedel ortak hesaba dahildir.
dataliste: nesne (Payment)EvetBu sayfanın görünür kayıtları; boş liste de geçerli bir sayfadır.
has_moretrue/falseEvetTaranacak başka sayfa varsa true; olaylarda boş data ile de true olabilir.false
next_cursormetin · null olabilirEvetSonraki sayfa için aynen gönderilecek opak imleç; kaynak listesi bittiyse null.null
summarynesne (MoneySummary)EvetSiparişin bütün tahsilat ve iadelerinden hesaplanan para özeti; yalnız bu sayfanın toplamı değildir.

Hatalar

HTTPcodeAnlamıNasıl düzelir?
403forbiddenMevcut ticari kural bu işlemi yapmanıza izin vermiyor.Gerekli kapsamları ve siparişin durumunu kontrol edin.
409conflictSipariş veya ödeme bilgisi değişmiş ya da işlem mevcut duruma uygun değil.Güncel siparişi okuyun, iş kuralını kontrol edip yeni tekrar anahtarıyla deneyin.
400insufficient_stockSipariş için yeterli stok yok.Miktarı azaltın veya paneldeki bekleyen stok kuralını açıkça allow_waiting=true ile seçin.
400invalid_if_matchIf-Match geçerli bir güçlü ETag değil.GET kaynak yanıtındaki ETag değerini çift tırnaklarıyla aynen kullanın.
412revision_mismatchKayıt siz okuduktan sonra değişmiş.Güncel kaydı okuyun; düzeltmeyi yeniden değerlendirip yeni tekrar anahtarıyla gönderin.
409status_mismatchSipariş durumu expected_status ile uyuşmuyor.Güncel durumu okuyup yeni tekrar anahtarıyla deneyin.
422duplicate_lineAynı sipariş satırı birden çok kez gönderilmiş.Her lin_ kimliğini yalnız bir kez yazın.
409amount_changedİade tutarı değişti; yeniden önizleyip onaylayın.current_amount güncel TRY tutarıdır; önizlemeyi okuyup yeni anahtar ve expected_amount ile gönderin.
409return_not_requestedBu kayıt bir müşteri iade talebi değil.Siparişin returns listesinden müşteri talebini seçin.
409refund_distribution_confirmKart ve elle ödeme dağılımı değişti.Yeniden önizleyip refund_distribution alanını aynen ve yeni tekrar anahtarıyla gönderin.

Ortak hatalar (anahtar, izin, istek biçimi, hız sınırı, tekrar anahtarı) her uçta aynıdır: Hata kodları › Ortak hatalar.