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

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

گزارش تحویل این ارسال‌ها کجاست؟

این وب‌سرویس خودش سرویس گزارش‌گیری جداگانه ندارد. پیام‌های ارسال‌شده با همان messageid بازگشتی در سرویس‌های وضعیتِ بخش «تراکنشی» قابل پیگیری‌اند — مثلاً استعلام وضعیت با شناسه پیامک یا استعلام وضعیت ارسال پیامک‌ها.

فقط پیامک نیست

این وب‌سرویس علاوه بر پیامک، برای ارسال از طریق پیام‌رسان‌ها (بله و روبیکا) نیز قابل استفاده است. کافی است سرشماره‌ای انتخاب کنید که ارائه‌دهندهٔ آن یکی از پیام‌رسان‌ها باشد؛ بقیهٔ پارامترها تغییری نمی‌کنند.

در صورت خطا، به بخش کدهای خطا مراجعه کنید.

احراز هویت

نوع احراز هویتتوکن 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
      }
    }
  ]
}