در این راهنما، اطلاعات اتصال، شناسه الگو، متغیرها و خطاهای فراز اس‌ام‌اس را بررسی می‌کنیم. برای انتخاب روش و اتصال مشترک، انتخاب پنل، برای تنظیم اعلان سفارش، مدیریت رویدادها و برای تشخیص خطاهای عمومی، عیب‌یابی پیامک را ببینید.
برای اتصال فراز اس‌ام‌اس به جم پک به کلید API نیاز دارید. این اتصال دو روش ارسال دارد: متن مستقیم و الگو. در روش الگویی، کد الگو و نام متغیرها باید با متن آماده‌شده در پنل هماهنگ باشند.
برای مثال، اگر در متن الگو متغیر %order_id% دارید، نامی که در نگاشت وارد می‌کنید order_id است؛ بدون علامت درصد. سپس مشخص می‌کنید این متغیر از کدام داده سفارش پر شود.
این راهنما مخصوص گزینه FarazSMS در جم پک است. شباهت نام دامنه سرویس یا نام متغیرها، به معنی یکسان‌بودن آن با گزینه جداگانه ایران‌پیامک نیست. برای تنظیم رویدادها و دریافت‌کنندگان، راهنمای مرکز پیامک ووکامرس را هم مطالعه کنید.
این راهنما چه مواردی را پوشش می‌دهد؟
- دریافت کلید اتصال و بررسی خط حساب؛
- انتخاب فراز اس‌ام‌اس در جم پک؛
- آزمون مسیر مستقیم؛
- آماده‌کردن الگو و ثبت کد آن؛
- نگاشت نام‌دار داده‌های سفارش؛
- آزمون اعلان الگویی با سفارش؛
- بررسی خطاهای اتصال، متن، الگو و گیرنده؛
- حفظ اطلاعات محرمانه در گزارش و رسانه آموزشی.
اطلاعات موردنیاز اتصال
| عنوان فیلد در جم پک | چه مقداری وارد شود؟ | کاربرد |
|---|---|---|
| کلید API | کلید وب‌سرویس حساب فراز اس‌ام‌اس | مستقیم و الگویی |
| شماره خط | خط مجاز حساب، در صورت تعیین خط مشخص | مستقیم و الگویی |
| شناسه الگو | کد همان الگوی آماده‌شده در پنل | اعلان الگویی مربوط به هر رویداد |
کلید API را با رمز ورود پنل یا کد الگو اشتباه نگیرید. فقط مقدار کلید را وارد کنید؛ نام سرآیند Api-Key را به آن اضافه نکنید.
«شماره خط» در فرم اختیاری است. اگر خالی بماند، کد اتصال شماره خطی در درخواست نمی‌فرستد. توضیح فیلد، این حالت را برای استفاده از خط پیش‌فرض حساب در نظر گرفته است؛ وجود خط پیش‌فرض و مجوز آن باید در حساب شما بررسی شود.
اختیاری‌بودن فیلد در جم پک به معنی تضمین ارسال بدون خط قابل‌استفاده در سرویس نیست.
آماده‌کردن حساب فراز اس‌ام‌اس
- وارد حساب فراز اس‌ام‌اس شوید.
- کلید API را از بخش وب‌سرویس حساب دریافت کنید.
- فعال‌بودن دسترسی ارسال و اعتبار حساب را بررسی کنید.
- خط مجاز یا خط پیش‌فرض حساب را مشخص کنید.
- برای ارسال الگویی، متن، کد الگو و نام متغیرهای آن را آماده کنید.
- در صورت ابهام، سازگاری کلید و حساب با وب‌سرویس مورد استفاده این اتصال را از پشتیبانی بپرسید.
محل دقیق منوهای حساب در این راهنما تأیید نشده است. برای دریافت کلید و تأیید الگو، راهنمای داخل پنل را دنبال کنید.
انتخاب فراز اس‌ام‌اس در جم پک
- وارد پیشخوان وردپرس شوید.
- در جم پک، «اعلان‌های پیامکی» را باز کنید.
- وارد «تنظیمات اصلی» شوید.
- «فعال‌سازی پیامک» را روشن کنید.
- در «درگاه پیامک»، گزینه
FarazSMSرا انتخاب کنید. - تنظیمات را ذخیره و صفحه را دوباره باز کنید.
- «کلید API» را وارد کنید.
- اگر قرار است از خط مشخصی استفاده کنید، «شماره خط» را با مقدار تأییدشده پنل تکمیل کنید.
- دوباره تنظیمات را ذخیره کنید.
پس از انتخاب درگاه، تنظیمات را ذخیره کنید و سپس سراغ نگاشت بروید. نگاشت مشخص می‌کند هر متغیر الگو با کدام داده سفارش پر شود. راهنمای آن بر اساس درگاه ذخیره‌شده نمایش داده می‌شود.
برخلاف گزینه ایران‌پیامک، این اتصال فیلد تغییر آدرس پایه ندارد. دامنه api.iranpayamak.com در کد فراز اس‌ام‌اس تعریف شده است؛ صرف دیدن این نام، دلیل تغییر گزینه انتخاب‌شده به ایران‌پیامک نیست.
تفاوت ارسال مستقیم و الگویی
پیامک مستقیم
جم پک متن پیام را با داده‌های سفارش کامل می‌کند و آن را برای یک شماره می‌فرستد. نمونه متن:
سفارش {order_number} شما ثبت شد.
برای شماره سفارش فرضی 1250، نتیجه موردانتظار این است:
سفارش 1250 شما ثبت شد.
این نمونه فقط نتیجه موردانتظار را نشان می‌دهد. ارسال همین متن به شماره خودتان را با خط و حساب موردنظر آزمایش کنید.
الگو/قالب
متن پایه در پنل آماده می‌شود. جم پک کد الگو، شماره گیرنده و مقدار متغیرهای نام‌دار را می‌فرستد. نوشتن متن دلخواه در جم پک جای ایجاد و آماده‌کردن الگو در پنل را نمی‌گیرد.
وجود ارسال الگویی در کد به معنی تضمین تحویل فوری یا عبور قطعی از محدودیت شماره‌های مسدود نیست. این شرایط را با سرویس و آزمون واقعی بررسی کنید.
آزمون اولیه ارسال مستقیم
پس از ذخیره اطلاعات:
- در «تنظیمات اصلی»، بخش تست پیامک را پیدا کنید.
- شماره متعلق به خودتان را در «شماره موبایل تست» وارد کنید.
- از رقم‌های انگلیسی و قالب معمول شماره همراه ایران استفاده کنید.
- روی «ارسال پیامک تست» بزنید.
- منتظر نتیجه بمانید و دکمه را پی‌درپی نزنید.
- نتیجه کادر تست، گزارش حساب و گوشی را بررسی کنید.
دکمه تست، متن آماده جم پک را از مسیر مستقیم می‌فرستد. کد الگو و نگاشت سفارش در این تست بررسی نمی‌شوند.
پیامک تست در تاریخچه معمول اعلان‌ها ثبت نمی‌شود. برای بررسی نتیجه، پاسخ کادر تست، گزارش پنل و گوشی را ببینید.
اگر خطا به گیرنده یا دفترچه تلفن اشاره داشت، از تغییر تصادفی کلید و خط خودداری کنید. ابهام این مسیر در بخش رفع مشکل توضیح داده شده است. اگر فقط مسیر الگویی را نیاز دارید، آن را جدا با سفارش آزمایشی بررسی کنید.
آماده‌کردن الگوی سفارش
نمونه آموزشی متن پنل:
سفارش %order_id% شما ثبت شد.
در این نمونه، نام متغیر پنل order_id است.
- متن موردنظر را در پنل آماده کنید.
- وضعیت مجازبودن و آماده‌بودن الگو برای ارسال را بررسی کنید.
- کد الگو را بردارید.
- نام دقیق متغیرهای متن را یادداشت کنید.
- مشخص کنید هر متغیر با کدام داده سفارش پر می‌شود.
- وضعیت خط قابل‌استفاده برای الگو را بررسی کنید.
این متن، الگوی موجود یا تأییدشده حساب شما نیست. کد واقعی الگو را از همان حساب دریافت کنید.
کد الگو با نام متغیر متفاوت است. کد مشخص می‌کند کدام متن انتخاب شود؛ نام متغیر مشخص می‌کند هر داده در کدام بخش آن قرار بگیرد.
ثبت کد الگو و نگاشت در جم پک
مراحل مشترک انتخاب مخاطب، رویداد، روش ارسال و ذخیره در مدیریت رویدادها و الگوهای پیامکی آمده است. در اجرای این مراحل، نکته اختصاصی این پنل را رعایت کنید:
کد الگو را ثبت کنید و نام متغیرها را بدون علامت درصد وارد کنید.
برای %order_id% در نام نگاشت بنویسید order_id، نه %order_id% یا {order_id}.
نام متغیر پنل می‌تواند با نام داده جم پک فرق داشته باشد. برای مثال، متغیر پنل order_id می‌تواند از داده order_number جم پک پر شود، اگر هدف متن، نمایش شماره سفارش به مشتری است.
روش ارسال و رویدادهای مدیر و مشتری جدا هستند. کد و نگاشت تمام اعلان‌های فعال هر گروه را کامل کنید.
مثال کامل نگاشت نام‌دار
فرض کنید متن پنل این باشد:
%customer% عزیز، سفارش %order_id% شما در وضعیت %status% قرار گرفت.
نگاشت:
| نام در متن پنل | نام واردشده در نگاشت | داده انتخابی جم پک |
|---|---|---|
%customer% | customer | نام مشتری — customer_name |
%order_id% | order_id | شماره سفارش — order_number |
%status% | status | وضعیت سفارش — order_status |
با داده‌های فرضی «سارا احمدی»، «1250» و «در حال انجام»، نتیجه موردانتظار:
سارا احمدی عزیز، سفارش 1250 شما در وضعیت در حال انجام قرار گرفت.
در فراز اس‌ام‌اس، نام هر متغیر باید دقیقاً با نام آن در الگو یکسان باشد. جابه‌جاکردن ردیف‌ها، نام اشتباه را اصلاح نمی‌کند.
- نام‌ها را عیناً مطابق الگو وارد کنید.
- درصدها را در نام نگاشت ننویسید.
- نام تکراری نسازید؛ مقدار بعدی می‌تواند جای قبلی همان نام را بگیرد.
- ردیف بدون نام یا داده معتبر باقی نگذارید.
- از نام‌هایی مانند
token1فقط وقتی استفاده کنید که واقعاً نام متغیر همان الگوی پنل باشند.
نگاشت الگوی دارای متغیر را خالی نگذارید. مسیر عمومی سفارش در نبود نگاشت ممکن است داده‌های ترتیبی را از متن ذخیره‌شده استخراج کند؛ این جای نگاشت صحیح نام‌دار را نمی‌گیرد.
آزمون اعلان الگویی با سفارش
برای بررسی الگو، از محیط آزمایشی و شماره خودتان استفاده کنید:
- کلید، خط موردنظر، کد الگو و نام متغیرها را بازبینی کنید.
- فقط اعلان موردنظر را فعال کنید.
- در صورت نیاز به تاریخچه، ثبت گزارش پیامک را فعال کنید.
- شماره آزمایشی را در محل دریافت‌کننده قرار دهید: شماره صورتحساب مشتری یا شماره مدیر.
- برای اعلان ثبت سفارش، خرید آزمایشی تازه‌ای انجام دهید.
- برای اعلان تغییر وضعیت، سفارش آزمایشی را به وضعیتی ببرید که اعلانش فعال است.
- متن گوشی، گزارش پنل و تاریخچه جم پک را مقایسه کنید.
- نام، شماره سفارش و وضعیت را با اطلاعات همان سفارش تطبیق دهید.
تاریخچه الگویی می‌تواند کد الگو و مقدارهای ارسالی را نشان دهد، نه متن کامل نهایی. متن دریافت‌شده را هم بررسی کنید.
اگر نتیجه نامشخص بود، پیش از تکرار، پنل و گوشی را کنترل کنید. خطای شبکه همیشه ثابت نمی‌کند که درخواست قبلی پذیرفته نشده است.
آزمون یک پیام به معنی تأیید همه رویدادها نیست. الگوهای مهم و گروه دیگر دریافت‌کنندگان را جدا بررسی کنید.
موفقیت درخواست با دریافت پیام یکسان نیست
جم پک مقدار وضعیت پاسخ سرویس را بررسی می‌کند. پاسخ با وضعیت success در مسیر موفق قرار می‌گیرد؛ صرف دریافت HTTP موفق کافی نیست.
بااین‌حال، نتیجه موفق در جم پک گزارش قطعی تحویل به گوشی نیست. این اتصال وضعیت تحویل پیام را خودکار استعلام نمی‌کند. دریافت واقعی و گزارش پنل را جدا بررسی کنید.
خطاهای رایج و روش بررسی
کلید API تنظیم نشده است
فیلد کلید را تکمیل و ذخیره کنید. رمز پنل، کد الگو و نام سرآیند جای مقدار کلید نیستند.
اگر کلید موجود است ولی سرویس آن را رد می‌کند، تعلق آن به حساب صحیح، فعال‌بودن دسترسی و سازگاری حساب با وب‌سرویس این اتصال را بررسی کنید. بدون خواندن پاسخ، علت را تمام‌شدن اعتبار فرض نکنید.
شناسه الگو تنظیم نشده یا پذیرفته نمی‌شود
کد الگوی همان رویداد را با پنل تطبیق دهید. نام دلخواه پیام یا شماره ردیف یک فهرست جای کد نیست.
وضعیت آماده‌بودن الگو و تعلق آن به حساب را نیز کنترل کنید. پیام خطای واقعی سرویس را نگه دارید؛ برای این اتصال جدول شماره خطای یک پنل دیگر را استفاده نکنید.
خط ارسال مشخص نیست یا سرویس آن را نمی‌پذیرد
اگر شماره خط خالی است، جم پک آن را در درخواست نمی‌فرستد. وضعیت خط پیش‌فرض حساب را بررسی کنید یا خط مجاز تأییدشده را وارد کنید.
از شماره ساختگی یا خط متعلق به حساب دیگر استفاده نکنید. خط پذیرفته‌شده برای یک روش ممکن است نیاز به بررسی جداگانه در روش دیگر داشته باشد.
خطای گیرنده یا دفترچه تلفن در ارسال مستقیم
کد فعلی، شماره مقصد را مستقیم در درخواست ارسال می‌کند؛ دفترچه تلفن ایجاد نمی‌کند و شناسه دفترچه را نمی‌فرستد.
توضیحات و ساختار مستندات سرویس درباره گیرندگان این روش با هم تفاوت دارند. به همین دلیل، لازم است پذیرش شماره گیرنده با حساب خودتان آزمایش شود.
اگر پاسخ، دفترچه تلفن یا selectedPhoneBooks را الزامی اعلام کرد:
- متن دقیق خطا و زمان رخداد را ثبت کنید.
- صحت شماره و کلید را بررسی کنید.
- موضوع پذیرش گیرنده مستقیم در همین مسیر را از پشتیبانی سرویس بپرسید.
- تا روشن‌شدن نتیجه، ارسال مستقیم را آماده استفاده عمومی معرفی نکنید.
ساخت دستی یک دفترچه تلفن به‌تنهایی اتصال فعلی جم پک را به استفاده از آن تغییر نمی‌دهد. تغییر نحوه درخواست، اگر لازم باشد، یک اصلاح فنی جداست و با دست‌کاری تصادفی تنظیمات حل نمی‌شود.
مستقیم موفق است ولی الگو ارسال نمی‌شود
موفقیت مستقیم، کد الگو و نام متغیرها را بررسی نکرده است. این موارد را کنترل کنید:
- روش ارسال گروه موردنظر الگویی باشد.
- کد الگوی همان رویداد تکمیل شده باشد.
- نام متغیرها دقیق و بدون درصد باشند.
- داده معتبر انتخاب شده باشد.
- خط و حساب مجوز استفاده از الگو را داشته باشند.
- پاسخ سرویس در تاریخچه خوانده شود.
حالت الگویی انتخاب شده ولی پیام مستقیم می‌رود
در مسیر اعلان سفارش، خالی‌بودن شناسه الگو می‌تواند ارسال را به مستقیم برگرداند. کد الگوی تمام رویدادهای فعال گروه را کامل کنید.
این نکته برای فراز اس‌ام‌اس مهم است، چون مسیر مستقیم و الگویی باید جدا آزموده شوند. آماده‌بودن الگو، مسیر مستقیمِ جایگزین را خودکار تأیید نمی‌کند.
متغیرها خالی یا نادرست هستند
نام‌های نگاشت را با الگوی پنل مقایسه کنید. نام تکراری، علامت درصد اضافه، ردیف ناقص و انتخاب داده اشتباه را بررسی کنید.
ترتیب‌دادن دوباره ردیف‌ها به‌تنهایی نام اشتباه را اصلاح نمی‌کند. اگر داده سفارش خالی است، مقدار موردانتظار را در همان سفارش هم کنترل کنید.
خطای نامشخص یا پایان زمان انتظار
این اتصال در همه حالت‌ها متن خام پاسخ و کد HTTP را به کاربر نشان نمی‌دهد. اگر سرویس پاسخ قابل‌شناسایی ندهد، ممکن است فقط «خطای نامشخص» نمایش داده شود.
زمان رخداد، نوع ارسال، رویداد و نتیجه پنل را ثبت کنید. بررسی فنی سمت سرور ممکن است برای دیدن جزئیات لازم باشد. کلید و داده مشتری را از گزارش حذف کنید.
برای خطای شبکه، دسترسی خروجی HTTPS به api.iranpayamak.com را از هاست پیگیری کنید. آدرس سرویس یا بررسی گواهی را برای دورزدن خطا تغییر ندهید.
امنیت اطلاعات اتصال
- کلید را در تصویر، ویدئو یا گزارش عمومی قرار ندهید.
- گزارش درخواست ممکن است سرآیند حاوی کلید و متن یا داده مشتری را داشته باشد؛ پیش از اشتراک‌گذاری پاک‌سازی کنید.
- آزمون را با شماره خودتان انجام دهید.
- در صورت افشای کلید، آن را در پنل تعویض و مقدار جدید را ذخیره کنید.
- پس از تغییر کلید، خط یا الگو، مسیر مربوط را دوباره بیازمایید.
- شماره‌ها و اعلان‌های موقت آزمون را پس از پایان بازبینی کنید.
چک‌لیست پایان راه‌اندازی
- فراز اس‌ام‌اس به‌عنوان درگاه ذخیره شده است.
- کلید صحیح حساب وارد شده است.
- خط مشخص یا پیش‌فرض حساب بررسی شده است.
- کد الگوی هر رویداد فعال تکمیل شده است.
- نگاشت نام‌دار، کامل و بدون نام تکراری است.
- مستقیم و الگویی جدا آزموده شده‌اند.
- ابهام گیرندگان مسیر مستقیم، در صورت مشاهده خطا، تعیین تکلیف شده است.
- متن پیام با اطلاعات سفارش تطبیق داده شده است.
- موفقیت درخواست با تحویل قطعی یکسان فرض نشده است.
جمع‌بندی
کلید فراز اس‌ام‌اس را ثبت کنید، وضعیت خط را مشخص کنید و برای هر اعلان الگویی، کد الگو و نام متغیرها را دقیق نگاشت کنید.
نتیجه را با سفارش آزمایشی و دریافت واقعی بررسی کنید. مسیر مستقیم و الگویی مستقل‌اند؛ ابهام یا موفقیت یکی را به دیگری تعمیم ندهید.