منو Navbar
json xml
  • مقدمه
  • احراز هویت
  • متدها
  • خطاها
  • جدول وضعیت پیام‌ها
  • مقدمه

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

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

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

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

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

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

    احراز هویت

    مثال:

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

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

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

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

    متدها

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

    [POST, GET]

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

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

    {
      "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]

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

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

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

    {
      "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]

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

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

    {
      "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]

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

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

    {
      "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]

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

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

    {
       "entry":{
          "balance":"651173.00"
       },
       "status":{
          "code":200,
          "message":"تایید شد"
       }
    }
    
    <response>
       <entry xmlns="http://sms.asan-payam.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://sms.asan-payam.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]

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

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

    {
       "entries":[
    
       ],
       "status":{
          "code":200,
          "message":"شماره مورد نظر با موفقیت به گروه اضافه شد."
       }
    }
    
    <response>
       <entries xmlns="http://sms.asan-payam.ir" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <item />
       </entries>
       <status xmlns="http://sms.asan-payam.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 شناسه پیش‌نویس

    خطاها

    خطاهای عمومی

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