این راهنما برای تیمهایی است که فقط جریان لحظه ای قیمت را دریافت میکنند و به API سفارش دسترسی ندارند.
تمام درخواستهای HTTP به دامنه اپ Gold شما ارسال میشود و دریافت لحظهای قیمت از کانال خصوصی Pusher/Soketi انجام میگیرد.
یک Snapshot کامل برای شروع + رویدادهای لحظهای external.price.changed.
مهم
این دسترسی به یک گروه قیمت مشخص قفل است. تغییر گروه قیمت یک «مشتری» در Gold، این کانال را جابهجا نمیکند.
رفتار کانال ثابت بر اساس مشتری فقط مربوط به دسترسی «قیمت + سفارش» است.
اطلاعات لازم از پنل
تمام مقادیر واقعی را از طریق مدیریت اپ مورد نظر دریافت و نگهداری آن دقت لازم را داشته باشید. هیچ مقدار محیطی را حدس نزنید چون IP شما در خطر بلاک قرار میگیرد.
Reconnect
پس از قطع ارتباط، دوباره WebSocket را باز کنید، socket_id جدید بگیرید، دوباره auth کنید و سپس Snapshot تازه بگیرید.
socket_id اتصال قبلی را reuse نکنید.
فرمت رویداد قیمت
نام event در Pusher خام دقیقاً external.price.changed است.
مرز امنیتی ( توصیه ای برای هماهنگی بیشتر )
آدرس یا Secret داخلی سرویس Pricing را نیاز ندارید و نباید ذخیره کنید. اتصال خارجی فقط از مسیر Gold انجام میشود.
و p <= 0 بهعنوان قیمت قابل نمایش/معامله در نظر گرفته نمیشود.
یک کلید مشترک برای Price Socket و Order API
دسترسی قیمت لحظه ای + سفارشگذاری
این راهنما برای مشتریانی است که علاوه بر قیمت لحظه ای، امکان ثبت و استعلام سفارش دارند.
همان X-SOCKET-KEY هویت مشتری را برای سوکت قیمت و API سفارش مشخص میکند و
customer_id هرگز از سمت کلاینت ارسال نمیشود.
قیمت و سفارش با یک Access مشترک کار میکنند، اما کانال قیمت بر اساس مشتری ثابت است.
۱
Access را از طریق مدیر سیستم دریافت کنید
کلید، کانال ثابت مشتری، اطلاعات سوکت و Callback URL.
۲
قیمت زنده را دریافت کنید
Snapshot + external.price.changed روی کانال customer_{CUSTOMER_ID}.
۳
همان قیمت خام را در سفارش بفرستید
قیمت توسط Gold بازنویسی نمیشود؛ stale price با 409 رد میشود.
۴
order_id را نگه دارید
برای GET و تطبیق Callback.
۵
وضعیت نهایی را از Callback دریافت کنید
برای ابهام یا همگامسازی، GET استفاده کنید. سوکت وضعیت سفارش خارجی وجود ندارد.
کانال ثابت است
اگر گروه قیمت مشتری تغییر کند، ACCESS_KEY، CHANNEL_TOKEN و نام کانال تغییر نمیکنند.
قیمتهای گروه جدید روی همان کانال منتشر میشوند و resubscribe لازم نیست.
Integer؛ محصول باید در گروه قیمت فعلی مشتری، visible و transactional برای سمت سفارش باشد.
type
buy یا sell
price
دقیقاً همان p خام سوکت
trade_measurement_type
quantity_based، weight_based یا value_based مطابق نوع محصول
amount
برای quantity/weight؛ در quantity باید integer باشد
total
فقط برای value_based
description
اختیاری، حداکثر ۱۰۰۰ کاراکتر
معنی trade_measurement_type
اگر کالا بر اساس تعداد معامله شود، مقدار این فیلد quantity_based است.
اگر کالا بر اساس وزن معامله شود، weight_based.
اگر بر اساس مجموع معامله شود — یعنی کاربر بخواهد مثلاً به اندازه یک میلیارد گرم ۱۸ بخرد — باید value_based باشد و بهجای amount فیلد total فرستاده شود.
رفتار صحیح کلاینت
قیمت جدید را به کاربر/منطق شما برگردانید و یک سفارش جدید با قیمت جدید ثبت کنید.
اگر سفارش جدید میسازید، Idempotency-Key جدید تولید کنید.
اگر فقط بهخاطر timeout همان درخواست قبلی را retry میکنید، UUID قبلی را تکرار کنید.
Idempotency برای Retry امن
برای جلوگیری از ثبت دوباره سفارش در timeoutهای شبکه از یک UUID ثابت برای همان تلاش منطقی استفاده کنید.
Timeout
همان UUID قبلی را دوباره ارسال کنید.
سفارش جدید
UUID جدید تولید کنید.
UUID نامعتبر
درخواست با 422 رد میشود.
پنجره فعلی
سرویس سفارش فعلاً dedupe را در پنجره ۳۰۰ ثانیه انجام میدهد. اگر این عدد در قرارداد عمومی شما تضمین نشده، Client نباید منطق کسبوکارش را به همین عدد hard-code کند.
استعلام وضعیت سفارش
GET https://{GOLD_DOMAIN}/api/v1/platform/orders/{ORDER_ID}
هر کلید فقط سفارشهای متعلق به همان مشتری را میبیند. شناسه سفارش مشتری دیگر نیز بهصورت 404 پاسخ داده میشود.
Callback را idempotent پردازش کنید
تحویل شبکهای exactly-once تضمین نمیشود. بهعلت retry ممکن است همان
{order_id, status} بیش از یکبار برسد.
کلید dedupe پیشنهادی سمت شما: order_id + status.
نمونه Receiver در Laravel
PHP · Laravel Controller
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
public function __invoke(Request $request)
{
$data = $request->validate([
'order_id' => ['required', 'string'],
'status' => ['required', 'in:APPROVED,REJECTED,EXPIRED'],
]);
DB::transaction(function () use ($data) {
$key = $data['order_id'].'|'.$data['status'];
// روی این کلید یک unique constraint / dedupe واقعی داشته باشید.
// اگر قبلاً پردازش شده، no-op کنید.
// وضعیت سیستم خودتان را بهروزرسانی کنید.
});
return response()->json(['ok' => true]);
}
کدهای HTTP
کد
معنی
رفتار Client
201
سفارش پذیرفته شد
order_id را ذخیره کنید
200
GET/Auth/Snapshot موفق
ادامه
401
کلید سفارش وجود ندارد یا ناشناخته است
Credential را بررسی کنید
403
Access غیرفعال/منقضی یا IP غیرمجاز
تنظیمات دسترسی را بررسی کنید
404
سفارش برای این مشتری پیدا نشد
شناسه/مالکیت را بررسی کنید
409
PRICE_MISMATCH
با قیمت جدید سفارش تازه بفرستید
422
Validation یا Business Rule
Body یا وضعیت کسبوکار را اصلاح کنید
429
Rate limit
Backoff و Retry-After
503
زیرساخت سفارش موقتاً آماده نیست
سفارش را ثبتشده فرض نکنید؛ بعداً retry کنید
قوانین کسبوکار
گروه قیمت فعلی
محصول باید در گروه قیمت زنده مشتری وجود داشته باشد.
وضعیت حساب و کالا
حساب فعال و سمت buy/sell محصول transactional باشد.
سقفها و حداقل/حداکثر
سقف روزانه/شب و محدوده تعداد یا وزن اعمال میشوند.
اعتبار و موجودی
خرید و فروش بر اساس اعتبار/موجودی واقعی مشتری کنترل میشوند.
سفارش همزمان
اگر تنظیم سفارش همزمان غیرفعال باشد، سفارش فعال قبلی میتواند سفارش جدید را مسدود کند.
قیمت زنده
قیمت ارسالی باید با قیمت فعلی موتور برابر باشد؛ در غیر این صورت 409.
جریان پیشنهادی یک معامله
۱
کانال مشتری را Subscribe کنید
بعد از موفقیت، Snapshot بگیرید.
۲
قیمت زنده را انتخاب کنید
فقط p > 0 را قابل معامله بدانید.
۳
UUID بسازید
برای Idempotency-Key.
۴
POST سفارش
همان قیمت خام سوکت را ارسال کنید.
۵
409؟
قیمت جدید را بگیرید و با UUID جدید سفارش تازه ثبت کنید.
۶
Timeout؟
همان UUID را retry کنید.
۷
Callback را idempotent اعمال کنید
در ابهام، GET وضعیت را بخوانید.
امنیت
Secretها
Access Key فقط در env/secret manager. نه Frontend، نه URL و نه log عمومی.
Callback
از HTTPS استفاده کنید و endpoint را عمومی اما کنترلشده نگه دارید. وضعیتها را idempotent پردازش کنید.
ویرایش سفارش
سفارشهای API از پنل Gold قابل ویرایش دستی نیستند.
چکلیست نهایی
✓
یک کلید مشترک دارید
برای Price Socket و Order API.
✓
customer_id ارسال نمیکنید
هویت فقط از روی Access Key تعیین میشود.
✓
کانال بر اساس مشتری ثابت است
تغییر گروه قیمت resubscribe نمیخواهد.
✓
409 و Idempotency را درست هندل کردهاید
Price mismatch سفارش تازه؛ timeout همان UUID.
✓
Callback idempotent است
دریافت تکراری همان order_id + status مشکلی ایجاد نمیکند.