ارسال پیامک با متن یکسان به یک یا چند گیرنده

احراز هویت: این سرویس کلید API را از مسیر URL می‌خواند (/v1/{apiKey}/...) و هدر احراز هویتی ندارد. درخواست فقط از آی‌پی‌های وایت‌لیست‌شده پذیرفته می‌شود. به احراز هویت و وایت‌لیست IP نگاه کنید.

یک متن مشترک را به یک یا چند شمارهٔ گیرنده ارسال می‌کند. گیرنده‌ها به‌صورت رشته‌ای جدا شده با کاما در پارامتر receptor ارسال می‌شوند و سرویس آن‌ها را به قالب 09xxxxxxxxx نرمال می‌کند؛ شماره‌های نامعتبر و تکراری باعث رد شدن کل درخواست نمی‌شوند بلکه به‌عنوان رکوردی جداگانه با وضعیت 0 (دریافت کننده نامعتبر) یا 15 (شماره تکراری) در entries بازگردانده می‌شوند و فقط زمانی خطای 411 برمی‌گردد که هیچ شمارهٔ معتبری باقی نماند.

اگر date ارسال شود و دست‌کم ۶۰ ثانیه از زمان حال جلوتر باشد، پیام زمان‌بندی می‌شود و وضعیت 2 برمی‌گردد؛ در غیر این صورت پیام بلافاصله در صف ارسال قرار می‌گیرد و وضعیت 1 برمی‌گردد. برای ارسال آنی، اعتبار حساب پیش از ثبت پیام بررسی می‌شود و در صورت ناکافی بودن، خطای 418 برمی‌گردد.

نکتهٔ مهم: این متد هم با POST و هم با GET قابل فراخوانی است، اما تمام پارامترها فقط از query string آدرس خوانده می‌شوند (ctx.Query) و بدنهٔ فرم یا JSON نادیده گرفته می‌شود؛ بنابراین در POST هم باید پارامترها را در انتهای URL قرار دهید.

روی سرشماره‌های پیامکی، عبارت لغو (\nلغو۱۱) به‌صورت خودکار به انتهای متن اضافه (یا در صورت وجود، یکسان‌سازی) می‌شود؛ روی سرشماره‌های پیام‌رسان (بله/روبیکا) این کار انجام نمی‌شود. هزینهٔ بازگشتی در فیلد cost بر حسب ریال است.

نکتهٔ مهم: تمام پارامترها از query string خوانده می‌شوند. این مسیر برای POST هم ثبت شده، ولی حتی در POST هم باید پارامترها در انتهای نشانی بیایند؛ بدنهٔ form-urlencoded یا JSON خوانده نمی‌شود.

این مسیر با متد GET هم ثبت شده و رفتار یکسانی دارد؛ در مستندات فقط شکل POST نشان داده شده است.

پارامترهای مسیر

نام	نوع	الزامی	توضیح
`apiKey`*	string	الزامی	کلید API حساب کاربری که به‌صورت بخشی از مسیر ارسال می‌شود (نه هدر). میان‌افزار `AuthTokenMiddleware` با همین مقدار احراز هویت را انجام می‌دهد. نمونه`a1b2c3d4e5f60718293a4b5c6d7e8f90`

پارامترهای کوئری

نام	نوع	الزامی	توضیح
`receptor`*	string	الزامی	فهرست شماره‌های گیرنده، جدا شده با کاما. هر شماره باید با الگوی `^((\+?98)\|0)?9[0-9]{9}$` بخواند (مثلاً `09121234567`، `9121234567`، `989121234567` یا `+989121234567`) و به قالب `09xxxxxxxxx` نرمال می‌شود. شماره‌های نامعتبر و تکراری حذف شده و به‌صورت رکورد جداگانه در پاسخ گزارش می‌شوند؛ اگر هیچ شمارهٔ معتبری باقی نماند خطای 411 برمی‌گردد. — فهرست شماره‌های گیرنده، جدا شده با کاما. هر شماره باید با الگوی `^((\+?98)\|0)?9[0-9]{9}$` بخواند (مثلاً `09121234567`، `9121234567`، `989121234567` یا `+989121234567`) و به قالب `09xxxxxxxxx` نرمال می‌شود. شماره‌های نامعتبر و تکراری حذف شده و به‌صورت رکورد جداگانه در پاسخ گزارش می‌شوند؛ اگر هیچ شمارهٔ معتبری باقی نماند خطای 411 برمی‌گردد. محدودیت: در کد سقف صریحی برای تعداد گیرنده وجود ندارد؛ اما در صورت ارسال `localid` عملاً حداکثر ۲۰۰ گیرنده قابل ارسال است. نمونه`09121234567,09351234567,09221234567`
`message`*	string	الزامی	متن پیامک. متن خالی باعث خطای 400 می‌شود. برای سرشماره‌های پیامکی، عبارت `\nلغو۱۱` به‌طور خودکار به انتهای متن افزوده می‌شود (و اگر متن از قبل عبارت لغو مانند `لغو11` یا `laghv11` داشته باشد، با همین قالب یکسان‌سازی می‌شود). متن نهایی — همراه با همین پسوند — در پاسخ بازگردانده می‌شود. — متن پیامک. متن خالی باعث خطای 400 می‌شود. برای سرشماره‌های پیامکی، عبارت `\nلغو۱۱` به‌طور خودکار به انتهای متن افزوده می‌شود (و اگر متن از قبل عبارت لغو مانند `لغو11` یا `laghv11` داشته باشد، با همین قالب یکسان‌سازی می‌شود). متن نهایی — همراه با همین پسوند — در پاسخ بازگردانده می‌شود. محدودیت: در کد این مسیر هیچ محدودیت طولی برای متن اعمال نمی‌شود (statuscode.INVALIDMESSAGESIZE در سرویس استفاده نشده است). نمونه`کد ورود شما: 12345`
`sender`	string	اختیاری	شمارهٔ خط (سرشماره) فرستنده. باید متعلق به همین حساب باشد و دسترسی `can_send_text_transactional` داشته باشد. اگر ارسال نشود یا خالی بماند، نخستین خط مجاز حساب به‌صورت خودکار انتخاب می‌شود. در صورت نامعتبر بودن، خطای 412 برمی‌گردد. نمونه`30007487`
`date`	integer	اختیاری	زمان ارسال به‌صورت unix timestamp بر حسب ثانیه. مقدار پیش‌فرض، زمان جاری است. اگر مقدار کمتر از «زمان حال + ۶۰ ثانیه» باشد پیام بلافاصله ارسال می‌شود؛ در غیر این صورت زمان‌بندی شده و وضعیت `2` برمی‌گردد. مقدار غیرعددی باعث خطای 417 می‌شود. پیش‌فرض`زمان جاری سرور`نمونه`1757251200`
`localid`	string	اختیاری	شناسه‌های محلی (سمت شما) برای پیام‌ها، جدا شده با کاما. اعداد صحیح بدون علامت هستند و پس از حذف موارد تکراری، تعدادشان باید دقیقاً برابر تعداد گیرنده‌های معتبر باشد وگرنه خطای 400 برمی‌گردد. مقدار غیرقابل تجزیه نیز خطای 400 و بیش از ۲۰۰ شناسه خطای 414 می‌دهد. بعداً می‌توان با همین شناسه‌ها از `/v1/{apiKey}/sms/statuslocalmessageid.json` وضعیت را استعلام کرد. — شناسه‌های محلی (سمت شما) برای پیام‌ها، جدا شده با کاما. اعداد صحیح بدون علامت هستند و پس از حذف موارد تکراری، تعدادشان باید دقیقاً برابر تعداد گیرنده‌های معتبر باشد وگرنه خطای 400 برمی‌گردد. مقدار غیرقابل تجزیه نیز خطای 400 و بیش از ۲۰۰ شناسه خطای 414 می‌دهد. بعداً می‌توان با همین شناسه‌ها از `/v1/{apiKey}/sms/statuslocalmessageid.json` وضعیت را استعلام کرد. محدودیت: حداکثر ۲۰۰ شناسهٔ یکتا نمونه`10001,10002,10003`
`file_id`	string	اختیاری	شناسهٔ فایلی که پیش‌تر از طریق `POST /upload-file/bale` آپلود شده است؛ برای ارسال روی سرشماره‌های پیام‌رسان (بله/روبیکا) کاربرد دارد. فایل باید متعلق به همین حساب باشد و ارائه‌دهندهٔ آن با ارائه‌دهندهٔ سرشمارهٔ فرستنده یکی باشد، وگرنه خطای 400 برمی‌گردد. — شناسهٔ فایلی که پیش‌تر از طریق `POST /upload-file/bale` آپلود شده است؛ برای ارسال روی سرشماره‌های پیام‌رسان (بله/روبیکا) کاربرد دارد. فایل باید متعلق به همین حساب باشد و ارائه‌دهندهٔ آن با ارائه‌دهندهٔ سرشمارهٔ فرستنده یکی باشد، وگرنه خطای 400 برمی‌گردد. محدودیت: حداکثر ۱۰۰ کاراکتر نمونه`3f9a1c8e-2b6d-4a7f-9c31-5d0e8b7a4c22`
`type`	string	اختیاری	در کد خوانده می‌شود اما هیچ اثری بر رفتار ارسال ندارد (فیلد `Type` در ساختار کنترلر با کامنت `// Unused` علامت خورده است). صرفاً برای سازگاری با API قدیمی نگه داشته شده است. نمونه`0`

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	array<MessageInfo>	اختیاری	اطلاعات یک پیامک ثبت‌شده (`dto.MessageInfo`).
`messageid`	integer· int64	اختیاری	شناسهٔ پیامک در نجوا. برای رکوردهای نامعتبر/تکراری صفر است. نمونه`18392011`قالب`int64`
`message`	string	اختیاری	متن نهایی پیامک پس از افزودن «لغو۱۱».
`status`	integer	اختیاری	وضعیت پیامک: ۰ دریافت کننده نامعتبر · ۱ در صف ارسال · ۲ زمان‌بندی شده · ۴ ارسال شده به مخابرات · ۶ خطا در ارسال · ۱۰ رسیده به گیرنده · ۱۱ مشکل در رسیدن پیام · ۱۳ لغو شده · ۱۴ بلاک شده · ۱۵ شماره تکراری · ۱۰۰ شناسه نامعتبر. مقادیر مجاز`012461011131415100`نمونه`1`
`statustext`	string	اختیاری	متن فارسی وضعیت. نمونه`در صف ارسال`
`sender`	string	اختیاری	سرشمارهٔ ارسال. نمونه`3000505`
`receptor`	string	اختیاری	شمارهٔ گیرنده، نرمال‌شده به قالب `09xxxxxxxxx`. نمونه`09121234567`
`date`	integer· int64	اختیاری	زمان ثبت درخواست (unix، ثانیه). نمونه`1757145600`قالب`int64`
`cost`	number· float	اختیاری	هزینه به ریال (مقدار داخلی تومان × ۱۰). نمونه`700`قالب`float`

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": [
    {
      "messageid": 87923451,
      "message": "کد ورود شما: 12345\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "sender": "30007487",
      "receptor": "09121234567",
      "date": 1757251200,
      "cost": 1200
    },
    {
      "messageid": 87923452,
      "message": "کد ورود شما: 12345\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "sender": "30007487",
      "receptor": "09351234567",
      "date": 1757251200,
      "cost": 1100
    },
    {
      "messageid": 0,
      "message": "",
      "status": 0,
      "statustext": "دریافت کننده نامعتبر",
      "sender": "",
      "receptor": "0912123",
      "date": 0,
      "cost": 0
    },
    {
      "messageid": 0,
      "message": "",
      "status": 15,
      "statustext": "شماره تکراری",
      "sender": "",
      "receptor": "09121234567",
      "date": 0,
      "cost": 0
    }
  ]
}