راهنمای وبسرويس (SOAP)
اين سرویس به صورت SOAP پيادهسازی شده است
- آغاز به کار
- مقدمه
- آغاز کار با سرويس
- احراز هويت
- بهکارگیری WSDL در زبانهای برنامهنويسی
- مراحل به کارگيری در Java
- مراحل به کارگيری در MS Visual Studio
- URL
- متدها
- متد getCredit
- متد enqueue
- متد getMessageId
- متد getRealMessageStatus
- متد getMessages
- متد getAllMessages
- متد getMessagesWithNumber
- متد getAllMessagesWithNumber
- موجوديتها (Entity)
- CustomerReturnIncomingFormat
- DatedCustomerReturnIncomingFormat
- کدهای خطا
آغاز به کار
مقدمه
اين سرويس برای آن دسته از برنامهنويسان طراحی شده که میخواهند به صورت 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 نخواهد بود.
- با ابزار 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
- اکنون میتوانید از سرويس SOAP استفاده نماييد
مراحل به کارگيری در MS Visual Studio
لطفا مراحل زير را برای افزودن Web reference دنبال نماييد:
- در صورتی که از Visual Studio 2010 یا قبلتر استفاده میکنيد، در منوی Project گزينهی «Add Web Reference» را انتخاب نماييد. برای نسخههای جدیدتر Visual Studio در منوی Project گزينهی «Add Service Reference»، سپس «Advanced» و آنگاه «Add Web Reference» را انتخاب نماييد. شايان ذکر است دسترسی به اين موارد با right-click بر نام پروژه در Solution Explorer نيز مقدور است
- در کادر URL، نشانی WSDL را وارد نماييد. مانند: http://wsdl_url
- دکمه «Go» را برای دريافت اطلاعات وبسرويس بزنيد
- نام دلخواه خود را برای سرویس وارد نماييد
- دکمهی «Add» را برای افزودن وبسرويس بزنيد
URL
URL جهت دريافت فايل WSDL در پایین آمده است
متدها
متدهای پیادهسازیشده به شرح زير است:
متد | توضيحات |
---|---|
getCredit | دريافت مانده اعتبار حساب |
enqueue | ارسال پيامک به يک یا چند گيرنده (حداکثر يکصد (۱۰۰) عدد) |
getMessageId | دريافت شناسه یکتای پيامک متناظر با شناسه کاربر |
getRealMessageStatuses | پيگيری وضعيت نهایی پيامک |
getMessages | دریافت پیامکهای ورودی (حداکثر يکصد (۱۰۰) عدد) |
getAllMessages | دریافت پیامکهای ورودی (حداکثر يکصد (۱۰۰) عدد) |
getMessagesWithNumber | دریافت پیامکهای ورودی (حداکثر يکصد (۱۰۰) عدد) مربوط به يک شماره ۳۰۰۰ |
getAllMessagesWithNumber | دریافت پیامکهای ورودی (حداکثر يکصد (۱۰۰) عدد) مربوط به يک شماره ۳۰۰۰ |
متد getCredit
از اين متد برای دريافت مانده اعتبار حساب استفاده میشود.
پارامترها
پارامترهای username و password از روی Header ارسالی خوانده میشوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
domain | string | بله | دامنه |
خروجی
ميزان مانده اعتبار (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 ارسالی خوانده میشوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
domain | string | بله | دامنه |
messageBodies | string array | بله | آرايهای از پيام |
recipientNumbers | string array | بله | آرايهای از گيرنده |
senderNumbers | string array | بله | آرايهای از فرستنده |
encodings | int array | آرايهای از يکی از مقادير 0 (تشخيص خودکار زبان پیامک[پيش فرض])، 2 (فارسی)، 5 (ارسال به صورت 8BIT) و 6 (ارسال به صورت BINARY) | |
udhs | string array | آرايهای از UDH (برای اطلاعات بيشتر به مستند UDH مراجعه نماييد) | |
int array | آرايهای از يکی از مقادير 0 (نمايش پيامک روی صفحه نمايش گوشی بدون ذخيرهشدن [پيامک خبری])، 1 (پيامک عادی[پیشفرض])، 2 (ذخيره در سیمکارت) و 3 (ارسال به SIM toolkit) | ||
int array | آرايهای از اولويت پیامک | ||
checkingMessageIds | long 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 است.
بدین صورت که پس از بروز چنین خطاهايی هنگام ارسال پيامک به همراه شناسهی يکتای کاربر،
با فراخوانی این متد به ازای شناسههای يکتا و دریافت شناسه پیامک میتوان از ارسال دوباره پيشگيری نمود .
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
domain | string | بله | دامنه |
chkmessageid | long | شناسهی یکتای کاربر |
خروجی
شناسه پیامک متناظر (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
برای پيگيری وضعيت نهایی پيامک از اين متد میتوانيد استفاده نماييد
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
messageId | long | بله | آرايهای از شناسه پيامک |
خروجی
یک از مقادير زير به عنوان وضعيت بازگشت داده میشود / کدهای خطا
- 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
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
domain | string | بله | دامنه |
numberOfMessages | int | بله | شناسهی یکتای کاربر |
خروجی
آرايهای از DatedCustomerReturnIncomingFormat/ کدهای خطا
نمونهکد
متد getAllMessages
دريافت پیامکهای ورودی به غالب CustomerReturnIncomingFormat
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
domain | string | بله | دامنه |
numberOfMessages | int | بله | شناسهی یکتای کاربر |
خروجی
آرايهای از CustomerReturnIncomingFormat / کدهای خطا
نمونهکد
متد getMessagesWithNumber
دريافت پیامکهای ورودی یک شماره به غالب DatedCustomerReturnIncomingFormat
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
domain | string | بله | دامنه |
numberOfMessages | int | بله | شناسهی یکتای کاربر |
destNumber | string | بله | فرستنده |
خروجی
آرايهای از DatedCustomerReturnIncomingFormat / کدهای خطا
نمونهکد
متد getAllMessagesWithNumber
دريافت پیامکهای ورودی یک شماره به غالب CustomerReturnIncomingFormat
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
domain | string | بله | دامنه |
numberOfMessages | int | بله | شناسهی یکتای کاربر |
destNumber | string | بله | فرستنده |
خروجی
آرايهای از 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
پارامتر | نوع | توضيحات |
---|---|---|
body | string | پيام |
errorResult | string | خطا |
recipientNumber | string | گيرنده |
senderNumber | string | فرستنده |
DatedCustomerReturnIncomingFormat
پارامتر | نوع | توضيحات |
---|---|---|
body | string | پيام |
errorResult | string | خطا |
recipientNumber | string | گيرنده |
senderNumber | string | فرستنده |
date | string | تاريخ |
کدهای خطا
جدول کدهای خطا سرويس به شرح زير است
کد خطا | توضيحات |
---|---|
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 با طول آرايه گيرندگان تطابق ندارد |