راهنمای وب‌سرويس (SOAP)

اين سرویس به صورت SOAP پياده‌سازی شده است

آغاز به کار

مقدمه

اين سرويس برای آن دسته از برنامه‌نويسان طراحی شده که می‌خواهند به صورت SOAP به ارسال و دريافت پيامک بپردازند. با توجه به عمر اين سرويس ، پيشنهاد می‌گردد تا از نسخه v2 وب‌سرويس يا REST استفاده نماييد

آغاز کار با سرويس

گام اول: ايجاد حساب کاربری و ورود به سامانه‌ی پیام‌دهی مگفا

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

گام دوم: فعال‌سازی شماره

جهت فعال‌سازی ارسال پیامک، کافی است تا با مراجعه به منوی «مديریت حساب»/«شماره‌ها»، در برگه‌ی «اطلاعات شماره‌ها» مشخصات استفاده‌کننده‌ی نهايی شماره را وارد نمايید. پس از ثبت موفق، این اطلاعات برای بررسی به سامانه‌ی احراز هويت ارسال شده و پس از لحظاتی در صورت درست بودن اطلاعات، وضعیت آن به تاييد شده (تيک سبز) تغيير خواهد یافت.

گام سوم: دريافت رمزعبور (گذر واژه) سرويس.

پس از ورود به سامانه، با مراجعه به منوی «مديریت حساب»/«رمز عبور و امنيت»، می‌توانيد در برگه‌ی «رمز عبور سرويس‌ها» از سامانه رمزی دريافت نمايید که در فراخوانی سرويس قابل استفاده خواهد بود. برای این منظور باید رمز اصلی را که هنگام ورود به سامانه وارد نموده‌اید بار ديگر وارد نماييد تا به صورت خودکار رمز عبور سرويس برای شما توليد شود. پس از توليد در هنگام فراخوانی سرويس، از رمز سرويس توليد شده استفاده نماييد.

گام چهارم: معرفی آی‌پی‌های معتبر

افزون بر فراخوانی سرويس به صورت HTTPS، در صورت نياز با مراجعه به منوی «مديریت حساب»/«رمز عبور و امنيت»، می‌توانيد در برگه‌ی «آی‌پی‌های معتبر» اقدام به فعال‌سازی بررسی و همچنین ثبت آی‌پی(های) مبدا نماييد. بدیهی است با فعال‌سازی این بخش درخواست‌هایی با مبدا غير از آی‌پی‌های معرفی‌شده با پیغام خطا مواجه شده و سامانه از پاسخ‌گویی به این درخواست‌ها خودداری می‌نمايد.

احراز هويت

احراز هويت اين سرويس بر اساس ارسال نام‌کاربری، رمز عبور سرويس در سرایند HTTP با کليد Authorization و به صورت HTTP Basic Authentication است.

به‌کارگیری WSDL در زبان‌های برنامه‌نويسی

در هر یک از زبان‌های برنامه‌نويسی برای به‌کارگیری فایل WSDL روشی وجود دارد. برخی نياز به import و ساخت proxy objectها پيش از آغاز به کار دارند مانند Java و Net. و بعضی ديگر این کار را در زمان اجرا انجام می‌دهند. بنابراین برای دو محیط Java و Net. توضيحات مربوط به نحوه‌ی به کارگيری در زير ارايه می‌گردد.

مراحل به کارگيری در Java

جاوای 1.6 و بالاتر شامل JAX-WS API (Java API for XML Web Services) برای ايجاد web service client است. ساده‌ترين روش برای کار با وب‌سرويس استفاده از کلاس‌های proxy است، بنابراين نيازی به پردازش مستقيم XMLهای SOAP نخواهد بود.

  1. با ابزار wsimport (در مسير JDK_PATH/bin) به صورت زير، می‌توان کلاس‌های proxy را ايجاد نمود.

wsimport -Xnocompile -p com.example.magfasoap -d DestDir -extension http://wsdl_url

اين ابزار، کلاس‌های proxy را در مسير DestDir می‌سازد

در صورت خطای SOAP Encoding می‌توانيد از ابزار Apache Axis 1.4 به صورت زير استفاده نماييد:

  • دريافت Apache Axis 1.4 (axis-bin-1_4)
  • باز کردن Apache Axis 1.4
  • تغيیر مسیر به پوشه‌ی axis-1_4
  • اجرای WSDL2Java

linux

java -cp 'lib/axis.jar:lib/commons-logging-1.0.4.jar:lib/commons-discovery-0.2.jar:lib/jaxrpc.jar:lib/wsdl4j-1.5.1.jar' org.apache.axis.wsdl.WSDL2Java -pcom.example.magfasoap -T1.1 -oDestDir http://wsdl_url

windows

java -cp 'lib/axis.jar;lib/commons-logging-1.0.4.jar;lib/commons-discovery-0.2.jar;lib/jaxrpc.jar;lib/wsdl4j-1.5.1.jar' org.apache.axis.wsdl.WSDL2Java -pcom.example.magfasoap -T1.1 -oDestDir http://wsdl_url

  1. اکنون می‌توانید از سرويس SOAP استفاده نماييد

مراحل به کارگيری در MS Visual Studio

لطفا مراحل زير را برای افزودن Web reference دنبال نماييد:

  1. در صورتی که از Visual Studio 2010 یا قبل‌تر استفاده می‌کنيد، در منوی Project گزينه‌ی «Add Web Reference» را انتخاب نماييد. برای نسخه‌‌های جدید‌تر Visual Studio در منوی Project گزينه‌ی «Add Service Reference»، سپس «Advanced» و آنگاه «Add Web Reference» را انتخاب نماييد. شايان ذکر است دسترسی به اين موارد با right-click بر نام پروژه در Solution Explorer نيز مقدور است
  2. در کادر URL، نشانی WSDL را وارد نماييد. مانند: http://wsdl_url
  3. دکمه «Go» را برای دريافت اطلاعات وب‌سرويس بزنيد
  4. نام دلخواه خود را برای سرویس وارد نماييد
  5. دکمه‌ی «Add» را برای افزودن وب‌سرويس بزنيد

URL

URL جهت دريافت فايل WSDL در پایین آمده است

https://sms.magfa.com/services/urn:SOAPSmsQueue?wsdl

https://sms.magfa.com/api/soap/sms/v1/server?wsdl

متدها

متدهای پیاده‌سازی‌شده به شرح زير است:

متدتوضيحات
getCreditدريافت مانده اعتبار حساب
enqueueارسال پيامک به يک یا چند گيرنده (حداکثر يک‌صد (۱۰۰) عدد)
‫‪getMessageIdدريافت شناسه یکتای پيامک متناظر با شناسه کاربر
‫‪getRealMessageStatusesپيگيری وضعيت نهایی پيامک
getMessagesدریافت پیامک‌های ورودی (حداکثر يک‌صد (۱۰۰) عدد)
getAllMessagesدریافت پیامک‌های ورودی (حداکثر يک‌صد (۱۰۰) عدد)
getMessagesWithNumberدریافت پیامک‌های ورودی (حداکثر يک‌صد (۱۰۰) عدد) مربوط به يک شماره ۳۰۰۰
getAllMessagesWithNumberدریافت پیامک‌های ورودی (حداکثر يک‌صد (۱۰۰) عدد) مربوط به يک شماره ۳۰۰۰

متد getCredit

از اين متد برای دريافت مانده اعتبار حساب استفاده می‌شود.

پارامترها

پارامترهای username و password از روی Header ارسالی خوانده می‌شوند

پارامترنوعاجباری؟توضيحات
domainstringبلهدامنه

خروجی

ميزان مانده اعتبار (double) / کدهای خطا

نمونه‌کد

php
// credentials
$username = 'USERNAME';
$password = 'PASSWORD';
$domain = 'DOMAIN';

// url $url = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl'; // soap options $options = [     'login' => $username,'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'trace' => false // -Optional (debug) ];

// soap client $client = new SoapClient( $url, $options);

// balance $result['balance'] = $client->getCredit($domain);
java
URL url = new URL("https://sms.magfa.com/api/soap/sms/v1/server?wsdl");
SoapSmsQueuableImplementation service = new SoapSmsQueuableImplementationServiceLocator().getTSOAP(url);

// credentials String username = "username"; String password = "password"; String domain = "domain";

// set basic auth TSOAPSoapBindingStub stub = (TSOAPSoapBindingStub) service; stub.setUsername(username); stub.setPassword(password);

// call System.out.println(service.getCredit(domain));
python
# -*- coding: utf-8 -*-
#
# Python samples are made with
#
# Requests: HTTP for Humans - https://pypi.org/project/requests/
# Zeep: Python SOAP client - https://pypi.org/project/zeep/
#
from requests import Session
from requests.auth import HTTPBasicAuth # or HTTPDigestAuth, or OAuth1, etc.
from zeep import Client
from zeep.transports import Transport

# credentials username = "username" password = "password" domain = "domain"

# session session = Session() # basic auth session.auth = HTTPBasicAuth(username, password)

# soap wsdl = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl' client = Client(wsdl=wsdl, transport=Transport(session=session))

# call print(client.service.getCredit(domain))
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Service SoapSmsQueuableImplementationService service = new SoapSmsQueuableImplementationService();

// Basic Auth NetworkCredential netCredential = new NetworkCredential(username, password); Uri uri = new Uri(service.Url); ICredentials credentials = netCredential.GetCredential(uri, "Basic"); service.Credentials = credentials;

// Call float c = service.getCredit(domain); Console.WriteLine("credit: " + c);

متد enqueue

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

پارامترها

پارامترهای username و password از روی Header ارسالی خوانده می‌شوند

پارامترنوعاجباری؟توضيحات
domainstringبلهدامنه
messageBodiesstring arrayبلهآرايه‌ای از پيام
recipientNumbersstring arrayبلهآرايه‌ای از گيرنده
senderNumbersstring arrayبلهآرايه‌ای از فرستنده
encodingsint arrayآرايه‌ای از يکی از مقادير 0 (تشخيص خودکار زبان پیامک[پيش فرض])، 2 (فارسی)، 5 (ارسال به صورت 8BIT) و 6 (ارسال به صورت BINARY)
udhsstring arrayآرايه‌ای از UDH (برای اطلاعات بيشتر به مستند UDH مراجعه نماييد)
messageClassesint arrayآرايه‌ای از يکی از مقادير 0 (نمايش پيامک روی صفحه نمايش گوشی بدون ذخيره‌شدن [پيامک خبری])، 1 (پيامک عادی[پیش‌فرض])، 2 (ذخيره در سیم‌کارت) و 3 (ارسال به SIM toolkit)
prioritiesint arrayآرايه‌ای از اولويت پیامک
checkingMessageIdslong arrayآرايه‌ای از شناسه‌ی یکتای کاربر
فرستنده

شماره فرستنده به یکی از حالت‌های زير قابل استفاده است:

  • 3000xxxxxx
  • 983000xxxxxx
  • %2B983000xxxxxx
گيرنده

برای ارسال به چندين گيرنده، شماره‌ها را با کاما [,] از هم جدا نمایید

  • 09xxxxxxxxx
  • 989xxxxxxxxx
  • %2B989xxxxxxxxx
  • 9xxxxxxxxx
پيام

متن پيامک بايد به صورت UTF-8 باشد. بر اساس نوع متن (فارسی، لاتین و باينری)، طول متن و نيز با توجه به تعرفه‌ی تخصیص‌داده‌شده به حساب، هزينه‌ی پيامک تشخيص داده‌شده و از مانده اعتبار کسر می‌گردد. با توجه به محدود بودن حجم پیامک در استاندارد شبکه‌های تلفن همراه (۱۴۰ بايت)، شرکت مگفا به صورت خودکار و در صورت نياز (طولانی بودن متن پيامک) اقدام به شکستن متن طولانی به تعداد بخش‌های مناسب می‌نمايد.
طول استاندارد يک پيامک فارسی ۷۰ کاراکتر ( هر کاراکتر ۲ بايت)، پيامک باينری ۱۴۰ بايت و لاتین ۱۶۰ کاراکتر (هر کاراکتر ۷ بيت) است. وجود حتی يک کاراکتر چند بايتی (غير ASCII) منجر به تشخيص پيامک به صورت فارسی خواهد شد تا متن ارسالی به درستی ارسال گردد.
با توجه به این که گوشی برای تشخيص بخش‌های یک پيامک نياز به اطلاعاتی دارد، قسمتی از حجم پيامک (معمولا ۶ بايت از ۱۴۰ بایت) صرف این اطلاعات خواهد شد. در اين صورت برای پيامک‌های طولانی هر بخش پيامک فارسی ۶۷ و هر بخش پيامک لاتين ۱۵۳ کاراکتر می‌تواند داشته باشد.

خروجی

شناسه پيامک به ازای هر گيرنده (long) / کدهای خطا

نمونه‌کد

php
// credentials
$username = 'USERNAME';
$password = 'PASSWORD';
$domain = 'DOMAIN';

// url $url = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl'; // soap options $options = [     'login' => $username,'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'trace' => false // -Optional (debug) ];

// soap client $client = new SoapClient( $url, $options);

// send $result['send'] = $client->send(     $domain,     ["تست ارسال پيامک. Sample Text for test.", "test2: ".date('Y-m-d H:i:s')], // messages     [$mobile, $mobile], // recipients     [$sender, $sender], // short numbers can be 1 or same count as recipients (mobiles)     [], // Encodings are optional, The system will guess it, itself ;)     [], // UDHs, Please read Magfa UDH Documnet     [], // message class     [] // Message priorities (unused).     [1989812, 12332], // client-side unique IDs. );
java
URL url = new URL("https://sms.magfa.com/api/soap/sms/v1/server?wsdl");
SoapSmsQueuableImplementation service = new SoapSmsQueuableImplementationServiceLocator().getTSOAP(url);

// credentials String username = "username"; String password = "password"; String domain = "domain";

// set basic auth TSOAPSoapBindingStub stub = (TSOAPSoapBindingStub) service; stub.setUsername(username); stub.setPassword(password);

// call long[] result = service.enqueue(domain,     new String[] { "تست ارسال پيامک. Sample Text for test.", "Hi!" },     new String[] { "0912xxxxxxx", "0902xxxxxxx" },     new String[] { "3000xxx", "3000xxxxxxx" },     new int[] { 0 },     new String[] { "" },     new int[] { 0 },     new int[] { 0 },     new long[] { 198981, 123032 } ); for (long mid : result) {     System.out.println(mid); }
python
# -*- coding: utf-8 -*-
#
# Python samples are made with
#
# Requests: HTTP for Humans - https://pypi.org/project/requests/
# Zeep: Python SOAP client - https://pypi.org/project/zeep/
#
from requests import Session
from requests.auth import HTTPBasicAuth # or HTTPDigestAuth, or OAuth1, etc.
from zeep import Client
from zeep.transports import Transport

# credentials username = "username" password = "password" domain = "domain"

# session session = Session() # basic auth session.auth = HTTPBasicAuth(username, password)

# soap wsdl = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl' client = Client(wsdl=wsdl, transport=Transport(session=session))

# data stringArray = client.get_type('ns1:ArrayOf_xsd_string'); longArray = client.get_type('ns1:ArrayOf_xsd_long'); intArray = client.get_type('ns1:ArrayOf_xsd_int');

# data plain_string = "Hi!" unicode_string = "تست ارسال پيامک. Sample Text for test."

# call resp = client.service.enqueue( domain=domain, messageBodies=stringArray([unicode_string, plain_string]), recipientNumbers=stringArray(["0912xxxxxxx", "0902xxxxxxx"]), senderNumbers=stringArray(["3000xxx", "3000xxxxxxx"]), encodings=stringArray([0]), udhs=stringArray([""]), messageClasses=intArray([1]), priorities=intArray([0]), checkingMessageIds=longArray([200,201]) );

for r in resp:     print(r.text);
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Service (Add a Web Reference) SoapSmsQueuableImplementationService service = new SoapSmsQueuableImplementationService();

// Basic Auth NetworkCredential netCredential = new NetworkCredential(username, password); Uri uri = new Uri(service.Url); ICredentials credentials = netCredential.GetCredential(uri, "Basic"); service.Credentials = credentials;

// Call long[] resp = service.enqueue(domain,     new string[] { "تست ارسال پيامک. Sample Text for test.", "Hi!" },     new string[] { "0912xxxxxxx", "0902xxxxxxx" },     new string[] { "3000xxx", "3000xxxxxxx" },     new int[] { 0 },     new string[] { "" },     new int[] { 0 },     new int[] { 0 },     new long[] { 198981, 123032 } ); foreach (long r in resp) {     Console.WriteLine("send: " + r); }

متد ‫‪getMessageId

در صورتی که هنگام ارسال هر پيامک، شناسه‌ی يکتای کاربر نيز به عنوان پارامتر، تحويل شده باشد، با استفاده از اين متد می‌توان شناسه‌ی پیامک متناظر با آن را دريافت کرد.
شايان ذکر است که مورد استفاده‌ی اين متد جلوگيری از ارسال تکراری پيامک به هنگام رخداد خطای ارتباطی مانند TIMEOUT است. بدین صورت که پس از بروز چنین خطاهايی هنگام ارسال پيامک به همراه شناسه‌ی يکتای کاربر، با فراخوانی این متد به ازای شناسه‌های يکتا و دریافت شناسه پیامک می‌توان از ارسال دوباره پيشگيری نمود .

پارامترنوعاجباری؟توضيحات
domainstringبلهدامنه
chkmessageidlongشناسه‌ی یکتای کاربر

خروجی

شناسه پیامک متناظر (long) / کدهای خطا

نمونه‌کد

php
// credentials
$username = 'USERNAME';
$password = 'PASSWORD';
$domain = 'DOMAIN';

// url $url = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl'; // soap options $options = [     'login' => $username,'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'trace' => false // -Optional (debug) ];

// soap client $client = new SoapClient( $url, $options);

// message-id $result['mid'] = $client->‫‪getMessageId($domain, 12345678);
java
URL url = new URL("https://sms.magfa.com/api/soap/sms/v1/server?wsdl");
SoapSmsQueuableImplementation service = new SoapSmsQueuableImplementationServiceLocator().getTSOAP(url);

// credentials String username = "username"; String password = "password"; String domain = "domain";

// set basic auth TSOAPSoapBindingStub stub = (TSOAPSoapBindingStub) service; stub.setUsername(username); stub.setPassword(password);

// call System.out.println(service.getMessageId(domain, 12345L));
python
# -*- coding: utf-8 -*-
#
# Python samples are made with
#
# Requests: HTTP for Humans - https://pypi.org/project/requests/
# Zeep: Python SOAP client - https://pypi.org/project/zeep/
#
from requests import Session
from requests.auth import HTTPBasicAuth # or HTTPDigestAuth, or OAuth1, etc.
from zeep import Client
from zeep.transports import Transport

# credentials username = "username" password = "password" domain = "domain"

# session session = Session() # basic auth session.auth = HTTPBasicAuth(username, password)

# soap wsdl = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl' client = Client(wsdl=wsdl, transport=Transport(session=session))

# call print(client.service.getMessageId(domain, 12345))
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Service (Add a Web Reference) SoapSmsQueuableImplementationService service = new SoapSmsQueuableImplementationService();

// Basic Auth NetworkCredential netCredential = new NetworkCredential(username, password); Uri uri = new Uri(service.Url); ICredentials credentials = netCredential.GetCredential(uri, "Basic"); service.Credentials = credentials;

// Call long uid = 123456; long mid = service.getMessageId(domain, uid); Console.WriteLine("mid: ۰", mid);

متد ‫‪getRealMessageStatus

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

پارامترنوعاجباری؟توضيحات
messageIdlongبلهآرايه‌ای از شناسه پيامک

خروجی

یک از مقادير زير به عنوان وضعيت بازگشت داده می‌شود / کدهای خطا

  • 1-: شناسه موجود نيست (شناسه نادرست یا گذشت بيش از ۲۴ ساعت از ارسال پيامک)
  • 0: وضعيتی دريافت نشده
  • 1: رسیده به گوشی
  • 2: نرسیده به گوشی
  • 8: رسیده به مخابرات
  • 16: نرسیده به مخابرات

نمونه‌کد

php
// credentials
$username = 'USERNAME';
$password = 'PASSWORD';
$domain = 'DOMAIN';

// url $url = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl'; // soap options $options = [     'login' => $username,'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'trace' => false // -Optional (debug) ];

// soap client $client = new SoapClient( $url, $options);

// status $result['status'] = $client->‫‪getRealMessageStatuses($domain, [12345678,5678934]);
java
URL url = new URL("https://sms.magfa.com/api/soap/sms/v1/server?wsdl");
SoapSmsQueuableImplementation service = new SoapSmsQueuableImplementationServiceLocator().getTSOAP(url);

// credentials String username = "username"; String password = "password"; String domain = "domain";

// set basic auth TSOAPSoapBindingStub stub = (TSOAPSoapBindingStub) service; stub.setUsername(username); stub.setPassword(password);

// call long[] mids = new long[]{12345678L, 5678934L}; for (int status : service.getRealMessageStatuses(mids)) {     System.out.println(status); }
python
# -*- coding: utf-8 -*-
#
# Python samples are made with
#
# Requests: HTTP for Humans - https://pypi.org/project/requests/
# Zeep: Python SOAP client - https://pypi.org/project/zeep/
#
from requests import Session
from requests.auth import HTTPBasicAuth # or HTTPDigestAuth, or OAuth1, etc.
from zeep import Client
from zeep.transports import Transport

# credentials username = "username" password = "password" domain = "domain"

# session session = Session() # basic auth session.auth = HTTPBasicAuth(username, password)

# soap wsdl = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl' client = Client(wsdl=wsdl, transport=Transport(session=session)) # data longArray = client.get_type('ns1:ArrayOf_xsd_long'); # call resp = client.service.getRealMessageStatuses(longArray([12345, 67249]));

for r in resp:     print(r.text)
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Service (Add a Web Reference) SoapSmsQueuableImplementationService service = new SoapSmsQueuableImplementationService();

// Basic Auth NetworkCredential netCredential = new NetworkCredential(username, password); Uri uri = new Uri(service.Url); ICredentials credentials = netCredential.GetCredential(uri, "Basic"); service.Credentials = credentials;

// Call long[] mids = new long[] { 1234, 213434 }; int[] statuses = service.getRealMessageStatuses(mids); foreach (int s in statuses) {     Console.WriteLine("status: " + s); }

متد ‫‪getMessages

دريافت پیامک‌های ورودی به غالب DatedCustomerReturnIncomingFormat

پارامترنوعاجباری؟توضيحات
domainstringبلهدامنه
numberOfMessagesintبلهشناسه‌ی یکتای کاربر

خروجی

آرايه‌ای از DatedCustomerReturnIncomingFormat/ کدهای خطا

نمونه‌کد

متد ‫‪getAllMessages

دريافت پیامک‌های ورودی به غالب CustomerReturnIncomingFormat

پارامترنوعاجباری؟توضيحات
domainstringبلهدامنه
numberOfMessagesintبلهشناسه‌ی یکتای کاربر

خروجی

آرايه‌ای از CustomerReturnIncomingFormat / کدهای خطا

نمونه‌کد

متد ‫‪getMessagesWithNumber

دريافت پیامک‌های ورودی یک شماره به غالب DatedCustomerReturnIncomingFormat

پارامترنوعاجباری؟توضيحات
domainstringبلهدامنه
numberOfMessagesintبلهشناسه‌ی یکتای کاربر
destNumberstringبلهفرستنده

خروجی

آرايه‌ای از DatedCustomerReturnIncomingFormat / کدهای خطا

نمونه‌کد

متد ‫‪getAllMessagesWithNumber

دريافت پیامک‌های ورودی یک شماره به غالب CustomerReturnIncomingFormat

پارامترنوعاجباری؟توضيحات
domainstringبلهدامنه
numberOfMessagesintبلهشناسه‌ی یکتای کاربر
destNumberstringبلهفرستنده

خروجی

آرايه‌ای از CustomerReturnIncomingFormat / کدهای خطا

نمونه‌کد

php
// credentials
$username = 'USERNAME';
$password = 'PASSWORD';
$domain = 'DOMAIN';

// url $url = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl'; // soap options $options = [     'login' => $username,'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'trace' => false // -Optional (debug) ];

// soap client $client = new SoapClient( $url, $options);

// messages $result['messages'] = $client->getMessages(50); // or // messages $result['messages'] = $client->getAllMessages(50); // short-number sample // messages of a short-number $result['messagesOf'] = $client->getMessagesWithNumber(20, "3000xxxx"); // or // messages of a short-number $result['messagesOf'] = $client->getAllMessagesWithNumber(20, "3000xxxx");
java
URL url = new URL("https://sms.magfa.com/api/soap/sms/v1/server?wsdl");
SoapSmsQueuableImplementation service = new SoapSmsQueuableImplementationServiceLocator().getTSOAP(url);

// credentials String username = "username"; String password = "password"; String domain = "domain";

// set basic auth TSOAPSoapBindingStub stub = (TSOAPSoapBindingStub) service; stub.setUsername(username); stub.setPassword(password);

// get messages Object[] messages = service.getAllMessages(domain, 50); // Object[] messages = service.getAllMessagesWithNumber(domain, 50, "3000xxxx"); for (Object m : messages) {     CustomerReturnIncomingFormat msg = (CustomerReturnIncomingFormat) m;     System.out.println(msg.getBody()); } // get dated messages Object[] dmessages = service.getMessages(domain, 50); // Object[] dmessages = service.getMessagesWithNumber(domain, 50, "3000xxx"); for (Object m : dmessages) {     DatedCustomerReturnIncomingFormat msg = (DatedCustomerReturnIncomingFormat) m;     System.out.println(msg.getBody()); }
python
# -*- coding: utf-8 -*-
#
# Python samples are made with
#
# Requests: HTTP for Humans - https://pypi.org/project/requests/
# Zeep: Python SOAP client - https://pypi.org/project/zeep/
#
from requests import Session
from requests.auth import HTTPBasicAuth # or HTTPDigestAuth, or OAuth1, etc.
from zeep import Client
from zeep.transports import Transport

# credentials username = "username" password = "password" domain = "domain"

# session session = Session() # basic auth session.auth = HTTPBasicAuth(username, password)

# soap wsdl = 'https://sms.magfa.com/api/soap/sms/v1/server?wsdl' client = Client(wsdl=wsdl, transport=Transport(session=session))

# call # print(client.service.getMessages(domain, 50)) print(client.service.getAllMessages(domain, 50)) # print(client.service.getMessagesWithNumber(domain, 50, "3000xxxx")) print(client.service.getAllMessagesWithNumber(domain, 50, "3000xxxx"))
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Service (Add a Web Reference) SoapSmsQueuableImplementationService service = new SoapSmsQueuableImplementationService();

// Basic Auth NetworkCredential netCredential = new NetworkCredential(username, password); Uri uri = new Uri(service.Url); ICredentials credentials = netCredential.GetCredential(uri, "Basic"); service.Credentials = credentials;

// Call object[] msgs = service.getAllMessages(domain, 10); //object[] msgs = service.getAllMessagesWithNumber(domain, 10, "3000xxxx"); foreach (object m in msgs) {     CustomerReturnIncomingFormat msg = (CustomerReturnIncomingFormat) m;     Console.WriteLine("messages: " + msg.body); } // object[] dmsgs = service.getMessages(domain, 10); //object[] dmsgs = service.getMessagesWithNumber(domain, 10, "3000xxxx"); foreach (object m in dmsgs) {     DatedCustomerReturnIncomingFormat msg = (DatedCustomerReturnIncomingFormat)m;     Console.WriteLine("messages: " + msg.body); }

موجوديت‌ها (Entity)

اطلاعات بازگشت داده‌شده در سرويس از طريق موجوديت‌های زیر ارايه می‌گردند. این موجوديت‌ها در WSDL وجود دارند

CustomerReturnIncomingFormat

پارامترنوعتوضيحات
bodystringپيام
errorResultstringخطا
recipientNumberstringگيرنده
senderNumberstringفرستنده

DatedCustomerReturnIncomingFormat

پارامترنوعتوضيحات
bodystringپيام
errorResultstringخطا
recipientNumberstringگيرنده
senderNumberstringفرستنده
datestringتاريخ

کدهای خطا

جدول کدهای خطا سرويس به شرح زير است

کد خطاتوضيحات
1شماره گيرنده نادرست است
2شماره فرستنده نادرست است
3پارامتر encoding نامعتبراست. (بررسی صحت و هم‌خوانی متن پيامک با encoding انتخابی)
4پارامتر mclass نامعتبر است
6پارامتر UDH نامعتبر است
13محتويات پيامک (تركيب UDH و متن) خالی است. (بررسی دوباره‌ی متن پيامک و پارامتر UDH)
14مانده اعتبار ريالی مورد نياز برای ارسال پیامک کافی نيست
15سرور در هنگام ارسال پيام مشغول برطرف نمودن ايراد داخلی بوده است. (ارسال مجدد درخواست)
16حساب غيرفعال است. (تماس با واحد فروش سيستم‌های ارتباطی)
17حساب منقضی شده است. (تماس با واحد فروش سيستم‌های ارتباطی)
18نام كاربری و يا كلمه عبور نامعتبر است. (بررسی مجدد نام كاربری و كلمه عبور)
19درخواست معتبر نيست. (تركيب نام كاربری، رمز عبور و دامنه اشتباه است. تماس با واحد فروش برای دريافت كلمه عبور جديد)
20شماره فرستنده به حساب تعلق ندارد
22اين سرويس برای حساب فعال نشده است
23در حال حاضر امکان پردازش درخواست جديد وجود ندارد، لطفا دوباره سعی كنيد. (ارسال مجدد درخواست)
24شناسه پيامک معتبر نيست. (ممكن است شناسه پيامک اشتباه و يا متعلق به پيامكی باشد كه بيش از يک روز از ارسال آن گذشته)
25نام متد درخواستی معتبر نيست. (بررسی نگارش نام متد با توجه به بخش متدها در اين راهنما)
27شماره گيرنده در ليست سياه اپراتور قرار دارد. (ارسال پيامک‌های تبليغاتی برای اين شماره امكان‌پذير نيست)
28شماره گیرنده، بر اساس پیش‌شماره در حال حاضر در مگفا مسدود است
29آدرس IP مبدا، اجازه دسترسی به این سرویس را ندارد
30تعداد بخش‌های پیامک بیش از حد مجاز استاندارد (۲۶۵ عدد) است
101طول آرايه پارامتر messageBodies با طول آرايه گيرندگان تطابق ندارد
102طول آرايه پارامتر messageClass با طول آرايه گيرندگان تطابق ندارد
103طول آرايه پارامتر senderNumbers با طول آرايه گيرندگان تطابق ندارد
104طول آرايه پارامتر udhs با طول آرايه گيرندگان تطابق ندارد
105طول آرايه پارامتر priorities با طول آرايه گيرندگان تطابق ندارد
106آرايه‌ی گيرندگان خالی است
107طول آرايه پارامتر گيرندگان بيشتر از طول مجاز است
108آرايه‌ی فرستندگان خالی است
109طول آرايه پارامتر encoding با طول آرايه گيرندگان تطابق ندارد
110طول آرايه پارامتر checkingMessageIds با طول آرايه گيرندگان تطابق ندارد