وب سرویس سامانه پیام کوتاه

این راهنما جهت سهولت در کار برنامه نویسانی طراحی شده است که قصد دارند سرویس پیامهای خود را به نرم افزار های کاربردی خود ارتباط دهند.
این شرکت در حال حاضر وب سرویس ارسال پیام کوتاه و وب سرویس ارسال پیام صوتی ارئه میکند
روش های ارائه شده برای ارسال پیام کوتاه به شرح زیرمیباشد
1- وب سرویس REST
2- وب سرویس SOAP
3- ارسال از طریق URL
که از بین روش های ذکر شده این شرکت روش وب سرویس REST را پیشنهاد میدهد
روش های ارائه شده برای ارسال پیام صوتی به شرح زیرمیباشد
1- وب سرویس REST

برخی ارور ها

برخی از ارور هایی که در وب سرویس ها داده میشود به شرح زیر میباشد

کد خطا توضیح
error_login_user_not_found چنین کاربری یافت نشد
error_login_not_like_username نام کاربری مشکلی دارد مانند وجود فاصله
error_login_not_like_password پسورد مشکلی دارد
error_login_not_like_accept دسترسی شما مسدود شده است و یا کد تایید پیامکی را وارد نکرده اید
error_register_taken_email چنین ایمیلی قبلا استفاده شده است
error_register_taken_user_username نام کاربری قبلا اسفتاده شده است
error_register_taken_user_mobile موبایل قبلا استفاده شده است
error_no_receiver گیرنده های خالی میباشد
error_sender_number_is_not_allow شماره ی ارسال کننده مجاز نمیباشد
error_long_request_uniqueid طول کد یکتا بیشتر از جد مجاز است
error_sender_number_is_disable شماره ی ارسال کننده غیرفعال میباشد
error_number_format_error فرمت شماره ی گیرنده مشکل دارد
error_number_whois_error شماره ی ارسال کننده اجراز هویت نشده است
error_sms_receiver_number_limit تعداد گیرنده ها بیشتر از حد مجاز میباشد
error_sms_send_config_is_disable ارسال از این پیش شماره موقتا غیر فعال میباشد
error_sms_price_not_found_for_admin هزینه ی اراسال پیامک مدیر مشخص نمیباشد
error_sms_price_packageid_not_found_for_admin پکیج قیمت مدیر یافت نشد
error_sms_price_not_found_for_user هزینه ی اراسال پیامک برای کاربر مشخص نمیباشد
error_credit_admin_error شارژ مدیر کم است
error_credit_admin_empty_error هزینه ی ارسال برای مدیر اشتباه محاسبه شده است
error_credit_error کمبود شارژ کاربر
درگاه ها

مقادیر ذکر شده در جدول برای تمامی متدهایی که پارامتر dargahha یا dargah دارند قابل استفاده میباش

مقداری که باید استفاده شود اپراتور مورد نظر
5700 50002 راهکار سرزمین هوشمند
50002 50002 راهکار سرزمین هوشمند
50001 50001 رهیاب پیام گستران
50004 50004 ارمغان راه طلایی
1000 1000 رهیاب
2000 2000 آتیه
3000 3000 مگفا
9821 9821 آسانک
118 اپراتور مسیر عمومی
وضعیت پیامک ها

وضعیت پیامک ها در سیستم به شرح زیر میباشد

عدد معنا
-1 پیام یافت نشد - ممکن است پیام به آرشیو منتقل شده باشد
0 بدون وضعیت - ممکن است پیام تازه ارسال شده باشد و در انتظار دریافت وضعیت باشد
1 رسیده به گوشی
2 نرسیده به گوشی
3 ارسال نشده به مخابرات
4 ارسال شده به مخابرات - ممکن است پیام ها پس از مدت زمانی برای ارسال به آرشیو به این وضعیت تبدیل شوند
5 لیست سیاه مخابرات - ممکن است به معنای بازگشت وجه نیز باشد
8 ارسال شده به مخابرات
انتقال پیامک های دریافتی به آدرس

با استفاده از این سرویس پیامک دریافتی شما بلافاصله پس از دریافت به آدرسی که در تنظیمات مشخص کرده اید به صورت POST ارسال میشود.

تذکر تمامی پارامتر هایی که خود شما در آدرس قرار میدهید به صورت GET برای شما ارسال میشوند و فقط پارامتر های زیر که غیر قابل تغییر هستند به صورت POST ارسال میشوند!

نام پارامتر توضیح
from شماره ی ارسال کننده ی پیامک مثلا 09132677411
to شماره ی دریافت کننده ی پیامک مثلا 500021
note متن پیامک مثال این یک تست است
smsid شناسه ی پیامک مثلا 1234567
فرمت تاریخ

تمامی تاریخ ها بر اساس unix timestamp میباشد

ای تاریخ شامل یک عدد میباشد که از تاریخ January 1st, 1970 at UTC شروع شده است

Example: 1493532518 (ISO 8601: 2017-04-30T06:08:38Z)

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

برای اطلاعات بیشتر بر روی این نوشته کلیک نمایید

مفاهیم کلی ارسال پیامک از طریق SOAP

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

SOAP مخفف Simple Object Access Protocol است. SOAP یک پادمان مبتنی بر XML است، برای رد و بدل کردن اطلاعات بین برنامه ها. اطلاعات در SOAP به صورت پیام (Message) و از طریق پادمان‏های موجود در اینترنت مانند HTTP منتقل می‏شود (SOAP در سایر پادمان ها، مانند SMTP یا MIME نیز قابل استفاده است). به زبان ساده‏تر، SOAP یک پادمان است برای دستیابی به یک سرویس ارایه شده در وب (Web Service). آخرین نسخه SOAP، نسخه 1.2 می‏باشد

آدرس وب سرویس SOAP

http://textsms.ir/webservice/soap/smsService.php?wsdl

آدرس راهنما شامل نام متد ها و پارامتر های ورودی و مقادیر خروجی به شرح زیر میباشد :
http://textsms.ir/webservice/soap/smsService.php

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

از این متد برای گرفتن لیست پیام های دریافتی استفاده می شود.

نام متد:

sms_receive

پارامتر نوع توضیحات مقادیر
username String نام کاربری مورد استفاده در سامانه پیامک
password String

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

number String شماره خط اختصاصی کاربر مورد استفاده در سامانه
catid int شناسه دسته بندی پیامک های دریافتی
start int شناسه شروع لیست پیامک ها از 1 شروع میشود
perpage int تعداد پیامک های دریافتی در هر صفحه 30=پیش فرض
read int نوع خواندن '-1'=مهم نیست
'0' =خوانده نشده
'1'=خوانده شده
order string نوع مرتب سازی 'ASC' = از اول به آخر
'DESC' = از آخر به اول
ارسال پیامک

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

نام متد:

send_sms

پارامتر نوع توضیحات مقادیر
username String نام کاربری مورد استفاده در سامانه پیامک
password String رمز عبور مورد استفاده در سامانه پیامک
sender_number ArrayOfString شماره ارسال کننده در سامانه پیامک
receiver_number ArrayOfString شماره دریافت کننده پیامک
note ArrayOfString متن پیامک ارسالی
date ArrayOfString تاریخ ارسال پیامک ( ارسال در آینده ) - این متغیر به صورت آرایه ارسال میشود و میتواند شامل یک یا بیش از یک تاریخ باشد 0=هم اکنون ارسال شود
request_uniqueid ArrayOfString جهت جلوگیری از ارسال پیامک تکراری از منبع کد , میتوانید این متغیر را با یک عدد یا متن منحصر به فرد مقداردهی کنید . در صورت ارسال درخواست تکراری در پاسخ این متد smsid های قبلی ارسال خواهند شد 0=نیازی به چک کردن ندارد
flash ArrayOfString آیا پیامک به صورت فلش ارسال شود یا خیر ok , no
onlysend String جهت ارسال سریع بدون وقفه در زمان ارسال پیامک ( ارسال پیامک با تاخیر 30 ثانیه به مشترک انجام خواهد شد) ok , no ( ok == ارسال با تاخیر )
مفاهیم کلی ارسال پیامک از طریق REST

REST بهترین روش برای وب سرویس ها میباشد و در تمامی زبان های برنامه نویسی قابلیت پیاده سازی دارد

در این روش خروجی بر اساس JSON میباشد ( توضیحات بیشتر در مورد JSON)

در این روش شما میتوانید با یکی از متد های POST یا GET اطلاعات را برای وب سرویس ارسال نمایید

آدرس وب سرویس رست به صورت زیر میباشد :

http://textsms.ir/webservice/rest/

در تمامی فانکشن ها میتوانید به جای login_username و login_password از api_key استفاده نمایید

api_key را از قسمت تنظیمات در پنل کاربری میتوانید بدست آورید

api_key برای همیشه ثابت است و فقط برای وب سرویس REST استفاده میشود

مثال :

برای پاسخ تمامی متد ها result با ۲ مقدار true و false وجود دارند که مقدار false نشانه ی ناموفق بودن عملیات است

به طور مثال وقتی نام کاربری و رمز عبور اشتباه باشد چنین خطایی دریافت خواهید کرد

{"result":false,"error":"error_login_user_not_found"}

دریافت اطلاعات کاربری

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

نام متد:

user_info

آدرس مورد استفاده :

http://textsms.ir/webservice/rest/user_info?

پارامتر نوع توضیحات مقادیر
login_username String نام کاربری مورد استفاده در سامانه پیامک
login_password String رمز عبور مورد استفاده در سامانه پیامک

مثال :

نمونه پاسخ : مقدار result برابر true میباشد که نشاندهنده ی موفق بودن عملیات است