مقدمه

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

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

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

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

مراحل کار:

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

آدرس وب سرویس

(بنابر تشخیص خود، یکی از دو آدرس زیر را انتخاب نمایید)

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

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

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

تعاریف

ارسال پیام به صورت نظیر به نظیر : در این حالت تمام پارامترهای متد باید دارای آرایه‌ا‌ی هم سایز و متناظر با آرایه پارامتر شماره دریافت کنندگان باشد. در این صورت میتوان SMS های گوناگونی به گیرندگان ارسال نمود.

ارسال پیام به صورت یک به چند (بالک):

این حالت تمام پارامترهای متد به جز پارامتر شماره دریافت کنندگان باید دارای آرایه‌ا‌ی به طول یک باشد. در این صورت یک متن واحد برای چندین نفر (شماره گیرنده) فرستاده می‌شود.

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

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

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

سایز استاندارد پیامک 140 بایت می‌باشد. در صورتی که در متن پیامک از کاراکترهای Alphanumeric استفاده شود طول یک پیامک حداکثرمیتواند 160 کاراکتر، و در صورتی که از Unicode دو بایتی (کاراکترهای فارسی) استفاده شود طول استاندارد آن 65 و طول حداکثر پیامک (پیامک اول) 70 کاراکتر می‌تواند باشد.

Encodings:

عددی از نوع Integer است که برای مشخص کردن urlEncode پیام بکار می‌رود. مقادیر مجاز برای این پارامتر 1 ، 2 ، 5 یا 6 می‌باشد.

  • عدد یک برای حالتی است که متن پیام حاوی کاراکترهای لاتین(ISO-8859-1) باشد.
  • عدد دو برای حالتی که متن پیام حاوی کاراکترهای فارسی (UTF-8) باشد.
  • عدد پنج برای حالتی که متن پیام حاوی Data (8-BIT) مانند ملودی باشد.
  • عدد شش برای حالاتی متن پیام باینری (BINARY) باشد.

مثال: اگر متن پیام شامل کاراکترهای خاص باشد باید از این encoding استفاده نمایید.

UDH :

رشته کدی است که برای اضافه کردن حالات خاص و گسترش قابلیت پیامک بکار می‌رود. در زیر به چند نمونه از این قابلیت ها اشاره می‌شود:

  • Application Port Addressing: ارسال پیامک به گونه ای که گیرنده آن را بر روی پورت خاصی دریافت کند. این قابلیت برای نرم‌افزار‌های مبتنی بر موبایل کاربرد دارد.
  • EMS (Enhanced Message Service: ارسال عکس، صدا و ... از طریق پیامک و همچنین فرمت دادن به متن پیام های ارسالی مانند: ایتالیک، بولد و ...

Message-class:

با تنظیم این پارامتر می‌توان نحوه دریافت پیامک روی گوشی گیرنده را به دلخواه تغییر داد، مقادیر قابل قبول برای این پارامتر چهار عدد 0، 1، 2 و 3 می‌باشد.

  • 0 : پیامک بصورت مستقیم به روی صفحة موبایل شخص گیرنده فرستاده می‌شود. در این حالت پیامک در موبایل یا سیم کارت شخص گیرنده بصورت اتوماتیک ذخیره نمی‌شود.
  • 1 : پیامک در حافظة موبایل شخص گیرنده ذخیره می‌شود.
  • 2 : پیامک برروی حافظة سیم کارت شخص گیرنده ذخیره می‌شود.
  • 3 : در صورتی که موبایل شخص گیرنده دارای یک نرم‌افزار کاربردی خاص برای ذخیره پیامک باشد و یا به یک نرم‌افزار کاربردی خاص بر روی یک کامپیوتر متصل باشد، پیامک دریافتی در آن نرم افزارها ذخیره می‌شود.

شماره پیامک:

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

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

کدهای خطا

کد خطا توضیحات
1 شماره گیرنده(mobile) نامعتبر (خالی) است.
2 مقدار پارامتر line نامعتبر است. (خطوط 3000 با 983000….. شروع می شوند)
3 مقدار پارامتر encoding نامعتبر است.
4 مقدار پارامتر messageClass نامعتبر است.
6 مقدار پارامتر messageClass نامعتبر است.
13 پیامک (ترکیب udh و message ) خالی است.
14 حساب اعتبار مورد نیاز را دارا نمی‌باشد.
15 سرور در هنگام ارسال پیام مشغول برطرف نمودن ایراد داخلی بوده و لازم است پیام‌ها دوباره ارسال شوند.
16 حساب غیر فعال می باشد.
17 حساب منقضی شده است. (expired)
18 نام کاربر و یا کلمه ی عبور نامعتبر است.
19 درخواست دارای اعتبار نمی‌باشد. (authentication failure)
22 استفاده از این سرویس برای این حساب مقدور نمی‌باشد.
23 به دلیل ترافیک بالا، سرور آمادگی دریافت پیام جدید را ندارد. دوباره سعی کنید.
24 شناسه پیامک معتبر نمی‌باشد.
25 نوع سرویس درخواستی نامعتبر است.
27 انصراف مخاطب از دریافت پیامک اینترنتی
101 طول آرایه پارامتر messages با طول آرایه گیرندگان تطابق ندارد.
102 طول آرایه پارامتر messageClass با طول آرایه گیرندگان تطابق ندارد.
104 طول آرایه پارامتر udhs با طول آرایه گیرندگان تطابق ندارد.
105 طول آرایه پارامتر priorities با طول آرایه گیرندگان تطابق ندارد.
106 آرایه‌ی گیرندگان خالی می باشد.
107 طول آرایه پارامتر گیرندگان بیشتر از طول مجاز است.
108 آرایه ی فرستندگان خالی می‌باشد.
109 طول آرایه پارامتر priorities با طول آرایه گیرندگان تطابق ندارد.
409 حداقل فاصله زمانی بین درخواست ها رعایت نشده است. (حداقل پنج ثانیه)

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

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

  • کد 1- : ارسال نشده
  • کد 1: گیرنده، پیام ارسالی را دریافت کرده است.
  • کد 2: گیرنده، پیام ارسالی را دریافت نکرده است و پیام fail شده است و در صورت نیاز برنامه سمت مشتری می‌تواند مجدداً عملیات ارسال را تکرار نماید.
  • کد 8: مخابرات، پیام ارسالی را دریافت کرده است.
  • کد 16: مخابرات، پیام ارسالی را دریافت نکرده است. و در صورت نیاز برنامه سمت مشتری می‌تواند مجدداً عملیات ارسال را تکرار نماید.

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

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

کد خطا شرح
2- (عدد منفی) متد با موفقیت اجرا شده است
0 اجرای سرویس با خطای غیر منتظره (Exception) مواجه شده است.لطفا پارامتر های خود را چک نمایید
14 اعتبار ریالی کافی برای اجرای متد وجود ندارد
18 نام کاربری و یا کلمه عبور اشتباه است. (نکته1 از مقدمه همین راهنما را ملاحظه کنید)
20 شناسه پیامک اشتباه است
100 طول آرایه ENCODING اشتباه است
101 طول آرایه MESSAGE اشتباه است
102 طول آرایه اشتباه MCLASS است
103 طول آرایه MOBILES اشتباه است
104 طول آرایه UDH اشتباه است

لیست توابع پرکاربرد

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

نحوه فراخوانی

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

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

  • pUsername: نام کاربری
  • pPassword: کلمه عبور
  • Messages: آرایه ای از متن پیامکها
  • Mobiles: آرایه ای از شماره های همراه دریافت کننده پیامک

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

pMessageIds: آرایه ای از شناسه های پیام

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

در صورت صحت اجرای متد، عددی منفی و در صورت رخ دادن خطا، شماره خطا

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

نحوه فراخوانی

public long SendSms2(string pUsername, string pPassword, string[] messages, string[] mobiles, string[] UDH, int[] encodings,int[] mclass, out long[] pMessageIds)

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

  • pUsername: نام کاربری
  • pPassword: کلمه عبور
  • Messages: آرایه ای از متن پیامکها
  • Mobiles: آرایه ای از شماره های همراه دریافت کننده پیامک
  • UDH
  • Encodings
  • mClass

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

pMessageIds: آرایه ای از شناسه های پیام

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

در صورت صحت اجرای متد، عددی منفی و در صورت رخ دادن خطا، شماره خطا

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

نحوه فراخوانی

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

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

  • pUsername: نام کاربری
  • pPassword: کلمه عبور
  • Messages: آرایه ای از متن پیامکها

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

  • pStatuses: آرایه ای از وضعیت مخابرات مربوط به شناسه های پیام
  • pMsgIds: آرایه شناسه های پیام متناظر با ارایه وضعیتها

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

در صورت صحت اجرای متد، عددی منفی و در صورت رخ دادن خطا، شماره خطا

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

نحوه فراخوانی

public long GetReceivedSms2(string pUsername, string pPassword, out string pMessages, out string pFroms, out string pSmsc, out string pMessageIds, out DateTime pEnteredDate)

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

  • pUsername: نام کاربری
  • pPassword: کلمه عبور

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

  • pMessages
  • pFroms
  • pSmsc
  • pMessageIds
  • pEnteredDate

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

در صورت صحت اجرای متد، عددی منفی و در صورت رخ دادن خطا، شماره خطا

ChangePassword (برای تغییر کلمه عبور)

نحوه فراخوانی

public int ChangePassword(string pUsername, string pPassword, string pNewPassword)

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

  • pUsername: نام کاربری
  • pPassword: کلمه عبور
  • pNewPassword: کلمه عبور جدید

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

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

در صورت صحت اجرای متد، عددی منفی و در صورت رخ دادن خطا، شماره خطا

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

نحوه فراخوانی

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

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

  • pUsername: نام کاربری
  • pPassword: کلمه عبور

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

pCredit: میزان اعتبار باقیمانده به ریال

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

در صورت صحت اجرای متد، عددی منفی و در صورت رخ دادن خطا، شماره خطا

GetSmsCost (برای مشاهده هزینه یک پیامک)

نحوه فراخوانی

public int GetSmsCost(string pUsername, string pPassword, string sms, out int cost)

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

  • pUsername: نام کاربری
  • pPassword: کلمه عبور
  • sms: متن پیامک

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

cost: هزینه ارسال پیامک به ریال

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

در صورت صحت اجرای متد، عددی منفی و در صورت رخ دادن خطا، شماره خطا

در این بخش حالات ممکن برای ارسال بررسی می‌شود. برای هر یک از دو پارامتر messages و mobiles، می توان یکی از مقدار 1 و N را در نظر گرفت. در اینصورت، 2 حالت کلی برای ارسال پیامک وجود دارد:

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

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

در صورتی‌ که قصد مقدار دهی آرایه‌های encodings, udh, mClass را دارید، توجه داشته باشید که طول این آرایه ها یا باید برابر با طول دیگر پارامترها یا برابر با یک باشند.

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

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

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