بازپرداخت سفارش
POST
/api/v1/orders/{id}/refundscope: orders:writeاحراز هویت: Bearerlive و test
بازپرداخت خودکار سفارشی که هنوز انجامش شروع نشده؛ کل مبلغ به همان کیف پول برمیگردد. سفارش انجامشده خودکار قابل بازپرداخت نیست (برای آن با پشتیبانی تماس بگیر). برای بوست، اگر سفارش به پنل ارسال شده باشد بازپرداخت پذیرفته نمیشود.
درخواست
| نام | محل | نوع | توضیح | |
|---|---|---|---|---|
Authorization | header | string | الزامی | Bearer sk_live_… یا Bearer sk_test_… |
id | path | string | الزامی | کد پیگیری سفارش (ord_… یا کد live) |
نمونه
curl -X POST "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund" \
-H "Authorization: Bearer $STARD_API_KEY"const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.STARD_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } };
const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.STARD_API_KEY}`,
},
});
if (!res.ok) {
const { error } = (await res.json()) as StardError;
throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}
const data: Record<string, unknown> = await res.json();import os
import requests
r = requests.post(
"https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund",
headers={
"Authorization": f"Bearer {os.environ['STARD_API_KEY']}",
},
timeout=20,
)
data = r.json()
if r.status_code >= 400:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)<?php
$ch = curl_init("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("STARD_API_KEY"),
],
CURLOPT_TIMEOUT => 20,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) {
throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]);
}
print_r($data);package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
b, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(b))
}پاسخ — 200
{
"object": "order",
"id": "ord_test_9pq3kfjbTmRLfMDR",
"order_id": null,
"environment": "test",
"status": "cancelled",
"raw_status": "cancelled",
"title": "⭐ 500 استارز برای @username (test)",
"product_id": null,
"product_tag": null,
"type": "stars",
"quantity": 500,
"recipient": "@username",
"amount": {
"amount": 2249000,
"currency": "IRT"
},
"paid": {
"amount": 2249000,
"currency": "IRT"
},
"failure_reason": null,
"metadata": {
"invoice": "INV-1042"
},
"created_at": "2026-10-02T17:43:22Z",
"updated_at": "2026-10-02T17:43:22Z"
}هدرهای پاسخ
content-type: application/json
x-request-id: req_dAlugYNqQS5ouO3hP82I
x-ratelimit-limit: 1000
x-ratelimit-remaining: 996کاربرد و نکتهها
کی به کار میآید؟ وقتی سفارشی را ثبت کردهای ولی هنوز انجامش شروع نشده و میخواهی پول برگردد؛ مثلاً یوزرنیم گیرنده اشتباه وارد شده یا مشتری فروشگاهت پشیمان شده است.
- وضعیت سفارش را با
GET /orders/{id}بگیر؛ فقط سفارشی که انجامش شروع نشده خودکار برمیگردد. POST /orders/{id}/refundرا بزن. پاسخ همان شیء سفارش با وضعیت تازه است و کل مبلغ به همان کیف پولی که از آن کسر شده بود برمیگردد.- نتیجه را با
GET /orders/{id}/refundیا وبهوکorder.*تأیید کن.
- سفارش انجامشده (استارز تحویلشده، گیفت ارسالشده) خودکار برنمیگردد و خطای
409 order_not_refundableمیدهد؛ برای آن با پشتیبانی تماس بگیر. - سفارش بوستی که به پنل تحویل ارسال شده هم خودکار برنمیگردد؛ بخش تحویلنشدهی بوست را خود سیستم خودکار برمیگرداند.
- در محیط test هیچ پول واقعی جابهجا نمیشود؛ رفتار پاسخ همان live است.
خطاها
| HTTP | code | کی |
|---|---|---|
409 | order_not_refundable | انجام سفارش شروع شده یا تمام شده |
404 | order_not_found | سفارش پیدا نشد |
403 | insufficient_scope | کلید scope orders:write را ندارد |
401 | invalid_api_key / missing_api_key / api_key_revoked / api_key_expired | کلید نیامده، نامعتبر، باطل یا منقضی است |
429 | rate_limit_exceeded | سقف درخواست در دقیقه پر شده؛ بعد از Retry-After ثانیه دوباره بفرست |
محدودیت نرخ
پیشفرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای X-RateLimit-* برمیگردد — جزئیات.
