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

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

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

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

اتصال قاصدک در جم پک از API جدید روی دامنه gateway.ghasedak.me استفاده می‌کند. آموزش‌های قدیمی که به api.ghasedak.me/v2، بدنه Form یا ساختار پاسخ result.code اشاره می‌کنند با این اتصال یکسان نیستند.

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

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

• آماده‌سازی حساب قاصدک؛
• دریافت API Key؛
• ثبت IP عمومی خروجی سرور؛
• انتخاب قاصدک در مرکز پیامک؛
• تنظیم شماره خط یا روش انتخاب خط؛
• آزمون ارسال Direct؛
• ساخت و تأیید OTP Template؛
• ثبت نام Template؛
• نگاشت نام‌دار پارامترها؛
• آزمون Pattern با سفارش واقعی؛
• تفاوت پاسخ موفق API با تحویل نهایی؛
• خطاهای احراز هویت، IP، خط، اعتبار و Template؛
• نکات امنیت API Key و حریم خصوصی.

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

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

فیلد	اجباری	کاربرد
API Key	بله	احراز هویت درخواست‌ها در هدر ApiKey
شماره فرستنده	خیر	مقدار lineNumber در ارسال Direct

نام کاربری و رمز ورود پنل را در این فیلدها وارد نکنید. API Key مجوز مستقلی برای وب‌سرویس است.

دریافت API Key

پس از ورود به پنل قاصدک، از بخش توسعه‌دهندگان و مدیریت API Key یک کلید برای سایت بسازید یا کلید موجود را بردارید. عنوان منو ممکن است با بروزرسانی پنل تغییر کند؛ معیار، کلیدی است که برای API جدید و هدر ApiKey صادر شده باشد.

نکات پیشنهادی:

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

نسخه بررسی‌شده API Key را در هدر درخواست می‌فرستد و آن را داخل URL یا بدنه پیام قرار نمی‌دهد:

ApiKey: YOUR_API_KEY

ثبت IP عمومی سرور

قاصدک علاوه بر API Key، IP مبدأ درخواست را کنترل می‌کند. IP عمومی خروجی سرور باید برای همان کلید در پنل ثبت شود. اگر کلید صحیح باشد ولی IP ثبت نشده یا تغییر کرده باشد، درخواست می‌تواند با خطای 401 رد شود.

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

• IP کامپیوتر مدیر؛
• IP بازدیدکننده؛
• IP نمایش‌داده‌شده در DNS دامنه؛
• IP عمومی CDN یا Cloudflare.

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

در زیرساخت‌های دارای NAT، Proxy، سرور خروجی مشترک یا چند Node، ممکن است IP خروجی با IP میزبان سایت متفاوت باشد. پس از مهاجرت هاست یا تغییر شبکه نیز IP را دوباره بررسی کنید.

چک‌لیست IP

• [ ] IP از روی خود سرور یا پشتیبانی هاست دریافت شده است.
• [ ] IP در تنظیمات همان API Key ثبت شده است.
• [ ] تغییرات پنل ذخیره شده‌اند.
• [ ] در صورت وجود چند IP خروجی، همه مسیرهای مجاز بررسی شده‌اند.
• [ ] پس از تغییر هاست، IP جدید جایگزین شده است.

انتخاب قاصدک در مرکز پیامک

برای اتصال:

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

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

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

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

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

فیلد «شماره فرستنده» فقط در Direct استفاده می‌شود. مقدار آن بدون تغییر به‌عنوان lineNumber به قاصدک فرستاده می‌شود.

برای تعیین خط فرستنده، این گزینه‌ها را دارید:

مقدار	رفتار مورد انتظار
شماره خط حساب	ارسال با همان خط، در صورت مجازبودن
fastest	واگذاری انتخاب خط سریع‌تر به قاصدک
cheapest	واگذاری انتخاب خط اقتصادی‌تر به قاصدک
priority	استفاده از منطق اولویت خطوط حساب
خالی	ارسال بدون lineNumber و استفاده از تنظیم پیش‌فرض حساب

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

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

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

شماره فرستنده روی Pattern اثر ندارد. ارسال OTP از خط مرتبط با Template و تنظیمات خود قاصدک استفاده می‌کند.

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

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

https://gateway.ghasedak.me/rest/api/v1/webservice/sendsinglesms

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

پارامتر	کاربرد
message	متن نهایی پیام
receptor	شماره نرمال‌شده گیرنده
lineNumber	فقط در صورت خالی‌نبودن فیلد فرستنده

هدرهای اصلی:

ApiKey: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

افزونه حداکثر ۳۰ ثانیه منتظر پاسخ می‌ماند. در صورت خطای شبکه، پیام خطای وردپرس در مرکز پیامک نمایش داده می‌شود.

اتصال نتیجه را از مقدار isSuccess می‌خواند. چون نمونه‌های مختلف قاصدک گاهی نام را به‌شکل IsSuccess بازمی‌گردانند، نسخه بررسی‌شده هر دو حالت را می‌پذیرد. اتکا صرف به HTTP 200 برای موفقیت کافی نیست.

متدهای Bulk، Pair-to-Pair، زمان‌بندی، UDH و Client Reference در اتصال فعلی استفاده نمی‌شوند. ارسال گروهی مرکز پیامک، سفارش‌ها را در سطح افزونه پردازش می‌کند و هر ارسال از مسیر تکی عبور می‌کند.

آزمون اولیه Direct

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

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

نمونه متن:

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

پیام آزمایشی فقط Direct را بررسی می‌کند و در تاریخچه مرکزی جم پک ثبت نمی‌شود. موفقیت این تست به معنی صحت Template یا نگاشت Pattern نیست.

Pattern در قاصدک

در اتصال فعلی، Pattern با Endpoint جدید OTP ارسال می‌شود:

https://gateway.ghasedak.me/rest/api/v1/webservice/sendotpsms

ساختار اصلی درخواست:

{
  "receptors": [
    { "mobile": "09120000000" }
  ],
  "templateName": "orderStatus",
  "inputs": [
    { "param": "Order", "value": "1234" },
    { "param": "Status", "value": "در حال انجام" }
  ]
}

این نمونه فقط ساختار را نشان می‌دهد. اطلاعات واقعی مشتری یا API Key را در مستند عمومی قرار ندهید.

ساخت OTP Template

در پنل قاصدک یک Template برای پیام موردنظر ایجاد کنید. هر Template باید:

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

نمونه نام Template:

orderStatus

نمونه متن:

سفارش %Order% شما در %Shop% اکنون در وضعیت %Status% قرار دارد.

در فیلد «شناسه Pattern» جم پک، نام Template را وارد کنید:

orderStatus

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

نگاشت متغیرهای نام‌دار

قاصدک در نسخه بررسی‌شده از نگاشت نام‌دار استفاده می‌کند. برای هر ردیف باید دو مقدار مشخص شود:

• نام پارامتر تعریف‌شده در Template قاصدک؛
• متغیر متناظر جم پک.

اگر Template این پارامترها را دارد:

%Order%
%Shop%
%Status%

نگاشت صحیح:

کلید در نگاشت جم پک	متغیر انتخابی
Order	{order_number}
Shop	{shop_name}
Status	{order_status}

در کلید نگاشت، فقط نام متغیر را بدون علامت درصد وارد کنید:

Order

این حالت نادرست است:

%Order%

نام‌ها بدون تغییر به قاصدک ارسال می‌شوند و باید از نظر حروف، املا و بزرگی یا کوچکی حروف دقیقاً با Template تطابق داشته باشند.

آیا ترتیب ردیف‌ها مهم است؟

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

آیا تعریف نگاشت اختیاری است؟

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

برای هر Pattern:

• برای همه متغیرهای ضروری، ردیف نگاشت بسازید؛
• کلید هر ردیف را از پنل قاصدک کپی کنید؛
• ردیف ناقص یا بدون کلید نگذارید؛
• متغیر فروشگاه را فقط زمانی انتخاب کنید که در آن رویداد مقدار دارد؛
• پس از تغییر Template، نگاشت را نیز بروزرسانی کنید.

SDK رسمی قاصدک نیز ورودی‌های OTP جدید را به‌صورت جفت‌های param و value نشان می‌دهد: نمونه Send OTP در SDK رسمی.

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

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

Template:

سفارش %Order% به مبلغ %Total% در %Shop% ثبت شد.

نگاشت:

کلید	متغیر
Order	{order_number}
Total	{order_total}
Shop	{shop_name}

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

Template:

%Name% عزیز، وضعیت سفارش %Order% به %Status% تغییر کرد. %Shop%

نگاشت:

کلید	متغیر
Name	{customer_name}
Order	{order_number}
Status	{order_status}
Shop	{shop_name}

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

Template:

موجودی %Product% به %Stock% رسید. شناسه: %Sku%

نگاشت:

کلید	متغیر
Product	{product_title}
Stock	{stock}
Sku	{product_sku}

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

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

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

نام Template قاصدک را ثبت کنید و برای پارامترهای آن نگاشت نام‌دار بسازید.

تنظیمات Pattern قاصدک مستقل از پنل‌های دیگر ذخیره می‌شوند. تغییر پنل آن‌ها را حذف نمی‌کند، اما پس از بازگشت باید API Key، IP و وضعیت Template را دوباره آزمایش کنید.

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

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

فرم تست عمومی از Direct استفاده می‌کند. برای آزمون Pattern:

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

برای تشخیص خطای کلید، IP و Template بهتر است آزمون را مرحله‌ای انجام دهید:

1. ابتدا Direct؛
2. سپس Pattern تک‌متغیره؛
3. بعد Pattern کامل سفارش.

پاسخ API و ثبت نتیجه

پاسخ API جدید قاصدک شامل این داده‌هاست:

• isSuccess یا IsSuccess؛
• statusCode یا StatusCode؛
• message یا Message؛
• data یا Data.

اگر Success درست باشد، مرکز پیامک نتیجه را sent ثبت می‌کند. در خطا، پیام خوانای قاصدک همراه HTTP Code و Status Code در تاریخچه ذخیره می‌شود.

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

اتصال فعلی شناسه پیام را برای دریافت خودکار Delivery نگهداری و متد Check Status را اجرا نمی‌کند. در نتیجه sent یعنی API درخواست را پذیرفته است، نه اینکه پیام حتماً به گوشی رسیده باشد.

عیب‌یابی

خطای 401

در این اتصال، 401 معمولاً یکی از دو علت را دارد:

• API Key نامعتبر، غیرفعال یا اشتباه است؛
• IP عمومی این سرور برای همان کلید ثبت نشده است.

راه‌حل:

1. API Key را دوباره از پنل کپی کنید.
2. فاصله ابتدا و انتها را حذف کنید.
3. فعال‌بودن کلید و حساب را بررسی کنید.
4. IP خروجی را از خود سرور یا هاست بگیرید.
5. IP را برای همان کلید ثبت کنید.
6. پس از ذخیره، دوباره Direct را آزمایش کنید.

API Key درست است اما همه درخواست‌ها رد می‌شوند

• IP ثبت‌شده را با IP خروجی فعلی مقایسه کنید؛
• تغییر هاست، NAT، Proxy یا Node خروجی را بررسی کنید؛
• مطمئن شوید کلید به محیط و حساب درست تعلق دارد؛
• دسترسی وب‌سرویس و وضعیت حساب را از قاصدک پیگیری کنید.

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

• خط باید در همان حساب و برای API مجاز باشد؛
• شماره را بدون فاصله وارد کنید؛
• برای آزمون فیلد را خالی بگذارید؛
• یکی از گزینه‌های fastest، cheapest یا priority را فقط مطابق تنظیم حساب آزمایش کنید؛
• توجه کنید Pattern از خط Template استفاده می‌کند.

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

• نام Template را به‌جای شناسه عددی وارد کنید؛
• وضعیت تأیید Template را بررسی کنید؛
• کلیدهای نگاشت را بدون % وارد کنید؛
• حروف و املای کلیدها را دقیق تطبیق دهید؛
• نگاشت خالی یا ردیف بدون کلید را اصلاح کنید؛
• مطمئن شوید مقدار متغیر در رویداد خالی نیست؛
• Pattern را با سفارش واقعی و نه فرم تست Direct اجرا کنید.

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

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

Pattern انتخاب شده ولی پیام Direct ارسال شده است

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

خطای اعتبار حساب

• موجودی ریالی پنل را کنترل کنید؛
• تاریخ انقضا یا وضعیت پلن را بررسی کنید؛
• هزینه خط یا مسیر انتخاب‌شده را در نظر بگیرید؛
• پس از شارژ، ارسال کوتاه آزمایشی انجام دهید.

پیام sent است اما دریافت نشده

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

خطای شبکه یا پاسخ نامشخص

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

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

• API Key را مانند رمز عبور نگهداری کنید؛
• کلید را در Screenshot یا ویدئو نمایش ندهید؛
• برای سایت آزمایشی و اصلی کلید جداگانه داشته باشید؛
• IPهای مجاز قدیمی را پس از مهاجرت حذف کنید؛
• دسترسی کاربران مدیریت به تنظیمات را محدود کنید؛
• شماره و متن مشتری را فقط برای هدف مرتبط با سفارش بفرستید؛
• در سیاست حریم خصوصی، انتقال داده لازم به قاصدک را توضیح دهید؛
• دوره نگهداری تاریخچه را متناسب با نیاز پشتیبانی محدود کنید؛
• پاسخ خام API را پیش از ارسال برای پشتیبانی بازبینی کنید؛
• پس از افشای احتمالی، کلید را فوراً تعویض کنید.

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

چک‌لیست نهایی قاصدک

• [ ] حساب و وب‌سرویس قاصدک فعال‌اند.
• [ ] API Key معتبر ثبت شده است.
• [ ] IP خروجی واقعی سرور برای همان کلید ثبت شده است.
• [ ] قاصدک به‌عنوان پنل فعال ذخیره شده است.
• [ ] شماره خط، کلیدواژه انتخاب خط یا حالت خالی عمداً تعیین شده است.
• [ ] اعتبار کافی در حساب وجود دارد.
• [ ] تست Direct موفق است.
• [ ] نتیجه در پنل قاصدک مشاهده شده است.
• [ ] Template تأییدشده است.
• [ ] نام Template دقیقاً ثبت شده است.
• [ ] کلیدهای نگاشت بدون علامت % وارد شده‌اند.
• [ ] نام و حروف کلیدها با Template تطابق کامل دارند.
• [ ] هیچ ردیف ناقص یا بدون کلید وجود ندارد.
• [ ] Pattern با سفارش واقعی آزمایش شده است.
• [ ] نتیجه تاریخچه با گزارش قاصدک مقایسه شده است.
• [ ] تفاوت sent و Delivery برای تیم پشتیبانی روشن است.
• [ ] API Key و شماره‌ها در محتوای آموزشی محو شده‌اند.

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

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

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

منابع

• وب‌سرویس قاصدک
• SDK رسمی جدید PHP قاصدک
• نمونه Send OTP در SDK رسمی

جمع‌بندی

برای اتصال قاصدک، API Key به‌تنهایی کافی نیست؛ IP خروجی سرور نیز باید برای همان کلید ثبت شود. ابتدا Direct را با خط مشخص یا انتخاب خودکار آزمایش کنید و پس از تأیید اتصال، سراغ OTP Template بروید.

در Pattern قاصدک، نام هر پارامتر مهم است. کلید را بدون علامت % و دقیقاً مطابق Template وارد کنید. برخلاف کاوه‌نگار، ترتیب ردیف‌ها تعیین‌کننده نیست؛ تطبیق براساس نام انجام می‌شود. در پایان نتیجه را هم در تاریخچه مرکز پیامک و هم در پنل قاصدک کنترل کنید.