در این راهنما، اطلاعات اتصال، متن پیام‌ها و خطاهای نیازپرداز را بررسی می‌کنیم. برای انتخاب روش و اتصال مشترک، انتخاب پنل، برای تنظیم اعلان سفارش، مدیریت رویدادها و برای تشخیص خطاهای عمومی، عیب‌یابی پیامک را ببینید.
اتصال نیازپرداز در جم پک با کلید API و شماره فرستنده انجام می‌شود. جم پک اطلاعات سفارش را در متن پیام قرار می‌دهد و متن نهایی را برای سرویس می‌فرستد.
تفاوت اصلی نیازپرداز با پنل‌هایی مانند پیام‌رسان این است که در این اتصال، شناسه الگو و نگاشت متغیر جداگانه نداریم. روش ارسال در جم پک «پیامک مستقیم» است. اگر حساب شما از تطبیق متن با الگوی تأییدشده استفاده می‌کند، متن نهایی باید با ضوابط همان الگو سازگار باشد؛ انتخاب یک حالت الگویی جدا در جم پک لازم نیست.
این راهنما اتصال پنل را توضیح می‌دهد. برای تنظیم رویدادهای مدیر، مشتری و موجودی، راهنمای مرکز پیامک ووکامرس را هم مطالعه کنید.
این راهنما چه مواردی را پوشش می‌دهد؟
- آماده‌کردن کلید API و خط فرستنده؛
- انتخاب نیازپرداز در جم پک؛
- تنظیم متن اعلان‌های سفارش؛
- تفاوت ارسال مستقیم با تطبیق متن در پنل؛
- آزمون عمومی اتصال و آزمون پیام واقعی سفارش؛
- بررسی خطاهای کلید، خط، اعتبار، متن و درخواست تکراری؛
- رعایت امنیت اطلاعات اتصال و گزارش‌ها.
اطلاعات موردنیاز اتصال
| فیلد | مقدار موردنیاز | نکته |
|---|---|---|
| کلید API | کلید وب‌سرویس حساب نیازپرداز | نام کاربری یا رمز ورود پنل را جای آن ننویسید |
| شماره فرستنده | خط مجاز همان حساب | برای تمام پیام‌های این اتصال الزامی است |
در این اتصال فیلد نام کاربری، رمز حساب یا شناسه الگو نداریم. حتی اگر راهنمای قدیمی یا پیام خطا از نام کاربری و رمز صحبت کند، برای اتصال جم پک باید کلید API را وارد کنید.
کتابخانه رسمی نیازپرداز نیز در نمونه شروع، اتصال با کلید API و ارسال از یک شماره فرستنده مشخص را نشان می‌دهد. برای استفاده از مسیر داخلی جم پک نیازی به نصب این کتابخانه ندارید.
آماده‌کردن حساب نیازپرداز
- وارد حساب نیازپرداز شوید.
- کلید API را از بخش وب‌سرویس حساب دریافت کنید.
- فعال‌بودن دسترسی وب‌سرویس و حساب را بررسی کنید.
- شماره خطی را که اجازه ارسال از آن دارید بردارید.
- اعتبار و مهلت استفاده از پنل را کنترل کنید.
- برای پیام‌های مبتنی بر متن تأییدشده، قواعد پذیرش متن و خط قابل‌استفاده را از راهنمای حساب یا پشتیبانی نیازپرداز بپرسید.
محل دقیق منوها و مراحل تأیید متن در این راهنما تأیید نشده‌اند. برای انجام این مراحل، راهنمای داخل پنل نیازپرداز را دنبال کنید.
کلید API را در اختیار افراد غیرمرتبط قرار ندهید. نام کاربری و رمز پنل را هم برای تکمیل تنظیمات جم پک ارسال نکنید؛ این اتصال آن‌ها را نمی‌خواهد.
انتخاب نیازپرداز در جم پک
- وارد پیشخوان وردپرس شوید.
- در جم پک، «اعلان‌های پیامکی» را باز کنید.
- وارد «تنظیمات اصلی» شوید.
- «فعال‌سازی پیامک» را روشن کنید.
- در «درگاه پیامک»، گزینه
NiazPardazرا انتخاب کنید. - تنظیمات را ذخیره و صفحه را دوباره باز کنید.
- «کلید API» را وارد کنید.
- «شماره فرستنده» را با خط مجاز حساب تکمیل کنید.
- دوباره تنظیمات را ذخیره کنید.
پیش از نوشتن پیام‌ها، انتخاب درگاه را ذخیره کنید. راهنمای روش ارسال بر اساس درگاه ذخیره‌شده نمایش داده می‌شود، نه انتخابی که هنوز ذخیره نکرده‌اید.
پس از انتخاب و ذخیره نیازپرداز، در تنظیمات روش ارسال نباید انتظار گزینه فعال «الگو/قالب» و فیلدهای شناسه و نگاشت پنل قبلی را داشته باشید. نبودن این گزینه‌ها برای این اتصال طبیعی است.
اگر پیش‌تر از پنل دیگری استفاده می‌کردید، متن مستقیم تمام رویدادهای فعال را بازبینی کنید. شناسه الگوی قبلی جای متن پیام نیازپرداز را نمی‌گیرد.
تنظیم متن اعلان سفارش
در «پیامک ووکامرس»، دریافت‌کننده و رویداد موردنظر را انتخاب کنید. برای شروع فقط یک اعلان را فعال کنید تا نتیجه روشن باشد.
- بخش مدیر یا مشتری را باز کنید.
- روش ارسال را «پیامک مستقیم» در نظر بگیرید.
- متن مربوط به رویداد موردنظر را بنویسید.
- داده‌های سفارش را با متغیرهای مجاز همان بخش وارد کنید.
- تنظیمات را ذخیره کنید.
- نتیجه را با سفارش آزمایشی بررسی کنید.
نمونه متن در جم پک:
سفارش {order_number} شما ثبت شد.
اگر شماره سفارش آزمایشی 1250 باشد، متن موردانتظار چنین است:
سفارش 1250 شما ثبت شد.
این مثال فرضی است و به معنی تأیید آن در پنل نیازپرداز یا ارسال واقعی نیست.
جم پک پیش از ارسال، عبارت {order_number} را با شماره سفارش جایگزین می‌کند. از متغیرهای معتبر همان بخش استفاده کنید و پیام دریافتی را بررسی کنید تا هیچ متغیری به‌صورت خام در متن باقی نماند.
برای پیام مدیر و مشتری، متن‌ها و رویدادها جدا هستند. موفقیت پیام مشتری به معنی آماده‌بودن متن مدیر نیست.
متن تأییدشده در پنل چه تفاوتی با حالت الگویی دارد؟
در پنل‌هایی با ارسال الگویی مستقل، جم پک شناسه الگو و مجموعه‌ای از مقدارها را می‌فرستد. اتصال نیازپرداز چنین درخواستی نمی‌سازد؛ متن کامل پیام و شماره فرستنده ارسال می‌شوند.
طبق راهنمای اتصال نیازپرداز در جم پک، می‌توانید متن نمونه را برای تأیید در پنل ثبت کنید تا سرویس، متن نهایی را با آن تطبیق دهد. برای استفاده از این مسیر، شرایط حساب و خط را با نیازپرداز بررسی کنید؛ پذیرش متن به معنی تضمین تحویل به همه شماره‌ها یا عبور از محدودیت پیامک تبلیغاتی نیست.
برای آماده‌کردن متن:
- پیام موردنیاز کسب‌وکار را مشخص کنید.
- بخش ثابت و بخش متغیر آن را از هم جدا کنید.
- متن و شیوه معرفی قسمت‌های متغیر را مطابق راهنمای خود پنل برای تأیید آماده کنید.
- پس از آماده‌شدن الگو در حساب، بخش ثابت متن جم پک را با آن تطبیق دهید.
- در محل داده‌های متغیر، متغیرهای معتبر جم پک را قرار دهید.
- شماره فرستنده موردنیاز این مسیر را با پشتیبانی سرویس تأیید کنید.
- با سفارش آزمایشی، متن نهایی را بررسی کنید.
نحو تعریف متغیر در پنل نیازپرداز در این بررسی تأیید نشده است؛ {1}، {0} یا روش یک پنل دیگر را بدون بررسی به آن منتقل نکنید.
در این مسیر، تغییر متن ثابت می‌تواند باعث ناسازگاری با الگوی تأییدشده شود. پس از ویرایش متن، فقط به ذخیره موفق تنظیمات اکتفا نکنید؛ ارسال همان متن را دوباره آزمایش کنید.
آزمون عمومی اتصال
پس از ذخیره کلید و شماره فرستنده:
- در «تنظیمات اصلی»، بخش تست پیامک را پیدا کنید.
- شماره متعلق به خودتان را در «شماره موبایل تست» وارد کنید.
- از رقم‌های انگلیسی و قالب معمول شماره همراه ایران استفاده کنید.
- روی «ارسال پیامک تست» بزنید و منتظر نتیجه بمانید.
- نتیجه روی صفحه، پنل نیازپرداز و گوشی را بررسی کنید.
دکمه تست، متن آماده جم پک را می‌فرستد؛ متن اعلان سفارش شما را آزمایش نمی‌کند. پیامک تست در تاریخچه معمول اعلان‌ها ثبت نمی‌شود؛ برای بررسی نتیجه، پاسخ کادر تست، گزارش پنل و گوشی را ببینید.
اگر حساب یا خط فقط متن‌های تأییدشده را می‌پذیرد، پیام آماده تست ممکن است با خطای ۱۸ رد شود. در این حالت، نتیجه را فوراً به کلید اشتباه نسبت ندهید. متن واقعیِ تأییدشده را از طریق رویداد سفارش آزمایش کنید.
موفقیت تست عمومی نیز پذیرش همه متن‌های سفارش را ثابت نمی‌کند؛ متن، دریافت‌کننده و شرایط خط در ارسال بعدی می‌توانند متفاوت باشند.
آزمون واقعی با سفارش
برای بررسی کامل‌تر، از محیط آزمایشی و اطلاعات متعلق به خودتان استفاده کنید:
- فقط اعلان موردنظر را برای مدیر یا مشتری فعال کنید.
- متن ذخیره‌شده آن اعلان و شماره فرستنده را کنترل کنید.
- در صورت نیاز به تاریخچه، ثبت گزارش پیامک را فعال کنید.
- برای پیام مشتری، شماره آزمایشی را در اطلاعات صورتحساب سفارش قرار دهید؛ برای پیام مدیر، شماره مدیر را کنترل کنید.
- برای اعلان ثبت سفارش، یک خرید آزمایشی تازه انجام دهید.
- برای اعلان تغییر وضعیت، سفارش آزمایشی را به وضعیتی ببرید که اعلان آن فعال است.
- پیام گوشی و نتیجه ثبت‌شده در پنل و تاریخچه جم پک را بررسی کنید.
- شماره سفارش و سایر داده‌های جایگزین‌شده را با همان سفارش تطبیق دهید.
اگر از متن تأییدشده استفاده می‌کنید، متن نهایی را با متن و قواعد پذیرفته‌شده در پنل مقایسه کنید. تفاوتی مثل عبارت اضافه، نشانه‌گذاری، فاصله یا مقدار خالی را بررسی کنید؛ حساسیت دقیق سرویس به هر تفاوت باید با حساب واقعی مشخص شود.
در صورت نتیجه نامشخص، پیش از تکرار، گزارش پنل و گوشی را ببینید. پایان زمان انتظار همیشه ثابت نمی‌کند که پیام پذیرفته نشده است.
موفقیت درخواست با تحویل پیام متفاوت است
جم پک کد نتیجه پاسخ نیازپرداز را بررسی می‌کند. اگر کد نتیجه در پاسخ قابل‌شناسایی سرویس صفر باشد، ارسال موفق ثبت می‌شود. دریافت پاسخ HTTP به‌تنهایی برای اعلام موفقیت کافی نیست.
این وضعیت، گزارش قطعی تحویل پیام به گوشی نیست. اتصال بررسی‌شده برای اعلان‌ها استعلام خودکار وضعیت تحویل اجرا نمی‌کند. دریافت واقعی و گزارش پنل را جدا بررسی کنید.
هر درخواست این اتصال حداکثر ۱۰۰ گیرنده دارد. درخواست بزرگ‌تر رد می‌شود و خودکار به چند بخش تقسیم نمی‌شود. این محدودیت مربوط به هر درخواست است و تعداد کل مخاطبان فروشگاه یا پیام‌های روزانه را مشخص نمی‌کند.
خطاهای مهم و اقدام پیشنهادی
جدول زیر بر اساس کدهای شناخته‌شده در اتصال جم پک است. شماره «کد نتیجه سرویس» را با کد HTTP اشتباه نگیرید.
| کد نتیجه | معنی در اتصال | اقدام پیشنهادی |
|---|---|---|
| ۳ | شماره فرستنده نامعتبر | خط واردشده را با خطوط مجاز حساب تطبیق دهید |
| ۶ | خط فرستنده غیرفعال | وضعیت فعال‌بودن همان خط را بررسی کنید |
| ۸ | اعتبار کافی نیست | موجودی قابل‌استفاده حساب را کنترل کنید |
| ۱۰ | وب‌سرویس غیرفعال | دسترسی وب‌سرویس حساب را بررسی کنید |
| ۱۴ | تعرفه حساب تعریف نشده | از پشتیبانی نیازپرداز وضعیت تعرفه را بخواهید |
| ۱۵ | تکرار همان متن برای همان شماره در یک بازه | وضعیت پیام قبلی را بررسی کنید؛ پی‌درپی ارسال نکنید |
| ۱۶ | گیرنده یافت نشده یا در فهرست سیاه | صحت شماره، وضعیت خط و شرایط پیام خدماتی را بررسی کنید |
| ۱۷ | متن پیام خالی | متن رویداد و نتیجه جایگزینی متغیرها را کنترل کنید |
| ۱۸ | متن با الگوی تأییدشده مطابقت ندارد | متن نهایی را با الگو و قواعد حساب تطبیق دهید |
| ۱۹ | اعتبار زمانی پنل تمام شده | مهلت استفاده از حساب را بررسی کنید |
| ۲۱ | پارامتر ورودی نامعتبر | متن کامل خطا، خط، شماره و داده‌های پیام را بررسی کنید |
| ۲۲ | آی‌پی سرور موقتاً مسدود | از هاست و نیازپرداز وضعیت آی‌پی خروجی را پیگیری کنید |
| ۲۴ | درخواست کاملاً تکراری در فاصله کوتاه | پیش از ارسال دوباره، نتیجه درخواست قبلی را ببینید |
| ۲۵ | کلید API نامعتبر | کلید صحیح همان حساب را وارد و ذخیره کنید |
کدهای ۴ و ۵ به محدودیت روزانه و تعداد گیرندگان مربوط‌اند. کدهای ۲ و ۲۰ به وضعیت غیرفعال یا مسدود حساب اشاره دارند. در خطاهای به‌روزرسانی یا عملیات ناموفق، زمان و متن پاسخ را ثبت کنید و پیش از تکرار، وضعیت پیام قبلی را بررسی کنید.
خطا از نام کاربری یا رمز حرف می‌زند
در جدول خطای سرویس، کد ۱ با عبارت نام کاربری یا رمز نامعتبر توصیف شده است و کد منفی ۲۰ به مسدودشدن پنل پس از ورود رمز اشتباه اشاره دارد.
این پیام‌ها به معنی وجود فیلد رمز در اتصال جم پک نیستند. کلید API، وضعیت حساب و متن پاسخ را با پشتیبانی بررسی کنید؛ رمز پنل را جای کلید API وارد نکنید.
گزینه الگو یا شناسه الگو دیده نمی‌شود
برای نیازپرداز در این اتصال طبیعی است. تنظیم روش ارسال بر پایه متن مستقیم است؛ شناسه و نگاشت متغیر پنل‌های دیگر کاربرد ندارد.
اگر همچنان راهنمای پنل قبلی را می‌بینید، انتخاب نیازپرداز را ذخیره و صفحه را دوباره باز کنید.
خطای ۱۸ می‌گیرم
ابتدا مشخص کنید کدام متن ارسال شده است: پیام آماده تست یا متن رویداد سفارش؟
برای متن سفارش، بخش ثابت، داده‌های جایگزین‌شده و وضعیت تأیید متن در حساب را کنترل کنید. برای تست عمومی، ممکن است متن آماده با قواعد حساب شما سازگار نباشد. به‌جای تغییر بی‌دلیل کلید، یک رویداد آزمایشی با متن مجاز را بررسی کنید.
جزئیات قواعد تطبیق و وضعیت خط باید از نیازپرداز تأیید شود؛ صرف دریافت این کد، مشکل دقیق در فاصله یا یک واژه مشخص را ثابت نمی‌کند.
خطای ۱۶ می‌گیرم
این کد فقط یک علت قطعی ندارد. شماره نامعتبر یا یافت‌نشدن گیرنده و محدودیت دریافت پیامک می‌توانند مطرح باشند.
شماره متعلق به خودتان را کنترل کنید و از سرویس درباره خط و مسیر مجاز پیام خدماتی بپرسید. تأیید متن یا انتخاب یک خط، تضمین دریافت همه پیام‌ها توسط همه شماره‌ها نیست.
خطای ارتباط یا پاسخ نامشخص می‌بینم
زمان خطا، کد HTTP و کد نتیجه سرویس را، اگر موجودند، ثبت کنید. اتصال خروجی HTTPS سرور به دامنه نیازپرداز را از هاست پیگیری کنید.
پاسخ نامشخص یعنی جم پک نتوانسته موفقیت را از پاسخ دریافتی تشخیص دهد؛ ممکن است پاسخ سرویس یا واسط شبکه با ساختار موردانتظار تفاوت داشته باشد. پیش از تکرار، پنل را بررسی کنید.
نشانی اتصال را به دامنه‌های مشابه تغییر ندهید و HTTPS یا بررسی گواهی را برای دورزدن خطا خاموش نکنید. گزارش پاک‌سازی‌شده را برای پشتیبانی بفرستید.
اعلان سفارش نمی‌آید ولی تست موفق است
فعال‌بودن همان رویداد، دریافت‌کننده، شماره، متن و گزارش ارسال را بررسی کنید. تست عمومی اجرای رویداد سفارش را تأیید نمی‌کند.
پس از تغییر درگاه، به متن‌های مستقیم قبلی توجه کنید. در مسیر سفارش، انتخاب ذخیره‌شده حالت الگویی از پنل قبلی، نیازپرداز را به ارسال الگویی مستقل تبدیل نمی‌کند؛ ارسال از مسیر مستقیم انجام می‌شود.
امنیت و مراقبت از اطلاعات
- کلید API را در تصویر، ویدئو یا گزارش عمومی نمایش ندهید.
- سرآیندهای درخواست ممکن است کلید اتصال را داشته باشند؛ پیش از اشتراک‌گذاری حذفشان کنید.
- متن پیام و شماره مشتری را از گزارش عمومی پاک کنید.
- آزمون را با شماره خودتان انجام دهید، نه مشتری واقعی.
- در صورت افشای کلید، آن را در سرویس تعویض و مقدار جدید را در جم پک ثبت کنید.
- پس از آزمون، رویدادها و شماره‌های موقت را بازبینی کنید.
چک‌لیست پایان راه‌اندازی
- نیازپرداز به‌عنوان درگاه ذخیره شده است.
- کلید API و شماره فرستنده صحیح وارد شده‌اند.
- متن مستقیم رویدادهای فعال بازبینی شده است.
- شناسه یا نگاشت الگوی پنل دیگری استفاده نشده است.
- در صورت نیاز، شرایط تأیید متن و خط خدماتی با سرویس بررسی شده است.
- تست عمومی با آزمون متن واقعی سفارش اشتباه گرفته نشده است.
- متن نهایی، شماره سفارش و دریافت پیام آزمایشی بررسی شده‌اند.
- موفقیت درخواست با تحویل قطعی یکسان فرض نشده است.
- اطلاعات حساس از رسانه‌ها و گزارش‌ها حذف شده‌اند.
جمع‌بندی
برای اتصال نیازپرداز، کلید API و شماره فرستنده را ثبت کنید، متن اعلان‌ها را در جم پک بنویسید و با سفارش آزمایشی نتیجه را بررسی کنید.
اگر از متن تأییدشده استفاده می‌کنید، تمرکز روی متن نهایی و قواعد حساب است، نه شناسه الگو یا نگاشت جدا. آزمون عمومی اتصال و آزمون متن واقعی سفارش را هر دو متناسب با محدودیت‌های حساب انجام دهید.