ارسال همزمان پیام روی پیامک و پیام‌رسان‌ها

یک پیام واحد را برای یک گیرنده، همزمان از مسیر پیامک و پیام‌رسان‌های روبیکا و/یا بله ارسال می‌کند. خط پیامکی (sender_map.sms) اجباری است و علاوه بر آن حداقل یکی از sender_map.rubika یا sender_map.bale باید مقدار داشته باشد؛ در غیر این صورت خطای ۴۱۲ برگردانده می‌شود. هر خطی که در sender_map می‌آید باید متعلق به همان حساب کاربری بوده و مجوز ارسال متن تراکنشی (CanSendTextTransactional) داشته باشد. اعتبار حساب پیش از ارسال بر اساس گران‌ترین مسیر (بیشترین هزینه بین ارائه‌دهنده‌ها) بررسی و پس از ثبت موفق کسر می‌شود، و در پاسخ هزینهٔ هر مسیر به تفکیک در costmap برمی‌گردد.

احراز هویت

نوع احراز هویتتوکن BearerbearerAuth

کلید API را در هدر Authorization با پیشوند Bearer بفرستید:

``` Authorization: Bearer YOURAPIKEY ```

این روش برای سرویس‌های نسخهٔ ۲، نسخهٔ ۳ و بارگذاری فایل به کار می‌رود. سرویس‌های نسخهٔ ۱ کلید را از مسیر URL می‌گیرند و هدری نمی‌خواهند.

هدر لازم

Authorization: Bearer YOUR_ACCESS_TOKEN

کلید خود را کجا پیدا کنم؟

اطلاعات ورود را از پنل کاربری خود بگیرید و توکن را فقط روی سرور و در یک متغیر محیطی نگه دارید؛ هرگز آن را در کد سمت کاربر قرار ندهید.

بدنهٔ درخواست

application/jsonالزامی

بدنهٔ JSON شامل متن پیام، شمارهٔ گیرنده و نگاشت خطوط فرستنده به ازای هر ارائه‌دهنده.

نام	نوع	الزامی	توضیح
`message`*	string	الزامی	متن پیام. اگر عبارت انصراف («لغو۱۱» یا `laghv11` / `laqv11`) در انتهای متن نباشد، سرویس به‌صورت خودکار `\nلغو۱۱` را به انتهای پیام اضافه می‌کند و متنِ نهایی (با همین پسوند) در پاسخ بازگردانده می‌شود. محدودیت: حداقل ۱ کاراکتر؛ در این مسیر سقف طول پیام در کد بررسی نمی‌شود نمونه`کد ورود شما: 45231`
`receiver`*	string	الزامی	شمارهٔ موبایل گیرنده. فرمت‌های `09121234567`، `9121234567`، `989121234567` و `+989121234567` پذیرفته و همگی به `09121234567` تبدیل می‌شوند. در صورت نامعتبر بودن، خطای ۴۱۱ برمی‌گردد. محدودیت: شماره موبایل ایران؛ به شکل 09xxxxxxxxx نرمال‌سازی می‌شود نمونه`09121234567`
`sender_map`*	object	الزامی	نگاشت خط فرستنده برای هر ارائه‌دهنده. حداقل یکی از `rubika` یا `bale` باید پر باشد.
`sms`*	string	الزامی	شمارهٔ خط پیامکی حساب شما. باید خطی باشد که ارائه‌دهندهٔ آن در فهرست ارائه‌دهندگان پیامکی قرار دارد و مجوز ارسال متن تراکنشی دارد. نمونه`3000123456`
`rubika`	string	اختیاری	شناسهٔ خط روبیکای حساب شما. اگر خالی بماند، ارسال روی روبیکا انجام نمی‌شود. نمونه`najva_service`
`bale`	string	اختیاری	شناسهٔ خط بله حساب شما. اگر خالی بماند، ارسال روی بله انجام نمی‌شود. نمونه`najva_service`

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

{
  "message": "کد ورود شما: 45231",
  "receiver": "09121234567",
  "sender_map": {
    "sms": "3000123456",
    "rubika": "najva_service",
    "bale": "najva_service"
  }
}

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	array<V3SendResponse>	اختیاری	نتیجهٔ ارسال چندکاناله (`dto.V3SendResponse`).
`messageid`	integer· int64	اختیاری	شناسهٔ پیامک. نمونه`18392011`قالب`int64`
`message`	string	اختیاری	متن نهایی پیام.
`status`	integer	اختیاری	وضعیت پیامک: ۰ دریافت کننده نامعتبر · ۱ در صف ارسال · ۲ زمان‌بندی شده · ۴ ارسال شده به مخابرات · ۶ خطا در ارسال · ۱۰ رسیده به گیرنده · ۱۱ مشکل در رسیدن پیام · ۱۳ لغو شده · ۱۴ بلاک شده · ۱۵ شماره تکراری · ۱۰۰ شناسه نامعتبر. مقادیر مجاز`012461011131415100`نمونه`1`
`statustext`	string	اختیاری	متن فارسی وضعیت. در این سرویس همیشه «در صف ارسال». نمونه`در صف ارسال`
`receptor`	string	اختیاری	شمارهٔ گیرنده. نمونه`09121234567`
`costmap`	object	اختیاری	هزینهٔ تفکیک‌شده به ازای هر کانال. کلید `sms` برای خطوط پیامکی و نام کانال با حروف کوچک برای پیام‌رسان‌ها (`bale`، `rubika`).

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": [
    {
      "messageid": 98213345,
      "message": "کد ورود شما: 45231\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "receptor": "09121234567",
      "costmap": {
        "sms": 1200,
        "bale": 300,
        "rubika": 300
      }
    }
  ]
}