وب سرویس

راهنمای استفاده از وب سرویس

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

نسخهتاریخ نگارش
۰.۶۹۰/۱۲/۲۰
۰.۷۹۱/۰۵/۲۸
۰.۷۵۹۱/۱۲/۱۲
۱.۰۹۲/۱۰/۲۲
۱.۱۹۴/۰۲/۲۴

مقدمه
این مستند بعنوان راهنمای استفاده از سرویس وب پیام کوتاه معرکه می باشد و مخاطب آن برنامه نویسانی هستند که آشنا به مفاهیم تکنولوژی SOAP بوده و نحوه ایجاد یک SOAP Client را با زبانی که مسلط به آن هستند بدانند. البته مثالهای کاربردی با زبان PHP در انتهای مستند ارائه شده است. معرکه خود را موظف به ارائه صحیح سرویس وب می داند و هیچ تعهدی برای نصب، پیکربندی و راه اندازی SOAP Client بر روی سرویس دهنده های دیگر ندارد و در صورت نیاز مشتری طبق قرارداد جداگانه قابل انجام است.

نحوه عضویت
جهت استفاده از این سرویس وب ابتدا باید درخواست خود را از طریق صفحه مربوطه در وب سایت معرکه تنظیم و ارسال کنید. بر اساس درخواست شما یک یا چند شماره به حساب شما تخصیص داده می شود که از میان آنها یکی بصورت شماره پیش فرض (Default) انتخاب می شود. با استفاده از شناسه کاربری و رمز عبوری که در فرم ثبت نام وارد می کنید، پس از شارژ اعتبار و فعالسازی حساب شما توسط مدیر سیستم، اجازه استفاده از سرویس وب را خواهید داشت که در ادامه به معرفی متدهای سرویس وب، پارامترهای ورودی و خروجی آنها، کدهای خطا و کدهای وضعیت پیام کوتاه می پردازیم.

تعاریف

کد پیگیری پیام کوتاه
برای هر پیام کوتاه که ارسال می کنید، یک کد پیگیری منحصر به فرد باز گردانده می شود که بوسیله آن می توانید از وضعیت تحویل (Delivery) پیام کوتاه اطلاع کسب کنید. در سرویس وب پیام کوتاه معرکه، این کد عددی بالای ١٠٠٠ است.
کد پیغام خطا
در صورت بروز خطا مثلا عدم دسترسی به بانک اطلاعاتی، سوئیچ مخابرات و یا بروز خطا در اعتبارسنجی پارامترهای ارسال شده در فراخوانی عملیاتهای سرویس وب، یک آبجکت SoapFault بازگردانده می شود که دو خصیصه (Property) آن به نام faultcode و faultstring آن دارای مقدار است که به ترتیب کد خطا (برای نمایش خطاهای سفارشی شده توسط برنامه نویس) و دیگری توضیح قابل فهم خطا می باشد که در جدول یک شرح آنها آمده است. در حال حاضر کد خطا عددی بین ١ تا ٢٠ است.
کد وضعیت تحویل پیام کوتاه
این کد وضعیت تحویل (Delivery) پیام کوتاه را در لحظه درخواست مشخص می کند که شرح آنها در جدول دو آمده است.
آدرس انتقال ترافیک (Traffic Relay)
وقتی پیام کوتاهی به هر یک از شماره های تخصیص یافته شما ارسال می شود، پس از تایید صحت شماره، اطلاعات پیام کوتاه که شامل شماره فرستنده، متن پیام، شماره شما و کد امنیتی می باشد به آدرس اینترنتی (URL) که مشخص کرده اید بصورت POST ارسال می شود. جهت اطمینان از اینکه درخواست از طرف سرویس دهنده معرکه ارسال شده می توانید از کد امنیتی همراه پیام استفاده کنید. بدین صورت که با فراخوانی عملیات verifyReceive از سرویس وب و ارسال کد امنیتی یک پاسخ از نوع منطقی (Boolean) دریافت می کنید که True به معنای صحت پیام و False به معنای عدم صحت پیام است. البته موارد دیگری نیز جهت اطمینان از صحت پیام وجود دارد که با بررسی بیشتر نوع درخواست ارسالی توسط سرویس دهنده معرکه قابل پیاده سازی توسط برنامه نویس می باشد.

آدرس سرویس وب

با مراجعه به آدرس panel.mareke.ir/webservice شرح مختصری در مورد عملیات پشتیبانی شده توسط سرویس وب پیام کوتاه معرکه و نوع پارامترهای ورودی و خروجی آنها مشاهده می کنید.

آدرس WSDL سرویس وب پیام کوتاه معرکه: http://panel.mareke.ir/webservice/?WSDL

عملیاتها و پارامترها

متد send
جهت ارسال یک پیام کوتاه از این متد استفاده می شود. در جدول زیر پارامترهای ورودی این متد آورده شده است. مقدار بازگشتی این متد “کد پیگیری پیام کوتاه” می باشد که از نوع عدد صحیح و بزرگتر مساوی ١٠٠٠ است. در صورت بروز هر گونه خطایی یک Fault بازگشت داده می شود که در بخش تعاریف به توضیح آن پرداختیم.

ورودی

نام پارامترنوع پارامتراجباری/اختیاریتوضیح
toStringاجباریشماره گیرنده پیام کوتاه (مثال ٠٩١٢١١١١١١١)
msgStringاجباریمتن پیام کوتاه (رشته کاراکتری با طول حداکثر ١٦٠ کاراکتر برای حروف لاتین و حداکثر ٧٠ کاراکتر برای حروف فارسی)
fromStringاختیاریشماره فرستنده پیام کوتاه (در صورت خالی گذاشتن این پارامتر پیام کوتاه از شماره پیش فرض حساب ارسال می شود)
timeIntاختیاریزمان بر حسب Unix Timestamp به وقت تهران (در صورتی که بخواهید پیام کوتاه در آینده ارسال شود. در صورت خالی گذاشتن این پارامتر زمان جاری در نظر گرفته می‌شود.)

خروچی

نام پارامترتوضیح
Intکد پیگیری وضعیت تحویل پیام کوتاه

متد sendToMany
جهت ارسال یک پیام کوتاه به چندین مخاطب از این متد استفاده می شود. در جدول زیر پارامترهای ورودی این متد آورده شده است. مقدار بازگشتی این متد آرایه‌ای است که کلید هر عنصر آن «شماره موبایل مخاطب» و مقدار آن کلید، “کد پیگیری پیام کوتاه” می باشد که از نوع عدد صحیح و بزرگتر مساوی ١٠٠٠ است. در صورت بروز خطا در حین ارسال به هر مخاطب، کد خطا بعنوان مقدار کلید برای همان شماره بازگشت داده می‌شود و در صورت بروز خطاهای کلی‌تر یک Fault بازگشت داده می شود که در بخش تعاریف به توضیح آن پرداختیم. بنابراین برنامه‌نویس محترم می‌بایست پس از دریافت پاسخ این متد، آرایه را پیمونده و مقدار هر کلید(شماره موبایل) را از نظر بروز خطا بررسی کند. مجددا تاکید می‌کنیم خطا در ارسال به یک مخاطب فقط برای همان مخاطب گزارش می‌شود و سایر شماره‌ها پردازش خواهند شد.

ورودی

نام پارامترنوع پارامتراجباری/اختیاریتوضیح
toArray of Stringاجباریآرایه‌ای از رشته کاراکتر که هر عنصر حاوی شماره موبایل با فرمت ٠٩١٢١١١١١١١ می‌باشد
msgStringاجباریمتن پیام کوتاه (رشته کاراکتری با طول حداکثر ١٦٠ کاراکتر برای حروف لاتین و حداکثر ٧٠ کاراکتر برای حروف فارسی)
fromStringاختیاریشماره فرستنده پیام کوتاه (در صورت خالی گذاشتن این پارامتر پیام کوتاه از شماره پیش فرض حساب ارسال می شود)
timeIntاختیاریزمان بر حسب Unix Timestamp به وقت تهران (در صورتی که بخواهید پیام کوتاه در آینده ارسال شود. در صورت خالی گذاشتن این پارامتر زمان جاری در نظر گرفته می‌شود.)

خروجی

نام پارامترتوضیح
Array of Intآرایه‌ای که هر کلید آن شماره موبایل و مقدار کلید کد پیگیری وضعیت تحویل پیام کوتاه است.

متد sendOneToOne
جهت ارسال یک پیام کوتاه به یک مخاطب بصورت نظیر به نظیر از این متد استفاده می شود. در جدول زیر پارامترهای ورودی این متد آورده شده است. مقدار بازگشتی این متد آرایه‌ای است عددی که مقدار هر عنصر آن شامل “کد پیگیری پیام کوتاه” می باشد که از نوع عدد صحیح و بزرگتر مساوی ١٠٠٠ است. در صورت بروز خطا در حین ارسال به هر مخاطب، کد خطابازگشت داده می‌شود و در صورت بروز خطاهای کلی‌تر یک Fault بازگشت داده می شود که در بخش تعاریف به توضیح آن پرداختیم. بنابراین برنامه‌نویس محترم می‌بایست پس از دریافت پاسخ این متد، آرایه را پیمونده و مقدار هر عنصر را از نظر بروز خطا بررسی کند. کلیدهای این آرایه نیز عددی بوده و دقیقا متناظر با ترتیب پارامترهای ارسالی می‌باشد. مجددا تاکید می‌کنیم خطا در ارسال به یک مخاطب فقط برای همان مخاطب گزارش می‌شود و سایر شماره‌ها پردازش خواهند شد. در حال حاضر در هر بار فراخوانی این متد حداکثر ۲۰۰ شماره قابل قبول می‌باشد.

ورودی

نام پارامترنوع پارامتراجباری/اختیاریتوضیح
toArray of Stringاجباریآرایه‌ای از رشته کاراکتر که هر عنصر حاوی شماره موبایل با فرمت ٠٩١٢١١١١١١١ می‌باشد
msgArray of String
اجباریآرایه‌ای از متن پیام کوتاه (رشته کاراکتری با طول حداکثر ١٦٠ کاراکتر برای حروف لاتین و حداکثر ٧٠ کاراکتر برای حروف فارسی)
fromArray of String
اختیاریآرایه‌ای از شماره فرستنده پیام کوتاه (در صورت خالی گذاشتن این پارامتر پیام کوتاه از شماره پیش فرض حساب ارسال می شود)
timeArray of Int
اختیاریآرایه‌ای از زمان بر حسب Unix Timestamp به وقت تهران (در صورتی که بخواهید پیام کوتاه در آینده ارسال شود. در صورت خالی گذاشتن این پارامتر زمان جاری در نظر گرفته می‌شود.)

خروجی

نام پارامترتوضیح
Array of Intآرایه‌ای که متناظرا با ترتیب پارامترهای ارسالی می‌باشد و مقدار هر عنصر کد پیگیری وضعیت تحویل پیام کوتاه است.

متد deliveryStatus
جهت بررسی وضعیت تحویل یک پیام کوتاه از این متد استفاده می شود. تنها ورودی آن “کد پیگیری پیام کوتاه” است. مقدار بازگشتی این متد “کد وضعیت تحویل پیام کوتاه” می باشد که از نوع عدد صحیح بوده و شرح هر یک در جدول ٢ آمده است.

ورودی

نام پارامترنوع پارامتراجباری/اختیاریتوضیح
messageIdentifierIntاجباریکد پیگیری پیام کوتاه

خروجی

نام پارامترتوضیح
Intکد وضعیت تحویل پیام کوتاه

متد verifyReceive
جهت بررسی صحت پیام کوتاه دریافتی از سرویس دهنده هاست ایران از این متد استفاده می شود. تنها ورودی آن “کد امنیتی پیام کوتاه” است که همراه با سایر اطلاعات پیام کوتاه به آدرس اینترنتی انتقال ترافیک شما ارسال می شود. مقدار بازگشتی این متد نوع Boolean می باشد که True به معنای صحت پیام دریافتی و False به معنای عدم صحت پیام دریافتی است.

ورودی

نام پارامترنوع پارامتراجباری/اختیاریتوضیح
securityCodeStringاجباریکد امنیتی پیام کوتاه

خروجی

نام پارامترتوضیح
Booleanمقدار True صحت پیام دریافتی و مقدار False عدم صحت پیام دریافتی است

متد accountInfo
برای دریافت اطلاعات حساب در هاست ایران از این متد استفاده می شود. این متد هیچ ورودی ندارد. خروجی آن یک آبجکت است که شرح خصیصه های (Property) آن در جدول زیر آمده است.

خروجی

نام خصیصهنوع خصیصهتوضیح
numbersArray of Stringآرایه ای از رشته کاراکترها که شماره های اختصاص یافته به حساب است
receiveUrl Stringآدرس انتقال ترافیک جهت ارسال پیام کوتاه های ارسالی به شماره (های) اختصاص یافته
sentIntتعداد کل پیام کوتاه های ارسالی
receivedIntتعداد کل پیام کوتاه های دریافتی
totalIntتعداد اعتبار پیام کوتاه اختصاص یافته
remainingIntتعداد اعتبار باقیمانده

متد changePassword
برای تغییر رمز عبور حساب از این متد استفاده می شود. ورودی آن رمز عبور جدید است و در صورت انجام صحیح عملیات هیچ خروجی تولید نمی شود. در صورت بروز هر گونه خطایی یک Fault بازگشت داده می شود و عملیات انجام نمی پذیرد.

ورودی

نام پارامترنوع پارامتراجباری/اختیاریتوضیح
newPasswordStringاجباریرمزعبور جدید

متد changeTrafficRelay
برای تغییر آدرس اینترنتی انتقال ترافیک از این متد استفاده می شود. ورودی آن URL جدید است که باید بصورت کامل وارد شود نظیر (http://example.com/smsreceiver.php) و در صورت انجام صحیح عملیات هیچ خروجی تولید نمی شود. در صورت بروز هر گونه خطایی یک Fault بازگشت داده می شود و عملیات انجام نمی پذیرد.

ورودی

نام پارامترنوع پارامتراجباری/اختیاریتوضیح
newURLStringاجباریآدرس انتقال ترافیک جدید

جدول ١ – شرح کدهای خطا

کد خطاتوضیح خطا
١نام کاربری یا رمز عبور صحیح نیست
٢اعتبار حساب کافی نیست
٣حساب کاربر فعال نیست
٤شماره گیرنده خالی است
٥شماره گیرنده معتبر نیست
٦شماره فرستنده معتبر نیست
٧هیچ شماره ای به حساب شما اختصاص نیافته است
٨متن پیام خالی است
٩متن پیام طولانی است
١٠خطا در سرویس دهنده
١١خطا در برقراری ارتباط با سوئیچ مخابرات
١٢شناسه پیام نامعتبر است
١٣آدرس انتقال ترافیک معتبر نیست
١٤رمز عبور خالی است
١٥شما حق دسترسی به این ماژول را ندارید
١٦این ماژول در حال حاضر قابل استفاده نیست
١٧این ماژول برای شما غیرفعال شده است
١٨مهلت استفاده از این ماژول خاتمه یافته است
١٩مهلت استفاده از این شماره خاتمه یافته است
٢٠این شماره برای شما غیرفعال شده است
٢١تعداد پارامترها در ارسال نظیر به نظیر یکسان نیست
٢٢تعداد مخاطبین بیش از حد مجاز است

جدول ٢ – شرح کدهای وضعیت تحویل پیام کوتاه

کد خطاتوضیح خطا
٠ارسال شده به مخابرات
١رسیده به گوشی
٢نرسیده به گوشی
٤در صف ارسال
٨رسیده به مخابرات
١٦نرسیده به مخابرات
٣٢بلک لیست

نمونه کدها

در صورتی که از php٥ استفاده می کنید به راحتی با فعالسازی افزودنی (Extension) به نام SOAP و استفاده از کلاس SoapClient سرویس وب پیام کوتاه معرکه را مصرف کنید.
نحوه ارسال یک پیام کوتاه، بررسی وضعیت تحویل پیام کوتاه و مشاهده اطلاعات حساب:

$options = array(
‘login’ => ‘yourusername’,
‘password’ => ‘yourpassword’
);
$client = new SoapClient(‘http://panel.mareke.ir/webservice/?WSDL’, $options);
try
{
$messageId = $client->send(‘٠٩١٢١١١١١١١’, ‘تست پیام کوتاه!’);
sleep(٣);
print ($client->deliveryStatus($messageId));
var_dump($client->accountInfo());
}
catch (SoapFault $sf)
{
print $sf->faultcode.”\n”;
print $sf->faultstring.”\n”;
}