راهنمای سرويس 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&...
پارامترها
تمامی پارامترها به صورت URL-ENCODED ارسال شوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
service | string | بله | getCredit |
username | string | بله | نام کاربری |
password | string | بله | رمز عبور سرويسها |
domain | string | بله | دامنه |
خروجی
ميزان مانده اعتبار (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
پارامترها
تمامی پارامترها به صورت URL-ENCODED ارسال شوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
service | string | بله | enqueue |
username | string | بله | نام کاربری |
password | string | بله | رمز عبور سرويسها |
domain | string | بله | دامنه |
from | string | بله | فرستنده |
to | string | بله | گيرنده |
message (text) | string | بله | پيام |
encoding | int | يکی از مقادير 0 (تشخيص خودکار زبان پیامک[پيش فرض])، 2 (فارسی)، 5 (ارسال به صورت 8BIT) و 6 (ارسال به صورت BINARY) | |
chkmessageid | long | شناسهی یکتای کاربر | |
int | يکی از مقادير 0 (نمايش پيامک روی صفحه نمايش گوشی بدون ذخيرهشدن [پيامک خبری])، 1 (پيامک عادی[پیشفرض])، 2 (ذخيره در سیمکارت) و 3 (ارسال به SIM toolkit) | ||
udh | string | UDH (برای اطلاعات بيشتر به مستند 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 است.
بدین صورت که پس از بروز چنین خطاهايی هنگام ارسال پيامک به همراه شناسهی يکتای کاربر،
با فراخوانی این متد به ازای شناسههای يکتا و دریافت شناسه پیامک میتوان از ارسال دوباره پيشگيری نمود .
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
service | string | بله | getMessageId |
username | string | بله | نام کاربری |
password | string | بله | رمز عبور سرويسها |
domain | string | بله | دامنه |
chkmessageid | long | شناسهی یکتای کاربر |
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
برای پيگيری وضعيت نهایی پيامک از اين متد میتوانيد استفاده نماييد
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
service | string | بله | getRealMessageStatus |
username | string | بله | نام کاربری |
password | string | بله | رمز عبور سرويسها |
domain | string | بله | دامنه |
messageId | long | بله | شناسه پيامک |
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 با طول آرايه گيرندگان تطابق ندارد |