اتصال وب سرویس پیامک به سایت؛ از گرفتن کلید تا اولین پیامک موفق

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

بروزرسانی: زمان مطالعه حدود ۱۱ دقیقه نوشته‌ی تیم فنی فینگت

اتصال وب سرویس پیامک یعنی چه؟

وب‌سرویس پیامک یک آدرس اینترنتی است که شرکت پیامکی در اختیار شما می‌گذارد. وقتی برنامه‌ی شما به آن درخواست می‌فرستد، پیامک ساخته می‌شود. بنابراین «اتصال» یعنی سایت شما بتواند به آن آدرس برسد، خودش را با کلید معرفی کند و درخواستی با قالب درست بفرستد. اگر مفهوم کلی برایتان تازه است، ابتدا وب سرویس پیامک چیست را بخوانید.

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

دو راه برای وصل کردن

راه اول افزونه یا ماژول آماده است، مثلاً برای وردپرس یا فروشگاه‌ساز. در آن، کلید و خط را در یک صفحه‌ی تنظیمات می‌گذارید و افزونه بقیه را انجام می‌دهد. افزونه‌ی پیامک وردپرس و افزونه‌ی پیامک ووکامرس این مسیر را بیشتر شرح داده‌اند. راه دوم نوشتن کد خودتان است که برای پروژه‌های سفارشی لازم می‌شود؛ نمونه‌های آن در ارسال پیامک با php و ارسال پیامک لاراول هست.

در هر دو راه، اتصال تازه وقتی تمام است که یک پیامک واقعی به شماره‌ی خودتان برسد. پیام «تنظیمات ذخیره شد» ثابت نمی‌کند وب‌سرویس کار می‌کند.

گام‌های اتصال وب سرویس پیامک به سایت

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

  1. مستندات را کنار بگذارید

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

  2. کلید را بگیرید و جدا نگه دارید

    کلید api پیامک را در پنل بسازید یا کپی کنید و در یک مدیر گذرواژه یا فایل خصوصی نگه دارید. تا جایی که امکان دارد برای آزمایش و تولید کلید جدا بخواهید.

  3. اعتبار و خط را بسنجید

    پنل باید اعتبار داشته باشد و خطی که قرار است از آن بفرستید برای ارسال از طریق API فعال شده باشد. بسیاری از خطاهای «اولین ارسال» از همین دو مورد می‌آیند. نکته‌های خط را در خط خدماتی ببینید.

  4. درخواست را بیرون از سایت بسنجید

    پیش از هر چیز با ابزاری مثل curl یا یک برنامه‌ی ابزار API یک پیامک به شماره‌ی خودتان بفرستید. اگر اینجا کار نکرد، مشکل از وب‌سرویس، کلید یا خط است و سایت ربطی ندارد.

  5. به سایت یا افزونه وصل کنید

    حالا همان آدرس، کلید و خط را در افزونه یا در کد خودتان بگذارید. کلید را در تنظیمات امن نگه دارید و نه درون کد.

  6. اولین ارسال واقعی

    از مسیر واقعی سایت، مثلاً ثبت سفارش آزمایشی، پیامک بفرستید و ببینید به گوشی می‌رسد. زمان رسیدن را هم یادداشت کنید.

  7. پایش و هشدار

    هر خطای ارسال را ثبت کنید و برای کم شدن اعتبار هشدار بگذارید تا مشتری اولین کسی نباشد که متوجه قطع شدن پیامک می‌شود.

تست اتصال پیامک با curl پیش از دست زدن به سایت

ساده‌ترین و مطمئن‌ترین آزمون، یک درخواست دستی از ترمینال است. اگر این درخواست جواب موفق داد، دلیل خوبی دارید که بقیه‌ی راه هم می‌رود. نمونه‌ی زیر نشانی و نام فیلدها را جانشین کرده است و باید با مستندات سرویس‌دهنده‌ی شما هماهنگ شود.

کلید را مستقیم داخل فرمان ننویسید؛ آن را در یک متغیر محیطی بگذارید تا در تاریخچه‌ی ترمینال نماند. در ویندوز می‌توانید فرمان مشابه را در PowerShell یا Git Bash بزنید.

آزمون با curl
export SMS_API_KEY='کلید-شما'

curl -sS -X POST 'https://sms.example.test/api/send' \
  -H "Authorization: Bearer $SMS_API_KEY" \
  -H 'Content-Type: application/json; charset=utf-8' \
  --max-time 10 \
  -d '{"to":"09120000000","from":"3000XXXX","message":"آزمایش اتصال"}' \
  -w '\nHTTP %{http_code}\n'
اگر curl در دسترس نیست؛ آزمون با PHP
<?php
// php test-sms.php — فقط برای یک آزمون سریع؛ برای سایت از کلاینت کامل استفاده کنید
$ch = curl_init('https://sms.example.test/api/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['to' => '09120000000', 'from' => '3000XXXX', 'message' => 'آزمایش اتصال'], JSON_UNESCAPED_UNICODE),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json; charset=utf-8', 'Authorization: Bearer ' . getenv('SMS_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
]);
$body = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $body === false ? curl_error($ch) : $body, PHP_EOL;

نتیجه‌ی هر آزمون را یادداشت کنید: کد HTTP، متن جواب و زمان رسیدن پیامک. همین سه چیز در گفتگو با پشتیبانی سرویس‌دهنده، اگر لازم شد، کار شما را خیلی سریع‌تر می‌کند.

آدرس وب سرویس و کلید؛ جای درست نگه‌داری

در اتصال وب سرویس پیامک، دو چیز را جدا از هم ببینید: آدرس، که عمومی است، و کلید، که خصوصی است.

آدرس وب سرویس معمولاً محرمانه نیست، ولی کلید حتماً است. هر کس کلید شما را داشته باشد، می‌تواند به اسم شما پیامک بفرستد و اعتبارتان را مصرف کند. پس کلید را مثل رمز عبور بانک نگه دارید: در متغیر محیطی، فایل تنظیمات خارج از ریشه‌ی وب یا بخش «رازها» در پنل میزبانی. هرگز آن را در فایل‌های عمومی، مخزن کد یا اسکریپت‌هایی که سمت مرورگر اجرا می‌شوند نگذارید.

یک اشتباه خیلی رایج این است که فرم سایت مستقیم از مرورگر به وب‌سرویس پیامک درخواست بفرستد تا «سرور را درگیر نکند». این کار کلید را در دسترس هر بازدیدکننده‌ای می‌گذارد. درخواست باید همیشه از سرور شما بیرون برود و مرورگر فقط به سرور خودتان صحبت کند.

کلید محدودشده در برابر کلید کامل

اگر سرویس‌دهنده‌ی شما اجازه می‌دهد کلید را به یک IP یا به یک عملکرد محدود کنید، حتماً این کار را بکنید. حتی اگر کلید لو برود، فقط از همان سرور قابل استفاده خواهد بود. و اگر چنین امکانی ندارد، دست‌کم قابلیت باطل کردن و ساختن کلید جدید را بسنجید؛ بعد از هر مشکوک شدن به نشت، همان روز کلید را عوض کنید.

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

عیب‌یابی ارسال پیامک بعد از اتصال

جدول زیر راهنمای عمومی است و کدهای دقیق هر سرویس‌دهنده را نشان نمی‌دهد. کدهای خطای خود را از مستندات همان شرکت بخوانید.

نشانهعلت محتملاولین کار
جواب 401 یا 403کلید اشتباه، منقضی یا بدون دسترسیکلید را دوباره از پنل کپی کنید و به فاصله‌ی اضافی یا کاراکتر نامرئی دقت کنید.
جواب 400قالب شماره، نام فیلد یا بدنه درست نیستقالب نمونه‌ی مستندات را با درخواست خودتان مقایسه کنید.
جواب «اعتبار ناکافی»شارژ پنل تمام شدهپنل را شارژ و هشدار اعتبار تنظیم کنید.
جواب موفق ولی پیامک نمی‌رسدمشکل خط، محتوا، فیلتر یا اپراتوروضعیت پیام را در پنل ببینید و پیامک تحویل داده نمی‌شود را مرور کنید.
timeout یا خطای اتصالDNS، فایروال سرور یا کندی سرویس‌دهندهاز خود سرور با curl آزمون کنید؛ اگر بیرون کار می‌کند ولی از سرور نه، فایروال را بررسی کنید.
فقط در سرور کار نمی‌کند، روی کامپیوتر خودتان کار می‌کندIP سرور مجاز نیست یا خروجی شبکه بسته استIP ثابت سرور را به فهرست مجاز سرویس‌دهنده اضافه کنید.
گاهی می‌رسد، گاهی نهمحدودیت نرخ، فیلتر محتوا یا مشکل اپراتورچند نمونه‌ی ناموفق را با شناسه‌ی پیام برای پشتیبانی بفرستید.

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

دو سناریوی نمونه‌ی اتصال

هر دو سناریو فرضی‌اند و فقط برای نشان دادن دو مسیر مختلف نوشته شده‌اند.

سناریوی نمونه

نمونه: فروشگاه وردپرسی با افزونه

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

سناریوی نمونه

نمونه: سامانه‌ی رزرو با کد سفارشی

تیم فرضی یک سامانه‌ی رزرو، کلاینت ارسال پیامک را خودش نوشته است. در آزمون اول همه چیز درست بود، ولی بعد از انتشار در سرور، هیچ پیامکی نمی‌رفت. علت این بود که IP سرور در فهرست مجاز پنل ثبت نشده بود. تیم با یک آزمون curl از خود سرور علت را در چند دقیقه پیدا کرد و بعد IP را اضافه کرد. از آن روز، در فهرست استقرار یک گام «آزمون ارسال از خود سرور» هم ثبت شد.

اشتباه‌های رایج هنگام اتصال

این‌ها همان چیزهایی‌اند که بعد از چند هفته به شکل «پیامک‌هایمان یک‌دفعه نرسید» برمی‌گردند. هر کدام را پیش از انتشار بررسی کنید.

نوشتن کلید در کد سمت مرورگر

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

نرمال نکردن شماره

کاربر با رقم فارسی، فاصله یا پیش‌شماره‌ی ۹۸ شماره می‌دهد؛ اگر یکدست نشود، بخشی از پیامک‌ها رد می‌شوند.

نداشتن timeout

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

رها کردن خطا

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

بدون سقف ارسال

فرم درخواست کد یا فرم تماس که پیامک می‌فرستد، باید سقف داشته باشد.

آزمایش با شماره‌ی مشتری

آزمون‌ها را با شماره‌ی خودتان انجام دهید، نه شماره‌ی مشتری واقعی.

اعتماد به متن «موفق»

موفق معمولاً یعنی پیام به شرکت پیامکی تحویل شده، نه این‌که به گوشی رسیده است.

اگر هدف فقط ورود کاربر است

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

وصل کردن وب‌سرویس پیامک لازم است وقتی

  • می‌خواهید هر کاربر، حتی بدون اپ، با کد پیامکی وارد شود.
  • پیام‌های دیگر، مانند سفارش و یادآوری، باید روی شماره‌ی مخاطب برسند.
  • تیم و بودجه‌ی نگهداری یک کانال پیامکی را دارید.

شاید راه سبک‌تری هم کافی باشد وقتی

  • فقط ورود کاربر مهم است و هزینه‌ی کد پیامکی را نمی‌خواهید.
  • کاربران شما می‌توانند ورود را روی گوشی خود تأیید کنند.
  • نگران هزینه، تأخیر و کدهای نرسیده‌اید.

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

فهرست بررسی نهایی پیش از انتشار

پیش از این‌که بگویید اتصال تمام شد، این موارد را ببینید. هر مورد چند دقیقه کار دارد و جلوی ماجراهای بدتر را می‌گیرد.

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

واژه‌های این صفحه

چند اصطلاح که در مستندات سرویس‌دهنده‌ها پیش می‌آید.

کلید API
رشته‌ای محرمانه که برنامه‌ی شما را به وب‌سرویس معرفی می‌کند.
endpoint
نشانی مشخصی از وب‌سرویس که برای یک کار، مثل ارسال پیامک، صدا زده می‌شود.
فهرست IP مجاز
فهرستی از نشانی‌های شبکه که فقط از آنها اجازه‌ی استفاده از کلید داده می‌شود.
کد وضعیت HTTP
عدد سه‌رقمی پاسخ که نشان می‌دهد درخواست موفق بوده یا چه نوع خطایی رخ داده است.
timeout
حداکثر زمانی که برنامه حاضر است منتظر پاسخ بماند.

پرسش‌های متداول درباره اتصال وب سرویس پیامک

اتصال وب سرویس پیامک به سایت چقدر طول می‌کشد؟

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

آیا حتماً برنامه‌نویس لازم است؟

برای سایت‌های وردپرسی یا ووکامرسی معمولاً نه، چون افزونه‌ها این کار را انجام می‌دهند. برای پروژه‌ی سفارشی کد لازم است و نمونه‌هایش در صفحه‌های PHP و لاراول آمده است.

کلید API پیامک را کجا نگه دارم؟

در متغیر محیطی یا فایل تنظیمات خصوصی روی سرور. هرگز آن را در جاوااسکریپت صفحه، مخزن کد یا پیام‌های گروهی نگذارید.

چرا از سرور کار نمی‌کند ولی از کامپیوتر خودم کار می‌کند؟

معمولاً IP سرور در فهرست مجاز سرویس‌دهنده نیست یا فایروال خروجی سرور بسته است. آزمون curl از خود سرور علت را سریع نشان می‌دهد.

موفق است ولی پیامک نمی‌رسد؛ چه کنم؟

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

آیا فینگت وب سرویس پیامک ارائه می‌دهد؟

نه. فینگت پنل یا خط پیامکی ندارد. برای سایت‌ها ورود بدون رمز با تأیید روی گوشی کاربر دارد و می‌تواند بخشی از پیامک‌های ورود را کم کند.