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

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

یک متن مشترک را به یک یا چند شمارهٔ گیرنده ارسال می‌کند. گیرنده‌ها به‌صورت رشته‌ای جدا شده با کاما در پارامتر receptor ارسال می‌شوند و سرویس آن‌ها را به قالب 09xxxxxxxxx نرمال می‌کند.

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

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

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

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

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

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

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

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

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

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

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