khatibi/0098sms.md

راهنمای استفاده از لینک ارتباطی و وب‌سرویس سامانه پیامک (0098vip.com و 0098sms.com)

فهرست مطالب

• مقدمات اتصال (صفحه ۳)
• راهنمای استفاده از لینک ارتباطی (صفحه ۴)
• کدهای خطای لینک ارتباطی (صفحه ۵)
• راهنمای استفاده از وب‌سرویس (صفحه ۶)
• کدهای خطای وب‌سرویس (صفحه ۸)
• نمونه کدها:
  • نمونه کدهای ASP (صفحه ۹)
  • نمونه کدهای PHP (صفحه ۱۱)
  • نمونه کد Python (صفحه ۱۴)

مقدمات اتصال

جهت فعال‌سازی سرویس ابتدا وارد حساب کاربری خود در سامانه 0098vip شوید و از منوی سمت راست گزینه «لینک ارتباطی - وب سرویس (otp)» را انتخاب نمایید:

1. مرحله اول (ورود به بخش مربوطه): از منوی سمت راست پنل، بر روی گزینه «لینک ارتباطی - وب سرویس (otp)» کلیک کنید.
2. مرحله دوم (انتخاب شماره و فعال‌سازی): شماره اختصاصی پنل خود را در بخش فعال‌سازی انتخاب کرده و دکمه «فعال‌سازی» را بزنید.
3. مرحله سوم (انتخاب رمز وب‌سرویس): در پایین صفحه و در بخش «انتخاب رمز برای لینک ارتباطی - وب سرویس»، رمز اصلی ورود به پنل را وارد نموده و بر روی «ایجاد رمز وب سرویس» کلیک کنید. سامانه رمزی اختصاصی جهت اتصال به API و وب‌سرویس تولید می‌کند.

نکته امنیتی: پیشنهاد می‌شود از منوی تنظیمات، در بخش «IP های امن»، آدرس آی‌پی سرور خود را درج فرمایید تا ارسال پیامک منحصراً از سمت سرور شما مجاز باشد.

راهنمای استفاده از لینک ارتباطی (URL GET)

آدرس پایه جهت فراخوانی لینک ارسال پیامک به شرح زیر است:

Plaintext
https://0098vip.com/sendsmslink.aspx?FROM=$FROM&TO=$TO&TEXT=$TEXT&USERNAME=$USERNAME&PASSWORD=$PASSWORD&DOMAIN=$DOMAIN

پارامترهای متغیر در لینک:

• FROM: شماره اختصاصی فرستنده متصل به لینک
• TO: شماره مقصد (گیرنده پیامک)
• TEXT: متن ارسالی پیامک
• USERNAME: نام کاربری ورود به پنل
• PASSWORD: رمز عبور اتصال
• DOMAIN: عبارت 0098

جدول کدهای خطای لینک ارتباطی

کد خطا	شرح خطا
۰	عملیات با موفقیت به پایان رسید.
۱	شماره گیرنده اشتباه است.
۲	گیرنده تعریف نشده است.
۳	فرستنده تعریف نشده است.
۴	متن تنظیم نشده است.
۵	نام کاربری تنظیم نشده است.
۶	کلمه عبور تنظیم نشده است.
۷	نام دامین تنظیم نشده است.
۸	مجوز شما باطل شده است.
۹	اعتبار پیامک شما کافی نیست.
۱۰	برای این شماره لینک تعریف نشده است.
۱۱	عدم مجوز برای اتصال لینک.
۱۲	نام کاربری و کلمه عبور اشتباه است.
۱۳	کاراکتر غیر مجاز در متن وجود دارد.
۱۴	سقف ارسال روزانه پر شده است.
۱۶	عدم مجوز شماره برای ارسال از لینک.
۱۷	خطا در شماره پنل، لطفاً با پشتیبانی تماس بگیرید.
۱۸	اتمام تاریخ اعتبار شماره پنل؛ برای استفاده تمدید شود.
۱۹	تنظیمات کد opt انجام نشده است.
۲۰	فرمت کد opt صحیح نیست.
۲۱	تنظیمات کد opt توسط ادمین تایید نشده است.
۲۲	اطلاعات مالک شماره ثبت و تایید نشده است.
۲۳	هنوز اجازه ارسال به این شماره پنل داده نشده است.
۲۴	ارسال از IP غیر مجاز انجام شده است.

راهنمای استفاده از Web Service

آدرس وب‌سرویس سامانه:

Plaintext
https://webservice.0098vip.com/service.asmx

نکته: پس از افزودن ماژول وب‌سرویس، توصیه می‌شود Namespace اولیه را تغییر داده و نامی بدون نقطه (.) تنظیم کنید.
توابع وب‌سرویس:

1. SendSMS: ارسال پیامک تکی به‌صورت آنی.
2. SendSMSWithTime: ارسال پیامک تکی زمان‌بندی‌شده (با قابلیت تعیین تاریخ و زمان).
3. SendSMSWithID: ارسال پیامک تکی همراه با بازگرداندن شناسه پیامک (smsid) جهت رهگیری وضعیت.
4. smsdeliveryState: استعلام وضعیت دلیوری پیامک ارسالی با استفاده از شناسه پیامک.
5. RemainSms: دریافت مانده موجودی پیامک‌های پنل.

پارامترهای ورودی توابع وب‌سرویس

نام پارامتر	نوع داده	توضیح
Username	String	نام کاربری پنل
password	String	پسورد پنل
text	String	متن پیامک
MobileNo	String	شماره موبایل گیرنده
PnlNo (PniNo)	String	شماره اختصاصی پنل در سامانه
Timestmp	String	تاریخ و زمان ارسال در قالب Timestamp (۱۰ رقمی)
smsid	String	شناسه پیامک (عدد حداقل ۹ رقمی در فرمت string)

جدول کدهای خطای وب‌سرویس و وضعیت‌های دلیوری

کد برگشتی	توضیحات
۰	ارسال با موفقیت انجام شد.
۲ (یا عدد ۹+ رقمی)	ارسال با موفقیت انجام شد (خروجی تابع دریافت شناسه/دلیوری).
۴	مخاطب دریافت پیام‌های تبلیغاتی خود را بسته است (بلک‌لیست).
۵	رسیده به گوشی.
۶	نرسیده به گوشی.
۷	وضعیت دریافت پیامک منقضی شده است.
۸	وضعیت پیامک نامشخص است.
۹	اطلاعات مالک شماره ثبت و تایید نشده است.
۱۰	عدم تطابق نام کاربری و کلمه عبور؛ لطفاً با پشتیبانی تماس بگیرید.
۱۲	هنوز اجازه ارسال به این شماره پنل داده نشده است.
۱۳	ارسال از IP غیر مجاز انجام شده است.
۱۷	نام کاربری یا کلمه عبور اشتباه است؛ لطفاً با پشتیبانی تماس بگیرید.
۱۸	کاراکتر غیر مجاز در متن وجود دارد.
۱۹	متن پیامک خالی است.
-۲۲	خطای شارژ؛ لطفاً با پشتیبانی تماس بگیرید.
-23	حساب کاربری شما مسدود است؛ لطفاً با پشتیبانی تماس بگیرید.
-24	مرحله دوم ثبت‌نام شما انجام نگرفته است؛ لطفاً ثبت‌نام را کامل نمایید.
-25	عدم مجوز شماره برای ارسال از لینک.
-26	خطا در شماره پنل؛ لطفاً با پشتیبانی تماس بگیرید.
-27	اتمام تاریخ اعتبار شماره پنل؛ برای استفاده تمدید شود.
-28	تنظیمات کد opt انجام نشده است.
-29	فرمت کد opt صحیح نیست.
-31	smsid یافت نشد.
-32	smsid مطابقت ندارد.
۶۶	شارژ پنل شما برای ارسال کافی نیست؛ لطفاً اقدام به شارژ نمایید.
۱۱۱۱	شماره موبایل صحیح نیست.
Hang	عدم تطابق نام کاربری و کلمه عبور؛ لطفاً با پشتیبانی تماس بگیرید.
No Doc	کاراکتر غیر مجاز در متن وجود دارد.
Wrong timestamp	تایم‌استمپ ارسال‌شده صحیح نیست.
Wrong time	زمان در بازه صحیح نیست (تنظیم ارسال از همان روز تا ۱ سال بعد مجاز است).

نمونه کدهای پیاده‌سازی

۱. نمونه کدهای C# / ASP.NET

ارسال پیامک ساده (SendSMS):

C#
ServiceReference1.ServiceSoapClient ss = new ServiceReference1.ServiceSoapClient();
string username = "username";
string password = "password";
string smstext = "smstext";
string mobileno = "091XXXXXXXX";
string panelno = "3000XXXX";
string responsecode = ss.SendSMS(username, password, smstext, mobileno, panelno);

ارسال پیامک زمان‌دار (SendSMSWithTime):

C#
ServiceReference1.ServiceSoapClient ss = new ServiceReference1.ServiceSoapClient();
string username = "username";
string password = "password";
string smstext = "smstext";
string mobileno = "091XXXXXXXX";
string panelno = "3000XXXX";
string timestamp = "1658939130";
string responsecode = ss.SendSMSwithtime(username, password, smstext, mobileno, panelno, timestamp);

ارسال پیامک با دریافت شناسه (SendSMSWithID):

C#
ServiceReference1.ServiceSoapClient ss = new ServiceReference1.ServiceSoapClient();
string username = "username";
string password = "password";
string smstext = "smstext";
string mobileno = "091XXXXXXXX";
string panelno = "3000XXXX";
string responsecode = ss.SendSMSWithID(username, password, smstext, mobileno, panelno);

استعلام دلیوری (smsdeliveryState):

C#
ServiceReference1.ServiceSoapClient ss = new ServiceReference1.ServiceSoapClient();
string username = "username";
string password = "password";
string smsid = "XXXXXXXXXX";
string deliverystate = ss.smsdeliveryState(username, password, smsid);

استعلام مانده اعتبار (RemainSms):

C#
ServiceReference1.ServiceSoapClient ss = new ServiceReference1.ServiceSoapClient();
string username = "username";
string password = "password";
string remain = ss.RemainSms(username, password);

۲. نمونه کدهای PHP

ارسال ساده (SendSMS):

PHP
<?php
// Enable extension=php_soap.dll
ini_set("soap.wsdl_cache_enabled", "0");
$sms_client = new SoapClient('https://webservice.0098vip.com/service.asmx?wsdl', array('encoding'=>'UTF-8'));

$parameters['username'] = "username";
$parameters['password'] = "password";
$parameters['mobileno'] = "0912XXXXXXXX";
$parameters['pnlno'] = "3000XXXX";
$parameters['text'] = "test";
$parameters['isflash'] = false;

echo $sms_client->SendSMS($parameters)->SendSMSResult;
?>

ارسال زمان‌دار (SendSMSWithTime):

PHP
<?php
ini_set("soap.wsdl_cache_enabled", "0");
$sms_client = new SoapClient('https://webservice.0098vip.com/service.asmx?wsdl', array('encoding'=>'UTF-8'));

$parameters['username'] = "username";
$parameters['password'] = "password";
$parameters['mobileno'] = "0912XXXXXXXX";
$parameters['pnlno'] = "3000XXXX";
$parameters['text'] = "test";
$parameters['timestamp'] = "1658939130";
$parameters['isflash'] = false;

echo $sms_client->SendSMSwithtime($parameters)->SendSMSWithTimeResult;
?>

ارسال با دریافت شناسه (SendSMSWithID):

PHP
<?php
ini_set("soap.wsdl_cache_enabled", "0");
$sms_client = new SoapClient('https://webservice.0098vip.com/service.asmx?wsdl', array('encoding'=>'UTF-8'));

$parameters['username'] = "username";
$parameters['password'] = "password";
$parameters['mobileno'] = "0912XXXXXXXX";
$parameters['pnlno'] = "3000XXXX";
$parameters['text'] = "test";
$parameters['isflash'] = false;

echo $sms_client->SendSMSWithID($parameters)->SendSMSWithIDResult;
?>

استعلام دلیوری (smsdeliveryState):

PHP
<?php
ini_set("soap.wsdl_cache_enabled", "0");
$sms_client = new SoapClient('https://webservice.0098vip.com/service.asmx?wsdl', array('encoding'=>'UTF-8'));

$parameters['username'] = "username";
$parameters['password'] = "password";
$parameters['smsid'] = "XXXXXXXXXX";
$parameters['isflash'] = false;

echo $sms_client->smsdeliveryState($parameters)->smsdeliveryStateResult;
?>

استعلام مانده اعتبار (RemainSms):

PHP
<?php
ini_set("soap.wsdl_cache_enabled", "0");
$sms_client = new SoapClient('https://webservice.0098vip.com/service.asmx?wsdl', array('encoding'=>'UTF-8'));

$parameters['username'] = "username";
$parameters['password'] = "password";
$parameters['isflash'] = false;

echo $sms_client->RemainSms($parameters)->remainResult;
?>

۳. نمونه کد Python

ارسال ساده با کتابخانه Zeep:

Python
from zeep import Client

client = Client('https://webservice.0098vip.com/service.asmx?WSDL')

parameters = {
'username': 'your_username',
'password': 'your_password',
'mobileno': '0912XXXXXXX',
'panelno': '3000XXXXXXX',
'text': 'test',
'isflash': False
}

response = client.service.SendSMS(parameters)
print("SendSMSResult:", response)

منابع
1. https://github.com/c123ir/ai-123-flutter
2. https://github.com/c123ir/ai-123-flutter
3. https://github.com/c123ir/ai-123-flutter