کاربر ثبتنام میکند و باید همان لحظه کد تأیید بگیرد. سفارشی ثبت میشود و مشتری منتظر پیامک فاکتور است. انجام دستی این کارها از داخل پنل، عملاً ممکن نیست.
اینجاست که وب سرویس پیامکی وارد میشود: یک رابط برنامهنویسی که به کد شما اجازه میدهد بدون دخالت انسان، پیامک ارسال و دریافت کند. در این مقاله از دید توسعهدهنده به موضوع نگاه میکنیم؛ از معماری و متدها تا نمونه کد، امنیت و مراحل فعالسازی.
وب سرویس پیامکی چیست؟
وب سرویس پیامکی (SMS API) یک واسط نرمافزاری است که سامانه پیام کوتاه را در اختیار اپلیکیشن شما قرار میدهد. بهجای ورود به پنل و کلیک روی دکمه ارسال، برنامه شما یک درخواست HTTP به سرور سرویسدهنده میفرستد و پیامک ارسال میشود.
به نقل از سامانه پیامکی پیام رسان:
«وب سرویس پیامکی یا همان وب سرویس ارسال پیامک یک برنامه تحت وب است که ارتباط بین نرم افزار های مختلف و پنل اس ام اس را پیاده سازی می کند.»
از نظر فنی، این سرویس معمولاً شامل چند بخش است:
-
نقطه پایانی (Endpoint) ارسال: برای ارسال تکی، انبوه و مبتنی بر الگو.
-
لایه احراز هویت: با کلید دسترسی (API Key) اختصاصی هر کاربر.
-
گزارش وضعیت (Delivery Report): برای پیگیری اینکه پیام به گوشی مخاطب رسیده یا نه.
-
دریافت پیامک: برای خواندن پیامهایی که کاربران به خط شما ارسال میکنند.
به بیان ساده، وب سرویس پیام کوتاه همان کاری را میکند که پنل انجام میدهد، اما به زبانی که کد شما میفهمد.
وب سرویس یا ارسال از طریق URL؟ کدام را انتخاب کنیم؟
سرویسهای برنامه نویسان معمولاً دو مسیر ارائه میدهند و انتخاب بین آنها اولین تصمیم فنی شماست.
سرویس URL فقط یک کار انجام میدهد: ارسال. راهاندازیاش ساده است و نیازی به خط اختصاصی ندارد، اما نمیتوانید وضعیت پیامهای ارسالی را برگردانید یا پیامک ورودی را بخوانید.
وب سرویس علاوه بر ارسال، امکان دریافت پیامک و استعلام آخرین وضعیت پیامها را میدهد. طبق اعلام سامانه پیامرسان، سرعت ارسال در این روش بهمراتب بالاتر است و حدود ۵۰ پیامک در ثانیه برآورد شده است.
جمعبندی ساده: اگر پیامک بخشی از منطق محصول شماست. کد تأیید، وضعیت سفارش، گزارش تراکنش سراغ وب سرویس بروید. اگر فقط یک اطلاعرسانی یکطرفه و ساده لازم دارید، URL هم کافی است.
چرا توسعهدهندگان بهجای پنل، سراغ API میروند؟
۱. خودکارسازی کامل. رویدادهای داخل نرمافزار (ثبتنام، پرداخت، تغییر وضعیت سفارش) مستقیماً پیامک را فعال میکنند.
۲. حذف عامل انسانی. درخواست از نرمافزار شما مستقیم به سرور سرویسدهنده میرود؛ نتیجهاش تأخیر کمتر در پیامهای حساس مثل رمز یکبار مصرف است.
۳. یکپارچگی داده. شناسه پیام، وضعیت ارسال و اعتبار باقیمانده داخل سیستم خودتان قابل خواندن و ذخیره است.
۴. مقیاسپذیری. ارسال هزاران پیامک شخصیسازیشده با محتوای متفاوت از طریق پنل عملی نیست، اما با یک حلقه ساده در کد کاملاً شدنی است.
به نقل از سامانه پیامکی پیام رسان:
«با استفاده از وب سرویس ارسال پیامک بدون اینکه وارد سامانه پیامکی شوید پیامک به صورت خودکار برای مخاطب ارسال می شود.»
معماری و متدهای وب سرویس پیامکی
وب سرویس پیامرسان روی معماری REST API بنا شده و آدرس پایه آن به این شکل است:
https://api.sms-webservice.com/api/V3
بیش از ۱۵ متد برای ارسال، دریافت و گزارشگیری روی این آدرس پایه در دسترس است. دو متد پرکاربردتر را با هم مرور کنیم.
متد Send ارسال یک متن به یک یا چند شماره
این متد در هر بار فراخوانی تا ۹۹ شماره را پشتیبانی میکند. یعنی لازم نیست به ازای هر مخاطب یک درخواست جدا بفرستید؛ شمارهها را به دستههای ۹۹تایی تقسیم کنید و هر دسته را در قالب یک آرایه ارسال کنید.
پارامترهای اصلی: ApiKey، Text، Sender و Recipients.
curl “https://api.sms-webservice.com/api/V3/Send?ApiKey=123456&Text=test&Sender=123654&Recipients=9121112222”
نمونه همان درخواست در پایتون:
import requests
api_key = “your_api_key”
text = “your_message”
sender = “your_sender”
recipient = “recipient_phone_number”
url = (
“https://api.sms-webservice.com/api/V3/Send”
f”?ApiKey={api_key}&Text={text}&Sender={sender}&Recipients={recipient}”
)
try:
response = requests.get(url, timeout=10)
response.raise_for_status()
print(response.text)
except requests.exceptions.HTTPError as err:
print(err)
متد SendTokenSingle ارسال با الگو (پترن)
این متد برای پیامهای خدماتی و کد تأیید طراحی شده است. ابتدا الگوی پیام را در سامانه تعریف میکنید، پشتیبانی آن را تأیید میکند و سپس با فراخوانی متد، فقط مقدار پارامترها را میفرستید.
نکته مهم: در این متد شماره فرستنده وارد نمیشود. سامانه در همان لحظه سریعترین خط خدماتی را انتخاب میکند و ارسال را با آن ثبت میکند. نتیجهاش این است که بلکلیست مخابراتی دیگر مانع رسیدن پیام نمیشود.
curl “https://api.sms-webservice.com/api/V3/SendTokenSingle?ApiKey=123456&TemplateKey=123654&Destination=9121111111&p1=125&p2=45&p3=name”
الگو چیزی شبیه این است:
کاربر گرامی، بلیط اینترنتی شما با کدسفارش {۱} با موفقیت ثبت شده است.
و شما فقط مقدار {1} را در زمان فراخوانی پر میکنید. در سامانه پیامرسان امکان تعریف تا ۱۰ متغیر در یک پترن وجود دارد؛ برای پیامهای ساختاریافته مثل فاکتور یا اعلام وضعیت مرسوله همین کافی است.
چرا متن آزاد در وب سرویس آزاد نیست؟ برای جلوگیری از ارسال پیامهای نامناسب و اسپم و تطبیق با قوانین پیامکی. راهحل استاندارد، تعریف پترن با پارامترهای متغیر است.
کاربردهای رایج در محصولات نرمافزاری
احراز هویت دو مرحلهای و رمز یکبار مصرف. پرکاربردترین سناریو؛ با متد پترن و خط خدماتی پیاده میشود.
اطلاعرسانی تراکنشی. همان الگویی که در سیستمهای بانکی میبینید: تراکنش ثبت میشود و پیامک اطلاعرسانی خودکار ارسال میشود. تأیید سفارش، صدور فاکتور، اعلام ارسال مرسوله و یادآوری نوبت هم دقیقاً همین ساختار را دارند.
اتصال نرمافزارهای سازمانی. حسابداری، انبارداری، CRM، سیستمهای امنیتی و نرمافزار مدیریت مطب از رایجترین مصرفکنندههای SMS API هستند.
کمپینهای هدفمند بر اساس موقعیت مکانی. اگر محصول شما ماهیت محلی دارد، میتوانید مخاطبان را بر اساس کدپستی هدف بگیرید؛ در این روش بهجای در اختیار داشتن شماره موبایل، محدوده جغرافیایی مشخص میشود. توضیحات کامل این قابلیت اینجاست:
https://payam-resan.com/blog/features/send-sms-zip-code/
نظرسنجی و دریافت بازخورد. با ثبت یک لینک بازگشتی در بخش «دریافت از طریق وب سرویس»، سامانه بهمحض دریافت پیامک آن لینک را فراخوانی میکند و اطلاعات پیام ورودی را برای شما میفرستد. یعنی بهجای Polling، وبهوک دارید.
مسیر فعالسازی: از ثبتنام تا اولین ارسال
۱. ثبتنام و ورود به پنل.
۲. مراجعه به منوی «سرویسهای برنامهنویسان». زیرمنوهای اصلی این بخش عبارتاند از: وب سرویس ارسال پیامک (مشاهده وضعیت)، لیست کلید دسترسی (ساخت API Key)، دریافت از طریق وب سرویس (ثبت آدرس وبهوک) و وب سرویس ارسال پترن.
۳. احراز هویت. برای فعال شدن وب سرویس، سایت یا نرمافزار شما توسط کارشناسان بررسی و تأیید میشود.
۴. تعریف الگو. متن پترن را ثبت میکنید تا بررسی و تأیید شود.
۵. ساخت کلید دسترسی و ارسال آزمایشی. طبق اعلام پیامرسان تا ۱۰۰ پیامک هدیه برای تست در نظر گرفته شده و فعالسازی وب سرویس هزینه جداگانهای ندارد.
اگر با وردپرس یا فروشگاهساز آماده کار میکنید
لازم نیست همهچیز را از صفر بنویسید. برای بسترهای رایج افزونه آماده وجود دارد:
-
PrestaShop
-
WP SMS
-
WooCommerce و WooCommerce OTP
-
Digits و Digits OTP
-
OpenCart
-
Gravity Forms SMS و نسخه پترن آن
نصب افزونه، وارد کردن کلید دسترسی و اتمام کار. سراغ کدنویسی مستقیم بروید فقط وقتی که منطق شما پیچیدهتر از چیزی است که افزونه پوشش میدهد.
معماری درست: پیامک را در صف قرار دهید
یکی از رایجترین اشتباهات، فراخوانی مستقیم وب سرویس داخل چرخه درخواست کاربر است. اگر سرویسدهنده دیر پاسخ دهد، کاربر شما پشت یک اسپینر منتظر میماند.
معماری پیشنهادی:
۱. رویداد رخ میدهد (مثلاً ثبت سفارش). ۲. یک Job در صف (Queue) قرار میگیرد. ۳. Worker پسزمینه درخواست را به وب سرویس ارسال میکند. ۴. در صورت خطای موقت، با الگوی Exponential Backoff دوباره تلاش میشود. ۵. شناسه پیام و وضعیت نهایی در دیتابیس ثبت میشود.
این ساختار هم تجربه کاربری را حفظ میکند و هم در برابر قطعی موقت سرویسدهنده مقاوم است.
نکات امنیتی که نباید نادیده گرفت
-
کلید API را در کد قرار ندهید. آن را در متغیر محیطی یا سرویس مدیریت اسرار نگه دارید. کلید در Query String هم در لاگ سرور ثبت میشود؛ به سیاست نگهداری لاگهای خودتان توجه کنید.
-
از HTTPS استفاده کنید. آدرس پایه روی https در دسترس است؛ نسخه http را در محیط عملیاتی به کار نبرید.
-
محدودیت نرخ (Rate Limit) بگذارید. Endpoint ارسال کد تأیید بدون محدودیت، مسیر مستقیم هدر رفتن اعتبار شماست.
-
اعتبار کد یکبار مصرف را کوتاه نگه دارید و پس از یک بار استفاده باطلش کنید.
-
ورودی شماره موبایل را اعتبارسنجی کنید تا هزینه ارسال به شمارههای نامعتبر هدر نرود.
خطاهای رایج و راهحل آنها
پیام ثبت میشود اما به مخاطب نمیرسد. معمولاً چون مخاطب دریافت پیامک تبلیغاتی را مسدود کرده است. راهحل: ارسال از طریق پترن و خط خدماتی.
خطای احراز هویت با وجود کلید درست. بررسی کنید کلید دسترسی فعال باشد و فاصله یا کاراکتر اضافی به آن نچسبیده باشد.
تعداد بخشهای پیامک بیشتر از انتظار. متن فارسی با کدگذاری Unicode ارسال میشود و ظرفیت هر بخش کمتر از متن انگلیسی است. ایموجی نیز طول پیام را افزایش میدهد.
ارسال تکراری پس از خطای شبکه. اگر Worker شما دوباره تلاش میکند، از یک کلید یکتا در سمت خودتان استفاده کنید تا پیام دو بار ثبت نشود.
تغییر آدرس Endpoint. اگر ارسالهای قدیمی ناگهان قطع شد، پیش از هر چیز آدرس نسخه فعلی وب سرویس را در پنل بررسی کنید.
سوالات متداول
وب سرویس پیامکی چیست؟
وب سرویس پیامکی یک برنامه تحت وب است که ارتباط میان نرمافزارهای مختلف و پنل اس ام اس را برقرار میکند؛ در نتیجه بدون ورود دستی کسی به سامانه، پیام بهصورت خودکار برای کاربر ارسال میشود.
تفاوت وب سرویس و سرویس URL چیست؟
در وب سرویس امکان ارسال، دریافت پیامک و مشاهده وضعیت پیامهای ارسالی وجود دارد، اما در سرویس URL فقط امکان ارسال فراهم است. سرعت ارسال در وب سرویس نیز بهمراتب بالاتر است.
برای اتصال به وب سرویس پیامکی به چه زبانی نیاز دارم؟
هر زبانی که بتواند درخواست HTTP ارسال کند. برای PHP، #C، جاوا، پایتون و VB.net نمونه کد آماده در سامانه موجود است.
برای فعالسازی وب سرویس به احراز هویت نیاز است؟
بله. سایت یا نرمافزار شما ابتدا توسط کارشناسان بررسی و تأیید میشود و سپس الگوی پیام شما نیز باید تأیید شود.
آیا میتوان متن آزاد از طریق وب سرویس ارسال کرد؟
معمولاً خیر. برای جلوگیری از اسپم و رعایت قوانین پیامکی، پیامها در قالب پترن با پارامترهای متغیر ارسال میشوند.
آیا ارسال پیامک بر اساس کدپستی امکانپذیر است؟
بله. در این حالت بهجای در اختیار داشتن شماره موبایل مخاطبان، محدوده جغرافیایی و کدپستی مشخص میشود.
چگونه مطمئن شوم پیام به دست مخاطب رسیده است؟
با ذخیره شناسه پیام هنگام ارسال و سپس استعلام گزارش تحویل از سرویسدهنده، یا دریافت خودکار وضعیت از طریق وبهوک.
جمعبندی و قدم بعدی
وب سرویس پیامکی دیگر یک قابلیت جانبی نیست؛ بخشی از زیرساخت ارتباطی هر محصول دیجیتال است. انتخاب درست بین ارسال URL و وب سرویس، استفاده از پترن برای پیامهای خدماتی، معماری مبتنی بر صف و مدیریت صحیح کلیدها، تفاوت میان یک اتصال شکننده و یک سامانه پایدار را رقم میزند.
اگر آمادهاید، از یک ارسال آزمایشی ساده شروع کنید: در سامانه پیامرسان ثبتنام کنید، از بخش «سرویسهای برنامهنویسان» یک کلید دسترسی بسازید و اولین درخواست را به متد Send بفرستید. با ۱۰۰ پیامک هدیه تست، کمتر از ده دقیقه زمان میبرد و مسیر بقیه کار روشن میشود.
