روش استفاده

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

مرحله اول: دریافت توکن از پنل کاربری

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

مرحله دوم: ایجاد پروژه سی‌شارپ

یک پروژه جدید از نوع کنسول اپلیکیشن یا وب‌اپلیکیشن در محیط توسعه دلخواه خود (مثل Visual Studio، Visual Studio Code یا JetBrains Rider) ایجاد کنید. اطمینان حاصل کنید که از .NET Framework 4.7.2 یا .NET Core/5/6/7/8 استفاده می‌کنید. برای پروژه‌های جدید، استفاده از دات‌نت کور یا بالاتر توصیه می‌شود.

مرحله سوم: نصب کتابخانه Newtonsoft.Json

برای پردازش JSON، نیاز به کتابخانه Newtonsoft.Json دارید. این کتابخانه را از طریق NuGet Package Manager نصب کنید. برای این کار، در ترمینال یا Package Manager Console دستور زیر را اجرا کنید:

Install-Package Newtonsoft.Json

اگر از دات‌نت کور استفاده می‌کنید، از دستور زیر استفاده کنید:

dotnet add package Newtonsoft.Json

مرحله چهارم: ایجاد کلاس سرویس پیامک

یک کلاس جدید در پروژه خود ایجاد کنید (نام کلاس می‌تواند SmsService باشد). این کلاس شامل بخش‌های زیر خواهد بود:

• فیلدهای خصوصی: شامل توکن، آدرس پایه API و شیء HttpClient.

• سازنده (Constructor): که توکن را دریافت کرده و آدرس پایه و HttpClient را مقداردهی اولیه می‌کند.

• متد ارسال پیامک (به صورت Async): که پارامترهای شماره فرستنده، لیست گیرندگان، متن پیام و نوع پیام را دریافت کرده، درخواست را به سرور ارسال کرده و پاسخ را پردازش می‌کند.

• کلاس‌های کمکی: برای ساختاردهی درخواست (شامل from، recipients، message، type) و پاسخ (شامل status و result.id) به فرمت JSON.

مرحله پنجم: تنظیم توکن و پارامترهای پیامک

در متد Main یا در بخشی که قصد اجرای برنامه را دارید، توکن دریافتی را به سازنده کلاس پاس دهید. همچنین شماره خط اختصاصی خود (فرستنده)، لیست شماره موبایل گیرندگان و متن پیام را مشخص کنید. در صورت نیاز، نوع پیام را نیز تنظیم کنید (۰ برای معمولی و ۱ برای فلش).

مرحله ششم: ارسال درخواست به وب‌سرویس

با استفاده از کلاس HttpClient، یک درخواست از نوع POST به آدرس API سرویس ارسال می‌کنید. توکن دریافتی را در هدر درخواست با کلید token قرار می‌دهید. بدنه درخواست شامل شماره فرستنده، لیست گیرندگان، متن پیام و نوع پیام است که به فرمت JSON تبدیل شده و ارسال می‌شود. تایم‌اوت درخواست را روی ۳۰ ثانیه تنظیم کنید تا از قطعی ارتباط جلوگیری شود.

مرحله هفتم: دریافت پاسخ و تفسیر نتیجه

پس از ارسال درخواست، سرور پاسخ را به صورت یک شیء JSON بازمی‌گرداند. با استفاده از کتابخانه Newtonsoft.Json، پاسخ را تجزیه کرده و وضعیت آن را بررسی می‌کنید. اگر کلید status برابر با ۲۰۰ باشد و در بخش result یک id عددی بزرگتر از صفر وجود داشته باشد، عملیات با موفقیت انجام شده است و آن عدد، کد پیگیری شما خواهد بود. در غیر این صورت، کلید status مقدار خطا را نشان می‌دهد که می‌توانید بر اساس آن مشکل را شناسایی کنید.

مرحله هشتم: تست و عیب‌یابی

پیش از استفاده گسترده، حتماً سرویس را با یک یا دو شماره تست کنید. برنامه خود را اجرا کرده و خروجی را مشاهده کنید. اگر خطایی رخ داد، موارد زیر را به ترتیب بررسی کنید:

• صحت توکن

• معتبر بودن شماره فرستنده (خط اختصاصی ثبت‌شده در پنل)

• فرمت صحیح شماره‌های گیرندگان

• وجود اعتبار کافی در حساب کاربری برای ارسال پیامک

• اتصال اینترنت و عدم محدودیت دسترسی به آدرس API

۱. نکات فنی و بهینه‌سازی

• مدیریت تایم‌اوت: تایم‌اوت پیش‌فرض ۳۰ ثانیه برای اکثر موارد کافی است. در صورت نیاز به تغییر، مقدار TimeSpan.FromSeconds() را در کد تنظیم کنید.

• نوع پیام: پارامتر type با مقدار ۰ برای پیامک معمولی و ۱ برای پیامک فلش (نمایشی) استفاده می‌شود.

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

• پردازش پاسخ‌های JSON: ساختار پاسخ سرور به دقت در کد تعریف شده است. اگر پاسخ‌ها با ساختار متفاوتی بازگردانده شدند، می‌توانید ساختار کلاس‌های پاسخ را مطابق با مستندات سرویس به‌روزرسانی کنید.

• استفاده از Async/Await: متد ارسال پیامک به صورت غیرهمزمان (Async) طراحی شده است تا از بلاک‌شدن ترد اصلی برنامه جلوگیری کند. این روش برای اپلیکیشن‌های وب و دسکتاپ بسیار کارآمد است.

• مدیریت HttpClient: بهتر است از یک نمونه HttpClient به صورت Singleton یا با طول عمر کوتاه استفاده کنید تا از مصرف بی‌رویه منابع جلوگیری شود.

• ذخیره‌سازی امن توکن: هرگز توکن را به صورت مستقیم و آشکار در کدهای منبع قرار ندهید. از متغیرهای محیطی (Environment.GetEnvironmentVariable()) یا فایل‌های پیکربندی مانند appsettings.json استفاده کنید.

• استفاده از HTTPS: همیشه از پروتکل HTTPS برای ارتباط با سرور استفاده کنید تا اطلاعات در حین انتقال رمزگذاری شوند.

• تمدید دوره‌ای توکن: توکن‌ها معمولاً دارای تاریخ انقضا هستند. به صورت دوره‌ای توکن خود را بررسی کرده و در صورت نیاز آن را تمدید کنید.

• باطل‌سازی توکن: در صورت پایان پروژه یا تغییر کلیدها، توکن را از پنل کاربری باطل کنید تا از سوءاستفاده احتمالی جلوگیری شود.

• ثبت خطاها: تمام خطاها و پاسخ‌های دریافتی از سرور را در لاگ‌های برنامه ثبت کنید تا در صورت بروز مشکل، بتوانید به سرعت عیب‌یابی کنید.

۲. مزایای استفاده از روش توکن نسبت به روشنام کاربری و رمز عبور

• امنیت بالاتر: توکن به جای ارسال مستقیم نام کاربری و رمز عبور در هر درخواست، یک کلید موقت و قابل ابطال است.

• مدیریت دسترسی: می‌توانید برای توکن‌ها سطح دسترسی، تاریخ انقضا و محدودیت تعداد درخواست تعیین کنید.

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

• سازگاری با معماری‌های مدرن: روش توکن با معماری‌های مبتنی بر JWT و OAuth سازگاری کامل دارد و برای پروژه‌های توزیع‌شده و میکروسرویس‌ها ایده‌آل است.

۳. نام فایل در پروژه سی‌شارپ

در پروژه سی‌شارپ، نام فایل می‌تواند با نام کلاس یکی باشد یا متفاوت باشد، اما بهترین روش این است که نام فایل با نام کلاس مطابقت داشته باشد تا کد سازمان‌یافته‌تر باشد. بنابراین اگر کلاس شما با نام SmsService تعریف شده است، فایل را SmsService.cs نامگذاری کنید