نسخه‌های API و تاریخچهٔ تغییرات

وضعیت نسخه‌ها

پشتیبانی قراردادهای HTTP
قرارداد	مسیر و نسخه	وضعیت پشتیبانی
REST اصلی	`/api/v1/` v1	فعال؛ بدون تاریخ پایان پشتیبانی
REST سازگار	`/v1/` v1	فعال؛ بدون تاریخ پایان پشتیبانی
وب‌سرویس SOAP	`/api/soap/v1` v1	فعال؛ بدون تاریخ پایان پشتیبانی
REST آزمایشی	`/api/sandbox/v1/` v1	فعال؛ بدون تاریخ پایان پشتیبانی

این جدول دربارهٔ قرارداد نرم‌افزاری است. مجوز حساب، سهمیه و فعال‌بودن سرویس جداگانه بررسی می‌شوند. SMPP قرارداد مستقلی دارد و مشمول هدرهای HTTP نیست.

دریافت فهرست نسخه‌ها با فرمت JSON ↗

چه تغییری نیاز به نسخهٔ جدید دارد؟

حذف یا تغییر نام فیلد، اجباری‌کردن ورودی اختیاری، تغییر نوع داده، واحد مبلغ، معنای وضعیت یا رفتار کلید تکرار، تغییر شکننده است و باید در نسخهٔ اصلی جدید ارائه شود. تغییرات REST اصلی، API سازگار و SOAP مستقل از یکدیگر اعلام می‌شوند.

افزودن فیلد اختیاری یا هدر اطلاع‌رسانی می‌تواند در همان نسخه انجام شود. برنامهٔ شما باید فیلدهای ناشناختهٔ پاسخ را نادیده بگیرد. افزودن مقدار به وضعیت‌های بستهٔ مستندشده نیز تغییر شکننده محسوب می‌شود.

نسخهٔ مسیر مانند v1 با نسخهٔ سند مانند 1.1.0 یا نسخهٔ SDK یکی نیست. تغییر سند، به‌تنهایی نیاز به تغییر آدرس درخواست ندارد.

برای مهاجرت چقدر فرصت دارید؟

برای بازنشستگی برنامه‌ریزی‌شده، نسخهٔ جایگزین و راهنمای مهاجرت باید آماده باشند. پایان پشتیبانی زودتر از ۱۸۰ روز پس از اعلام و شروع دورهٔ بازنشستگی تعیین نمی‌شود. تاریخ و دامنهٔ تغییر در همین صفحه، کاتالوگ و هدر پاسخ اعلام می‌شود؛ اطلاعیهٔ پنل نیز پیش از بازنشستگی منتشر خواهد شد.

اعلام بازنشستگی به معنی قطع سرویس نیست. انتقال اتصال را ابتدا با دادهٔ آزمایشی بررسی کنید و هیچ ارسال نامشخصی را با کلید تازه تکرار نکنید. خاموش‌کردن یک نسخه مرحلهٔ عملیاتی جداگانه‌ای است و با رسیدن ساعت به یک تاریخ، خودکار انجام نمی‌شود.

اصلاح فوری آسیب‌پذیری یا محدودیت لازم برای جلوگیری از سوءاستفاده ممکن است بدون این مهلت اعمال شود. این استثنا برای تغییر عادی قابلیت‌ها یا واحدهای مالی استفاده نمی‌شود.

نسخه را از پاسخ تشخیص دهید

NextSMS-API-Contract: native-rest
NextSMS-API-Version: v1
Link: <https://nextsms.ir/docs/versions>; rel="deprecation"

وجود لینک سیاست به معنی منسوخ‌شدن نسخه نیست. هدرهای Deprecation و Sunset تنها بعد از ثبت برنامهٔ بازنشستگی اضافه می‌شوند. اولی تاریخ ساختاریافته با پیشوند @ و ثانیهٔ Unix است؛ دومی تاریخ استاندارد HTTP با GMT است. تاریخ‌های قابل خواندن این صفحه شمسی و با ساعت ایران هستند.

این هدرها وضعیت HTTP، بدنه، هزینه و منطق تلاش مجدد را تغییر نمی‌دهند. پاسخ خطا هم در مسیرهای این قراردادها نسخه را مشخص می‌کند؛ پاسخ مسدودشده در CDN یا WAF ممکن است این هدرها را نداشته باشد.

مراجع فنی: RFC 9745 و RFC 8594.

تاریخچهٔ تغییرات قرارداد

شفافیت نسخه و مهلت مهاجرت (1.1.0)

۲۰ مهر ۱۴۰۵ · سازگار با اتصال‌های قبلی

شناسهٔ قرارداد و نسخه در هدر پاسخ مشخص می‌شود؛ وضعیت و بدنهٔ پاسخ‌های قبلی تغییر نمی‌کند.
فهرست نسخه‌ها و سیاست بازنشستگی به‌صورت عمومی و ماشین‌خوان در دسترس است.
هیچ‌یک از قراردادهای نسخهٔ ۱ تاریخ پایان پشتیبانی ندارند.

انتشار ابزارهای اتصال (1.0.0)

۱۹ مهر ۱۴۰۵ · سازگار با اتصال‌های قبلی

قرارداد OpenAPI برای REST اصلی و ۲۷ متد سازگار پیامکی، مجموعهٔ Postman و SDK جاوااسکریپت ارائه شد.
محیط آزمایشی REST با کلید مستقل و بدون ارسال واقعی در پنل قرار گرفت.