راهنمای سرويس HTTP

این نسخه تنها با متد GET سازگار است.

آغاز به کار

مقدمه

سرويس ‍HTTP به صورت فراخوانی مستقيم URL با متد GET و به صورت امن HTTPS، طراحی شده و به راحتی در همه‌ی زبان‌های برنامه‌نويسی قابل استفاده است. به دلیل سربار کم این سرويس، پهنای باند مصرفی در آن بسیار اندک خواهد بود. شایان ذکر است در این سرويس تنها از UTF-8 پشتيبانی می‌شود.
سامانه به ازای هر پيامک ارسالی، شناسه‌ای یکتا جهت پيگیری وضعيت ارایه می‌نمايد. همچنین برای افزايش سرعت ارسال می‌توانيد از فراخوانی‌های همزمان استفاده نماييد.
بیشینه تعداد شماره گيرنده در درخواست‌ها يک‌صد عدد است. ارسال بيش از این تعداد با کد خطا مواجه خواهد شد.

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

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

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

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

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

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

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

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

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

احراز هويت

احراز هويت این سرويس با استفاده از ارسال نام‌کاربری، رمزعبور سرويس و دامنه به صورت پارامتر در درخواست‌ها است

متدهای HTTP

متد HTTPتوضيحات
GETاین نسخه تنها با متد GET سازگار است.

متدها

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

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

متد getCredit

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

URL

https://sms.magfa.com/magfaHttpService?service=getcredit&...

https://sms.magfa.com/api/http/sms/v1?service=getcredit&...

پارامترها

تمامی پارامترها به صورت URL-ENCODED ارسال شوند

پارامترنوعاجباری؟توضيحات
servicestringبلهgetCredit
usernamestringبلهنام کاربری
passwordstringبلهرمز عبور سرويس‌ها
domainstringبلهدامنه

خروجی

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

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --get \     --data-urlencode "username=$username" \     --data-urlencode "password=$password" \     --data-urlencode "domain=$domain" \     --data-urlencode 'service=getcredit' \     'https://sms.magfa.com/api/http/sms/v1'
php
// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data $data = []; $data['username'] = $username; $data['password'] = $password; $data['domain'] = $domain;

$data['service'] = 'getcredit';      // url $url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call $contents = file_get_contents($url);
java
// credentials
String username = "username";
String password = "password";
String domain = "domain";

// url URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=getcredit&username=" + username + "&password=" + password + "&domain=" + domain + "");

URLConnection con = url.openConnection(); InputStream in = con.getInputStream(); String encoding = con.getContentEncoding();

encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);
python
# https://requests.readthedocs.io/en/master/
import requests

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

# call contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=getcredit&username=" + username + "&password=" + password + "&domain=" + magfa + ""); print(contents.text());
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Client using var client = new HttpClient();

// Call var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=getcredit&username="+username+"&password="+password+"&domain="+domain+"");

متد enqueue

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

URL

https://sms.magfa.com/magfaHttpService?service=enqueue&...

https://sms.magfa.com/api/http/sms/v1?service=enqueue&...

پارامترها

تمامی پارامترها به صورت URL-ENCODED ارسال شوند

پارامترنوعاجباری؟توضيحات
servicestringبلهenqueue
usernamestringبلهنام کاربری
passwordstringبلهرمز عبور سرويس‌ها
domainstringبلهدامنه
fromstringبلهفرستنده
tostringبلهگيرنده
message (text)stringبلهپيام
encodingintيکی از مقادير 0 (تشخيص خودکار زبان پیامک[پيش فرض])، 2 (فارسی)، 5 (ارسال به صورت 8BIT) و 6 (ارسال به صورت BINARY)
chkmessageidlongشناسه‌ی یکتای کاربر
mclassintيکی از مقادير 0 (نمايش پيامک روی صفحه نمايش گوشی بدون ذخيره‌شدن [پيامک خبری])، 1 (پيامک عادی[پیش‌فرض])، 2 (ذخيره در سیم‌کارت) و 3 (ارسال به SIM toolkit)
udhstringUDH (برای اطلاعات بيشتر به مستند UDH مراجعه نماييد)
فرستنده

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

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

شماره‌ی گيرنده را به صورت‌های زير می‌توانيد مورد استفاده قرار دهيد. برای ارسال به چندين گيرنده، شماره‌ها را با کاما [,] از هم جدا نمایید

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

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

خروجی

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

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --get \     --data-urlencode "username=$username" \     --data-urlencode "password=$password" \     --data-urlencode "domain=$domain" \     --data-urlencode 'service=enqueue' \     --data-urlencode 'from=983000' \     --data-urlencode 'to=0912xxxxxxx,0935xxxxxxx' \     --data-urlencode 'text=sample text' \     'https://sms.magfa.com/api/http/sms/v1'
php
// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data $data = []; $data['username'] = $username; $data['password'] = $password; $data['domain'] = $domain;

$data['service'] = 'enqueue';

$data['from'] = '983000xxxx'; $data['to'] = '0912xxxxxxx,0935xxxxxxx'; $data['text'] = 'sample text';

// url $url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call $contents = file_get_contents($url);
java
// credentials
String username = "username";
String password = "password";
String domain = "domain";

// url URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=enqueue&username=" + username + "&password=" + password + "&domain=" + domain + "&from=983000&to=0912xxxxxxx,0935xxxxxxx&text=sample text");

URLConnection con = url.openConnection();

InputStream in = con.getInputStream(); String encoding = con.getContentEncoding(); encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);
python
# https://requests.readthedocs.io/en/master/
import requests

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

# call contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=enqueue&username=" + username + "&password=" + password + "&domain=" + magfa + "&from=983000&to=0912xxxxxxx,0935xxxxxxx&text=sample text"); print(contents.text());
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Client using var client = new HttpClient();

// Call var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=enqueue&username="+username+"&password="+password+"&domain="+domain+"&from=983000&to=0912xxxxxxx,0935xxxxxxx&text=sample text");

متد ‫‪getMessageId

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

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

URL

https://sms.magfa.com/magfaHttpService?service=getMessageId&...

https://sms.magfa.com/api/http/sms/v1?service=getMessageId&...

خروجی

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

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --get \     --data-urlencode "username=$username" \     --data-urlencode "password=$password" \     --data-urlencode "domain=$domain" \     --data-urlencode 'service=getmessageid' \     --data-urlencode 'chkmessageid=123' \     'https://sms.magfa.com/api/http/sms/v1'
php
// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data $data = []; $data['username'] = $username; $data['password'] = $password; $data['domain'] = $domain;

$data['service'] = 'getMessageId';

$data['chkmessageid'] = 123;      // url $url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call $contents = file_get_contents($url);
java
// credentials
String username = "username";
String password = "password";
String domain = "domain";

// url URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=getmessageid&username=" + username + "&password=" + password + "&domain=" + domain + "&chkmessageid=123");

URLConnection con = url.openConnection(); InputStream in = con.getInputStream(); String encoding = con.getContentEncoding(); encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);
python
# https://requests.readthedocs.io/en/master/
import requests

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

# call contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=getmessageid&username=" + username + "&password=" + password + "&domain=" + magfa + "&chkmessageid=123"); print(contents.text());
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Client using var client = new HttpClient();

// Call var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=getmessageid&username="+username+"&password="+password+"&domain="+domain+"&chkmessageid=123");

متد ‫‪getRealMessageStatus

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

پارامترنوعاجباری؟توضيحات
servicestringبلهgetRealMessageStatus
usernamestringبلهنام کاربری
passwordstringبلهرمز عبور سرويس‌ها
domainstringبلهدامنه
messageIdlongبلهشناسه پيامک

URL

https://sms.magfa.com/magfaHttpService?service=getRealMessageStatus&...

https://sms.magfa.com/api/http/sms/v1?service=getRealMessageStatus&...

خروجی

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

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

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --get \     --data-urlencode "username=$username" \     --data-urlencode "password=$password" \     --data-urlencode "domain=$domain" \     --data-urlencode 'service=getrealmessagestatus' \     --data-urlencode 'messageId=121212121' \     'https://sms.magfa.com/api/http/sms/v1'
php
// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data $data = []; $data['username'] = $username; $data['password'] = $password; $data['domain'] = $domain;

$data['service'] = 'getrealmessagestatus';

$data ['messageId'] = '121212121';      // url $url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call $contents = file_get_contents($url);
java
// credentials
String username = "username";
String password = "password";
String domain = "domain";

// url URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=getrealmessagestatus&username=" + username + "&password=" + password + "&domain=" + domain + "&messageId=121212121");

URLConnection con = url.openConnection(); InputStream in = con.getInputStream(); String encoding = con.getContentEncoding(); encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);
python
# https://requests.readthedocs.io/en/master/
import requests

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

# call contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=getrealmessagestatus&username=" + username + "&password=" + password + "&domain=" + magfa + "&messageId=121212121"); print(contents.text())
C#
// Credentials
string username = "username";
string password = "password";
string domain = "magfa";

// Client using var client = new HttpClient();

// Call var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=getrealmessagestatus&username="+username+"&password="+password+"&domain="+domain+"&messageId=121212121");

کدهای خطا

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

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