StardDevelopersداشبورد

وضعیت بازپرداخت

GET/api/v1/orders/{id}/refund
scope: orders:readاحراز هویت: Bearerlive و test

آیا مبلغ این سفارش برگشت داده شده و چقدر.

درخواست

ناممحلنوعتوضیح
AuthorizationheaderstringالزامیBearer sk_live_… یا Bearer sk_test_…
idpathstringالزامیکد پیگیری سفارش (ord_… یا کد live)

نمونه

curl "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund" \
  -H "Authorization: Bearer $STARD_API_KEY"
پاسخ — 200
{
  "object": "refund",
  "order_id": "ord_test_9pq3kfjbTmRLfMDR",
  "refunded": true,
  "amount": {
    "amount": 2249000,
    "currency": "IRT"
  }
}
هدرهای پاسخ
content-type: application/json
x-request-id: req_o7BQtSz6FuklFTgGJiQP
x-ratelimit-limit: 1000
x-ratelimit-remaining: 995

کاربرد و نکته‌ها

کی به کار می‌آید؟ برای نمایش «پول برگشت» در پنل مشتری یا تطبیق حساب: پاسخ می‌گوید مبلغ این سفارش برگشت داده شده یا نه (refunded) و چقدر (amount به تومان، currency: "IRT").

  • این اندپوینت فقط می‌خواند و چیزی را تغییر نمی‌دهد؛ scope آن orders:read است و می‌شود با کلید فقط‌خواندنی صدایش زد.
  • برگشت‌هایی که خود سیستم انجام می‌دهد (سفارش ناموفق، بخش تحویل‌نشده‌ی بوست) هم اینجا دیده می‌شوند، نه فقط بازپرداخت دستی با POST /refund.
  • به‌جای poll کردن مداوم، وب‌هوک order.* را فعال کن و فقط وقتی تغییری آمد این را بخوان (وب‌هوک‌ها).

خطاها

HTTPcodeکی
404order_not_foundسفارش پیدا نشد
403insufficient_scopeکلید scope orders:read را ندارد
401invalid_api_key / missing_api_key / api_key_revoked / api_key_expiredکلید نیامده، نامعتبر، باطل یا منقضی است
429rate_limit_exceededسقف درخواست در دقیقه پر شده؛ بعد از Retry-After ثانیه دوباره بفرست

محدودیت نرخ

پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای X-RateLimit-* برمی‌گردد — جزئیات.