در این راهنما، اطلاعات اتصال، الگوها، متغیرها و خطاهای ایران‌پیامک را بررسی می‌کنیم. برای انتخاب روش و اتصال مشترک، انتخاب پنل، برای تنظیم اعلان سفارش، مدیریت رویدادها و برای تشخیص خطاهای عمومی، عیب‌یابی پیامک را ببینید.
برای اتصال ایران‌پیامک، کلید API و شماره فرستنده را در جم پک وارد می‌کنید. سپس می‌توانید متن مستقیم بفرستید یا برای اعلان‌های سفارش از الگوی آماده پنل استفاده کنید.
در الگوهای ایران‌پیامک، هر متغیر نام مشخصی دارد. نگاشت یعنی تعیین کنید هر نام با کدام داده سفارش پر شود. نام‌ها باید دقیق باشند؛ مرتب‌کردن ردیف‌ها به‌تنهایی کافی نیست.
این اتصال از رابط Edge استفاده می‌کند و یک فیلد اختیاری برای آدرس پایه سرویس دارد. اگر ارائه‌دهنده برای حساب شما آدرس دیگری تعیین کرده باشد، باید همان نشانی تأییدشده را وارد کنید؛ آدرس صفحه ورود پنل لزوماً آدرس وب‌سرویس نیست.
برای انتخاب رویدادهای مدیر، مشتری و موجودی، راهنمای مرکز پیامک ووکامرس را هم مطالعه کنید.
این راهنما چه مواردی را پوشش می‌دهد؟
- آماده‌کردن کلید و خط فرستنده؛
- انتخاب ایران‌پیامک و تعیین آدرس پایه در صورت نیاز؛
- آزمون مستقیم اتصال؛
- ثبت کد الگو و نام متغیرها؛
- آزمون اعلان الگویی با سفارش؛
- بررسی خطاهای احراز هویت، آدرس، الگو و داده‌های پیام؛
- کنترل امنیت کلید و مقصد اتصال.
اطلاعات موردنیاز اتصال
| عنوان فیلد در جم پک | مقدار موردنیاز | نکته |
|---|---|---|
| کلید API | کلید دسترسی وب‌سرویس حساب | فقط مقدار کلید را وارد کنید |
| شماره فرستنده | خط مجاز همان حساب | برای مستقیم و الگویی لازم است |
| آدرس پایه API (اختیاری) | نشانی پایه تأییدشده ارائه‌دهنده | در حالت معمولِ استفاده از مقصد پیش‌فرض خالی بماند |
| شناسه الگو | کد الگو در پنل | در تنظیمات هر اعلان الگویی وارد می‌شود |
در فیلد کلید، عبارت Bearer یا Authorization اضافه نکنید. جم پک کلید واردشده را مستقیماً در سرآیند احراز هویت قرار می‌دهد.
«شناسه الگو» همان کد الگو است، نه شماره ردیف فهرست یا نام دلخواه پیام در سایت. کد واقعی پنل را بدون تغییر وارد کنید.
آماده‌کردن کلید و حساب
- وارد حساب ایران‌پیامک شوید.
- بخش کلیدهای دسترسی وب‌سرویس را پیدا کنید و کلید مربوط به حساب را دریافت کنید.
- خط فرستنده مجاز را مشخص کنید.
- فعال‌بودن دسترسی ارسال و اعتبار حساب را بررسی کنید.
- برای استفاده از الگو، کد و نام متغیرهای متن آماده را یادداشت کنید.
- اگر سرویس نشانی اختصاصی دارد، آدرس پایه دقیق آن را دریافت کنید.
راهنمای فیلد در جم پک از مسیر Developers > Access Keys نام می‌برد. محل دقیق منوهای حساب ایران‌پیامک در این راهنما تأیید نشده است؛ اگر منوهای حساب شما متفاوت‌اند، از راهنمای داخل پنل کمک بگیرید.
برای اتصال پایدار، کلید API حساب را تهیه کنید و به‌جای آن رمز ورود پنل یا توکن موقتی استخراج‌شده از مرورگر را ننویسید. شرایط اعتبار و ابطال کلید را از حساب و سرویس بررسی کنید.
انتخاب ایران‌پیامک در جم پک
- در پیشخوان وردپرس، جم پک را باز کنید.
- وارد «اعلان‌های پیامکی» و سپس «تنظیمات اصلی» شوید.
- «فعال‌سازی پیامک» را روشن کنید.
- در «درگاه پیامک»،
IranPayamakرا انتخاب کنید. - تنظیمات را ذخیره و صفحه را دوباره باز کنید.
- «کلید API» و «شماره فرستنده» را تکمیل کنید.
- آدرس پایه را فقط در صورت نیاز و بر اساس توضیح بخش بعد وارد کنید.
- دوباره تنظیمات را ذخیره کنید.
پیش از تنظیم نگاشت، انتخاب پنل را ذخیره کنید. راهنمای متغیرها بر اساس درگاه ذخیره‌شده ساخته می‌شود؛ انتخاب جدید بدون ذخیره ممکن است هنوز راهنمای پنل قبلی را نشان دهد.
آدرس پایه API را چه زمانی وارد کنیم؟
اگر فیلد خالی باشد، کد اتصال از این نشانی استفاده می‌کند:
https://edge.ippanel.com/v1
این مقدار، پیش‌فرض اتصال است؛ به معنی آزموده‌شدن همه حساب‌های ایران‌پیامک روی همین مقصد نیست.
اگر ارائه‌دهنده برای حساب شما نشانی متفاوتی اعلام کرده، همان آدرس پایه را وارد کنید. کلید و آدرس باید متعلق به یک سرویس سازگار باشند.
- آدرس صفحه ورود پنل را به‌جای آدرس پایه ننویسید.
- مسیر کامل ارسال را وارد نکنید؛ جم پک مسیر
/api/sendرا به پایه اضافه می‌کند. - بخش نسخه یا مسیر پایه اعلام‌شده را خودسرانه حذف نکنید.
- آدرس‌های قدیمی یا متعلق به پنل دیگر را از راهنماهای نامرتبط کپی نکنید.
- از HTTPS استفاده کنید.
- برای رفع یک خطای موقت شبکه، مقصد را حدس نزنید.
کلید API به مقصد تعیین‌شده در این فیلد ارسال می‌شود. درست‌بودن قالب آدرس به معنی قابل‌اعتمادبودن صاحب آن نیست. فقط نشانی تأییدشده ارائه‌دهنده را وارد کنید.
اگر آدرس نامعتبر باشد، اتصال خطا می‌دهد و خودکار از آدرس پیش‌فرض استفاده نمی‌کند. برای استفاده از پیش‌فرض، فیلد را واقعاً خالی و تنظیمات را ذخیره کنید.
شماره فرستنده را چگونه وارد کنیم؟
خط باید متعلق به حساب و برای روش موردنظر مجاز باشد. کد اتصال، خط عددی معمول را به قالب بین‌المللی تبدیل می‌کند. برای نمونه، مقدار فرضی 3000505 به +983000505 تبدیل می‌شود.
این نمونه به معنی اختصاص آن خط به حساب شما نیست. از خط واقعی خودتان و ترجیحاً شکل کامل تأییدشده پنل با رقم‌های انگلیسی استفاده کنید.
اگر خط حروفی دارید، شکل کامل اعلام‌شده با پیش‌شماره را وارد کنید. عبور مقدار از فرم به معنی تأیید مجوز خط نیست؛ پذیرش نهایی را سرویس تعیین می‌کند.
شماره فرستنده را با شماره مشتری اشتباه نگیرید. قالب گیرنده نیز در لایه اتصال به شکل بین‌المللی تبدیل می‌شود؛ برای آزمون، شماره همراه متعلق به خودتان را وارد کنید.
آزمون اولیه ارسال مستقیم
پس از ذخیره اطلاعات:
- در «تنظیمات اصلی»، بخش تست پیامک را پیدا کنید.
- شماره خودتان را در «شماره موبایل تست» وارد کنید.
- از رقم‌های انگلیسی و قالب معمول شماره همراه ایران استفاده کنید.
- روی «ارسال پیامک تست» بزنید.
- منتظر نتیجه بمانید و دکمه را پی‌درپی نزنید.
- نتیجه کادر تست، گزارش پنل و گوشی را با هم بررسی کنید.
این دکمه، پیام آماده جم پک را از مسیر مستقیم می‌فرستد؛ کد الگو و نگاشت سفارش را آزمایش نمی‌کند.
پیامک تست در تاریخچه معمول اعلان‌ها ثبت نمی‌شود. نتیجه را در کادر تست، گزارش پنل و گوشی بررسی کنید.
اگر خط یا حساب فقط برای نوع مشخصی از پیام آماده است، ردشدن متن تست را فوراً به کلید اشتباه نسبت ندهید. متن پاسخ و مجوز خط را بررسی کنید و مسیر الگویی را جدا آزمایش کنید.
ارسال مستقیم و محدودیت‌های آن
در حالت مستقیم، جم پک متن را با داده‌های سفارش کامل می‌کند و به سرویس می‌فرستد. نمونه:
سفارش {order_number} شما ثبت شد.
با شماره سفارش فرضی 1250، متن موردانتظار این است:
سفارش 1250 شما ثبت شد.
در این حالت، کد الگو و نام متغیرهای پنل لازم نیستند. مجوز خط، پذیرش متن و اعتبار حساب همچنان اهمیت دارند.
در ارسال مستقیم، هر درخواست حداکثر ۱۰۰۰ گیرنده دارد؛ افزونه درخواست بزرگ‌تر را خودکار به چند بخش تقسیم نمی‌کند. اگر ابزار شمارش متن چندبایتی روی سرور فعال باشد، طول متن هم به ۱۴۰۰ نویسه محدود می‌شود. این اعداد محدودیت هر درخواست‌اند و تعداد کل مشتریان فروشگاه یا سهمیه روزانه حساب را مشخص نمی‌کنند.
متن آزمون را کوتاه نگه دارید. محدودیت اندازه پیام با تعداد پیام‌های قابل‌صورتحساب یک مفهوم نیست؛ هزینه و شرایط سرویس را جدا بررسی کنید.
آماده‌کردن الگوی ایران‌پیامک
الگوهای این اتصال متغیر نام‌دار دارند. نمونه آموزشی:
سفارش %order_number% شما ثبت شد.
در این مثال، نام متغیر order_number است؛ علامت‌های درصد فقط مرز متغیر در متن پنل را مشخص می‌کنند.
- متن موردنیاز را در پنل آماده کنید.
- وضعیت آماده‌بودن الگو برای ارسال را بررسی کنید.
- کد الگو را بردارید.
- نام دقیق تمام متغیرها را یادداشت کنید.
- مشخص کنید هر متغیر از کدام داده سفارش پر می‌شود.
- مجازبودن خط برای ارسال آن الگو را کنترل کنید.
این نمونه آموزشی، الگوی موجود یا تأییدشده حساب شما نیست.
در راهنمای رسمی ارسال الگویی IPPanel Edge، نام کلیدهای داده باید با جایگاه‌های الگو مطابقت داشته باشد و هر درخواست الگویی یک گیرنده دارد. شرایط حساب ایران‌پیامک و آماده‌بودن الگوی خودتان را جدا بررسی کنید.
ثبت کد و نگاشت متغیرها در جم پک
مراحل مشترک انتخاب مخاطب، رویداد، روش ارسال و ذخیره در مدیریت رویدادها و الگوهای پیامکی آمده است. در اجرای این مراحل، نکته اختصاصی این پنل را رعایت کنید:
کد الگو را ثبت کنید و نام متغیرها را بدون علامت درصد وارد کنید.
مثلاً برای %order_number%، در قسمت نام متغیر بنویسید order_number، نه %order_number% و نه {order_number}.
روش ارسال و پیام‌های مدیر و مشتری جدا هستند. شناسه و نگاشت همه رویدادهای فعال هر گروه را کامل کنید.
مثال نگاشت نام‌دار
فرض کنید متن پنل چنین باشد:
%customer% عزیز، سفارش %order% شما در وضعیت %status% قرار گرفت.
نگاشت:
| نام در متن پنل | نامی که در نگاشت می‌نویسید | داده انتخابی جم پک |
|---|---|---|
%customer% | customer | نام مشتری — customer_name |
%order% | order | شماره سفارش — order_number |
%status% | status | وضعیت سفارش — order_status |
نام متغیر پنل لازم نیست با نام داده جم پک یکی باشد؛ نگاشت همین ارتباط را مشخص می‌کند.
برای داده‌های فرضی «سارا احمدی»، «1250» و «در حال انجام»، پیام موردانتظار چنین است:
سارا احمدی عزیز، سفارش 1250 شما در وضعیت در حال انجام قرار گرفت.
این مثال گزارش ارسال واقعی نیست.
نام درست مهم‌تر از ترتیب ردیف‌هاست
برخلاف رایگان اس‌ام‌اس، در این اتصال صرف قرارگرفتن در ردیف اول یا دوم تعیین‌کننده نیست؛ داده با نام مشخص فرستاده می‌شود.
- نام‌ها را دقیقاً مطابق الگوی پنل وارد کنید.
- علامت درصد را در نام نگاشت ننویسید.
- نام تکراری نسازید؛ مقدار بعدی می‌تواند جای مقدار قبلی همان نام را بگیرد.
- ردیف بدون نام یا داده معتبر را باقی نگذارید.
- برای الگوی دارای متغیر، نگاشت را خالی نگذارید و به متن قدیمی پیام تکیه نکنید.
اگر نگاشت خالی باشد، مسیر عمومی سفارش می‌تواند از متن ذخیره‌شده مقدارهای ترتیبی استخراج کند؛ این جای نگاشت صحیح نام‌دار را نمی‌گیرد.
آزمون اعلان الگویی با سفارش
تست مستقیم به‌تنهایی کافی نیست. در محیط آزمایشی:
- کد الگو، خط و کلید اتصال را بازبینی کنید.
- فقط اعلان موردنظر را فعال کنید.
- نام تمام متغیرهای نگاشت را با پنل مقایسه کنید.
- در صورت نیاز به تاریخچه، ثبت گزارش پیامک را فعال کنید.
- شماره آزمایشی را در محل دریافت‌کننده قرار دهید: صورتحساب مشتری یا شماره مدیر.
- برای اعلان ثبت سفارش، خرید آزمایشی تازه‌ای انجام دهید.
- برای اعلان تغییر وضعیت، سفارش آزمایشی را به وضعیت دارای اعلان ببرید.
- متن گوشی، گزارش پنل و تاریخچه جم پک را بررسی کنید.
- نام مشتری، شماره سفارش و وضعیت را با همان سفارش تطبیق دهید.
در تاریخچه الگویی، ممکن است کد الگو و مقدارهای ارسالی ثبت شوند، نه متن کامل نهایی پیام. برای بررسی متن نهایی، گوشی و گزارش سرویس را هم ببینید.
اگر پاسخ نامشخص بود، پیش از تکرار رویداد، گزارش پنل را کنترل کنید. پایان زمان انتظار ثابت نمی‌کند که سرویس درخواست قبلی را نپذیرفته است.
هر الگوی مهم و هر گروه دریافت‌کننده را جدا بیازمایید. موفقیت یک رویداد، بقیه را تأیید نمی‌کند.
موفقیت درخواست چه چیزی را تأیید می‌کند؟
جم پک وضعیت اعلام‌شده در پاسخ سرویس را بررسی می‌کند. نتیجه موفق یعنی سرویس درخواست را موفق اعلام کرده است؛ تحویل پیام به گوشی را باید جدا بررسی کنید.
این اتصال وضعیت تحویل پیام را خودکار استعلام نمی‌کند. دریافت واقعی و گزارش سرویس را جدا کنترل کنید و برای ارسال چندگیرنده‌ای، موفقیت کلی را تأیید تک‌تک گیرندگان فرض نکنید.
زمان تحویل پیام به شرایط سرویس، خط فرستنده و شبکه بستگی دارد و ممکن است فوری نباشد.
خطاهای رایج و روش بررسی
کلید پذیرفته نمی‌شود
اگر خطای احراز هویت می‌بینید:
- کلید صحیح همان حساب را وارد کرده باشید.
- عبارت
Bearerیا نام سرآیند را به مقدار اضافه نکرده باشید. - آدرس پایه متعلق به سرویس سازگار با همان کلید باشد.
- از رمز پنل یا توکن موقتی به‌جای کلید استفاده نکرده باشید.
- فعال‌بودن و مجوز کلید را در حساب بررسی کنید.
کد 400-1 و پاسخ HTTP برابر ۴۰۱ در راهنمای خطای اتصال به مشکل پذیرش کلید یا توکن مربوط می‌شوند. این موارد را بدون بررسی به تمام‌شدن اعتبار پیامک نسبت ندهید.
آدرس API نامعتبر است
نشانی را با مقدار دقیق اعلام‌شده مقایسه کنید. اگر قرار است از پیش‌فرض استفاده کنید، فیلد را خالی کنید.
آدرس ورود پنل، مسیر کامل ارسال یا نشانی دارای خطای تایپی را جای پایه قرار ندهید. کلید را برای آزمایش به مقصدهای حدسی نفرستید.
ارتباط با میزبان برقرار نشد
پیام خطای شبکه این اتصال نام میزبان مقصد را نشان می‌دهد. ابتدا بررسی کنید واقعاً همان سروری است که باید به آن متصل شوید.
از هاست بخواهید دسترسی خروجی HTTPS، نام دامنه و پاسخ‌گویی مقصد را بررسی کند. فقط اگر ارائه‌دهنده نشانی دیگری را تأیید کرد، آدرس پایه را تغییر دهید.
الگو یافت نشد
کد 404-1 در راهنمای اتصال به پیدا نشدن الگو مربوط است. کد ذخیره‌شده را با کد الگوی پنل تطبیق دهید.
تعلق الگو به حساب و مقصد درست، آماده‌بودن آن و انتخاب رویداد صحیح را هم کنترل کنید. نام دلخواه پیام یا شماره ردیف فهرست جای کد الگو نیست.
درخواست یا متغیرها نامعتبرند
کد 400-2 به پارامتر ناقص یا نامعتبر مربوط است. متن جزئیات خطا را بخوانید؛ فقط عنوان کلی خطا کافی نیست.
نام متغیرهای الگو، خط فرستنده، شماره گیرنده و کد الگو را بررسی کنید. برای نگاشت:
- درصدها حذف شده باشند.
- نام دقیق پنل نوشته شده باشد.
- نام تکراری یا خالی وجود نداشته باشد.
- داده معتبر همان نوع اعلان انتخاب شده باشد.
اتصال پیام‌های اعتبارسنجی برگشتی را، در صورت وجود در ساختارهای شناخته‌شده، کنار متن خطا نمایش می‌دهد. قالب دقیق آن‌ها به پاسخ سرویس بستگی دارد.
مستقیم موفق است ولی الگو شکست می‌خورد
موفقیت مستقیم، کد الگو و نگاشت را تأیید نکرده است. شناسه، نام متغیرها و مجوز خط برای الگو را جدا بررسی کنید.
ارسال الگویی ایران‌پیامک هم به خط فرستنده نیاز دارد؛ این فیلد را خالی نگذارید.
حالت الگویی انتخاب شده اما مستقیم ارسال می‌شود
شناسه الگوی همان رویداد را بررسی کنید. در مسیر اعلان سفارش، حالت الگویی با شناسه خالی می‌تواند به مستقیم برگردد.
انتخاب یک روش برای گروه مدیر یا مشتری، همه شناسه‌های رویدادهای آن را خودکار تکمیل نمی‌کند.
پاسخ خالی یا نامشخص دریافت می‌کنم
زمان، متن پاسخ، کد HTTP و کد سرویس را، در صورت وجود، نگه دارید. پنل را بررسی کنید و قبل از ارسال دوباره از وضعیت درخواست قبلی مطمئن شوید.
پاسخ نامشخص به معنی تشخیص‌ندادن موفقیت از پاسخ دریافتی است، نه اثبات قطعی ارسال‌نشدن. برای پشتیبانی، گزارش پاک‌سازی‌شده بفرستید؛ کلید و داده مشتری را حذف کنید.
امنیت اتصال
- آدرس پایه را فقط از ارائه‌دهنده معتبر بگیرید.
- کلید در سرآیند درخواست به همان مقصد می‌رود؛ مقصد نادرست می‌تواند کلید را افشا کند.
- از HTTPS استفاده کنید و برای رفع خطا بررسی گواهی را خاموش نکنید.
- کلید، شماره مشتری و متن سفارش را از تصویر و گزارش عمومی حذف کنید.
- اگر کلید به مقصد اشتباه یا شخص غیرمجاز رسیده، آن را در حساب ابطال یا تعویض کنید.
- بعد از تغییر کلید، خط یا آدرس، همان مسیر ارسال را دوباره آزمایش کنید.
- پس از تست، شماره‌های موقت و رویدادهای غیرضروری را بازبینی کنید.
چک‌لیست پایان راه‌اندازی
- ایران‌پیامک به‌عنوان درگاه ذخیره شده است.
- کلید بدون پیشوند اضافی وارد شده است.
- خط فرستنده مجاز ثبت شده است.
- آدرس پایه خالی یا دقیقاً تأییدشده ارائه‌دهنده است.
- کد الگوی هر رویداد فعال تکمیل شده است.
- نام‌های نگاشت دقیق، بدون درصد و غیرتکراری هستند.
- مستقیم و الگویی جدا آزموده شده‌اند.
- متن پیام آزمایشی با سفارش تطبیق داده شده است.
- موفقیت درخواست با تحویل قطعی یکسان فرض نشده است.
جمع‌بندی
برای ایران‌پیامک، کلید و خط صحیح را ثبت کنید و آدرس پایه را فقط در صورت نیاز تغییر دهید. در ارسال الگویی، کد الگو و نام دقیق متغیرها تعیین‌کننده‌اند؛ نگاشت باید بدون درصد، کامل و غیرتکراری باشد.
پس از تنظیم، یک سفارش آزمایشی اجرا کنید و متن واقعی پیام را با اطلاعات سفارش و گزارش سرویس مقایسه کنید.