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

İade

İadeyi önizle

POST/v1/orders/{id}/refunds/preview

İade yapmadan önce iade edilecek tutarı, stok etkisini ve uyarıları görün.

Gereken izin

Bearer anahtarı ve returns:write

Maliyet

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

Tekrar anahtarı

Gerekmez; istek hiçbir şeyi değiştirmez.

İstek

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

Yol parametreleri

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

Gövde (application/json)

AlanTürZorunluAçıklamaÖrnek
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/preview" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "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",
}
request = Request(base + "/orders/ord_1234567890abcdef1234567890abcdef/refunds/preview", headers=headers, method="POST",
    data="{\"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/preview", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SIPARIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  redirect: "manual", // 307 hedefini Bearer olmadan ayrı istekte okuyun.
  signal: AbortSignal.timeout(30_000),
  body: JSON.stringify({
  "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

200 İstek başarıyla tamamlandı.

İçerik türü: application/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": []
}
Yanıt alanları (18)
AlanTürZorunluAçıklamaÖrnek
amountmetinEvetİade edilecek TRY tutarı; expected_amount olarak gönderin."120.00"
completestrue/falseEvetBu işlem siparişi tam iade durumuna geçirecekse true.true
itemsliste: nesneEvetDoğrulanmış iade kalemleri ve uygulanacak stok seçimi.
itemmetinEvetİade edilecek lin_ kalemi."lin_1234567890abcdef1234567890abcdef"
quantitymetinEvetİade miktarı; kalemin biriminde ondalık metin."1.000"
restocktrue/falseEvetBu kalem iade edildiğinde satılabilir stoğa geri eklenecekse true.true
unitmetinEvetMiktarın birimi."adet"
ordermetinEvetİadesi önizlenen ord_ siparişi."ord_1234567890abcdef1234567890abcdef"
refund_distributionnesne · null olabilirEvetDeğişim/ayrılan siparişte onaylanması gereken kart ve elle ödeme tutarları.
cardmetinEvetKaynak karta gönderilecek TRY tutarı."100.00"
manualmetinEvetElle 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 · null olabilirEvetParanın yolu: card, cash, iban, pos veya split; belirlenmemişse null."iban"
remainingmetinEvetİade edilebilecek kalan TRY tutarı."120.00"
shipping_includedtrue/falseEvetPanel hesabı kalan kargo bedelini içeriyorsa true.true
suggested_amountmetinEvetPanelin önerdiği TRY tutarı."120.00"
warningsliste: metinEvetPanelin kart bekleme ve stoğa geri almama uyarıları.
currencysabit "TRY"HayırTutarların para birimi."TRY"

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.