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

İade

Elle verilen iadeyi kaydet

POST/v1/refunds/{id}/money-returned

Parayı nakit, POS veya havaleyle kendiniz geri verdikten sonra kaydedin.

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 ret_ önekli dış kimliği."ret_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 metinEvetBu iadede kalan, gerçekten geri verilen TRY tutarı; değişirse 409 amount_changed."120.00"
methodmetin (seçenekler: cash, bank, pos) · null olabilirHayırElle ödeme yöntemi: cash nakit, bank havale, pos kart. Boşsa ortak servis belirler."bank"

Örnek istek

curl --fail-with-body --silent --show-error --request POST \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/refunds/ret_1234567890abcdef1234567890abcdef/money-returned" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ornek-post-v1-refunds-ret-1234567890abcdef1234567890abcdef-money-returned-001' \
  --data-binary @- <<'JSON'
{
  "expected_amount": "120.00"
}
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-refunds-ret-1234567890abcdef1234567890abcdef-money-returned-001",
}
request = Request(base + "/refunds/ret_1234567890abcdef1234567890abcdef/money-returned", headers=headers, method="POST",
    data="{\"expected_amount\":\"120.00\"}".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 + "/refunds/ret_1234567890abcdef1234567890abcdef/money-returned", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SIPARIS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "ornek-post-v1-refunds-ret-1234567890abcdef1234567890abcdef-money-returned-001",
  },
  redirect: "manual", // 307 hedefini Bearer olmadan ayrı istekte okuyun.
  signal: AbortSignal.timeout(30_000),
  body: JSON.stringify({
  "expected_amount": "120.00"
}),
});
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",
  "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?
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.
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.