آموزشی

راهنمای استفاده از WebService نگین ارتباط

ارسال توسط

مقدمه

سند پیش رو برای استفاده برنامه نویسانی طراحی شده است که می خواهند توسط برنامه خود نسبت به ارسال و دریافت پیامک بر بستر وب با استفاده از پروتکل SOAP اقدام نمایند. این وب سرویس امکاناتی از قبیل :

  • ارسال پیامک تکی و آرایه ای(چند تایی)
  • دریافت پیامک رسیده به خط پیامک
  • بررسی اعتبار خط پیامک و ...

را در اختیار شما قرار می دهد.

نکته ۱: توجه داشته باشید که کلمه عبور وب سرویس شما عبارتی غیر از کلمه عبور پنل پیامکی شما بوده و لازم است خودتان آن را انتخاب نمایید.

مراحل تنظیم رمز عبور وب سرویس :

  • مرحله اول: ورود به پنل پیامک نگین
  • مرحله دوم: ورود به منوی "خدمات برنامه نویسان" (از منوی سمت راست)
  • مرحله سوم: ورود به زیر منوی "تنظیم کلمه عبور وب سرویس"

آدرس وب سرویس

https://sms.3300.ir/almassms.asmx

جهت مشاهده لیست توابع وب سرویس این صفحه را مطالعه کنید.

تعاریف

شماره فرستنده :

هر حساب می‌تواند شماره‌های گوناگونی برای ارسال پیام کوتاه در اختیار داشته باشد و پیامک‌های خود را با هر یک از آن شماره‌ها ارسال کند.

طول استاندارد پیامک:

سایز استاندارد پیامک ۱۴۰ بایت می‌باشد. در صورتی که در متن پیامک از کاراکترهای Alphanumeric استفاده شود طول یک پیامک حداکثرمیتواند ۱۶۰ کاراکتر، و در صورتی که از Unicode دو بایتی (کاراکترهای فارسی) استفاده شود طول استاندارد آن ۶۷ و طول حداکثر پیامک (پیامک اول) ۷۰ کاراکتر می‌تواند باشد.

شماره پیامک:

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

در صورتی که این شماره پیامک کمتر از ۱۰۰۰ باشد، مقدار بازگشتی یک کد خطا است و هزینه ارسال پیامک از اعتبار کاربر کسر نخواهد شد.

کدهای خطا

کد خطا توضیحات
۱ شماره گیرنده(mobile) نامعتبر (خالی) است.
۲ مقدار پارامتر line نامعتبر است. (خطوط ۳۰۰۰ با ۹۸۳۰۰۰….. شروع می شوند)
۳ مقدار پارامتر encoding نامعتبر است.
۴ مقدار پارامتر messageClass نامعتبر است.
۶ مقدار پارامتر messageClass نامعتبر است.
۱۳ پیامک (ترکیب udh و message ) خالی است.
۱۴ حساب اعتبار مورد نیاز را دارا نمی‌باشد.
۱۵ سرور در هنگام ارسال پیام مشغول برطرف نمودن ایراد داخلی بوده و لازم است پیام‌ها دوباره ارسال شوند.
۱۶ حساب غیر فعال می باشد.
۱۷ حساب منقضی شده است. (expired)
۱۸ نام کاربر و یا کلمه ی عبور نامعتبر است.
۱۹ درخواست دارای اعتبار نمی‌باشد. (authentication failure)
۲۲ استفاده از این سرویس برای این حساب مقدور نمی‌باشد.
۲۳ به دلیل ترافیک بالا، سرور آمادگی دریافت پیام جدید را ندارد. دوباره سعی کنید.
۲۴ شناسه پیامک معتبر نمی‌باشد.
۲۵ نوع سرویس درخواستی نامعتبر است.
۲۷ انصراف مخاطب از دریافت پیامک اینترنتی
۱۰۱ طول آرایه پارامتر messages با طول آرایه گیرندگان تطابق ندارد.
۱۰۲ طول آرایه پارامتر messageClass با طول آرایه گیرندگان تطابق ندارد.
۱۰۴ طول آرایه پارامتر udhs با طول آرایه گیرندگان تطابق ندارد.
۱۰۵ طول آرایه پارامتر priorities با طول آرایه گیرندگان تطابق ندارد.
۱۰۶ آرایه‌ی گیرندگان خالی می باشد.
۱۰۷ طول آرایه پارامتر گیرندگان بیشتر از طول مجاز است.
۱۰۸ آرایه ی فرستندگان خالی می‌باشد.
۱۰۹ طول آرایه پارامتر priorities با طول آرایه گیرندگان تطابق ندارد.
۴۰۹ حداقل فاصله زمانی بین درخواست ها رعایت نشده است. (حداقل پنج ثانیه)

کد وضعیت پیامک

کد‌های وضعیت ارسال به شرح ذیل می‌باشد.

کد وضعیت توضیحات
-۱ ارسال نشده
۱ گیرنده، پیام ارسالی را دریافت کرده است.
۲ گیرنده، پیام ارسالی را دریافت نکرده است و پیام fail شده است و در صورت نیاز برنامه سمت مشتری می‌تواند مجدداً عملیات ارسال را تکرار نماید.
۸ مخابرات، پیام ارسالی را دریافت کرده است.
۱۶ مخابرات، پیام ارسالی را دریافت نکرده است. و در صورت نیاز برنامه سمت مشتری می‌تواند مجدداً عملیات ارسال را تکرار نماید.

مقادیر بازگشتی در فراخوانی توابع

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

کد خطا شرح
۲- (عدد منفی) متد با موفقیت اجرا شده است
۰ اجرای سرویس با خطای غیر منتظره (Exception) مواجه شده است.لطفا پارامتر های خود را چک
نمایید
۱۴ اعتبار ریالی کافی برای اجرای متد وجود ندارد
۱۸ نام کاربری و یا کلمه عبور اشتباه است. (نکته۱ از مقدمه همین راهنما
را ملاحظه کنید)
۲۰ شناسه پیامک اشتباه است
۱۰۰ طول آرایه ENCODING اشتباه است
۱۰۱ طول آرایه MESSAGE اشتباه است
۱۰۲ طول آرایه اشتباه MCLASS است
۱۰۳ طول آرایه MOBILES اشتباه است
۱۰۴ طول آرایه UDH اشتباه است

SendSms (برای ارسال پیامک)

تعریف تابع

public long SendSms(
    string pUsername, 
    string pPassword, 
    string[] messages, 
    string[] mobiles,
    out long[] pMessageIds
)

پارامتر های ورودی

نام فیلد توضیحات
pUsername نام کاربری
pPassword کلمه عبور
messages آرایه‌ای از متن پیامک‌ها
mobiles آرایه‌ای از شماره‌های همراه دریافت‌کننده پیامک

پارامترهای خروجی

نام فیلد توضیحات
pMessageIds آرایه‌ای از شناسه‌های پیام ارسال‌شده

مقدار بازگشتی

وضعیت خروجی
اجرای موفق متد عدد منفی
رخ دادن خطا شماره خطا

توضیحات

برای پارامترهای messages و mobiles دو حالت کلی وجود دارد:

۱- ارسال یک پیام برای چند گیرنده:
messages = 1 , mobiles = N

۲- ارسال چند پیام برای چند گیرنده:
messages = N , mobiles = N

در حالت اول، متن پیام برای همه گیرنده‌ها یکسان در نظر گرفته می‌شود. در حالت دوم، هر پیام به صورت متناظر با شماره موبایل مربوطه ارسال خواهد شد.

SendSmsByCheckId (ارسال پیامک با کد پیگیری دلخواه)

تعریف تابع

public long SendSmsByCheckId(
    string pUsername,
    string pPassword,
    long line,
    string[] messages,
    string[] mobiles,
    long[] tempCheckIds,
    out long[] pMessageIds
)

توضیحات کلی

این متد برای ارسال پیامک به همراه شناسه پیگیری دلخواه (tempCheckIds) استفاده می‌شود.
کاربر می‌تواند برای هر پیامک یک شناسه اختصاصی تعریف کند تا بعداً وضعیت ارسال هر پیام را بر اساس همان شناسه در سیستم خود پیگیری کند.

دقت کنید که پیگیری پیام بر اساس CheckId فقط تا ۲۴ ساعت بعد از ارسال امکان‌پذیر است.

پارامتر های ورودی

نام فیلد توضیحات
pUsername نام کاربری
pPassword کلمه عبور
line شماره خط ارسال‌کننده پیامک
messages آرایه پیامک‌ها:

  • اگر طول آن برابر با mobiles باشد، هر پیام متناظر با همان شماره ارسال می‌شود (messages[i] → mobiles[i])
  • اگر فقط یک مقدار داشته باشد، همان پیام برای همه شماره‌ها ارسال می‌شود
mobiles آرایه شماره موبایل‌های گیرنده پیامک
tempCheckIds آرایه شناسه‌های پیگیری دلخواه کاربر:

  • باید دقیقاً هم‌اندازه mobiles باشد
  • هر مقدار به‌عنوان کد پیگیری همان پیام در سمت کاربر استفاده می‌شود
  • برای بررسی وضعیت ارسال پیام‌ها در آینده کاربرد دارد

قوانین نگاشت آرایه‌ها

آرایه رفتار
mobiles لیست شماره‌های گیرنده پیامک
messages اگر طول = mobiles → متناظر با هر شماره
اگر طول = 1 → ارسال یک متن برای همه شماره‌ها
tempCheckIds باید دقیقاً هم‌اندازه mobiles باشد (نگاشت ۱ به ۱ با هر پیام)

پارامترهای خروجی

نام فیلد توضیحات
pMessageIds آرایه‌ای از شناسه‌های پیام تولید شده در سیستم

مقدار بازگشتی

وضعیت خروجی
اجرای موفق متد عدد منفی
رخ دادن خطا شماره خطا

GetOutboxByCheckId (دریافت وضعیت پیام‌ها بر اساس کد پیگیری)

تعریف تابع

long GetOutboxByCheckId(
    string pUsername,
    string pPassword,
    long[] pTempCheckIds,
    out List<OutboxResult> outboxes
)

توضیحات کلی

این متد برای دریافت وضعیت پیامک‌های ارسال‌شده بر اساس کدهای پیگیری (CheckId) استفاده می‌شود.
این کدها همان مقادیری هستند که هنگام ارسال پیامک با متد SendSmsByCheckId تعیین شده‌اند.

با استفاده از این متد می‌توان وضعیت پیام‌های ارسال‌شده را در بازه زمانی مشخص بررسی کرد.

دقت کنید که پیگیری پیام بر اساس CheckId فقط تا ۲۴ ساعت بعد از ارسال امکان‌پذیر است.

پارامتر های ورودی

نام فیلد توضیحات
pUsername نام کاربری
pPassword کلمه عبور
pTempCheckIds آرایه‌ای از کدهای پیگیری تعریف‌شده توسط کاربر در زمان ارسال پیامک (SendSmsByCheckId)

پارامترهای خروجی

نام فیلد توضیحات
outboxes لیستی از نتایج پیام‌های ارسال‌شده شامل وضعیت کامل هر پیام

ساختار شیء خروجی (OutboxResult)

public class OutboxResult
{
    public long CheckId { get; set; }
    public long MessageId { get; set; }
    public int Status { get; set; }
    public DateTime SendDate { get; set; }
}

توضیحات فیلدهای خروجی

فیلد توضیحات
CheckId کد پیگیری تعریف‌شده توسط کاربر
MessageId شناسه پیام در سیستم
Status وضعیت ارسال پیام (کد وضعیت سیستم)
SendDate تاریخ و زمان ارسال پیام

مقدار بازگشتی

وضعیت خروجی
اجرای موفق متد عدد منفی
رخ دادن خطا شماره خطا

GetMessageStatus (برای دریافت وضعیت پیامک‌ها)

تعریف تابع

public long GetMessageStatus2(
    string pUsername, 
    string pPassword,
    long[] pMessageIds, 
    out int[] pStatuses, 
    out long[] pMsgIds
)

پارامتر های ورودی

نام فیلد توضیحات
pUsername نام کاربری
pPassword کلمه عبور
pMessageIds آرایه‌ای از شناسه پیام‌هایی که وضعیت آن‌ها باید بررسی شود

پارامترهای خروجی

نام فیلد توضیحات
pStatuses آرایه‌ای از وضعیت پیام‌ها (کد وضعیت مخابرات)
pMsgIds آرایه شناسه پیام‌های متناظر با وضعیت‌ها

مقدار بازگشتی

وضعیت خروجی
اجرای موفق متد عدد منفی
رخ دادن خطا شماره خطا

GetReceivedSms (برای دریافت پیامک‌های دریافت‌شده)

تعریف تابع

public long GetReceivedSms(
    string pUsername,
    string pPassword, 
    out List<InboxModel> pResult
)

پارامتر های ورودی

نام پارامتر توضیحات
pUsername نام کاربری
pPassword کلمه عبور

پارامترهای خروجی

نام پارامتر توضیحات
pResult لیست پیامک‌های دریافتی شامل جزئیات کامل هر پیام

ساختار شیء خروجی (InboxModel)

public class InboxModel
{
    public long id { get; set; }
    public string date { get; set; }
    public string message { get; set; }
    public string mobile { get; set; }
    public string line { get; set; }
}

توضیحات فیلدهای InboxModel

فیلد توضیحات
id شناسه پیامک در سیستم
date تاریخ دریافت پیامک
message متن پیامک
mobile شماره ارسال‌کننده پیامک
line شماره خط دریافت‌کننده پیامک

مقدار بازگشتی

وضعیت خروجی
اجرای موفق متد عدد منفی
رخ دادن خطا شماره خطا

GetCredit (برای دریافت میزان اعتبار باقیمانده)

تعریف تابع

public long GetCredit(
    string pUsername, 
    string pPassword, 
    out long pCredit
)

پارامتر های ورودی

نام پارامتر توضیحات
pUsername نام کاربری
pPassword کلمه عبور

پارامترهای خروجی

نام پارامتر توضیحات
pCredit میزان اعتبار باقیمانده به ریال

مقدار بازگشتی

وضعیت خروجی
اجرای موفق متد عدد منفی
رخ دادن خطا شماره خطا

GetInfo (دریافت اطلاعات کاربر و سرویس)

تعریف تابع

public int GetInfo(
    string pUsername,
    string pPassword,
    out int pUserId,
    out string pSmsNumber,
    out long pCredit,
    out DateTime pEndDate
)

پارامتر های ورودی

نام پارامتر توضیحات
pUsername نام کاربری
pPassword کلمه عبور

پارامترهای خروجی

نام پارامتر توضیحات
pUserId شناسه کاربر در سیستم
pSmsNumber شماره اختصاصی ارسال پیامک کاربر
pCredit میزان اعتبار باقی‌مانده (ریال)
pEndDate تاریخ پایان اعتبار یا سرویس

مقدار بازگشتی

وضعیت خروجی
اجرای موفق متد عدد منفی
رخ دادن خطا شماره خطا

ملاحظات لازم در ارتباط با فراخوانی متدها

  • ترتیب پارامترها دارای اهمیت است و جابجایی مجاز نیست.
  • حداکثر تعداد عناصر آرایه‌ در هر بار ارسال ۵۰ پیام می‌باشد.
  • پارامترهای ورودی، حتماً باید به عنوان ورودی به متد ارسال شوند و در صورت خالی گذاشتن آنها پیغام خطا داده می‌شود.
  • در بالک نظیر به نظیر لازم است ملاحظات لازم در مورد طول آرایه‌ها – که در بخش‌های پیشین آمد – مد نظرقرار داده شوند.
  • در هنگام تعیین وضعیت مخابرات، فقط تا ۷ روز بعد از ارسال پیامک، امکان بررسی وضعیت وجود دارد و بعد از آن وضعیت پیامک، نامشخص خواهد بود.
جدیدتر
راهنمای استفاده از REST API نگین ارتباط
بازگشت به لیست
قدیمی تر پنل پیامکی چیست؟