فهرست مطالب

مرور کلی سیاست نسخه‌گذاری سازگاری معکوس مهاجرت از V1 به V2 تغییرات نقاط پایانی به‌روزرسانی‌های فرمت پاسخ زمانبندی منسوخ‌سازی تغییرات شکست‌ناپذیر مهاجرت گام به گام پشتیبانی و منابع

مستندات API

راهنمای مهاجرت API — ارتقا بین نسخه‌ها

برنامه‌ریزی و اجرای ارتقای روان نسخه‌های API. درک تغییرات شکست‌ناپذیر، زمانبندی‌های منسوخ‌سازی و بهترین روش‌ها برای مهاجرت بین نسخه‌های Smart Money API.

منتشر شده در ۲۱ مارس ۲۰۲۶ • ۱۶ دقیقه مطالعه • پیشرفته

مرور کلی مهاجرت

Smart Money API به‌طور فعال توسعه می‌یابد و به‌روزرسانی‌های منظمی دارد. این راهنما مدیریت نسخه‌ها، تغییرات شکست‌ناپذیر و نحوه مهاجرت یکپارچه‌سازی شما بدون وقفه را پوشش می‌دهد.

اصول کلیدی مهاجرت:

نسخه‌گذاری معنایی — فرمت MAJOR.MINOR.PATCH به‌طور دقیق رعایت می‌شود
پشتیبانی بلندمدت — نسخه اصلی قبلی برای ۲۴+ ماه پشتیبانی می‌شود
هشدارهای منسوخ‌سازی — اخطار ۶ ماهه برای تمام تغییرات شکست‌ناپذیر
نسخه‌های موازی — اجرای همزمان v1 و v2 در طول مهاجرت
تست خودکار — ابزارهای سازگاری مجموعه تست ارائه شده‌است

وضعیت فعلی: v1 (فعلی)، v2 (بتا، دسترسی عمومی Q2 2026). v1 تا Q1 2028 پشتیبانی می‌شود.

سیاست نسخه‌گذاری

نسخه‌گذاری معنایی

فرمت نسخه
نسخه API: MAJOR.MINOR.PATCH
مثال: ۲.۱.۳
MAJOR (۲) - تغییرات شکست‌ناپذیر، معماری جدید
MINOR (۱) - ویژگی‌های سازگار معکوس
PATCH (۳) - رفع اشکالات، به‌روزرسانی‌های امنیتی

چرخه انتشار نسخه

فاز	مدت زمان	ویژگی‌ها
آلفا	۲-۴ هفته	تغییرات شکست‌ناپذیر زیاد، فقط برای تست
بتا	۴-۸ هفته	عمدتاً پایدار، بازخورد جامعه
نامزد انتشار	۲-۴ هفته	آماده تولید، آخرین اصلاحات
دسترسی عمومی	۲۴+ ماه	پشتیبانی کامل تولید

دریافت کلید API در ۳۰ ثانیه

آماده ساختید؟ یک کلید API رایگان دریافت کنید (۵۰ درخواست/روز، بدون کارت) و شروع به دریافت داده‌های زنده نهنگ‌ها، تأمین مالی و زنجیره‌ای کنید.

دریافت کلید API →

سازگاری معکوس

سازگاری نسخه

درون یک نسخه اصلی، همیشه می‌توانید با خیال راحت به نسخه‌های جزئی/پچ جدیدتر ارتقا دهید:

آدرس‌های نقاط پایانی — بدون تغییر باقی می‌مانند
فیلدهای الزامی — هرگز حذف نمی‌شوند (فقط فیلدهای اختیاری جدید اضافه می‌شوند)
کدهای وضعیت HTTP — برای سناریوهای موجود حفظ می‌شوند
ساختار پاسخ — فیلدهای اصلی یکسان باقی می‌مانند
احراز هویت — هیچ تغییری در مکانیزم‌های احراز هویت

منسوخ‌سازی آرام

زمانبندی منسوخ‌سازی
// ماه ۱: اعلام منسوخ‌سازی
// ویژگی با هدر Deprecation علامت‌گذاری می‌شود
Deprecation: version="2.2", sunset="2026-09-01"
// ماه ۳-۶: دوره فعال منسوخ‌سازی
// API هشدارها را بازمی‌گرداند اما همچنان کار می‌کند
X-Deprecation-Warning: این نقطه پایانی در ۲۰۲۶-۰۹-۰۱ حذف خواهد شد
// ماه ۶: حذف نهایی
// نقطه پایانی 410 Gone را بازمی‌گرداند
HTTP/1.1 410 Gone

مهاجرت از V1 به V2

تغییرات اصلی

بازطراحی REST API — نقاط پایانی منابع تمیزتر
فرمت پاسخ — پیچیدگی یکسان، مدیریت خطای بهتر
احراز هویت — پشتیبانی از OAuth 2.0 اضافه شد (کلیدهای API همچنان کار می‌کنند)
محدودیت نرخ — دانه‌بندی و وضوح بهبود یافته
Webhooks — فرمت رویداد و امضا بازطراحی شده

نقشه‌برداری نقاط پایانی

نقطه پایانی V1	نقطه پایانی V2	تغییرات
GET /whales	GET /v2/whales/tracking	سازمان‌دهی مجدد، فیلتر کردن اضافه شد
GET /funding	GET /v2/derivatives/funding-heatmap	پارامتر صرافی الزامی است
GET /positions	GET /v2/derivatives/positions	گزینه‌های تجمیع جدید

تغییرات نقاط پایانی

تغییرات پارامترهای درخواست

درخواست V1
// V1: نرخ‌های تأمین مالی
GET /v1/funding?symbol=BTCUSDT&exchange=binance

درخواست V2
// V2: همان داده‌ها، ساختار واضح‌تر
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

به‌روزرسانی‌های فرمت پاسخ

ساختار پاسخ V1

فرمت V1
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

ساختار پاسخ V2

فرمت V2
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

تفاوت‌های کلیدی: بدون پوشش وضعیت، نام‌های فیلد واضح‌تر، متادیتای استاندارد شده.

زمان‌بندی منسوخ‌شدن

منسوخ‌شدن‌های برنامه‌ریزی شده

ویژگی	اعلام شده	تاریخ پایان	جایگزین
/v1/whales	ژانویه 2026	ژانویه 2028	/v2/whales/tracking
/v1/funding	ژانویه 2026	ژانویه 2028	/v2/derivatives/funding-heatmap
احراز هویت فقط با کلید API	مارس 2026	مارس 2027	OAuth 2.0 (کلیدها همچنان کار می‌کنند)
فرمت Webhook v1	Q2 2026	Q2 2027	فرمت Webhook v2

جزئیات تغییرات شکست‌آمیز

نقاط پایانی حذف شده

/v1/stats — جایگزین شده توسط /v2/metrics
/v1/historical — جایگزین شده توسط /v2/historical با پارامترهای جدید
/v1/alerts/create — جایگزین شده توسط POST /v2/alerts

تغییرات پارامترها

limit — پیش‌فرض از 100 به 20 تغییر یافت (صریح باشید!)
timeframe — اکنون در پرس‌وجوهای تاریخی الزامی است
sort — فرمت از "field asc" به "field:asc" تغییر یافت

تغییرات فیلدهای پاسخ

funding → funding_rate
price → mark_price
vol → volume_quote

مهاجرت گام به گام

فاز 1: برنامه‌ریزی (هفته 1-2)

بررسی یکپارچه‌سازی موجود برای ویژگی‌های منسوخ شده
نقشه‌برداری نقاط پایانی v1 به معادل‌های v2
شناسایی تغییرات شکست‌آمیز که بر کد شما تأثیر می‌گذارند
برنامه‌ریزی استراتژی تست و زمان‌بندی

فاز 2: توسعه (هفته 3-4)

ایجاد شاخه v2 در کنترل نسخه
به‌روزرسانی تمام نقاط پایانی API به URL‌های v2
به‌روزرسانی مدیریت درخواست/پاسخ
اجرای تست‌های واحد در برابر محیط سندباکس

فاز 3: تست (هفته 5-6)

اجرای مجموعه کامل تست یکپارچه‌سازی
تست سناریوهای خطا و موارد خاص
تست بار با نقاط پایانی v2
بررسی امنیتی کد به‌روز شده

فاز 4: استیجینگ (هفته 7)

استقرار کد v2 در محیط استیجینگ
اجرای تست‌های پذیرش کامل
دریافت تأییدیه از ذینفعان
تهیه برنامه بازگشت

فاز 5: تولید (هفته 8)

استقرار آبی-سبز به تولید
مانیتورینگ معیارها و نرخ خطا
در دسترس بودن برای مسائل پشتیبانی
به‌تدریج کد v1 را از رده خارج کنید

پشتیبانی و منابع

ابزارهای موجود

اعتبارسنج مهاجرت — بررسی کد برای استفاده منسوخ شده
بررسی ارتقاء API — مقایسه سازگاری v1 و v2
چک‌لیست مهاجرت — PDF با وظایف و زمان‌بندی
نمونه‌های کد — نمونه‌های قبل و بعد از مهاجرت

دریافت کمک

ایمیل: [email protected]
مستندات: مشاهده changelog-versioning.html
Discord: کانال پشتیبانی جامعه
Enterprise: مهندس مهاجرت اختصاصی

مهاجرت خود را امروز شروع کنید

ارتقاء به API v2 با ابزارهای مهاجرت جامع، مستندات و پشتیبانی. ساخته شده برای پشتیبانی از مهاجرت بدون وقفه.

کاوش V2

V1 تا ژانویه 2028 پشتیبانی می‌شود. امروز مهاجرت خود را برنامه‌ریزی کنید.