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

اين سرويس نسخه‌ی به‌روزرسانی‌شده v1 است

آغاز به کار

مقدمه

اين سرويس برای علاقمندان به SOAP پياده‌سازی شده و نسخه‌ی به‌روزرسانی شده سرويس SOAP v1 است

نکته‌ها

  1. بیشینه تعداد شماره گيرنده در درخواست‌ها يک‌صد (۱۰۰) عدد است. ارسال بيش از این تعداد با کد خطا مواجه خواهد شد
  2. در پاسخ همه‌ی متدها ، پارامتر status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.

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

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

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

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

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

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

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

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

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

احراز هويت

احراز هويت اين سرويس بر اساس ارسال نام‌کاربری، رمز عبور سرويس و دامنه در سرایند HTTP با کليد Authorization و به صورت HTTP Basic Authentication است که در آن username به صورت ترکيب «نام‌کاربری به همراه دامنه» و password نيز همان رمز عبور سرويس ، به صورت زير است:

USERNAME/DOMAIN:PASSWORD

 

POST https://sms.magfa.com/api/soap/sms/v2/server

Authorization: Basic VVNFUk5BTUUvRE9NQUlOOlBBU1NXT1JECg==

به‌کارگیری 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/api/soap/sms/v2/server?wsdl

فشرده‌سازی

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

متدها

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

متدتوضيحات
balanceدريافت مانده اعتبار حساب
sendارسال پيامک به يک یا چند گيرنده (حداکثر يک‌صد (۱۰۰) عدد)
‫‪midدريافت شناسه یکتای پيامک متناظر با شناسه کاربر
‫‪statusesپيگيری وضعيت نهایی پيامک
‫‪messagesدریافت پیامک‌های ورودی (حداکثر يک‌صد (۱۰۰) عدد)

متد balance

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

پارامترها

ندارد

خروجی

دریافت مانده اعتبار به فرمت CreditResult / کدهای خطا

نمونه‌کد

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

// url $url = 'https://sms.magfa.com/api/soap/sms/v2/server?wsdl'; // soap options $options = [     'login' => "$username/$domain",'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'compression' => (SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5), // -Compression *     'trace' => false // -Optional (debug) ]; // * Accept response compression and compress requests using gzip with compression level 5

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

// balance var_dump($client->balance());
java
//
// after wsimport, classes can be used
//
URL url = new URL("https://sms.magfa.com/api/soap/sms/v2/server?wsdl");
MagfaSoapServer service = new MagfaSoapServer_Service(url).getMagfaSoapServer();

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

// set basic auth BindingProvider prov = (BindingProvider) service; prov.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, username + "/" + domain); prov.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

// Compression Map> httpHeaders = new HashMap<>(); httpHeaders.put("Content-Encoding", Collections.singletonList("gzip"));//this indicates you're sending a compressed request httpHeaders.put("Accept-Encoding", Collections.singletonList("gzip")); //this says you're willing to accept a compressed response prov.getRequestContext().put(MessageContext.HTTP_REQUEST_HEADERS, httpHeaders);

// call CreditResult result = service.balance(); // result if(result.getStatus() != 0 )     System.out.println(result.getStatus()); esle     System.out.println(result.getBalance());
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 + '/' + domain, password)

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

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

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

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

// SOAP Compression For .NET FrameWork 2 or later service.EnableDecompression = true;

// Call creditResult result = service.balance(); if (result.status != 0) {     Console.WriteLine("error: " + result.status); } else {     Console.WriteLine("balance: " + result.balance); }

متد send

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

پارامترها

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

پارامترنوعاجباری؟توضيحات
messagesstringبلهآرايه‌ای از پيام
sendersstringبلهآرايه‌ای از فرستنده
recipientsstringبلهآرايه‌ای از گيرنده
uidslongآرايه‌ای از شناسه‌ی یکتای کاربر
encodingsintآرايه‌ای از يکی از مقادير 0 (تشخيص خودکار زبان پیامک[پيش فرض])، 2 (فارسی)، 5 (ارسال به صورت 8BIT) و 6 (ارسال به صورت BINARY)
udhsstringآرايه‌ای از UDH (برای اطلاعات بيشتر به مستند UDH مراجعه نماييد)
prioritiesintآرايه‌ای از اولويت پیامک
فرستنده

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

  • 3000xxxxxx
  • 983000xxxxxx
  • +983000xxxxxx
گيرنده

شماره‌ی گيرنده را به صورت‌های زير می‌توانيد مورد استفاده قرار دهيد.

  • 09xxxxxxxxx
  • 989xxxxxxxxx
  • +989xxxxxxxxx
  • 9xxxxxxxxx
پيام

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

خروجی

اطلاعات پيامک‌های ارسال شده به فرمت SendResult / کدهای خطا

نمونه‌کد

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

// url $url = 'https://sms.magfa.com/api/soap/sms/v2/server?wsdl'; // soap options $options = [     'login' => "$username/$domain",'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'compression' => (SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5), // -Compression *     'trace' => false // -Optional (debug) ]; // * Accept response compression and compress requests using gzip with compression level 5

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

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

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

// set basic auth BindingProvider prov = (BindingProvider) service; prov.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, username + "/" + domain); prov.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

// Compression Map> httpHeaders = new HashMap<>(); httpHeaders.put("Content-Encoding", Collections.singletonList("gzip"));//this indicates you're sending a compressed request httpHeaders.put("Accept-Encoding", Collections.singletonList("gzip")); //this says you're willing to accept a compressed response prov.getRequestContext().put(MessageContext.HTTP_REQUEST_HEADERS, httpHeaders);

// messages StringArray messages = new StringArray(); List messageItems = messages.getItem(); messageItems.add("متن پیامک تست"); messageItems.add("New Text 2"); // recipients StringArray recipients = new StringArray(); List recipientItems = recipients.getItem(); recipientItems.add("0912xxxxxxx"); recipientItems.add("0902xxxxxxx"); // senders StringArray senders = new StringArray(); List senderItems = senders.getItem(); senderItems.add("3000xxxxxxx"); senderItems.add("3000xxxxxxx"); // user-ids LongArray uids = new LongArray(); List uidItems = uids.getItem(); uidItems.add(1L); uidItems.add(2L); // call SendResult result = service.send(messages, senders, recipients, uids, new IntArray(), new StringArray(), new IntArray()); System.out.println(result.getStatus()); for (SendMessage sendMessage : result.getMessages()) {     System.out.println(sendMessage); }
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 + '/' + domain, password)

# soap wsdl = 'https://sms.magfa.com/api/soap/sms/v2/server?wsdl' client = Client(wsdl=wsdl, transport=Transport(session=session)) # data messages = client.get_type('ns1:stringArray'); senders = client.get_type('ns1:stringArray'); recipients = client.get_type('ns1:stringArray'); uids = client.get_type('ns1:longArray'); encodings = client.get_type('ns1:intArray'); udhs = client.get_type('ns1:stringArray'); priorities = client.get_type('ns1:intArray');

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

# call print(client.service.send(     messages(item=[unicode_string, plain_string]),     senders(item=["3000xxx", "3000xxxxxxx"]),     recipients(item=["0912xxxxxxx", "0902xxxxxxx"]),     uids(item=[1989812L, 12332L]),     encodings(item=[]),     udhs(item=[]),     priorities(item=[])) )
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

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

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

// SOAP Compression For .NET FrameWork 2 or later service.EnableDecompression = true;

// Call sendResult result = service.send(     new string[] { "تست ارسال پيامک. Sample Text for test.", "Hi!" },     new string[] { "3000xxx", "3000xxxxxxx" },     new string[] { "0912xxxxxxx", "0902xxxxxxx" },     new long?[] { 198981, 123032 },     new int?[] { 0 },     new string[] { "" },     new int?[] { 0 } );

if (result.status != 0) {     Console.WriteLine("error: " + result.status); } else {     foreach (sendMessage msg in result.messages)     {         if (msg.status != 0)    Console.WriteLine("error: " + result.status);         else        Console.WriteLine("mid: " + msg.id + ", part-cnt:" + msg.parts + ", uid:" + msg.userId);     } }

متد ‫‪mid

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

پارامترها

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

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

خروجی

دريافت شناسه يکتای پيامک به فرمت MessageIdResult / کدهای خطا

نمونه‌کد

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

// url $url = 'https://sms.magfa.com/api/soap/sms/v2/server?wsdl'; // soap options $options = [     'login' => "$username/$domain",'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'compression' => (SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5), // -Compression *     'trace' => false // -Optional (debug) ]; // * Accept response compression and compress requests using gzip with compression level 5

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

// mid var_dump($client->mid(12345));
java
//
// after wsimport, classes can be used
//
URL url = new URL("https://sms.magfa.com/api/soap/sms/v2/server?wsdl");
MagfaSoapServer service = new MagfaSoapServer_Service(url).getMagfaSoapServer();

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

// set basic auth BindingProvider prov = (BindingProvider)service; prov.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, username + "/" + domain); prov.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

// Compression Map> httpHeaders = new HashMap<>(); httpHeaders.put("Content-Encoding", Collections.singletonList("gzip"));//this indicates you're sending a compressed request httpHeaders.put("Accept-Encoding", Collections.singletonList("gzip")); //this says you're willing to accept a compressed response prov.getRequestContext().put(MessageContext.HTTP_REQUEST_HEADERS, httpHeaders);

// call MessageIdResult result = service.mid(123456);

// result if(result.getStatus() != 0 )     System.out.println(result.getStatus()); else     System.out.println(result.getMid());
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 + '/' + domain, password)

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

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

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

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

// SOAP Compression For .NET FrameWork 2 or later service.EnableDecompression = true;

// Call long uid = 1234; messageIdResult result = service.mid(uid); if (result.status != 0) {     Console.WriteLine("error: " + result.status); } else {     Console.WriteLine("mid: " + result.mid); }

متد ‫‪statuses

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

پارامترها

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

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

خروجی

دريافت وضعيت پيامک‌ها به فرمت DeliveryResult / کدهای خطا

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

نمونه‌کد

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

// url $url = 'https://sms.magfa.com/api/soap/sms/v2/server?wsdl'; // soap options $options = [     'login' => "$username/$domain",'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'compression' => (SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5), // -Compression *     'trace' => false // -Optional (debug) ]; // * Accept response compression and compress requests using gzip with compression level 5

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

// statuses var_dump($client->statuses([42846287003,42846287004]));
java
//
// after wsimport, classes can be used
//
URL url = new URL("https://sms.magfa.com/api/soap/sms/v2/server?wsdl");
MagfaSoapServer service = new MagfaSoapServer_Service(url).getMagfaSoapServer();

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

// set basic auth BindingProvider prov = (BindingProvider) service; prov.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, username + "/" + domain); prov.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

// Compression Map> httpHeaders = new HashMap<>(); httpHeaders.put("Content-Encoding", Collections.singletonList("gzip"));//this indicates you're sending a compressed request httpHeaders.put("Accept-Encoding", Collections.singletonList("gzip")); //this says you're willing to accept a compressed response prov.getRequestContext().put(MessageContext.HTTP_REQUEST_HEADERS, httpHeaders);

// call LongArray mids = new LongArray(); mids.getItem().add(123456L); mids.getItem().add(456789L); DeliveryResult result = service.statuses(mids); // result if (result.getStatus() != 0 )     System.out.println(result.getStatus()); else     for (DeliveryStatus deliveryStatus : result.getDlrs()) {         System.out.println(deliveryStatus.getStatus());     }
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 + '/' + domain, password)

# soap wsdl = 'https://sms.magfa.com/api/soap/sms/v2/server?wsdl' client = Client(wsdl=wsdl, transport=Transport(session=session)) # data long_array = client.get_type('ns1:longArray'); # call print(client.service.statuses(long_array(item=[123456L, 567890L])))
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

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

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

// SOAP Compression For .NET FrameWork 2 or later service.EnableDecompression = true;

// Call long?[] mids = new long?[] { 1234, 213434 }; deliveryResult result = service.statuses(mids); if (result.status != 0) {     Console.WriteLine("error: " + result.status); } else {     foreach (deliveryStatus s in result.dlrs)     {         Console.WriteLine("mid: " + s.mid + ", dlr:" + s.status);     } }

متد ‫‪messages

برای دريافت پيامک‌های ورودی با هر بار فراخوانی این متد، حداکثر يک‌صد پيامک ورودی به صورت آرایه برگردانده می‌شود. در صورتی که تعداد وارد نشود(URL نخست) یا عددی بیش از يک‌صد (۱۰۰) وارد شود، تعداد صد در نظر گرفته می‌شود.

پارامترها

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

پارامترنوعاجباری؟توضيحات
countintبلهتعداد پیامک‌های ورودی
shortNumberstringفرستنده

خروجی

دريافت پيامک‌های ورودی از گوشی به فرمت MessagesResult / کدهای خطا

نمونه‌کد

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

// url $url = 'https://sms.magfa.com/api/soap/sms/v2/server?wsdl'; // soap options $options = [     'login' => "$username/$domain",'password' => $password, // -Credientials     'cache_wsdl' => WSDL_CACHE_NONE, // -No WSDL Cache     'compression' => (SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5), // -Compression *     'trace' => false // -Optional (debug) ]; // * Accept response compression and compress requests using gzip with compression level 5

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

// messages var_dump($client->messages(50));

// messages of a short-number var_dump($client->messages(20, "3000xxxx"));
java
//
// after wsimport, classes can be used
//
URL url = new URL("https://sms.magfa.com/api/soap/sms/v2/server?wsdl");
MagfaSoapServer service = new MagfaSoapServer_Service(url).getMagfaSoapServer();

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

// set basic auth BindingProvider prov = (BindingProvider) service; prov.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, username + "/" + domain); prov.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

// Compression Map> httpHeaders = new HashMap<>(); httpHeaders.put("Content-Encoding", Collections.singletonList("gzip"));//this indicates you're sending a compressed request httpHeaders.put("Accept-Encoding", Collections.singletonList("gzip")); //this says you're willing to accept a compressed response prov.getRequestContext().put(MessageContext.HTTP_REQUEST_HEADERS, httpHeaders);

// call MessagesResult result = service.messages(50, ""); // MessagesResult result = service.messages(10, "3000xxxx"); // result if(result.getStatus() != 0 )     System.out.println(result.getStatus()); else     for (DatedCustomerReturnIncomingFormat msg : result.getMessages()) {         System.out.println(msg);     }
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 + '/' + domain, password)

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

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

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

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

// SOAP Compression For .NET FrameWork 2 or later service.EnableDecompression = true;

// Call int count = 50; messagesResult result = service.messages(count, ""); // messagesResult result = service.messages(count, "3000xxx"); if (result.status != 0) {     Console.WriteLine("error: " + result.status); } else {     foreach(datedCustomerReturnIncomingFormat msg in result.messages)         Console.WriteLine("msg: " + msg.body); }

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

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

CreditResult

پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
balancedecimalمانده اعتبار

MessageIdResult

پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
middecimalشناسه يکتای پیامک

SendResult

پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
messagesSendMessageآرايه‌ای از SendMessage

SendMessage

پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
idlongشناسه يکتای پیامک
userIdlongشناسه‌ی یکتای کاربر
partsintتعداد بخش‌های پيامک
tarifffloatتعرفه
alphabetstringDEFAULT برای لاتین و UCS2 برای فارسی
recipientstringگيرنده

DeliveryResult

پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
dlrsDeliveryStatusآرايه‌ای از DeliveryStatus

DeliveryStatus

پارامترنوعتوضيحات
midlongشناسه يکتای پیامک
statusintوضعيت
datestringتاريخ

MessagesResult

پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
messagesDatedCustomerReturnIncomingFormatآرايه‌ای از DatedCustomerReturnIncomingFormat

DatedCustomerReturnIncomingFormat

پارامترنوعتوضيحات
bodystringپيام
recipientNumberstringگيرنده
senderNumberstringفرستنده
datestringتاريخ (yyyy-mm-dd hh:mm:ss)

کدهای خطا

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

کد خطاتوضيحات
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 با طول آرايه گيرندگان تطابق ندارد