در این راهنما، اطلاعات اتصال، شناسه الگو، متغیرها و خطاهای اختصاصی فراپیامک را بررسی می‌کنید. برای انتخاب روش و اتصال مشترک، انتخاب پنل، برای تنظیم اعلان سفارش، مدیریت رویدادها و برای تشخیص خطاهای عمومی، عیب‌یابی پیامک را ببینید.
برای ارسال پیامک‌های فروشگاه از فراپیامک، باید نام کاربری و کلید وب‌سرویس حساب را در جم پک ثبت کنید. پس از اتصال می‌توانید متن مستقیم بفرستید یا اعلان‌های سفارش را با یک الگوی تأییدشده ارسال کنید.
مهم‌ترین نکته اتصال این است: کلید API با رمز ورود پنل متفاوت است. حتی اگر در نمونه‌های فنی نام پارامتر password را دیدید، مقدار موردنیاز این اتصال کلید API است، نه رمز حساب.
در ارسال الگویی نیز شناسه عددی الگو و ترتیب متغیرها اهمیت دارند. این روش را با الگوهای نام‌دار بعضی پنل‌های دیگر یا توکن کنسول ملی‌پیامک اشتباه نگیرید.
برای تنظیم عمومی اعلان‌های مدیر، مشتری و موجودی، راهنمای مرکز پیامک ووکامرس را در کنار این آموزش داشته باشید.
این راهنما چه مواردی را پوشش می‌دهد؟
- آماده‌کردن نام کاربری و کلید API؛
- بررسی دسترسی وب‌سرویس و آی‌پی مجاز؛
- انتخاب فراپیامک و ثبت اطلاعات اتصال؛
- تنظیم خط فرستنده و آزمون ارسال مستقیم؛
- ثبت شناسه عددی الگو و نگاشت متغیرها؛
- بررسی پیام الگویی با سفارش آزمایشی؛
- تشخیص تفاوت موفقیت درخواست و تحویل پیام؛
- رفع خطاهای اطلاعات حساب، خط ارسال و الگو؛
- نگهداری امن اطلاعات اتصال.
اطلاعات موردنیاز اتصال
| عنوان فیلد | چه مقداری وارد شود؟ | چه زمانی لازم است؟ |
|---|---|---|
| نام کاربری | نام کاربری حساب فراپیامک | مستقیم و الگویی |
| کلید API | کلید صادرشده در تنظیمات وب‌سرویس حساب | مستقیم و الگویی |
| شماره فرستنده | خط مجاز ارسال پیامک | ارسال مستقیم و تست عمومی |
| شناسه الگو | شناسه عددی متن تأییدشده، یعنی bodyId | برای هر اعلان الگویی |
سه فیلد نخست مربوط به اتصال پنل هستند. شناسه الگو در تنظیمات همان پیام و رویداد ثبت می‌شود؛ یک فیلد عمومی برای همه پیام‌های فروشگاه نیست.
اختیاری‌بودن ظاهری «شماره فرستنده» در تنظیمات به این دلیل است که مسیر الگویی از آن استفاده نمی‌کند. ارسال مستقیم بدون این مقدار متوقف می‌شود.
دریافت کلید API و بررسی آی‌پی
- وارد حساب فراپیامک شوید.
- تنظیمات وب‌سرویس حساب را پیدا کنید و کلید API را دریافت کنید. نام و جای دقیق منوهای پنل ممکن است تغییر کند؛ از راهنمای داخل حساب استفاده کنید.
- مطمئن شوید کلید متعلق به همان نام کاربری است که در جم پک وارد خواهید کرد.
- بخش محدودیت آی‌پی حساب را بررسی کنید.
- در صورت نیاز، از هاست آی‌پی عمومی خروجی درخواست‌های سایت را بگیرید و همان مقدار را در فهرست مجاز حساب ثبت کنید.
آی‌پی خروجی سرور لزوماً همان آی‌پی دامنه، CDN یا رایانه مدیر نیست. پس از تغییر هاست یا مسیر خروجی شبکه، این بخش را دوباره بررسی کنید.
در صورت مشاهده خطای -110، ابتدا مطمئن شوید رمز ورود را به‌جای کلید API وارد نکرده‌اید. خطاهای -109 و -111 نیز در این اتصال به تنظیم آی‌پی مجاز مربوط‌اند.
برای آشنایی با خدمات و مسیرهای راهنمای سرویس، صفحه وب‌سرویس فراپیامک نقطه شروع رسمی است. امکانات کلی سرویس را با امکاناتی که در اتصال جم پک استفاده می‌شوند یکسان فرض نکنید.
انتخاب فراپیامک در جم پک
- وارد پیشخوان وردپرس شوید.
- در جم پک، «اعلان‌های پیامکی» را باز کنید.
- به «تنظیمات اصلی» بروید.
- «فعال‌سازی پیامک» را روشن کنید.
- از «درگاه پیامک»، فراپیامک را انتخاب کنید؛ ممکن است نام آن در فهرست به صورت
FaraPayamakدیده شود. - تنظیمات را ذخیره کنید و صفحه را دوباره باز کنید.
- «نام کاربری» و «کلید API» را تکمیل کنید.
- برای استفاده از ارسال مستقیم، «شماره فرستنده» را هم وارد کنید.
- دوباره روی «ذخیره تنظیمات» بزنید.
پیش از تنظیم الگوها، انتخاب پنل را ذخیره کنید. راهنمای متغیرها و نگاشت بر اساس پنل ذخیره‌شده نمایش داده می‌شوند.
برای شروع، فقط یک اعلان ضروری را فعال کنید تا نتیجه و هزینه آزمون روشن باشد.
ارسال مستقیم چه تفاوتی با ارسال الگویی دارد؟
پیامک مستقیم
در این روش، متن نهایی پیام از فروشگاه به فراپیامک فرستاده می‌شود. خطی که در «شماره فرستنده» ثبت کرده‌اید، در درخواست استفاده می‌شود.
برای مثال، در متن اعلان سفارش می‌توانید بنویسید:
وضعیت سفارش {order_number} در {shop_name}: {order_status}جم پک متغیرهای سفارش را پیش از ارسال جایگزین می‌کند. متن نهایی باید با مجوز خط و قواعد محتوایی حساب سازگار باشد.
ارسال دستی و دکمه عمومی تست نیز از مسیر مستقیم استفاده می‌کنند؛ تنظیم الگو برای اعلان مشتری، این مسیرها را خودکار الگویی نمی‌کند.
الگو/قالب
متن اصلی در پنل فراپیامک تعریف و تأیید می‌شود. جم پک شناسه آن متن و مقدار متغیرها را می‌فرستد. خط ارسال از مسیر خدماتی مرتبط با الگو تعیین می‌شود و فیلد شماره فرستنده مستقیم در این درخواست کاربرد ندارد.
دریافت پیام را روی شماره آزمایشی بررسی کنید. وضعیت حساب، تأیید متن، قواعد سرویس و محدودیت شماره مقصد می‌توانند بر نتیجه ارسال الگویی اثر بگذارند.
آزمون اولیه ارسال مستقیم
اگر خط مستقیم دارید، پیش از فعال‌کردن اعلان‌های سفارش:
- نام کاربری، کلید و خط را ذخیره کنید.
- در بخش «تست پیامک»، شماره خود را در «شماره موبایل تست» وارد کنید.
- برای آزمون اولیه از ارقام انگلیسی و قالب
09xxxxxxxxxاستفاده کنید؛ به‌جایx، رقم‌های شماره خودتان را بنویسید. - روی «ارسال پیامک تست» بزنید.
- پاسخ کنار فرم را یادداشت کنید.
- گزارش همان ارسال را در پنل فراپیامک پیدا کنید.
- دریافت پیام در گوشی را بررسی کنید.
فرم تست از متن آزمایشی آماده استفاده می‌کند؛ برای این مرحله نیازی به ساخت متن سفارشی در فرم ندارید.
پیام این آزمون در تاریخچه مرکزی جم پک ثبت نمی‌شود. برای بررسی آن، پاسخ فرم و گزارش خود فراپیامک را ملاک قرار دهید. نبودن ردیف در تاریخچه جم پک در این مرحله لزوماً خطا نیست.
موفقیت تست مستقیم، فقط همان مسیر را بررسی می‌کند. شناسه الگو و نگاشت متغیرها باید با رویداد سفارش جدا آزمایش شوند.
آماده‌کردن الگوی سفارش در فراپیامک
برای شروع، یک متن ساده با یک متغیر انتخاب کنید:
سفارش {0} شما ثبت شد.این فقط نمونه آموزشی است؛ متن واقعی باید در پنل پذیرفته و تأیید شود. اگر از قالب آماده حساب استفاده می‌کنید، متن و جایگاه‌های همان قالب را مبنا بگیرید.
- متن موردنظر را در بخش مربوط به پیامک خدماتی یا الگوهای پنل ثبت یا انتخاب کنید.
- وضعیت تأیید و دسترسی استفاده از آن را بررسی کنید.
- شناسه عددی متن، یعنی
bodyId، را بردارید. - تعداد متغیرها و ترتیب آن‌ها را یادداشت کنید.
در «شناسه الگو» باید عدد واقعی همان متن را وارد کنید. نام الگو، متن کامل پیام یا کلید API جایگزین این شناسه نیستند.
در این اتصال، ارسال الگویی بدون هیچ مقدار متغیر انجام نمی‌شود. برای شروع از الگویی استفاده کنید که حداقل یک متغیر قابل تأمین از سفارش داشته باشد.
ثبت الگو و نگاشت متغیر در جم پک
مراحل مشترک انتخاب مخاطب، رویداد، روش ارسال و ذخیره در مدیریت رویدادها و الگوهای پیامکی آمده است. در اجرای این مراحل، نکته اختصاصی این پنل را رعایت کنید:
شناسه عددی فراپیامک را برای همان رویداد ثبت کنید؛ جایگاه نخست نگاشت، متغیر {0} الگو را پر می‌کند.
در متن نمونه «سفارش شما ثبت شد»، رویداد باید ثبت سفارش باشد، نه ادعای پرداخت موفق. برای اعلام دریافت وجه، رویداد و متن متناسب با فرایند واقعی پرداخت فروشگاه انتخاب کنید.
انتخاب روش ارسال برای یک مخاطب ممکن است بر چند وضعیت فعال آن مخاطب اثر داشته باشد. شناسه الگوی همه وضعیت‌های فعال را بررسی کنید؛ صرف تکمیل یک شناسه برای همه آن‌ها کافی نیست.
ترتیب متغیرهای فراپیامک
نگاشت یعنی مشخص کنید هر جایگاه الگو کدام مقدار سفارش را بگیرد. در فراپیامک این ارتباط ترتیبی است:
| ردیف در جم پک | جایگاه در الگوی فراپیامک | مقدار نمونه |
|---|---|---|
| اول | {0} | {order_number} |
| دوم | {1} | {customer_name} |
| سوم | {2} | {order_status} |
برای مثال، متن الگو:
سفارش {0} متعلق به {1} در وضعیت {2} قرار گرفت.با مقادیر ساختگی زیر:
- شماره سفارش: ۱۲۳۴
- نام مشتری: مریم رضایی
- وضعیت: در حال انجام
باید به پیامی با همان ترتیب تبدیل شود:
سفارش ۱۲۳۴ متعلق به مریم رضایی در وضعیت در حال انجام قرار گرفت.این متن، نمونه خروجی مورد انتظار است.
نوشتن نام دلخواه برای یک ردیف، جایگاه آن را عوض نمی‌کند. برای اصلاح ترتیب، ردیف‌ها را جابه‌جا کنید و پس از ذخیره، دوباره پیام را آزمایش کنید.
ردیف خالی یا متغیر نامرتبط ممکن است هنگام ارسال حذف شود و ترتیب مقادیر بعدی را تغییر دهد. همه ردیف‌ها را با داده معتبر همان رویداد کامل کنید.
تفاوت دو نوع متغیر
{0}و{1}: جایگاه‌های داخل متن تأییدشده فراپیامک.{order_number}و{customer_name}: داده‌هایی که جم پک از سفارش تهیه می‌کند.
در پنل فراپیامک، متغیرهای مخصوص جم پک را جای جایگاه‌های عددی ننویسید. در جم پک نیز مقدار هر ردیف را از فهرست داده‌های مربوط به همان رویداد انتخاب کنید.
نقطه‌ویرگول داخل مقدارها
فراپیامک مقدارهای الگو را به صورت رشته‌ای با جداکننده ; دریافت می‌کند. جم پک نقطه‌ویرگول انگلیسی داخل هر مقدار را به ویرگول فارسی تبدیل می‌کند تا ترتیب متغیرها به هم نخورد.
بنابراین اگر داده‌ای مانند نام یا توضیح شامل ; باشد، ممکن است همان علامت در پیام نهایی حفظ نشود. مقدارهای ساده و متناسب با متن الگو انتخاب کنید.
آزمون پیام الگویی با سفارش
- یک سفارش آزمایشی با شماره صورتحساب متعلق به خودتان آماده کنید.
- شماره سفارش و مقدارهای مورد انتظار پیام را یادداشت کنید.
- برای اعلان ثبت سفارش، یک سفارش تازه از مسیر خرید آزمایشی بسازید؛ تغییر وضعیت یک سفارش قدیمی، همان رویداد ثبت اولیه نیست.
- برای اعلان وضعیت، سفارش آزمایشی را به همان وضعیت تنظیم‌شده ببرید.
- شماره مقصد و متن دریافتی را بررسی کنید.
- اگر ثبت تاریخچه فعال است، ردیف ارسال و یادداشت سفارش را در جم پک ببینید.
- همان زمان و شماره را در گزارش فراپیامک پیدا کنید.
تاریخچه پیام الگویی می‌تواند شناسه الگو و مقدارهای ارسالی را نشان دهد، نه متن کامل تأییدشده‌ای که پنل ساخته است. متن نهایی را از پیام دریافتی و گزارش سرویس بررسی کنید.
اگر اعلان فوری ثبت سفارش شکست خورد، روی تکرار خودکار آن حساب نکنید. پس از رفع مشکل، آزمون را با سفارش تازه انجام دهید یا پیام لازم را با مسیر دستیِ بررسی‌شده بفرستید؛ ارسال دستی، مستقیم است.
موفقیت درخواست با تحویل پیام فرق دارد
پیام «ارسال موفق» یعنی اتصال، پاسخ سرویس را به‌عنوان پذیرش ارسال تشخیص داده است. این نتیجه به‌تنهایی ثابت نمی‌کند پیام به گوشی رسیده است.
برای بررسی کامل، این سه مورد را کنار هم بگذارید:
- نتیجه فرم یا تاریخچه جم پک؛
- گزارش ارسال و تحویل در فراپیامک؛
- دریافت واقعی در گوشی آزمایشی.
اگر درخواست پذیرفته شده ولی پیام نرسیده، فوراً کلید یا الگو را تغییر ندهید. ابتدا وضعیت خط، اعتبار حساب، شماره مقصد و گزارش تحویل را بررسی کنید.
خطاهای مهم و اقدام پیشنهادی
کدهای زیر در اتصال فراپیامک شناسایی و توضیح داده می‌شوند. برای پیگیری، متن کامل پاسخ پنل و اینکه ارسال مستقیم بوده یا الگویی را نیز ثبت کنید؛ کد خطا را همراه نام پنل و روش ارسال ثبت کنید.
اطلاعات حساب و دسترسی
| کد | موضوع | اقدام |
|---|---|---|
0 | نام کاربری یا کلید نادرست | اطلاعات همان حساب را دوباره کنترل کنید |
-110 | نیاز به کلید API به‌جای رمز حساب | مقدار «کلید API» را از تنظیمات وب‌سرویس بردارید |
-109 | لزوم تنظیم آی‌پی مجاز | آی‌پی خروجی سرور را در پنل ثبت کنید |
-111 | آی‌پی درخواست مجاز نیست | مقدار ثبت‌شده را با خروجی واقعی هاست تطبیق دهید |
-108 | مسدودشدن آی‌پی پس از تلاش‌های ناموفق | تکرار آزمون را متوقف و از پشتیبانی پنل پیگیری کنید |
-112 | دسترسی وب‌سرویس غیرفعال | وضعیت فعال‌سازی وب‌سرویس حساب را بررسی کنید |
ارسال مستقیم
| کد | موضوع | اقدام |
|---|---|---|
2 | اعتبار ناکافی | موجودی حساب را بررسی کنید |
5 | شماره فرستنده نامعتبر | خط ثبت‌شده و مالکیت یا مجوز آن را کنترل کنید |
6 | مجوز خط یا وضعیت موقت سرویس | متن کامل پاسخ و وضعیت خط را بررسی کنید |
9 | محدودیت استفاده از خط عمومی | خط مجاز وب‌سرویس را از پنل مشخص کنید |
11 | رد ارسال برای مقصد | گزارش پنل و محدودیت دریافت شماره را بررسی کنید؛ عبور قطعی با الگو را فرض نکنید |
14 یا 15 | محدودیت لینک یا متن لغو | متن را مطابق مقررات اعلام‌شده برای همان خط اصلاح کنید |
17 یا 18 | متن خالی یا شماره نامعتبر | متن نهایی و شماره مقصد را کنترل کنید |
3 یا 19 | محدودیت ارسال روزانه | محدودیت حساب و زمان مجاز تلاش بعدی را از پنل بررسی کنید |
ارسال الگویی
| کد | موضوع | اقدام |
|---|---|---|
-1 | وب‌سرویس خدماتی فعال نیست | دسترسی ارسال الگویی را پیگیری کنید |
-4 | شناسه نادرست یا الگوی تأییدنشده | bodyId و وضعیت متن را کنترل کنید |
-5 | ناهماهنگی مقدارهای الگو | تعداد و ترتیب ردیف‌ها را تطبیق دهید |
-2 | بیش از یک مقصد در درخواست | آزمون را با یک شماره انجام دهید |
-10 | لینک در متغیرها | مقدار بدون لینک و مطابق متن تأییدشده انتخاب کنید |
این جدول فهرست کامل مقررات سرویس نیست. اگر پاسخ تازه‌ای دریافت کردید، شماره خطا را حدس نزنید؛ متن آن را همراه اطلاعات غیرمحرمانه آزمون برای پشتیبانی ارسال کنید.
عیب‌یابی مرحله‌ای
فراپیامک انتخاب شده ولی ارسال انجام نمی‌شود
انتخاب پنل و اطلاعات اتصال را ذخیره و صفحه را تازه‌سازی کنید. صرف پرکردن فیلدها بدون ذخیره کافی نیست. برای اعلان خودکار، فعال‌بودن مرکز پیامک و رویداد مربوط را نیز بررسی کنید.
تست مستقیم موفق است اما الگو خطا دارد
نام کاربری و کلید احتمالاً در مسیر مستقیم پذیرفته شده‌اند، اما این نتیجه تأیید الگو نیست. bodyId، مجوز وب‌سرویس خدماتی، تعداد ردیف‌ها و مقدارهای واقعی را کنترل کنید.
روش الگویی انتخاب شده ولی پیام مستقیم می‌رود
برای تشخیص این وضعیت، مراحل رفع خطاهای اتصال و ارسال پیامک را دنبال کنید. برای اطلاعات اتصال و کدهای اختصاصی، به بخش مربوط در همین راهنما مراجعه کنید.
داده‌ها جابه‌جا هستند
ترتیب ردیف‌ها را با جایگاه‌های عددی مقایسه کنید. ردیف ناقص را کامل کنید و متغیر سفارش را برای هشدار محصول به کار نبرید؛ داده‌های هر رویداد یکسان نیستند.
خطای شبکه یا پاسخ خالی دیده می‌شود
برای تشخیص این وضعیت، مراحل رفع خطاهای اتصال و ارسال پیامک را دنبال کنید. برای اطلاعات اتصال و کدهای اختصاصی، به بخش مربوط در همین راهنما مراجعه کنید.
شماره پذیرفته نمی‌شود
شماره آزمایشی را با ارقام لاتین و قالب معمول موبایل ایران وارد کنید. ممکن است شماره پیش از رسیدن به اتصال پنل، در فرم یا رویداد بررسی شود؛ بنابراین روی اصلاح خودکار همه قالب‌ها حساب نکنید.
امنیت و حریم خصوصی
- کلید API را مانند رمز نگه دارید؛ مخفی‌بودن فیلد در صفحه، جایگزین کنترل دسترسی نیست.
- در تصویر تنظیمات، کلید و اطلاعات حساب را بپوشانید.
- شماره و محتوای واقعی مشتری را در ویدئوی عمومی نمایش ندهید.
- گزارش خام درخواست را بدون بررسی ارسال نکنید؛ اطلاعات احراز هویت داخل بدنه درخواست قرار دارند.
- اگر کلید افشا شد، آن را از پنل تعویض و مقدار تازه را در جم پک ثبت کنید.
- آزمون را فقط با شماره مجاز و اطلاع صاحب شماره انجام دهید.
- پیام‌های سفارش را به اطلاعات لازم محدود کنید و قواعد ارسال سرویس را رعایت کنید.
- دسترسی به تاریخچه و مدت نگهداری آن را متناسب با نیاز فروشگاه تنظیم کنید.
چک‌لیست نهایی
- [ ] فراپیامک به‌عنوان پنل انتخاب و ذخیره شده است.
- [ ] نام کاربری و کلید API متعلق به یک حساب‌اند.
- [ ] رمز ورود حساب به‌جای کلید وارد نشده است.
- [ ] دسترسی وب‌سرویس و آی‌پی مجاز بررسی شده‌اند.
- [ ] برای مستقیم، خط معتبر ثبت شده است.
- [ ] تست مستقیم با گزارش پنل و گوشی تطبیق داده شده، یا به دلیل استفاده صرفاً الگویی کنار گذاشته شده است.
- [ ] bodyId عددی و مربوط به متن تأییدشده است.
- [ ] همه رویدادهای الگویی فعال، شناسه و نگاشت کامل دارند.
- [ ] ترتیب ردیف‌ها با جایگاه‌های الگو یکسان است.
- [ ] پیام الگویی با سفارش آزمایشی بررسی شده است.
- [ ] شماره سفارش و سایر مقدارها در جای درست قرار گرفته‌اند.
- [ ] موفقیت درخواست با تحویل واقعی اشتباه گرفته نشده است.
- [ ] کلیدها و اطلاعات مشتری در رسانه و گزارش عمومی پوشیده‌اند.
جمع‌بندی
برای اتصال فراپیامک، ابتدا نام کاربری، کلید API و دسترسی وب‌سرویس را درست تنظیم کنید. اگر ارسال مستقیم دارید، خط مجاز را ثبت و مسیر را با دکمه تست بررسی کنید.
برای پیام الگویی، bodyId عددی و ترتیب ردیف‌ها را مطابق متن تأییدشده بچینید و آزمون را با رویداد واقعیِ یک سفارش آزمایشی انجام دهید. هر مسیر را مستقل بررسی کنید و پیش از فعال‌کردن اعلان‌های بیشتر، نتیجه را در پنل و گوشی تطبیق دهید.
پیوندهای داخلی پیشنهادی
منابع تکمیلی
- وب‌سرویس فراپیامک — معرفی رسمی خدمات و مسیرهای راهنما.
- کتابخانه رسمی PHP فراپیامک — شامل فهرست روش‌های SendSMS، BaseServiceNumber و GetCredit؛ نام password در مثال‌های کتابخانه، جایگزین قرارداد کلید API اتصال جم پک نیست.