اتصال پنل ملی‌پیامک به مرکز پیامک

در این راهنما، اطلاعات اتصال، الگوها، متغیرها و خطاهای ملی‌پیامک را بررسی می‌کنیم. برای انتخاب روش و اتصال مشترک، انتخاب پنل، برای تنظیم اعلان سفارش، مدیریت رویدادها و برای تشخیص خطاهای عمومی، عیب‌یابی پیامک را ببینید.

اتصال ملی‌پیامک در مرکز پیامک جم پک، امکان ارسال اعلان‌های سفارش ووکامرس، هشدارهای موجودی و پیام‌های دستی را از حساب ملی‌پیامک فراهم می‌کند. این اتصال دو مسیر دارد:

• Direct: متن کامل پیام با شماره فرستنده از API ارسال ساده کنسول فرستاده می‌شود؛
• Pattern (الگویی): شناسه عددی متن خدماتی و مقدار متغیرها به‌ترتیب از طریق API خط خدماتی اشتراکی ارسال می‌شوند.

اتصال ملی‌پیامک در جم پک فقط از توکن کنسول ملی‌پیامک استفاده می‌کند. نام کاربری و رمز وب‌سرویس قدیمی، SOAP و Endpointهای rest.payamak-panel.com در این اتصال کاربرد ندارند. آموزش‌های قدیمی را با تنظیمات فعلی ترکیب نکنید.

برای تنظیم اعلان‌های مدیر و مشتری، وضعیت‌های سفارش، هشدار موجودی، ارسال دستی و تاریخچه، ابتدا راه‌اندازی مرکز پیامک ووکامرس را مطالعه کنید. این صفحه فقط اتصال و رفتار اختصاصی ملی‌پیامک را توضیح می‌دهد.

این راهنما چه مواردی را پوشش می‌دهد؟

• دریافت توکن کنسول؛
• تفاوت توکن با نام کاربری و رمز قدیمی؛
• ثبت توکن یا URL کامل نمونه؛
• تنظیم شماره فرستنده Direct؛
• آزمون ارسال ساده؛
• ساخت متن خدماتی در ملی‌پیامک؛
• دریافت bodyId؛
• نگاشت ترتیبی {0}، {1}، {2} و ادامه آن؛
• آزمون Pattern با سفارش واقعی؛
• بررسی پاسخ recId و status؛
• تشخیص پاسخ نامعتبر و خطاهای سرویس؛
• نکات امنیت توکن و حریم خصوصی.

اطلاعات موردنیاز اتصال

در نسخه بررسی‌شده دو فیلد برای ملی‌پیامک وجود دارد:

فیلد	وضعیت	کاربرد
Console API Token	همیشه اجباری	احراز هویت Direct و Pattern از طریق URL
شماره فرستنده	برای Direct اجباری	مقدار from در ارسال ساده

فیلد شماره فرستنده در فرم عمومی اختیاری است، چون Pattern از آن استفاده نمی‌کند. اما پیام آزمایشی، ارسال دستی و هر اعلان Direct بدون شماره فرستنده پیش از تماس با API متوقف می‌شوند.

دریافت توکن کنسول

توکن را از کنسول ملی‌پیامک دریافت کنید:

1. وارد کنسول شوید.
2. یکی از صفحه‌های Send API مانند ارسال ساده را باز کنید.
3. URL نمونه تولیدشده برای حساب خود را پیدا کنید.
4. فقط آخرین بخش URL، یعنی قسمت بعد از آخرین /، را کپی کنید.
5. آن را به‌عنوان Console API Token در جم پک ثبت کنید.

ساختار نمونه:

https://console.melipayamak.com/api/send/simple/YOUR_TOKEN

مقدار پیشنهادی برای فیلد:

YOUR_TOKEN

نسخه بررسی‌شده اگر به‌اشتباه URL کامل نمونه را وارد کنید، آخرین بخش مسیر را به‌عنوان توکن استخراج می‌کند. URL باید بدون Query String اضافی باشد. برای کاهش احتمال خطا هنگام ذخیره یا انتقال تنظیمات، فقط خود توکن را وارد کنید.

توکن کنسول با موارد زیر یکی نیست:

• رمز ورود پنل؛
• نام کاربری وب‌سرویس قدیمی؛
• رمز وب‌سرویس SOAP؛
• API Key سامانه دیگری؛
• شناسه bodyId متن خدماتی.

امنیت توکن کنسول

در این API، توکن داخل مسیر URL قرار می‌گیرد:

https://console.melipayamak.com/api/send/.../{token}

بنابراین علاوه بر مخفی‌کردن فیلد در پیشخوان، این موارد را کنترل کنید:

• توکن در Screenshot یا ویدئو دیده نشود؛
• URL کامل درخواست در Log عمومی ذخیره نشود؛
• گزارش‌های Proxy، Firewall و ابزار مانیتورینگ از نظر ثبت URL بازبینی شوند؛
• توکن در پیام، یادداشت سفارش یا تیکت پشتیبانی قرار نگیرد؛
• پس از افشا، توکن قبلی تعویض یا باطل شود؛
• برای محیط آزمایشی و اصلی، در صورت امکان توکن جداگانه داشته باشید.

مقدار توکن در فرم مانند رمز عبور پنهان می‌شود و جزو اطلاعات محرمانه اتصال است. بااین‌حال، دسترسی کاربران به تنظیمات را هم باید محدود کنید.

دریافت شماره فرستنده Direct

برای ارسال متن آزاد، شماره خط فعال حساب را از پنل ملی‌پیامک بردارید. مقدار نمونه:

5000XXXX

شماره فرستنده باید:

• متعلق به همان حساب باشد؛
• برای وب‌سرویس و ارسال ساده فعال باشد؛
• با ارقام انگلیسی ثبت شود؛
• بدون فاصله یا نویسه اضافی وارد شود؛
• برای نوع پیام و مقصد موردنظر محدودیت نداشته باشد.

در Pattern این شماره به API ارسال نمی‌شود؛ خط خدماتی اشتراکی یا خط مرتبط با متن تأییدشده، فرستنده را تعیین می‌کند.

انتخاب ملی‌پیامک در مرکز پیامک

برای اتصال:

1. وارد پیشخوان وردپرس شوید.
2. از منوی جم پک، «اعلان‌های پیامکی» را باز کنید.
3. وارد «تنظیمات عمومی» شوید.
4. مرکز پیامک را فعال کنید.
5. «ملی‌پیامک» را از فهرست پنل‌ها انتخاب کنید.
6. تنظیمات را ذخیره کنید.
7. صفحه را تازه‌سازی کنید.
8. توکن کنسول را وارد کنید.
9. برای Direct، شماره فرستنده را ثبت کنید.
10. تنظیمات را دوباره ذخیره کنید.

مسیر فنی صفحه:

/wp-admin/admin.php?page=gempack#sms-settings

پیش از تنظیم الگو، انتخاب پنل را ذخیره کنید تا فرم نگاشت متغیرها متناسب با ملی‌پیامک نمایش داده شود.

ارسال Direct چگونه انجام می‌شود؟

نسخه بررسی‌شده درخواست POST با بدنه JSON را به این Endpoint می‌فرستد:

https://console.melipayamak.com/api/send/simple/{token}

بدنه درخواست:

{
  "from": "5000XXXX",
  "to": "09120000000",
  "text": "متن نهایی پیام"
}

در این درخواست:

پارامتر	کاربرد
from	شماره فرستنده Direct
to	شماره موبایل نرمال‌شده گیرنده
text	متن نهایی پس از جایگزینی متغیرها

هدر محتوا:

Content-Type: application/json

افزونه حداکثر ۳۰ ثانیه منتظر پاسخ می‌ماند. احراز هویت با همان توکن موجود در URL انجام می‌شود و Header جداگانه‌ای برای API Key ارسال نمی‌شود.

آزمون اولیه Direct

پیش از فعال‌کردن اعلان‌های سفارش:

1. توکن و شماره فرستنده را ذخیره کنید.
2. در فرم پیام آزمایشی، شماره مقصد را با ارقام انگلیسی وارد کنید.
3. متن کوتاهی بنویسید.
4. ارسال را اجرا کنید.
5. نتیجه کنار فرم را یادداشت کنید.
6. رکورد ارسال را در پنل ملی‌پیامک بررسی کنید.
7. دریافت پیام در گوشی را کنترل کنید.

نمونه متن:

این یک پیام آزمایشی از مرکز پیامک فروشگاه است.

پیام آزمایشی Direct است و در تاریخچه مرکزی جم پک ثبت نمی‌شود. موفقیت آن، bodyId و ترتیب متغیرهای Pattern را تأیید نمی‌کند.

پاسخ ارسال Direct

پاسخ کنسول به‌صورت کلی این ساختار را دارد:

{
  "recId": 3741437414,
  "status": ""
}

جم پک وجود یک recId عددی و بزرگ‌تر از صفر را نشانه موفقیت می‌داند. اگر recId خالی، صفر یا غیرعددی باشد، متن status به‌عنوان خطا برگردانده می‌شود.

اگر پاسخ JSON قابل تشخیص نباشد، خطای «پاسخ نامعتبر از کنسول ملی پیامک» نمایش داده می‌شود.

اتصال فعلی recId را برای استعلام خودکار Delivery نگهداری نمی‌کند. در نتیجه sent در تاریخچه یعنی API درخواست را پذیرفته است؛ برای تحویل نهایی به گزارش پنل مراجعه کنید.

ساخت متن خدماتی Pattern

برای Pattern باید در پنل اصلی ملی‌پیامک یک متن خدماتی بسازید:

1. وارد پنل ملی‌پیامک شوید.
2. از بخش «ابزار ویژه»، «وب‌سرویس خدماتی» را باز کنید.
3. گزینه افزودن متن جدید را انتخاب کنید.
4. قوانین سرویس را مطالعه و تأیید کنید.
5. متن را همراه متغیرهای شماره‌گذاری‌شده بنویسید.
6. نشانی سایت را طبق ضوابط جاری پنل در انتهای متن قرار دهید.
7. متن را برای بررسی ارسال کنید.
8. منتظر وضعیت تأییدشده بمانید.
9. شناسه عددی متن یا bodyId را یادداشت کنید.

نام منوها و ضوابط ممکن است تغییر کنند؛ راهنمای رسمی فرایند را در آموزش Pattern ملی‌پیامک توضیح می‌دهد.

ساختار متغیرهای ملی‌پیامک

متغیرهای الگوی ملی‌پیامک به‌ترتیب و از شماره صفر تعریف می‌شوند:

{0}
{1}
{2}
{3}
...

نمونه متن:

{0} عزیز، سفارش {1} در وضعیت {2} قرار گرفت.
example.com

در این ساختار:

جایگاه متن	ردیف نگاشت در جم پک	مقدار نمونه
{0}	۱	نام مشتری
{1}	۲	شماره سفارش
{2}	۳	وضعیت سفارش

عنوان یا کلیدی که کنار ردیف می‌نویسید برای ملی‌پیامک ارسال نمی‌شود. تنها ترتیب ردیف‌ها مهم است.

دریافت و ثبت bodyId

پس از تأیید متن، ملی‌پیامک یک شناسه عددی برای آن ایجاد می‌کند. این شناسه همان Pattern ID موردنیاز جم پک است.

نمونه:

254

در فیلد Pattern ID فقط bodyId را وارد کنید؛ متن کامل، عنوان نمایشی یا توکن کنسول را در این فیلد قرار ندهید.

نسخه بررسی‌شده خالی‌بودن شناسه را کنترل می‌کند، اما پیش از ارسال آن را با intval به عدد تبدیل می‌کند. اگر مقدار غیرعددی وارد شود، مقدار صفر به API می‌رود و خطای سرویس دریافت می‌شود. بنابراین bodyId باید عدد مثبت و دقیقاً مطابق پنل باشد.

نگاشت ترتیبی متغیرها

برای متن زیر:

{0} عزیز، سفارش {1} به مبلغ {2} اکنون {3} است.
example.com

نگاشت صحیح:

ردیف	جایگاه ملی‌پیامک	متغیر جم پک
۱	{0}	{billing_first_name}
۲	{1}	{order_number}
۳	{2}	{order_total}
۴	{3}	{order_status}

اگر ردیف دوم و سوم جابه‌جا شوند، مبلغ در محل شماره سفارش و شماره سفارش در محل مبلغ نمایش داده می‌شود. سرویس نام متغیرها را نمی‌شناسد و فقط آرایه args را به ترتیب دریافت می‌کند.

قواعد نگاشت

• ردیف اول همیشه {0} را پر می‌کند؛
• ردیف دوم برای {1} است؛
• هیچ جایگاهی را از وسط ترتیب حذف نکنید؛
• تعداد ردیف‌ها را با تعداد جایگاه‌های متن برابر کنید؛
• متغیری انتخاب کنید که در زمان رویداد مقدار داشته باشد؛
• پس از تغییر متن خدماتی، نگاشت را دوباره بسازید؛
• برای هر وضعیت سفارش، bodyId و نگاشت همان متن را ثبت کنید.

در نسخه بررسی‌شده سقف ثابتی برای تعداد ردیف‌ها در رابط درگاه تعریف نشده است. این موضوع به معنی نامحدودبودن API نیست؛ تعداد متغیرها را کم و مطابق متن تأییدشده نگه دارید و محدودیت جاری سرویس را از ملی‌پیامک بررسی کنید.

آیا باید نگاشت متغیرها را مشخص کنم؟

بهتر است برای هر متغیر الگو، ردیف نگاشت مشخصی بسازید. اگر نگاشت خالی باشد، افزونه متغیرها را به‌ترتیب اولین حضورشان در متن ذخیره‌شده استخراج می‌کند؛ در این حالت، تغییر متن ممکن است ترتیب args را ناخواسته عوض کند.

عنوان کلیدها در یک پنل نام‌دار اهمیت دارد، اما در ملی‌پیامک نادیده گرفته می‌شود. برای جلوگیری از اشتباه تیم، می‌توانید عنوان‌های خوانا بنویسید، ولی تصمیم نهایی را براساس شماره ردیف بگیرید.

درخواست Pattern چگونه ساخته می‌شود؟

نسخه بررسی‌شده درخواست POST را به این Endpoint می‌فرستد:

https://console.melipayamak.com/api/send/shared/{token}

بدنه نمونه:

{
  "bodyId": 254,
  "to": "09120000000",
  "args": ["مهدی", "1052", "در حال انجام"]
}

پارامتر from در این درخواست وجود ندارد. خط خدماتی اشتراکی مرتبط با متن تأییدشده، فرستنده را تعیین می‌کند.

پاسخ Pattern نیز با recId و status تفسیر می‌شود؛ recId عددی مثبت نشانه پذیرش درخواست است.

نمونه‌های پیشنهادی Pattern

سفارش جدید برای مدیر

متن خدماتی:

سفارش {0} به مبلغ {1} ثبت شد. تعداد اقلام: {2}
example.com

نگاشت:

ردیف	متغیر
۱	{order_number}
۲	{order_total}
۳	{order_items_count}

تغییر وضعیت برای مشتری

متن خدماتی:

{0} عزیز، وضعیت سفارش {1} به {2} تغییر کرد.
example.com

نگاشت:

ردیف	متغیر
۱	{billing_first_name}
۲	{order_number}
۳	{order_status}

هشدار موجودی برای مدیر

متن خدماتی:

موجودی محصول با SKU {0} به {1} رسید.
example.com

نگاشت:

ردیف	متغیر
۱	{product_sku}
۲	{stock}

اگر SKU بعضی محصولات خالی است، پیش از فعال‌سازی آن را تکمیل کنید یا متغیر دیگری برگزینید.

فعال‌سازی Pattern در مرکز پیامک

مراحل مشترک انتخاب مخاطب، رویداد، روش ارسال و ذخیره در مدیریت رویدادها و الگوهای پیامکی آمده است. در اجرای این مراحل، نکته اختصاصی این پنل را رعایت کنید:

شناسه عددی bodyId را ثبت کنید و ردیف‌های نگاشت را مطابق جایگاه‌های {0} به بعد بچینید.

تنظیمات Pattern هر پنل مستقل ذخیره می‌شوند. تغییر پنل، مقدارهای ملی‌پیامک را حذف نمی‌کند؛ اما پس از بازگشت باید توکن، bodyId و وضعیت تأیید متن را دوباره آزمایش کنید.

اگر Pattern انتخاب شود ولی bodyId همان رویداد خالی باشد، نسخه بررسی‌شده به Direct برمی‌گردد. چون Direct به شماره فرستنده نیاز دارد، این بازگشت می‌تواند باعث ارسال متن آزاد یا خطای نبود شماره فرستنده شود.

آزمون Pattern با سفارش واقعی

فرم تست عمومی فقط Direct است. برای آزمون Pattern:

1. یک متن خدماتی ساده و تأییدشده انتخاب کنید.
2. فقط یک اعلان مشتری یا مدیر را فعال کنید.
3. bodyId را وارد کنید.
4. ردیف‌ها را دقیقاً از {0} به بعد نگاشت کنید.
5. شماره موبایل مشتری را با ارقام انگلیسی ثبت کنید.
6. رویداد هدف را روی سفارش آزمایشی اجرا کنید.
7. تاریخچه مرکز پیامک را براساس سفارش فیلتر کنید.
8. گزارش ملی‌پیامک را با زمان و مقصد تطبیق دهید.
9. مقدار هر جایگاه را در متن دریافتی بررسی کنید.

ترتیب پیشنهادی آزمون:

1. Direct با متن کوتاه؛
2. Pattern تک‌متغیره؛
3. Pattern چندمتغیره؛
4. اعلان مدیر؛
5. اعلان مشتری؛
6. مقصد دارای محدودیت تبلیغاتی، در صورت مجازبودن متن خدماتی.

عیب‌یابی

خطای «توکن کنسول ملی پیامک تنظیم نشده است»

• ملی‌پیامک را به‌عنوان پنل فعال ذخیره کنید؛
• فقط Token را از URL نمونه بردارید؛
• تنظیمات را ذخیره و صفحه را تازه‌سازی کنید؛
• پس از انتقال سایت یا درون‌ریزی تنظیمات، اطلاعات محرمانه اتصال را دوباره وارد کنید.

URL کامل را وارد کرده‌ام

نسخه بررسی‌شده آخرین بخش مسیر را به‌عنوان Token استخراج می‌کند. اگر URL ساده نمونه و بدون Query String باشد، قابل استفاده است. برای جلوگیری از خطا، فقط Token را ثبت کنید.

خطای نبود شماره فرستنده

این خطا مربوط به Direct است:

• شماره خط فعال را ثبت کنید؛
• به یاد داشته باشید پیام آزمایشی و پیام دستی Direct هستند؛
• خالی‌بودن Pattern ID و بازگشت خودکار به Direct را بررسی کنید؛
• اگر فقط Pattern نیاز دارید، آزمون آن را با رویداد واقعی انجام دهید.

پاسخ نامعتبر از کنسول

• دسترسی HTTPS سرور را بررسی کنید؛
• مطمئن شوید Token مربوط به کنسول جدید است؛
• صفحه ورود یا Firewall نباید به‌جای JSON پاسخ دهد؛
• Proxy، WAF یا محدودیت هاست را بررسی کنید؛
• وضعیت سرویس را از پنل یا پشتیبانی ملی‌پیامک پیگیری کنید؛
• URL قدیمی را با Endpoint کنسول ترکیب نکنید.

Direct موفق است اما Pattern ناموفق است

• bodyId را با پنل تطبیق دهید؛
• متن باید تأیید شده باشد؛
• تعداد args باید با جایگاه‌های متن هماهنگ باشد؛
• ترتیب ردیف‌ها را بررسی کنید؛
• مقدار غیرعددی Pattern ID را اصلاح کنید؛
• Pattern را با سفارش واقعی، نه فرم تست Direct، اجرا کنید؛
• از Token همان حسابی استفاده کنید که متن روی آن ثبت شده است.

مقادیر در جای اشتباه قرار گرفته‌اند

این خطا از ترتیب نگاشت است:

• ردیف اول را با {0} تطبیق دهید؛
• ردیف دوم را با {1} کنترل کنید؛
• هیچ ردیفی را در وسط حذف نکنید؛
• پس از تغییر متن خدماتی، نگاشت را بروزرسانی کنید؛
• عنوان کلید ردیف را معیار تطبیق ندانید.

Pattern انتخاب شده ولی Direct اجرا می‌شود

برای تشخیص این وضعیت، مراحل رفع خطاهای اتصال و ارسال پیامک را دنبال کنید. برای بررسی توکن، خط فرستنده و شناسه الگو، به بخش مربوط در همین راهنما مراجعه کنید.

recId دریافت شده ولی پیام نرسیده است

برای تشخیص این وضعیت، مراحل رفع خطاهای اتصال و ارسال پیامک را دنبال کنید. برای بررسی توکن، خط فرستنده و شناسه الگو، به بخش مربوط در همین راهنما مراجعه کنید.

خطای شبکه یا Timeout

برای تشخیص این وضعیت، مراحل رفع خطاهای اتصال و ارسال پیامک را دنبال کنید. برای بررسی توکن، خط فرستنده و شناسه الگو، به بخش مربوط در همین راهنما مراجعه کنید.

امنیت و حریم خصوصی

• Token را مانند رمز عبور نگهداری کنید؛
• URL کامل API را در محتوای عمومی نمایش ندهید؛
• توکن را در تصویر، ویدئو یا تیکت عمومی محو کنید؛
• دسترسی مدیریت تنظیمات را محدود کنید؛
• برای آزمایش و تولید، در صورت امکان Token جداگانه داشته باشید؛
• متن و شماره مشتری را فقط برای هدف مرتبط با سفارش ارسال کنید؛
• انتقال داده لازم به ملی‌پیامک را در سیاست حریم خصوصی توضیح دهید؛
• گزارش‌های دارای شماره و متن را برای مدت لازم نگه دارید؛
• پس از افشا یا تغییر تیم، Token را تعویض کنید؛
• یادداشت‌ها و Logهای سرور را از نظر ثبت URL حاوی Token بررسی کنید.

چک‌لیست نهایی ملی‌پیامک

• [ ] حساب و کنسول ملی‌پیامک فعال‌اند.
• [ ] Token کنسول صحیح ثبت شده است.
• [ ] از نام کاربری و رمز API قدیمی استفاده نشده است.
• [ ] ملی‌پیامک به‌عنوان پنل فعال ذخیره شده است.
• [ ] شماره فرستنده Direct صحیح و فعال است.
• [ ] اعتبار کافی در حساب وجود دارد.
• [ ] تست Direct موفق بوده است.
• [ ] نتیجه Direct در پنل ملی‌پیامک دیده می‌شود.
• [ ] متن خدماتی تأیید شده است.
• [ ] bodyId عددی و مثبت ثبت شده است.
• [ ] ردیف اول به {0} مربوط است.
• [ ] ترتیب همه ردیف‌ها با متن هماهنگ است.
• [ ] تعداد نگاشت‌ها با تعداد جایگاه‌ها تطابق دارد.
• [ ] Pattern با سفارش واقعی آزمایش شده است.
• [ ] نتیجه تاریخچه با گزارش پنل مقایسه شده است.
• [ ] تفاوت sent و Delivery برای تیم روشن است.
• [ ] Token و شماره‌ها در تصاویر محو شده‌اند.

پیوندهای داخلی پیشنهادی

• راه‌اندازی مرکز پیامک ووکامرس
• اتصال پنل SMS.ir به مرکز پیامک
• آشنایی با محیط جم پک و مدیریت ماژول‌ها
• مرکز پیامک ووکامرس
• اتصال پنل فراپیامک به مرکز پیامک

پیوند فراپیامک پس از ایجاد مستند بعدی فعال شود.

منابع

• کنسول ملی‌پیامک
• راهنمای رسمی ارسال پیامک با الگو
• مستند ساختار Simple و Shared در کتابخانه Console API

جمع‌بندی

برای اتصال ملی‌پیامک، Token کنسول را ثبت کنید و از واردکردن نام کاربری و رمز API قدیمی خودداری کنید. Direct علاوه بر Token به شماره فرستنده نیاز دارد؛ Pattern از خط خدماتی مرتبط با متن تأییدشده استفاده می‌کند.

در Pattern، bodyId عددی و ترتیب ردیف‌ها تعیین‌کننده‌اند: ردیف اول {0}، ردیف دوم {1} و ردیف سوم {2} را پر می‌کند. پس از هر تغییر در متن یا نگاشت، رویداد را با سفارش آزمایشی اجرا و نتیجه را هم در تاریخچه مرکز پیامک و هم در پنل ملی‌پیامک بررسی کنید.