مقدمه
به راهنمای وبسرویس REST سامانهی صبانوین ( به فردا ) خوش آمدید.
در این راهنما در مورد چگونگی کار با وبسرویس REST سامانه صبانوین ( به فردا ) صحبت خواهیم کرد.
در ابتدا باید بگوییم که در وبسرویس REST تمامی درخواستها در قالب یک HTTP(S) Request انجام میشود.
فرمت کلی هر درخواست به شکل زیر است:
https://api.sabanovin.com/v1/YOUR-API-KEY/Region/MethodName.OutputFormat
خروجی هر دستور بسته به نیاز شما میتواند با فرمت JSON
یا XML
باشد که باید نام فرمت دلخواه را در انتهای هر درخواست قرار دهید.
احراز هویت
مثال:
https://api.sabanovin.com/v1/YOUR-API-KEY/account/balance.json
https://api.sabanovin.com/v1/YOUR-API-KEY/account/balance.xml
در تمامی مثالها بجای
YOUR-API-KEY
باید API-Key واقعی خود را قرار دهید.
وبسرویس REST سامانه صبانوین ( به فردا ) از API-Key برای وصل شدن به سیستم API خود استفاده میکند.
ابتدا شما باید یک API-Key از بخش بخش وبسرویس سامانه ایجاد کنید و سپس در تمامی درخواستها باید API-Key خود را در آدرس URL وارد نمایید.
https://api.sabanovin.com/v1/YOUR-API-KEY/Region/method-name
متدها
ارسال پیامک تکی و گروهی
[POST, GET]
لینک ارسال درخواست:
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/send.json?gateway=500043340673&to=09373889007,09176097612&text=تست
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/send.xml?gateway=500043340673&to=09373889007,09176097612&text=تست
خروجی درخواست بالا بصورت زیر است:
{
"batch_id": 354854211,
"entries": [
{
"reference_id": 326545,
"number": "9373889007",
"status": "ENQUEUED",
"datetime": "2017-10-31 11:02:31"
},
{
"reference_id": 326546,
"number": "9176097612",
"status": "ENQUEUED",
"datetime": "2017-10-31 11:02:31"
}
],
"status": {
"code": 200,
"message": "تایید شد"
}
}
<response>
<batch_id>354854211</batch_id>
<entries>
<item>
<reference_id>326545</reference_id>
<number>9373889007</number>
<status>ENQUEUED</status>
<datetime>2017-10-31 13:22:39</datetime>
</item>
<item>
<reference_id>326546</reference_id>
<number>9176097612</number>
<status>ENQUEUED</status>
<datetime>2017-10-31 13:22:39</datetime>
</item>
</entries>
<status>
<code>200</code>
<message>تایید شد</message>
</status>
</response>
از این متد برای ارسال پیامک به یک یا چند شماره استفاده نمایید.
پارامترهای ورودی
نام | نوع | الزامی | توضیحات |
---|---|---|---|
gateway | Numeric |
شماره درگاه (شماره خط) | |
to | Numeric |
گیرندگان | |
text | String |
متن پیام | |
at | String |
زمان ارسال(شمسی) |
پارامترهای خروجی
نام | توضیحات |
---|---|
batch_id | شناسه دسته پیامک(گیرندگان بیش از یک شماره) |
reference_id | شناسه پیامک |
number | گیرنده |
status | وضعیت |
datetime | تاریخ ارسال (میلادی) |
ارسال پیامک نظیر به نظیر
[POST]
لینک ارسال درخواست:
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/send_array.json
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/send_array.xml
پارامترهای ارسالی:
gateway = 500043340673 to = ["093880000", "09120000"] text = ["صبانوین ( به فردا )" ,"سامانه پیامکی"]
خروجی درخواست بالا بصورت زیر است:
{
"batch_id": 354854211,
"entries": [
{
"reference_id": 326545,
"number": "9373889007",
"status": "ENQUEUED",
"datetime": "2017-10-31 11:02:31"
},
{
"reference_id": 326546,
"number": "9176097612",
"status": "ENQUEUED",
"datetime": "2017-10-31 11:02:31"
}
],
"status": {
"code": 200,
"message": "تایید شد"
}
}
<response>
<batch_id>354854211</batch_id>
<entries>
<item>
<reference_id>326545</reference_id>
<number>9373889007</number>
<status>ENQUEUED</status>
<datetime>2017-10-31 13:22:39</datetime>
</item>
<item>
<reference_id>326546</reference_id>
<number>9176097612</number>
<status>ENQUEUED</status>
<datetime>2017-10-31 13:22:39</datetime>
</item>
</entries>
<status>
<code>200</code>
<message>تایید شد</message>
</status>
</response>
از متد برای ارسال پیامک بصورت نظیر به نظیر(هر متن متعلق به یک شماره) استفاده کنید. در این متد نحوه ارسال درخواست کمی متفاوتتر است. شما باید شماره گیرندگان را بصورت یک آرایه و همینطور متنها را نیز بصورت یک آرایه جداگانه ارسال کنید.
پارامترهای ورودی
نام | نوع | الزامی | توضیحات |
---|---|---|---|
gateway | Numeric |
شماره درگاه (شماره خط) | |
to | Array |
گیرندگان | |
text | Array |
متن پیام |
پارامترهای خروجی
نام | توضیحات |
---|---|
batch_id | شناسه دسته پیامک(گیرندگان بیش از یک شماره) |
reference_id | شناسه پیامک |
number | گیرنده |
status | وضعیت |
datetime | تاریخ ارسال (میلادی) |
دریافت وضعیت
[POST, GET]
لینک ارسال درخواست:
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/status.json?batch_id=44
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/status.xml?batch_id=44
خروجی درخواست بالا بصورت زیر است:
{
"entries": [
{
"reference_id": 187,
"number": "9373889007",
"status": "ENQUEUED",
"datetime": "2017-10-31 14:34:21"
},
{
"reference_id": 188,
"number": "9176097612",
"status": "ENQUEUED",
"datetime": "2017-10-31 14:34:21"
}
],
"status": {
"code": 200,
"message": "تایید شد"
}
}
<response>
<entries>
<item>
<reference_id>187</reference_id>
<number>9373889007</number>
<status>ENQUEUED</status>
<datetime>2017-10-31 14:34:21</datetime>
</item>
<item>
<reference_id>188</reference_id>
<number>9176097612</number>
<status>ENQUEUED</status>
<datetime>2017-10-31 14:34:21</datetime>
</item>
</entries>
<status>
<code>200</code>
<message>تایید شد</message>
</status>
</response>
از این متد برای دریافت وضعیت پیام استفاده کنید.
پارامترهای ورودی
نام | نوع | الزامی | توضیحات |
---|---|---|---|
batch_id | Numeric |
شماره دسته پیامک | |
reference_id | Numeric |
شناسه پیامک |
پارامترهای خروجی
نام | توضیحات |
---|---|
reference_id | شناسه پیامک |
number | گیرنده |
status | وضعیت |
datetime | تاریخ ارسال (میلادی) |
دریافت پیامک
[POST, GET]
لینک ارسال درخواست:
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/receive.json?gateway=500043340673&is_read=0
https://api.sabanovin.com/v1/YOUR-API-KEY/sms/receive.xml?gateway=500043340673&is_read=0
خروجی درخواست بالا بصورت زیر است:
{
"entries": [
{
"reference_id": 1244590,
"number": "0937956770",
"message": "سلام متن یک",
"datetime": "2017-11-02 10:28:19"
},
{
"reference_id": "185654",
"number": "0937762994",
"message": "سلام متن دو",
"datetime": "2017-10-27 10:28:19"
},
{
"reference_id": 2454545,
"number": "0937287124",
"message": "سلام متن سه",
"datetime": "2017-10-22 10:28:19"
},
{
"reference_id": 3454904,
"number": "0937160906",
"message": "سلام متن چهار",
"datetime": "2017-11-17 10:28:19"
}
],
"status": {
"code": 200,
"message": "تایید شد"
}
}
<response>
<entries>
<item>
<reference_id>1244590</reference_id>
<number>0937956770</number>
<message>سلام متن یک</message>
<datetime>2017-11-02 10:28:19</datetime>
</item>
<item>
<reference_id>185654</reference_id>
<number>0937762994</number>
<message>سلام متن دو</message>
<datetime>2017-10-27 10:28:19</datetime>
</item>
<item>
<reference_id>2454545</reference_id>
<number>0937287124</number>
<message>سلام متن سه</message>
<datetime>2017-10-22 10:28:19</datetime>
</item>
<item>
<reference_id>3454904</reference_id>
<number>0937160906</number>
<message>سلام متن چهار</message>
<datetime>2017-11-17 10:28:19</datetime>
</item>
</entries>
<status>
<code>200</code>
<message>تایید شد</message>
</status>
</response>
از این متد برای دریافت پیامکهای دریافتی استفاده کنید.
پارامترهای ورودی
نام | نوع | الزامی | توضیحات |
---|---|---|---|
gateway | Numeric |
شماره درگاه(شماره خط) | |
from_date | DateTime |
دریافت شده از تاریخ | |
to_date | DateTime |
دریافت شده تا تاریخ | |
is_read | Boolean |
خوانده شده یا نشده(پیشفرض خوانده نشده) |
پیام "خوانده شده" چیست؟
پیامهای خواندهشده پیامهایی هستند که قبلا یا از طریق وبسرویس و یا از طریق وبهوک آنها را دریافت کردهاید. برای دریافت پیامهای خوانده شده باید پارامتر is_read=1
قرار دهید.
پارامترهای خروجی
نام | توضیحات |
---|---|
reference_id | شناسه پیامک |
number | گیرنده |
datetime | تاریخ ارسال (میلادی) |
دریافت مانده اعتبار
[POST, GET]
لینک ارسال درخواست:
https://api.sabanovin.com/v1/YOUR-API-KEY/account/balance.json
https://api.sabanovin.com/v1/YOUR-API-KEY/account/balance.xml
خروجی درخواست بالا بصورت زیر است:
{
"entry":{
"balance":"651173.00"
},
"status":{
"code":200,
"message":"تایید شد"
}
}
<response>
<entry xmlns="https://sms.sabanovin.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<balance>1999043.70</balance>
</entry>
<status xmlns="https://sms.sabanovin.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<code>200</code>
<message>تایید شد</message>
</status>
</response>
از این متد برای دریافت اعتبار جاری خود استفاده کنید.
پارامترهای خروجی
نام | توضیحات |
---|---|
balance | مانده حساب |
شمارهگیر خودکار(افزودن شماره به دفترچه)
[POST, GET]
لینک ارسال درخواست:
https://api.sabanovin.com/v1/YOUR-API-KEY/utils/add_contact.json?group_id=467&number=09373889007
https://api.sabanovin.com/v1/YOUR-API-KEY/utils/add_contact.json?group_id=467&number=09373889007
خروجی درخواست بالا بصورت زیر است:
{
"entries":[
],
"status":{
"code":200,
"message":"شماره مورد نظر با موفقیت به گروه اضافه شد."
}
}
<response>
<entries xmlns="https://sms.sabanovin.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<item />
</entries>
<status xmlns="https://sms.sabanovin.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<code>200</code>
<message>تایید شد</message>
</status>
</response>
از این متد برای اضافه کردن یک شماره موبایل جدید به دفترچه تلفن استفاده کنید.
پارامترهای ورودی
نام | نوع | الزامی | توضیحات |
---|---|---|---|
group_id | Numeric |
شناسه گروه دفترچه تلفن | |
number | Numeric |
شماره موبایل برای درج در دفترچه تلفن | |
fname | String |
نام | |
lname | String |
نام خانوادگی | |
gateway | Numeric |
درگاه | |
draft_id | Numeric |
شناسه پیشنویس |
خطاها
خطاهای عمومی
کد خطا | توضیحات |
---|---|
401 | کد شناسه(API-KEY) وب سرویس نامعتبر |
403 | آدرس IP غیر مجاز |
400 | پارامترها ناقص هستند |
خطاهای متد ارسال(تکی و گروهی)
کد خطا | توضیحات |
---|---|
400 | پارامترها ناقص هستند یا متن پیام خالی است |
401 | اعتبار کافی نیست |
411 | گیرنده نامعتبر |
413 | تعداد گیرندگان بیش از ۱۰۰ شماره است. |
422 | درگاه ارسالی نامعتبر است |
خطاهای متد ارسال(نظیر به نظیر)
کد خطا | توضیحات |
---|---|
400 | پارامترها ناقص هستند |
401 | اعتبار کافی نیست |
411 | گیرنده نامعتبر |
422 | تعداد گیرندگان با تعداد متن برابر نیست |
413 | تعداد گیرندگان بیش از ۱۰۰ شماره است. |
جدول وضعیت پیامها
جدول وضعیت پیامها:
وضعیت | توضیح |
---|---|
ENQUEUED | پیام در صف قرار گرفته است |
SENT | ارسال شده به مخابرات |
DELIVERED | پیام تحویل داده شده |
FAILED | خطا از اپراتور |
FILTERED | فیلتر شده - بازگشت هزینه |
BLACKLIST | شماره گیرنده در بلکلیست است - برگشت هزینه |
UNDELIVERED | پیام هنوز به گیرنده تحویل داده نشده |
SCHEDULED | پیام زمانبندی شده |
INVALID_NUMBER | شماره گیرنده اشتباه - برگشت هزینه |
PENDING | در انتظار تایید توسط مدیر |
REJECTED | رد شده توسط مدیر - برگشت هزینه |
INAPPROPRIATE_CONTENT | پیام با متن نامناسب - برگشت هزینه |