راه اندازی وب سرویس و API

  • تاریخ ثبت : یکشنبه,۱۳۹۲/۰۶/۲۴
  • تاریخ ویرایش : پنجشنبه,۱۴۰۰/۰۹/۱۸
  • تعداد بازدید : ۴۱۹۳
  • دسته : پنل پیام کوتاه

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

مقدمه

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

نحوه عضویت

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

تعاریف

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

آدرس سرویس وب

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

آدرس WSDL سرویس وب پیام کوتاه سامانه گستر آکو: http://sms.ako.ir/webservice/?WSDL

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

  • متد send
  • جهت ارسال یک پیام کوتاه از این متد استفاده می شود. در جدول زیر پارامترهای ورودی این متد آورده شده است. مقدار بازگشتی این متد "کد پیگیری پیام کوتاه" می باشد که از نوع عدد صحیح و بزرگتر مساوی 1000 است. در صورت بروز هر گونه خطایی یک Fault بازگشت داده می شود که در بخش تعاریف به توضیح آن پرداختیم.
    ورودی
    نام پارامترنوع پارامتراجباری/اختیاریتوضیح
    toStringاجباریشماره گیرنده پیام کوتاه (مثال 09391339399)
    msgStringاجباریمتن پیام کوتاه (رشته کاراکتری با طول حداکثر 160 کاراکتر برای حروف لاتین و حداکثر 70 کاراکتر برای حروف فارسی)
    fromStringاختیاریشماره فرستنده پیام کوتاه (در صورت خالی گذاشتن این پارامتر پیام کوتاه از شماره پیش فرض حساب ارسال می شود)
    timeIntاختیاریزمان بر حسب Unix Timestamp به وقت UTC (در صورتی که بخواهید پیام کوتاه در آینده ارسال شود)
    خروجی
    نوع پارامترتوضیح
    Intکد پیگیری وضعیت تحویل پیام کوتاه
  • متد deliveryStatus
  • جهت بررسی وضعیت تحویل یک پیام کوتاه از این متد استفاده می شود. تنها ورودی آن "کد پیگیری پیام کوتاه" است. مقدار بازگشتی این متد "کد وضعیت تحویل پیام کوتاه" می باشد که از نوع عدد صحیح  بوده  و شرح هر یک در جدول 2 آمده است.
    ورودی
    نام پارامترنوع پارامتراجباری/اختیاریتوضیح
    messageIdentifierIntاجباریکد پیگیری پیام کوتاه
    خروجی
    نوع پارامترتوضیح
    Intکد وضعیت تحویل پیام کوتاه
  • متد verifyReceive
  • جهت بررسی صحت پیام کوتاه دریافتی از سرویس دهنده سامانه گستر آکو از این متد استفاده می شود. تنها ورودی آن "کد امنیتی پیام کوتاه" است که همراه با سایر اطلاعات پیام کوتاه به آدرس اینترنتی انتقال ترافیک شما ارسال می شود. مقدار بازگشتی این متد نوع Boolean می باشد که True به معنای صحت پیام دریافتی و False به معنای عدم صحت پیام دریافتی است.
    ورودی
    نام پارامترنوع پارامتراجباری/اختیاریتوضیح
    securityCodeStringاجباریکد امنیتی پیام کوتاه
    خروجی
    نوع پارامترتوضیح
    Booleanمقدار True صحت پیام دریافتی و مقدار False عدم صحت پیام دریافتی است
  • متد accountInfo
  • برای دریافت اطلاعات حساب در سامانه گستر آکو از این متد استفاده می شود. این متد هیچ ورودی ندارد. خروجی آن یک آبجکت است که شرح خصیصه های (Property) آن در جدول زیر آمده است.
    خروجی
    نام خصیصهنوع خصیصهتوضیح
    numbersArray of Stringآرایه ای از رشته کاراکترها که شماره های اختصاص یافته به حساب است
    receiveUrlStringآدرس انتقال ترافیک جهت ارسال پیام کوتاه های ارسالی به شماره (های) اختصاص یافته
    sentIntتعداد کل پیام کوتاه های ارسالی
    receivedIntتعداد کل پیام کوتاه های دریافتی
    totalIntتعداد اعتبار پیام کوتاه اختصاص یافته
    remainingIntتعداد اعتبار باقیمانده
  • متد changePassword
  • برای تغییر رمز عبور حساب از این متد استفاده می شود. ورودی آن رمز عبور جدید است و در صورت انجام صحیح عملیات هیچ خروجی تولید نمی شود. در صورت بروز هر گونه خطایی یک Fault بازگشت داده می شود و عملیات انجام نمی پذیرد.
    ورودی
    نام پارامترنوع پارامتراجباری/اختیاریتوضیح
    newPasswordStringاجباریرمزعبور جدید
  • متد changeTrafficRelay
  • برای تغییر آدرس اینترنتی انتقال ترافیک از این متد استفاده می شود. ورودی آن URL جدید است که باید بصورت کامل وارد شود نظیر (http://ako.ir/smsreceiver.php) و در صورت انجام صحیح عملیات هیچ خروجی تولید نمی شود. در صورت بروز هر گونه خطایی یک Fault بازگشت داده می شود و عملیات انجام نمی پذیرد.
    ورودی
    نام پارامترنوع پارامتراجباری/اختیاریتوضیح
    newURLStringاجباریآدرس انتقال ترافیک جدید

جدول 1 - شرح کدهای خطا

کد خطاتوضیح خطا
1نام کاربری یا رمز عبور صحیح نیست
2اعتبار حساب کافی نیست
3حساب کاربر فعال نیست
4شماره گیرنده خالی است
5شماره گیرنده معتبر نیست
6شماره فرستنده معتبر نیست
7هیچ شماره ای به حساب شما اختصاص نیافته است
8متن پیام خالی است
9متن پیام طولانی است
10خطا در سرویس دهنده
11خطا در برقراری ارتباط با سوئیچ مخابرات
12شناسه پیام نامعتبر است
13آدرس انتقال ترافیک معتبر نیست
14رمز عبور خالی است
15شما حق دسترسی به این ماژول را ندارید
16این ماژول در حال حاضر قابل استفاده نیست
17این ماژول برای شما غیرفعال شده است
18مهلت استفاده از این ماژول خاتمه یافته است
19مهلت استفاده از این شماره خاتمه یافته است
20این شماره برای شما غیرفعال شده است

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

کدتوضیح
0ارسال شده به مخابرات
1رسیده به گوشی
2نرسیده به گوشی
4در صف ارسال
8رسیده به مخابرات
16نرسیده به مخابرات

نمونه کدها

در صورتی که از php5 استفاده می کنید میتوانید به راحتی با فعالسازی افزودنی (Extension) به نام SOAP و استفاده از کلاس SoapClient  از  وب سرویس پنل پیام کوتاه سامانه گستر آکو استفاده نمایید.

لیست کل توابع موجود در وب سرویسhttp://sms.ako.ir/webservice/?WSDL

توجه : برای ارسال با شماره های ثابت نظیر 77650782 نیاز به قرار دادن کد منطقه و یا شهر مانند 02177650782 نیست و تنها شماره خود را بدون کد اضافی و غیره وارد نمایید.

نحوه ارسال یک پیام کوتاه، بررسی وضعیت تحویل پیام کوتاه و مشاهده اطلاعات حساب:

= array(
'login' => 'user_name',
'password' => 'user_password'
);
 
= new SoapClient('http://sms.ako.ir/webservice/?WSDL', );
 
try
{
= ->send('09391339399', 'متن دلخواه من ','user_number');
sleep(2);
print (->deliveryStatus());
var_dump(->accountInfo());
}
catch (SoapFault )
{
print ->faultcode." ";
print ->faultstring." ";
}