StardDevelopersداشبورد

ثبت سفارش

POST/api/v1/orders
scope: orders:writeاحراز هویت: Bearerlive و testIdempotency-Key

سفارش واقعی روی همان سیستم سفارش Stard. در محیط live مبلغ خودکار از کیف پول API (موجودی TON یا تومانی حساب Stard لینک‌شده؛ منبع پیش‌فرض در داشبورد) کسر می‌شود و سفارش مثل خرید از مینی‌اپ انجام می‌شود. در محیط test با موجودی آزمایشی شبیه‌سازی می‌شود و هیچ پول یا سفارش واقعی ساخته نمی‌شود.

درخواست

ناممحلنوعتوضیح
AuthorizationheaderstringالزامیBearer sk_live_… یا Bearer sk_test_…
Idempotency-Keyheaderstringاختیاریتا ۶۴ کاراکتر؛ تکرار درخواست با همین کلید همان پاسخ قبلی را برمی‌گرداند و دوباره کسر نمی‌کند. همیشه بفرست.

بدنه (JSON)

فیلدنوعتوضیح
typestringاختیاریproduct (پیش‌فرض) یا stars
product_idintegerاختیاریبرای type=product لازم است
quantityintegerاختیاریبرای محصول همیشه ۱؛ برای استارز تعداد (حداقل ۵۰)
recipientstringاختیارییوزرنیم تلگرام گیرنده (مثل @username)؛ برای استارز و گیفت استارزی لازم است
gift_messagestringاختیاریپیام روی گیفت استارزی (حداکثر ۲۰۰ کاراکتر)
pay_currencystringاختیاریTON یا IRT؛ اگر نفرستی، منبع پیش‌فرض کیف پول API در داشبورد (برای حساب تازه TON)
metadataobjectاختیاریتا ۲۰ کلید دلخواه (رشته/عدد/بولین) که همراه سفارش برمی‌گردد؛ مثلاً شماره فاکتور خودت

نمونه

curl -X POST "https://stard-market.ir/api/v1/orders" \
  -H "Authorization: Bearer $STARD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-INV-1042" \
  -d '{"type": "product", "product_id": 4518, "metadata": {"invoice": "INV-1042"}}'
پاسخ — 201
{
  "object": "order",
  "id": "ord_test_gGToQWxqOw89ssiL",
  "order_id": null,
  "environment": "test",
  "status": "pending",
  "raw_status": "pending",
  "title": "پریمیوم ۳ ماهه (test)",
  "product_id": 4518,
  "product_tag": null,
  "type": "product",
  "quantity": 1,
  "recipient": null,
  "amount": {
    "amount": 3788624,
    "currency": "IRT"
  },
  "paid": {
    "amount": 3788624,
    "currency": "IRT"
  },
  "failure_reason": null,
  "metadata": {
    "invoice": "INV-1042"
  },
  "created_at": "2026-10-01T10:31:49Z",
  "updated_at": "2026-10-01T10:31:49Z"
}
هدرهای پاسخ
x-request-id: req_Ne8SLkkri4MPzWnBQnQs
x-ratelimit-limit: 60
x-ratelimit-remaining: 44
x-ratelimit-reset: 1790850720

خطاها

HTTPcodeکی
400parameter_invalid / recipient_invalid / p2p_not_supported / not_fixed_priceبدنه نامعتبر است یا محصول از API قابل خرید نیست
402insufficient_fundsموجودی کیف پول (یا موجودی آزمایشی) کافی نیست
403account_not_linked / insufficient_scopeبرای live باید حساب تلگرام Stard وصل باشد؛ یا کلید scope لازم را ندارد
404product_not_foundمحصول وجود ندارد یا غیرفعال است
409product_unavailable / idempotency_key_reused / request_in_progressمحصول همین الان ناموجود شد، یا کلید idempotency با بدنه‌ی دیگری استفاده شده
403insufficient_scopeکلید scope orders:write را ندارد
401invalid_api_key / missing_api_key / api_key_revoked / api_key_expiredکلید نیامده، نامعتبر، باطل یا منقضی است
429rate_limit_exceededسقف درخواست در دقیقه پر شده؛ بعد از Retry-After ثانیه دوباره بفرست

محدودیت نرخ

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