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

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

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

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

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

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

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

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

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

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

۱۰

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