Web Service » Feresta

وب سرویس سامانه پیام کوتاه

این راهنما جهت سهولت در کار برنامه نویسانی طراحی شده است که قصد دارند سرویس پیامهای خود را به نرم افزار های کاربردی خود ارتباط دهند.
این شرکت در حال حاضر وب سرویس ارسال پیام کوتاه و وب سرویس ارسال پیام صوتی ارئه میکند
روش های ارائه شده برای ارسال پیام کوتاه به شرح زیرمیباشد
1- وب سرویس REST
2- وب سرویس SOAP
3- ارسال از طریق URL
که از بین روش های ذکر شده این شرکت روش وب سرویس REST را پیشنهاد میدهد
روش های ارائه شده برای ارسال پیام صوتی به شرح زیرمیباشد
1- وب سرویس REST

برخی خطاها

کدهای خطا (Legacy)

پاسخ‌های خطا در این API می‌توانند به دو شکل باشند:

خطاهای سیستمی (رشته‌ای): خطاهایی که مستقیماً توسط سیستم ما شناسایی و مدیریت می‌شوند، با یک کد خطای رشته‌ای مشخص (مانند error_credit_error) در فیلد error بازگردانده می‌شوند. مقدار result در این حالت false خواهد بود.
خطاهای اپراتور (عددی): در برخی موارد، ممکن است خطایی مستقیماً از سمت اپراتورهای بالادستی (CP) رخ دهد. اگر این خطا در سیستم ما به صورت خاص نگاشت (Map) نشده باشد، کد خطای عددی دریافتی از اپراتور (مانند 14) مستقیماً در فیلد status پاسخ بازگردانده می‌شود.

لیست جامع هر دو نوع خطا در زیر آمده است. توصیه می‌شود هر دو نوع پاسخ خطا را در کد خود مدیریت کنید.

نمونه پاسخ خطای سیستمی (رشته‌ای):

				
					{
  "result": false,
  "error": "error_credit_error"
}

نمونه پاسخ خطای اپراتور (عددی):

				
					{
  "status": 14,
  "messages": [] // ممکن است فیلدهای دیگری نیز وجود داشته باشد
}

کدهای خطای سیستمی (رشته‌ای - Legacy)

کد خطا	توضیح
`erorr_login_user_not_found`	چنین کاربری یافت نشد (نام کاربری اشتباه است).
`error_login_not_like_username`	نام کاربری مشکلی دارد (مثلاً استفاده از کاراکترهای غیرمجاز یا فاصله).
`error_login_not_like_password`	پسورد مشکلی دارد (رمز عبور اشتباه است).
`error_login_not_like_accept`	دسترسی شما مسدود شده است و یا کد تایید پیامکی را وارد نکرده‌اید.
`error_register_taken_email`	چنین ایمیلی قبلاً در سیستم ثبت شده است.
`error_register_taken_user_username`	نام کاربری قبلاً استفاده شده است.
`error_register_taken_user_mobile`	شماره موبایل قبلاً استفاده شده است.
`error_no_receiver`	لیست گیرنده‌ها خالی می‌باشد.
`error_sender_number_is_not_allow`	شماره‌ی ارسال کننده مجاز نمی‌باشد (این خط متعلق به شما نیست).
`error_long_request_uniqueid`	طول کد یکتا (request_uniqueid) بیشتر از حد مجاز است.
`error_sender_number_is_disable`	شماره‌ی ارسال کننده غیرفعال می‌باشد.
`error_number_format_error`	فرمت شماره‌ی گیرنده مشکل دارد (مثلاً تعداد ارقام صحیح نیست).
`error_number_whois_error`	شماره‌ی ارسال کننده احراز هویت نشده است.
`error_sms_receiver_number_limit`	تعداد گیرنده‌ها در یک درخواست، بیشتر از حد مجاز می‌باشد.
`error_sms_send_config_is_disable`	ارسال از این پیش‌شماره (اپراتور) موقتاً غیر فعال می‌باشد.
`error_sms_price_not_found_for_admin`	خطای سیستمی: هزینه‌ی ارسال پیامک مدیر مشخص نمی‌باشد.
`error_sms_price_packageid_not_found_for_admin`	خطای سیستمی: پکیج قیمت مدیر یافت نشد.
`error_sms_price_not_found_for_user`	خطای سیستمی: هزینه‌ی ارسال پیامک برای کاربر مشخص نمی‌باشد.
`error_credit_admin_error`	شارژ مدیر (سطح بالا) کم است.
`error_credit_admin_empty_error`	خطای سیستمی: هزینه‌ی ارسال برای مدیر اشتباه محاسبه شده است.
`error_credit_error`	اعتبار کاربر برای انجام این عملیات کافی نیست.

کدهای خطای اپراتور (عددی - Legacy)

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

درگاه‌های ارسال (Gateways)

لیست کدهای خطا (status) مختص پلتفرم ESB V2.

مقادیر ذکر شده در این جدول برای تمامی متدهایی که پارامتر dargahha یا dargah دارند (مانند sms_deliver) قابل استفاده می‌باشد.

اسم درگاه	مقداری که باید استفاده شود
3000 - مسیر اصلی	`3000`
3000 - مسیر فرعی اول	`30001`
3000 - ESB اصلی	`30000`
3000 - ESB یک	`300010`
3000 - مسیر فرعی دوم	`30002`
3000 - ESB فرعی دو	`300020`
9000 - مسیر اصلی	`9000`
50002 - مسیر اصلی	`50002`
آرینتل - ارسال گروهی و بالک خدماتی	`999800`
3000 - مسیر فرعی سوم	`30003`
3000 - مسیر فرعی چهارم	`30004`
3000 - مسیر فرعی پنجم	`30005`
3000 - مسیر فرعی ششم	`30006`
3000 - مسیر فرعی هفتم	`30007`
3000 - مسیر فرعی هشتم	`30008`
3000 - مسیر فرعی نهم	`30009`
3003 - ESB	`3003`
فناپ - خدماتی	`9992101`

وضعیت پیامک‌ها (Delivery Status)

کدهای وضعیتی که در پاسخ متدهای دریافت وضعیت (مانند sms_deliver) بازگردانده می‌شوند.

عدد	معنا
-1	پیام یافت نشد - ممکن است پیام به آرشیو منتقل شده باشد.
0	بدون وضعیت - در انتظار دریافت وضعیت.
1	رسیده به گوشی.
2	نرسیده به گوشی.
3	ارسال نشده به مخابرات.
4	ارسال شده به مخابرات - (ممکن است به وضعیت آرشیو تبدیل شود).
5	لیست سیاه مخابرات - (ممکن است به معنای بازگشت وجه نیز باشد).
8	ارسال شده به اپراتور پیامکی.
9	بازگشت هزینه به دلیل ترافیک مخابرات.
10	صف ارسال.
11	اسپم.
12	اکسپایر (منقضی شده).
13	بدون روت (مسیر ارسال یافت نشد).
14	ریجکت شده (رد شده).
16	نرسیده به مخابرات.
17	بدون وضعیت دلیوربیس.

فرمت تاریخ (Unix Timestamp)

تمامی تاریخ‌ها بر اساس Unix Timestamp (ثانیه) می‌باشد. این تاریخ شامل یک عدد است که از تاریخ 1 ژانویه 1970 (UTC) شروع شده است.

زبان / پلتفرم	نمونه کد
PHP	`time()`
Python	`import time; time.time()`
Ruby	`Time.now.to_i`
Perl	`time`
Java	`long epoch = System.currentTimeMillis()/1000;`
C#	`var epoch = (DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalSeconds;`
JavaScript	`Math.round(new Date().getTime()/1000.0)`
MySQL	`SELECT unix_timestamp(now())`
PostgreSQL	`SELECT extract(epoch FROM now());`
SQLite	`SELECT strftime('%s', 'now');`
Unix Shell	`date +%s`

وب‌هوک پیامک دریافتی (Legacy MO Webhook)

با استفاده از این سرویس، پیامک دریافتی (MO) شما بلافاصله پس از دریافت به آدرسی که در تنظیمات مشخص کرده‌اید به صورت POSTارسال می‌شود. پارامترهایی که شما در آدرس URL قرار می‌دهید به صورت GET و پارامترهای اصلی به صورت POST ارسال می‌شوند.

پارامترهای ارسالی (POST):

نام پارامتر	توضیح
`from`	شماره ارسال کننده پیامک (مثال: 09132125459)
`to`	شماره دریافت کننده پیامک (مثال: 3000569999)
`note`	متن پیامک (مثال: این یک تست است)
`smsid`	شناسه پیامک (مثال: 1234567)

وب‌سرویس REST (Legacy - PersiaFava)

این API پیشنهادی این پلتفرم است. آدرس پایه (Base URL) برای تمام متدهای REST به صورت زیر می‌باشد:

/http://sms.persiafava.com /webservice/rest

احراز هویت (Legacy)

در تمامی متدهای این بخش، می‌توانید به جای ارسال login_username و login_password، از api_key استفاده نمایید.

دریافت API Key: می‌توانید api_key خود را از پنل کاربری دریافت نمایید.

				
					GET http://sms.persiafava.com/webservice/rest/sms_send?note_arr[]=سلام&api_key=API_KEY&receiver_number=09132125459&sender_number=3000569999

				
					GET http://sms.persiafava.com/webservice/rest/sms_send?note_arr[]=سلام&login_username=USERNAME&login_password=PASSWORD&receiver_number=09132125459&sender_number=3000569999

دریافت اطلاعات کاربری (user_info)

از این متد برای دریافت اطلاعات کاربری، شماره‌های اختصاصی و میزان شارژ استفاده می‌شود.

GET /user_info

پارامترها (Query):

پارامتر	نوع	ضروری؟	توضیحات
`login_username`	string	✓ (یا api_key)	نام کاربری سامانه پیامک
`login_password`	string	✓ (یا api_key)	رمز عبور سامانه پیامک

نمونه پاسخ موفق (JSON):

				
					{
  "result": true,
  "list": {
    "username": "admin_USERNAME",
    "fullname": "ارسال",
    "email": "myemailt@yahoo.com",
    "mobile": "09132125459",
    "cash": "3212509",
    "date": "1389/5/5 00:46",
    "date_expire": "1394/2/24 00:00"
  },
  "number": { ... } // اطلاعات شماره‌ها
}

ارسال پیامک (sms_send)

از این متد برای ارسال پیامک استفاده می‌شود. می‌توانید از متد `POST` یا `GET` استفاده کنید.

POST / GET /sms_send

پارامترها (Query / Form-Data):

پارامتر	نوع	ضروری؟	توضیحات
`login_username`	string	✓ (یا api_key)	نام کاربری
`login_password`	string	✓ (یا api_key)	رمز عبور
`sender_number`	string	✓	شماره ارسال کننده
`receiver_number`	string / []string	✓	شماره(های) دریافت کننده. (با کاما `,` جدا شوند یا به صورت آرایه)
`note_arr`	string / []string	✓	متن پیامک. (می‌تواند آرایه باشد برای ارسال نظیر به نظیر)
`clientids`	[]string	خیر	شناسه پیامک برای دریافت دلیوری (آرایه)
`date`	string	خیر	تاریخ ارسال (Unix Timestamp). پیش‌فرض `0` (ارسال آنی).
`request_uniqueid`	string	خیر	کد یکتا برای جلوگیری از ارسال تکراری. پیش‌فرض `0`.
`flash`	string	خیر	`ok` (برای ارسال فلش) یا `no` (پیش‌فرض).
`onlysend`	string	خیر	`ok` (ارسال با تاخیر ۳۰ ثانیه) یا `no` (پیش‌فرض).
`show_faktor`	string	خیر	`ok` (عدم ارسال و فقط نمایش هزینه) یا `no` (پیش‌فرض).
`tb_name_in_smsid`	string	خیر	`ok` (برای استفاده از متد دلیوری `sms_deliver_tb_name_in_smsid`).

نمونه درخواست (cURL - POST):

				
					curl --location -k --request POST 'http://sms.persiafava.com/webservice/rest/sms_send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_key=2:628fa6a500d3b' \
--data-urlencode 'receiver_number=09132125459' \
--data-urlencode 'sender_number=3000569999' \
--data-urlencode 'note_arr[]=hi' \
--data-urlencode 'date=0'

نمونه درخواست (cURL - POST نظیر به نظیر):

				
					curl --location -k --request POST 'http://sms.persiafava.com/webservice/rest/sms_send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_key=2:628fa6a500d3b' \
--data-urlencode 'sender_number=3000569999' \
--data-urlencode 'note_arr[]=hi 1' \
--data-urlencode 'receiver_number[]=091321254591' \
--data-urlencode 'note_arr[]=hi 2' \
--data-urlencode 'receiver_number[]=091321254592'

نمونه پاسخ موفق (JSON):

				
					{
  "result": true,
  "list": [
    "788137_5fcc745d14604_0",
    "788137_5fcc745d14604_1"
  ]
}

وضعیت پیامک (sms_deliver)

از این متد برای اطلاع از وضعیت پیامک‌های ارسال شده استفاده می‌شود. (وضعیت‌ها هر ۳۰ دقیقه به‌روزرسانی می‌شوند).

GET /sms_deliver

پارامترها (Query):

پارامتر	نوع	ضروری؟	توضیحات
`dargah`	string	✓	علامت درگاه (مثلاً `3000`). به جدول درگاه‌ها مراجعه کنید.
`smsid`	[]string	✓	آرایه‌ای از شناسه‌های پیامک‌های ارسالی.
`archive_year`	int	خیر	برای جستجو در آرشیو، سال ارسال (مثلاً 1400).
`archive_month`	int	خیر	برای جستجو در آرشیو، ماه ارسال (مثلاً 3).

نمونه درخواست (HTTP):

				
					
GET http://sms.persiafava.com/webservice/rest/sms_deliver?smsid[]=92943981&smsid[]=92943982&dargah=3000

نمونه پاسخ موفق (JSON):

				
					{
  "result": true,
  "list": {
    "92943981": "5",
    "92943982": "1"
  }
}

وضعیت پیامک (sms_deliver_tb_name_in_smsid)

مانند متد sms_deliver عمل می‌کند، اما برای پیامک‌هایی که با پارامتر tb_name_in_smsid=ok ارسال شده‌اند.

GET /sms_deliver_tb_name_in_smsid

پارامترها (Query):

پارامتر	نوع	ضروری؟	توضیحات
`smsid`	[]string	✓	آرایه‌ای از شناسه‌های پیامک‌های ارسالی.

لیست پیامک‌های دریافتی (sms_receive_list)

از این متد برای دریافت لیست پیامک‌های دریافتی (MO) استفاده می‌شود.

GET /sms_receive_list

پارامترها (Query):

پارامتر	نوع	ضروری؟	توضیحات
`login_username`	string	✓ (یا api_key)	نام کاربری
`login_password`	string	✓ (یا api_key)	رمز عبور
`page_number`	int	خیر	شماره صفحه (شروع از 1)
`perpage`	int	خیر	تعداد نتایج در هر صفحه
`read`	int	خیر	`1` (خوانده شده)، `0` (خوانده نشده)، خالی (همه)
`catid`	int	خیر	فیلتر بر اساس شماره گروه دریافتی
`number`	int	خیر	فیلتر بر اساس شماره دریافت کننده (خط اختصاصی شما)
`labelid`	int	خیر	فیلتر بر اساس شناسه کلمه کلیدی
`count`	int	خیر	فقط تعداد را نمایش بده (ارسال نشود برای دریافت لیست)
`fromid`	int	خیر	دریافت پیام‌های با ID بزرگتر از این شناسه

نمونه پاسخ موفق (JSON):

				
					{
  "result": true,
  "list": [
    {
      "id": "1227955",
      "sender_number": "09132125459",
      "receiver_number": "3000569999",
      "date": "1493483544",
      "date_fa": "1396/2/9 21:02",
      "catid": "0",
      "read": "0",
      "note": "خانم شیرانی"
    }
  ]
}

دفترچه تلفن و کلمات کلیدی

این پلتفرم همچنین شامل متدهایی برای مدیریت دفترچه تلفن و کلمات کلیدی می‌باشد (جزئیات در مستندات اصلی).

user_cat_add
user_cat_list
user_cat_info
sms_number_add
sms_number_list
sms_receive_change_read
label_list
label_new
label_edit
label_remove

وب‌سرویس SOAP (Legacy)

این روش قدیمی‌تر است و استفاده از REST پیشنهاد می‌شود.

آدرس WSDL:

http://sms.persiafava.com/ webservice/soap/smsService.php?wsdl

متد: ارسال پیامک (send_sms)

پارامترها:

پارامتر	نوع	ضروری؟	توضیحات
`username`	string	✓	نام کاربری
`password`	string	✓	رمز عبور
`sender_number`	ArrayOfString	✓	شماره ارسال کننده (آرایه)
`receiver_number`	ArrayOfString	✓	شماره(های) دریافت کننده (آرایه)
`note`	ArrayOfString	✓	متن(های) پیامک (آرایه)
`date`	ArrayOfString	✓	تاریخ ارسال (Unix Timestamp). `"0"` برای ارسال آنی.
`request_uniqueid`	ArrayOfString	✓	کد یکتا. `""` (خالی) برای عدم نیاز به چک کردن.
`flash`	ArrayOfString	✓	`"ok"` یا `"no"`.
`onlysend`	string	✓	`"ok"` (ارسال با تاخیر) یا `"no"` (ارسال آنی).

نمونه درخواست (XML - SOAP):

				
					<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="sms_webservice_wsdl" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns2="urn:sms_webservice_wsdl" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <ns1:send_sms>
      <username xsi:type="xsd:string">username here</username>
      <password xsi:type="xsd:string">password here</password>
      <sender_number SOAP-ENC:arrayType="xsd:string[1]" xsi:type="ns2:ArrayOfString">
        <item xsi:type="xsd:string">3000569999</item>
      </sender_number>
      <receiver_number SOAP-ENC:arrayType="xsd:string[1]" xsi:type="ns2:ArrayOfString">
        <item xsi:type="xsd:string">+989126133361</item>
      </receiver_number>
      <note SOAP-ENC:arrayType="xsd:string[1]" xsi:type="ns2:ArrayOfString">
        <item xsi:type="xsd:string">تست</item>
      </note>
      <date SOAP-ENC:arrayType="xsd:string[1]" xsi:type="ns2:ArrayOfString">
        <item xsi:type="xsd:string">0</item>
      </date>
      <request_uniqueid SOAP-ENC:arrayType="xsd:string[1]" xsi:type="ns2:ArrayOfString">
        <item xsi:type="xsd:string"></item>
      </request_uniqueid>
      <flash SOAP-ENC:arrayType="xsd:string[1]" xsi:type="ns2:ArrayOfString">
        <item xsi:type="xsd:string">no</item>
      </flash>
      <onlysend xsi:type="xsd:string">ok</onlysend>
    </ns1:send_sms>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

متد: پیام‌های دریافتی (sms_receive)

از این متد برای گرفتن لیست پیام‌های دریافتی (MO) استفاده می‌شود.

پارامترها:

پارامتر	نوع	ضروری؟	توضیحات
`username`	string	✓	نام کاربری
`password`	string	✓	رمز عبور
`number`	string	✓	شماره خط اختصاصی
`catid`	int	✓	شناسه دسته‌بندی پیامک‌های دریافتی
`start`	int	✓	شناسه شروع لیست (شروع از 1)
`perpage`	int	✓	تعداد پیامک در هر صفحه (پیش‌فرض 30)
`read`	int	✓	`-1` (مهم نیست)، `0` (خوانده نشده)، `1` (خوانده شده)
`order`	string	✓	`'ASC'` (صعودی) یا `'DESC'` (نزولی)

وب‌سرویس GET (Legacy)

این روش به دلیل ارسال رمز عبور در URL، **ناامن** بوده و استفاده از آن به هیچ وجه توصیه نمی‌شود.

آدرس پایه:

http://sms.persiafava.com/ send_via_get/send_sms.php

متد: ارسال پیامک (send_sms)

GET /send_sms.php

پارامترها (Query):

پارامتر	نوع	ضروری؟	توضیحات
`username`	string	✓	نام کاربری
`password`	string	✓	رمز عبور
`sender_number`	string	✓	شماره ارسال کننده
`receiver_number`	string	✓	شماره(های) دریافت کننده (جدا شده با `,`)
`note`	string	✓	متن پیامک
`request_uniqueid`	string	خیر	کد یکتا (پیش‌فرض `0`)
`ersal_flash`	string	خیر	`ok` (فلش) یا `no` (معمولی)
`onlysend`	string	خیر	`ok` (ارسال با تاخیر) یا `no` (آنی)

نمونه درخواست (HTTP):

				
					GET http://sms.persiafava.com/send_via_get/send_sms.php?note=سلام&username=USERNAME&password=PASSWORD&receiver_number=09132125459&sender_number=3000569999

نمونه پاسخ موفق (Plain Text):

				
					92943981,92943982

وب‌سرویس پیام صوتی (VMS - Legacy)

متدهای مربوط به ارسال پیام صوتی (VMS).

آدرس پایه:

http://sms.persiafava.com/ webservice/vms/api.php

متد: ارسال پیام صوتی (send)

POST /api.php

پارامترها (Form-Data):

پارامتر	نوع	ضروری؟	توضیحات
`login_username`	string	✓	نام کاربری
`login_password`	string	✓	رمز عبور
`api`	string	✓	مقدار ثابت: `send`
`receiver_number`	string	✓	شماره(های) گیرنده (جدا شده با `,`)
`uniqid`	string	خیر	کد یکتا (پیش‌فرض `0`)
`kind`	string	✓	کانال ارسال (مقدار فعلی: `yek`)
`billing_note`	string	خیر	توضیحات (برای درج در امور مالی)
`fileToUpload`	File	✓	فایل صوتی (multipart/form-data)

متد: احراز هویت صوتی (otp)

POST /api.php

پارامترها (Form-Data):

پارامتر	نوع	ضروری؟	توضیحات
`login_username`	string	✓	نام کاربری
`login_password`	string	✓	رمز عبور
`api`	string	✓	مقدار ثابت: `send`
`receiver_number`	string	✓	شماره(های) گیرنده (جدا شده با `,`)
`uniqid`	string	خیر	کد یکتا (پیش‌فرض `0`)
`kind`	string	✓	کانال ارسال (مقدار فعلی: `yek`)
`billing_note`	string	خیر	توضیحات (برای درج در امور مالی)
`fileToUpload`	File	✓	فایل صوتی (multipart/form-data)

پلتفرم ۱.۵ (ESB - Persia Fava)

این سرویس ESB با متدهای REST و به صورت امن HTTPS (پورت 7074) طراحی شده است.

احراز هويت (ESB 1.5)

احراز هويت اين سرويس بر اساس auth string در هدر HTTP با کليد Authorization و به صورت HTTP Basic Authentication است.

				
					POST https://sms.persiafava.com:7074/api/v1/sms/send/3000
Authorization: Basic [auth string]

متد ارسال (send)

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

POST https://sms.persiafava.com:7074/ api/v1/sms/send/3000

پارامترها (Body - JSON/FORM):

پارامتر	نوع	ضروری؟	توضیحات
`senders`	[]string	✓	آرایه‌ای از فرستنده‌ها (مثال: `["3000xxxxxx"]`)
`recipients`	[]string	✓	آرایه‌ای از گیرنده‌ها (مثال: `["+989xxxxxxxxx"]`)
`messages`	[]string	✓	آرایه‌ای از پیام‌ها (باید UTF-8 باشد)
`uids`	[]long	✓	آرایه‌ای از شناسه‌های یکتای کاربر (به ازای هر گیرنده)

نمونه پاسخ موفق:

				
					{
  "status": 0,
  "messages": [
    {
      "status": 0,
      "id": 111111111,
      "userId": 1224,
      "parts": null,
      "tariff": null,
      "alphabet": null,
      "recipient": "98913xxxxxxx"
    }
  ]
}

نمونه پاسخ خطا:

				
					{
  "status": 19,
  "messages": []
}

وب‌هوک دلیوری (ESB 1.5 Webhook)

مشتری باید آدرسی را ارائه دهد تا وضعیت پیامک‌ها به صورت GET به آن ارسال گردد.

پارامترهای ارسالی (Query):

پارامتر	نوع	ضروری؟	توضیحات
`clientid`	long	✓	شناسه یکتای کاربر (`uid`) که هنگام ارسال ثبت شده.
`deliver_date`	long	✓	زمان دریافت دلیوری (Unix Timestamp).
`deliver_state`	int	✓	وضعیت دلیوری (جدول زیر).

کدهای وضعیت دلیوری (ESB 1.5)

مقدار	معنا
1	رسیده به گوشی
2	نرسیده به گوشی
3	ارسال نشده به مخابرات
4	ارسال شده به مخابرات
5	لیست سیاه مخابرات
8	ارسال شده به مخابرات

کدهای خطای پلتفرم ESB 1.5

لیست کدهای خطا (status) مختص پلتفرم ESB 1.5.

کد خطا	توضیحات
1	شماره گيرنده نادرست است.
2	شماره فرستنده نادرست است.
14	مانده اعتبار ريالی کافی نيست.
15	سرور در هنگام ارسال پيام مشغول برطرف نمودن ايراد داخلی بوده است. (ارسال مجدد)
16	حساب غيرفعال است.
17	حساب منقضی شده است.
19	درخواست معتبر نيست (خطا در احراز هویت).
20	شماره فرستنده به حساب تعلق ندارد.
22	اين سرويس برای حساب فعال نشده است.
23	امکان پردازش درخواست جديد وجود ندارد، لطفا دوباره سعی كنيد.
24	شناسه پيامک معتبر نيست (قدیمی یا اشتباه).
25	نام متد درخواستی معتبر نيست.
28	شماره گیرنده، بر اساس پیش‌شماره مسدود است.
29	آدرس IP مبدا، اجازه دسترسی به این سرویس را ندارد.
101	طول آرايه `messages` با `recipients` تطابق ندارد.
103	طول آرايه `senders` با `recipients` تطابق ندارد.
106	آرايه‌ی گيرندگان خالی است.
107	طول آرايه گيرندگان بيشتر از طول مجاز (۱۰۰) است.
108	آرايه‌ی فرستندگان خالی است.

پلتفرم ۲ (ESB V2)

سرویس ESB V2 با متدهای REST طراحی شده است. در اين سرويس به ازای هر پیامک ارسالی به یک گیرنده، باید یک شناسه‌ یکتا (uids) جهت پيگیری وضعيت ارایه شود.

نکات مهم:

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

احراز هويت (ESB V2)

احراز هويت اين سرويس بر اساس auth string در هدر HTTP با کليد Authorization و به صورت HTTP Basic Authentication است.

				
					Authorization: Basic [auth string]

متد ارسال نظیر به نظیر (PeerToPeer)

برای ارسال پيامک‌های متفاوت به گيرنده‌های متفاوت در یک درخواست (حداکثر ۱۰۰ عدد). پارامترهای senders، messages و recipients باید آرایه‌هایی با طول یکسان باشند.

مهم: جهت ارسال پیامک‌های رمز یکبار مصرف (OTP) فقط از متد Otp که در ادامه توضیح داده شده است، استفاده کنید.

POST https://sms.persiafava.com:3000/ PeerToPeer

پارامترها (Body - JSON):

پارامتر	نوع	ضروری؟	توضیحات
`senders`	[]string	✓	آرایه‌ای از فرستنده‌ها (مثال: `["9899921xxxxx"]`)
`recipients`	[]string	✓	آرایه‌ای از گیرنده‌ها (مثال: `["+989xxxxxxxxx"]`)
`messages`	[]string	✓	آرایه‌ای از پیام‌ها
`uids`	[]string	✓	آرایه‌ای از شناسه‌های یکتای کاربر. (به ازای هر گیرنده یک شناسه یکتا)

نمونه در خواست:

				
					curl -k -v --location 'https://sms.persiafava.com:3000/PeerToPeer' \
--header 'Authorization: Basic US9Z........................6g' \
--header 'Content-Type: application/json' \
--data '{
    "senders": [
        "989992178097"
    ],
    "messages": [
        "تست"
    ],
    "recipients": [
        "+989127962521"
    ],
    "uids": [
        "202505111322032890"
    ]
}'

نمونه پاسخ موفق:

				
					{
  "status": 0,
  "smsids": [
    "ABC123",
    "DEF456"
  ]
}

نمونه پاسخ خطا:

				
					{
  "status": 19,
  "messages": "error note" 
}

متد ارسال گروهی (Bulk)

از این متد برای ارسال یک متن از یک سرشماره به چندین گیرنده استفاده می‌شود.

POST https://sms.persiafava.com:3001/Bulk

پارامترها (Body - JSON):

پارامتر	نوع	ضروری؟	توضیحات
`sender`	string	✓	فرستنده (یک شماره)
`recipients`	[]string	✓	آرایه‌ای از گیرنده‌ها
`message`	string	✓	متن پیام (یک متن)
`uids`	[]string	✓	آرایه‌ای از شناسه‌های یکتای کاربر (به ازای هر گیرنده)

نمونه پاسخ موفق:

				
					{
  "status": 0,
  "smsids": [
    "ABC123",
    "DEF456",
    "GHI789"
  ]
}

متد ارسال پیامک OTP

این متد *فقط* برای ارسال پیامک‌های One Time Password (یک گیرنده، یک فرستنده، یک متن) استفاده می‌شود.

POST https://sms.persiafava.com:3002/Otp

پارامترها (Body - JSON):

پارامتر	نوع	ضروری؟	توضیحات
`sender`	string	✓	فرستنده
`recipient`	string	✓	گیرنده (مثال: `+989132677411`)
`message`	string	✓	متن پیام (مثال: `کد احراز هویت شما 123456`)
`uid`	string	✓	شناسه یکتای کاربر (جلوگیری از تکرار در بازه ۲ ساعته)

نمونه پاسخ موفق:

				
					{
  "status": 0,
  "smsid": "4040@1402@3@789as1"
}

متد دریافت دلیوری (Delivery)

دریافت وضعیت دلیوری پیامک‌های ارسال شده در ۴۸ ساعت اخیر. در این متد، بدنه درخواست (Body) فقط شامل آرایه‌ای از `smsid` ها است.

POST https://sms.persiafava.com:3003/ Delivery

نمونه در خواست:

				
					[
    "SMSID1",
    "SMSID2",
    "SMSID3"
]

نمونه پاسخ موفق:

				
					{
  "dlrs": {
    "SMSID1": {
      "DateDlr": 12345678912,
      "DateSent": 12345678912,
      "dlr": 1,
      "uid": "1234453sdas"
    },
    "SMSID2": {
      "DateDlr": 12345678912,
      "DateSent": 12345678912,
      "dlr": 2,
      "uid": "1234453sdas"
    }
  },
  "status": 0
}

متد دریافت اطلاعات کاربر (UserInfo)

در این متد صرفاً هدر احراز هویت ارسال شده و اطلاعات کاربر بازگردانده می‌شود.

GET https://sms.persiafava.com:3006/ UserInfo

نمونه در خواست:

				
					curl --location 'https://sms.persiafava.com:3006/UserInfo' \
--header 'Authorization: Basic Uxxxx'

نمونه پاسخ موفق:

				
					{
  "status": 0,
  "userInfo": {
    "Username": "admin_mojahedi",
    "Fullname": "حسین صادقی",
    "Email": "sadeghi@gmail.com",
    "Mobile": "+989132125459",
    "Cash": 40034755,
    "Date": 1667161800,
    "DateExpire": 4531408200
  }
}

متد دریافت لیست پیامک‌های دریافتی (ReceivedList)

این متد لیست پیامک‌های دریافتی (MO) را بازمی‌گرداند. این متد پیام‌ها را به عنوان “خوانده شده” علامت نمی‌زند.

POST https://sms.persiafava.com:3004/ ReceivedList

پارامترها (Body - JSON):

پارامتر	نوع	ضروری؟	توضیحات
`page_number`	int	خیر	شماره صفحه (شروع از 1)
`perpage`	int	خیر	تعداد در هر صفحه (بین 1 تا 100)
`read`	int	خیر	`-1`: همه، `0`: خوانده نشده، `1`: خوانده شده
`catid`	int	خیر	شماره گروه (فیلتر)
`number`	int	خیر	شماره دریافت کننده (فیلتر)
`labelid`	int	خیر	شناسه کلمه کلیدی (فیلتر)
`count`	bool	خیر	`true` (برای دریافت تعداد کل نتایج)
`fromid`	int	خیر	دریافت پیام‌های با ID بزرگتر از این مقدار
`ordermode`	string	خیر	`DESC` (نزولی) یا `ASC` (صعودی)

نمونه پاسخ موفق:

				
					{
  "list": [
    {
      "id": 4583095,
      "userid": 201,
      "note": "تست",
      "date": 1704912561,
      "sender_number": "09xxxxxxxxx",
      "receiver_number": "4040xxxx",
      "smsid": "40d6ffb9-9da1-4025-b297-9dfed12ea792",
      "read": "0",
      "...": "..."
    }
  ],
  "count": 20
}

متد علامت‌گذاری پیامک‌های دریافتی (ReceivedChangeRead)

این متد برای علامت‌گذاری پیامک‌های دریافتی (MO) به عنوان خوانده شده/نشده استفاده می‌شود تا از دریافت تکراری آن‌ها در متد `ReceivedList` جلوگیری شود.

POST https://sms.persiafava.com:3005/ ReceivedChangeRead

پارامترها (Body - JSON):

پارامتر	نوع	ضروری؟	توضیحات
`read`	int	✓	`1` (خوانده شده) یا `0` (خوانده نشده)
`ids`	[]int	✓	آرایه‌ای از `id` های دریافتی از متد `ReceivedList`

نمونه درخواست:

				
					{
  "read": 1,
  "ids": [4581399, 12666]
}

نمونه پاسخ موفق:

				
					{
  "status": 0
}

وب‌هوک دلیوری (ESB V2 Delivery Webhook)

گیت‌وی می‌تواند وضعیت پیامک‌ها را به صورت `POST` (Content-Type: application/json) به آدرس اختصاصی شما ارسال کند. در هر درخواست حداکثر وضعیت ۱۰۰ پیامک ارسال می‌گردد.

نکته: وضعیت نهایی پیامک‌ها نهایتاً تا ۲۴ ساعت پس از ارسال، به این آدرس ارسال می‌شوند.

نمونه پاسخ موفق:

				
					[
    {
        "clientid": "27_62db95259e0e7_0",
        "sender_number": "1234567890",
        "receiver_number": "9876543210",
        "deliver_date": 1643723400,
        "deliver_state": 2
    },
    {
        "clientid": "27_62db95259756a_0",
        "sender_number": "1234567891",
        "receiver_number": "9876543211",
        "deliver_date": 1643723401,
        "deliver_state": 1
    }
]

وب‌هوک پیامک دریافتی (ESB V2 MO Webhook)

پیامک‌های دریافتی (MO) بلافاصله پس از دریافت به آدرس شما به صورت `POST` (Content-Type: application/x-www-form-urlencoded) ارسال می‌شوند.

پارامترهای ارسالی:

from: شماره ارسال کننده
to: شماره دریافت کننده
note: متن پیامک
smsid: شناسه پیامک

کدهای خطای پلتفرم ESB V2

لیست کدهای خطا (status) مختص پلتفرم ESB V2.

کد خطا	توضیحات
1	نام متد درخواستی معتبر نيست.
2	هدر احراز هویت وجود ندارد.
3	فرمت درخواست احراز هویت معتبر نيست.
4	سرور در هنگام ارسال پيام مشغول برطرف نمودن ايراد داخلی یک بوده است. (ارسال مجدد درخواست)
5	سرور در هنگام ارسال پيام مشغول برطرف نمودن ايراد داخلی دو بوده است. (ارسال مجدد درخواست)
6	سرور در هنگام ارسال پيام مشغول برطرف نمودن ايراد داخلی سه بوده است. (ارسال مجدد درخواست)
7	حساب کاربری یافت نشد (تماس با مدیریت سامانه).
8	حساب غيرفعال است. (تماس با مدیریت سامانه)
9	آدرس IP مبدا، اجازه دسترسی به این سرویس را ندارد.
10	فرمت جیسون ارسالی مشکل دارد.
11	فرمت جیسون ارسالی اطلاعات حساب کاربری مشکل دارد (تماس با پشتیبانی).
12	خطا در تولید جیسون خروجی.
20	طول آرايه پارامترهای ورودی با هم تطابق ندارد (مثلاً تعداد `uids` با `recipients`).
21	آرایه `uid` خالی است.
22	طول آرايه پارامتر `uid` بيشتر از طول مجاز است.
23	شماره فرستنده به حساب تعلق ندارد.
24	مانده اعتبار ريالی کافی نيست.
25	شناسه پيامک معتبر نيست (ممکن است تکراری باشد یا بیش از ۲۴ ساعت گذشته باشد).
26	فرمت شماره گیرنده معتبر نیست.
27	شماره گیرنده در لیست سیاه قرار دارد.

کدهای وضعیت دلیوری (ESB V2)

کدهایی که در فیلد `dlr` (در متد Delivery) یا `deliver_state` (در وب‌هوک دلیوری) بازگردانده می‌شوند.

کد	توضیح
-2	پیام یافت نشد - حذف شده
-1	پیام یافت نشد - ممکن است پیام به آرشیو منتقل شده باشد
0	بدون وضعیت - در انتظار دریافت وضعیت
1	رسیده به گوشی
2	نرسیده به گوشی
3	ارسال نشده به مخابرات
4	ارسال شده به مخابرات
5	لیست سیاه مخابرات
8	ارسال شده به اپراتور پیامکی
9	بازگشت هزینه به دلیل ترافیک مخابرات
10	صف ارسال
11	اسپم
12	اکسپایر
13	بدون روت
14	ریجکت شده
16	نرسیده به مخابرات
17	بدون وضعیت دلیوربیس

فهرست مستندات

موارد کلی

وب سرویس REST

وب سرویس SOAP

وب سرویس GET

وب‌سرویس پیام صوتی

پلتفرم ۱.۵ ESB

پلتفرم ۲ ESB