مقدمه

به راهنمای وب‌سرویس REST سامانه‌ی کاوه پیامک خوش آمدید.

در این راهنما در مورد چگونگی کار با وب‌سرویس REST سامانه کاوه پیامک صحبت خواهیم کرد.

در ابتدا باید بگوییم که در وب‌سرویس REST تمامی درخواست‌ها در قالب یک HTTP(S) Request انجام می‌شود.

فرمت کلی هر درخواست به شکل زیر است:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/Region/MethodName.OutputFormat

خروجی هر دستور بسته به نیاز شما می‌تواند با فرمت JSON یا XML باشد که باید نام فرمت دلخواه را در انتهای هر درخواست قرار دهید.

احراز هویت

مثال:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/account/balance.json

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/account/balance.xml

در تمامی مثال‌ها بجای YOUR-API-KEY باید API-Key واقعی خود را قرار دهید.

وب‌سرویس REST سامانه کاوه پیامک از API-Key برای وصل شدن به سیستم API خود استفاده می‌کند.

ابتدا شما باید یک API-Key از بخش بخش وب‌سرویس سامانه ایجاد کنید و سپس در تمامی درخواست‌ها باید API-Key خود را در آدرس URL وارد نمایید.

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/Region/method-name

بجای YOUR-API-KEY باید API-Key واقعی خود را قرار دهید.

متدها

ارسال پیامک تکی و گروهی

[POST, GET]

لینک ارسال درخواست:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/sms/send.json?gateway=500043340673&to=09373889007,09176097612&text=تست

http://api.kavehpayamak.ir/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`	زمان ارسال(شمسی)

برای تعداد بیش از یک گیرنده، شماره ها را با کاما , از هم جدا کنید.

برای ارسال پیام در آینده تاریخ را بصورت شمسی همراه با زمان وارد کنید.
مثال: 14:20 1398/10/10

پارامتر‌های خروجی

نام	توضیحات
batch_id	شناسه دسته پیامک(گیرندگان بیش از یک شماره)
reference_id	شناسه پیامک
number	گیرنده
status	وضعیت
datetime	تاریخ ارسال (میلادی)

بصورت پیش‌فرض مقدار datetime تاریخ میلادی خواهد بود. اگر مایل به دریافت تاریخ شمسی(جلالی) هستید، باید در header درخواستی مقدار Jalali-DateTime را برابر با 1 قرار دهید.

ارسال پیامک نظیر به نظیر

[POST]

لینک ارسال درخواست:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/sms/send_array.json

http://api.kavehpayamak.ir/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]

لینک ارسال درخواست:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/sms/status.json?batch_id=44

http://api.kavehpayamak.ir/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]

لینک ارسال درخواست:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/sms/receive.json?gateway=500043340673&is_read=0

http://api.kavehpayamak.ir/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]

لینک ارسال درخواست:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/account/balance.json

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/account/balance.xml

خروجی درخواست بالا بصورت زیر است:

{
   "entry":{
      "balance":"651173.00"
   },
   "status":{
      "code":200,
      "message":"تایید شد"
   }
}

<response>
   <entry xmlns="http://tnt.kavehpayamak.ir" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <balance>1999043.70</balance>
   </entry>
   <status xmlns="http://tnt.kavehpayamak.ir" 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]

لینک ارسال درخواست:

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/utils/add_contact.json?group_id=467&number=09373889007

http://api.kavehpayamak.ir/v1/YOUR-API-KEY/utils/add_contact.json?group_id=467&number=09373889007

خروجی درخواست بالا بصورت زیر است:

{
   "entries":[

   ],
   "status":{
      "code":200,
      "message":"شماره مورد نظر با موفقیت به گروه اضافه شد."
   }
}

<response>
   <entries xmlns="http://tnt.kavehpayamak.ir" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <item />
   </entries>
   <status xmlns="http://tnt.kavehpayamak.ir" 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`	شناسه پیش‌نویس

اگر میخواهید پس از درج شماره موبایل به دفترچه تلفن، پیامی به همان شماره ارسال کنید، باید دو مقدار gateway و draft_id را نیز به پارامترهای ورودی خود اضافه کنید.

خطاها

خطاهای عمومی

کد خطا	توضیحات
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	پیام با متن نامناسب - برگشت هزینه