ارسال پیامک با الگو (لوکاپ)

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

ارسال پیامک بر پایهٔ یک الگوی (تمپلیت) تاییدشده به یک شمارهٔ گیرنده. متن پیام از بدنهٔ الگو ساخته می‌شود و جای‌نگهدارهای %token، %token2، %token3، %token10 و %token20 با مقدار پارامترهای هم‌نام جایگزین می‌شوند؛ جای‌نگهدار تنها زمانی جایگزین می‌شود که بلافاصله پس از آن فاصله (یا پایان متن) باشد.

همهٔ پارامترها — چه در متد GET و چه در POST — از query string آدرس خوانده می‌شوند و بدنهٔ درخواست (form یا JSON) نادیده گرفته می‌شود.

پیام همیشه بلافاصله در صف ارسال قرار می‌گیرد (زمان‌بندی پشتیبانی نمی‌شود) و پیش از ثبت، اعتبار حساب بررسی می‌شود. اطلاعات الگو تا ۱۰ دقیقه کش می‌شود، بنابراین تایید یا ویرایش الگو ممکن است با تاخیر اعمال شود.

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

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

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

نام الگو، نه شناسهٔ آن

نام الگو را در پارامتر template بفرستید، نه شناسه (ID) آن. فرستادن شناسهٔ عددی باعث می‌شود الگو پیدا نشود.

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

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

نام	نوع	الزامی	توضیح
`apiKey`*	string	الزامی	کلید API حساب کاربری که به‌صورت بخشی از مسیر آدرس ارسال می‌شود (نه هدر). همین مقدار برای احراز هویت حساب و نیز برای واکشی الگو از سرویس مدیریت الگوها به‌کار می‌رود. نمونه`1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d`

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

۱۰

نام	نوع	الزامی	توضیح
`receptor`*	string	الزامی	شمارهٔ موبایل گیرنده. تنها یک شماره پذیرفته می‌شود. قالب‌های `09121234567`، `9121234567`، `989121234567` و `+989121234567` معتبرند و در پاسخ به شکل `09121234567` برگردانده می‌شوند. — محدودیت: الگوی مجاز: ^((\+?98)\|0)?9[0-9]{9}$ — نرمال‌سازی به قالب 09xxxxxxxxx نمونه`09121234567`
`template`*	string	الزامی	نام الگو را وارد کنید، نه شناسه (ID) آن. نام الگوی (تمپلیت) ثبت‌شده در پنل. الگو باید متعلق به همین حساب، فعال و دارای بدنهٔ غیرخالی باشد. نمونه`verify-code`
`sender`*	string	الزامی	شمارهٔ خط فرستنده. خط باید به حساب شما تعلق داشته باشد و مجوز ارسال الگو را داشته باشد: برای الگوهای OTP مجوز `can_send_otp_template_transactional` و برای سایر الگوها مجوز `can_send_template_transactional`. نمونه`30007650`
`token`	string	اختیاری	مقدار جایگزین جای‌نگهدار `%token` در بدنهٔ الگو. اگر الگو شامل `%token` باشد، ارسال این پارامتر اجباری است. طول آن حداکثر ۱۰۰ بایت است (حروف فارسی هر کدام ۲ بایت) و نباید هیچ فاصله، تب یا خط جدیدی داشته باشد. — محدودیت: حداکثر ۱۰۰ بایت؛ هیچ کاراکتر فاصله‌ای مجاز نیست نمونه`123456`
`token2`	string	اختیاری	مقدار جایگزین جای‌نگهدار `%token2`. اگر الگو شامل `%token2` باشد اجباری است. همان محدودیت‌های `token` را دارد. — محدودیت: حداکثر ۱۰۰ بایت؛ هیچ کاراکتر فاصله‌ای مجاز نیست نمونه`najva`
`token3`	string	اختیاری	مقدار جایگزین جای‌نگهدار `%token3`. اگر الگو شامل `%token3` باشد اجباری است. همان محدودیت‌های `token` را دارد. — محدودیت: حداکثر ۱۰۰ بایت؛ هیچ کاراکتر فاصله‌ای مجاز نیست نمونه`9821`
`token10`	string	اختیاری	مقدار جایگزین جای‌نگهدار `%token10`. برخلاف سه توکن نخست، تا ۴ کاراکتر فاصله (فاصله، تب یا خط جدید) در آن مجاز است. اگر الگو شامل `%token10` باشد اجباری است. — محدودیت: حداکثر ۴ کاراکتر فاصله‌ای؛ محدودیت طول اعمال نمی‌شود نمونه`سفارش شماره ۱۲۳`
`token20`	string	اختیاری	مقدار جایگزین جای‌نگهدار `%token20`. تا ۸ کاراکتر فاصله در آن مجاز است. اگر الگو شامل `%token20` باشد اجباری است. — محدودیت: حداکثر ۸ کاراکتر فاصله‌ای؛ محدودیت طول اعمال نمی‌شود نمونه`آدرس تحویل سفارش شما ثبت شد`
`file_id`	string	اختیاری	شناسهٔ فایل آپلودشدهٔ قبلی برای پیوست به پیام (کاربرد آن برای بسترهای پیام‌رسان مانند بله است). — محدودیت: حداکثر ۱۰۰ کاراکتر نمونه`3f0c1b7e-95a4-4f2c-9a1b-7d2e6c8f0a11`
`type`	string	اختیاری	پارامتر قدیمی که خوانده می‌شود ولی در پردازش درخواست هیچ اثری ندارد. ارسال آن لازم نیست.

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`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": 1548112,
      "message": "کد تایید شما 123456 است\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "sender": "30007650",
      "receptor": "09121234567",
      "date": 1788739200,
      "cost": 1000
    }
  ]
}