برای ارسال پیامک با PHP، باید اطلاعات گیرنده و پیام را مطابق قرارداد API به سرویس پیامکی بفرستید و پاسخ را بررسی کنید.
اتصال قابل اتکا به وب سرویس پیامکی، علاوه بر ساخت درخواست، به نگهداری امن کلید، تشخیص خطا و پیگیری وضعیت تحویل نیاز دارد.
در این راهنما، یک درخواست الگویی را پیاده سازی می کنیم و سپس مسیر آماده سازی آن برای محیط عملیاتی را توضیح می دهیم.
| مرحله | ورودی موردنیاز | معیار بررسی |
| آماده سازی | کلید دسترسی و الگوی فعال | مجاز بودن حساب برای ارسال |
| ساخت درخواست | گیرنده و متغیرهای الگو | انطباق با قرارداد متد |
| فراخوانی API | بدنه JSON و اتصال HTTPS | دریافت پاسخ قابل بررسی |
| ارزیابی پاسخ | وضعیت HTTP و نتیجه سرویس | تشخیص پذیرش یا رد درخواست |
| پیگیری | شناسه پیام | مشاهده وضعیت تحویل |
انتخاب روش ارسال متناسب با نیاز پروژه
پیش از کدنویسی مشخص کنید چه رویدادی باید پیامک ایجاد کند. تأیید پرداخت، تغییر وضعیت سفارش و درخواست ورود، رویدادهای متفاوتی هستند و نباید همگی از یک مسیر بدون کنترل عبور کنند. برای مثال، اعلان پرداخت باید پس از تأیید سمت سرور فعال شود؛ باز شدن صفحه تشکر، به تنهایی مرجع معتبری برای اثبات پرداخت نیست.
برای متن های ثابت با متغیرهایی مثل کد تأیید یا شماره سفارش، ارسال الگویی انتخاب قابل بررسی است. ارسال متن آزاد نیز قرارداد جداگانه ای دارد و ممکن است به شماره فرستنده نیاز داشته باشد. پارامترهای این دو روش را با یکدیگر ترکیب نکنید و مجاز بودن محتوای پیام برای مسیر خدماتی را بررسی کنید.
اگر در حال ارزیابی سرویس هستید، در صفحه api ارسال پیامک پیام رسان، نمونه درخواست PHP و راهنمای شروع اتصال ارائه شده است. نمونه این مقاله بر متد الگویی معرفی شده در همان صفحه تکیه دارد؛ پیش از استقرار، قرارداد نسخه مورد استفاده را دوباره بررسی کنید.
پیش نیازهای اجرای درخواست در PHP
برای این نمونه، محیط PHP نسخه ۸ یا بالاتر با پردازش اعداد صحیح ۶۴ بیتی در نظر گرفته شده است. افزونه cURL باید در محیط اجرای واقعی برنامه فعال باشد. اگر کد در خط فرمان اجرا می شود اما در وب سرور خطا می دهد، تنظیمات PHP همان محیط را بررسی کنید؛ فایل تنظیمات و افزونه های فعال آن ها می تواند متفاوت باشد.
پیش از نخستین آزمایش، این موارد را آماده کنید:
- کلید دسترسی معتبر که از متغیر محیطی یا مخزن اسرار خوانده شود.
- شناسه الگوی تأییدشده و ترتیب متغیرهای مورد انتظار آن.
- شماره ای تحت کنترل خودتان برای دریافت پیام آزمایشی.
- دسترسی خروجی سرور به مقصد HTTPS و تنظیم صحیح گواهی های معتبر.
کلید را در مخزن Git، کد جاوااسکریپت مرورگر یا آدرس درخواست قرار ندهید. در این نمونه، احراز دسترسی داخل بدنه درخواست انجام می شود؛ سرویس دیگری ممکن است هدر اختصاصی بخواهد. نام فیلدها و روش احراز دسترسی را از مستندات همان API بگیرید.
شماره موبایل را در پایگاه داده به صورت رشته نگه دارید تا صفر ابتدایی یا پیش شماره از بین نرود. تبدیل آن به قالب عددی موردنیاز این متد باید پس از اعتبارسنجی، در مرز اتصال انجام شود. عدد مقصد در نمونه صرفاً نمایشی است و برای آزمایش باید جایگزین شود.
نمونه درخواست ارسال پیامک با PHP
کد زیر ارسال الگویی را با JSON انجام می دهد و پاسخ را در سه سطح ارتباط، HTTP و نتیجه سرویس بررسی می کند. مقدار verifycode نمونه نام الگو است؛ باید آن را با شناسه واقعی الگوی حساب خود جایگزین کنید. مقدار p1 نیز ورودی تابع است و باید با کاربرد الگو تطبیق داشته باشد.
<?php
function sendPattern(
string $apiKey,
string $templateKey,
int $destination,
string $value
): array {
if ($apiKey === '' || $templateKey === '') {
throw new InvalidArgumentException('Missing configuration');
}
$body = json_encode([
'ApiKey' => $apiKey,
'TemplateKey' => $templateKey,
'Destination' => $destination,
'p1' => $value,
], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
ch=curlinit('https://api.sms-webservice.com/api/V3/SendTokenSingle');if(ch === false) {
throw new RuntimeException('Cannot initialize cURL');
}
try {
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json; charset=utf-8'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
]);
raw=curlexec(ch);
if ($raw === false) {
throw new RuntimeException(
'Transport error: ' . curl_errno($ch)
);
}
http=(int)curlgetinfo(ch, CURLINFO_HTTP_CODE);
if ($http < 200 || $http >= 300) {
throw new RuntimeException('HTTP error: ' . $http);
}
$data = json_decode(
raw,true,512,JSONTHROWONERROR|JSONBIGINTASSTRING);if(!isarray(data) || !array_key_exists('Success', data))thrownewUnexpectedValueException('Unexpectedresponse');if(data['Success'] !== true) {
throw new RuntimeException(
'Provider error: ' . ($data['ErrorCode'] ?? 'unknown')
);
}
if (!is_array($data['Result'] ?? null) || $data['Result'] === []) {
throw new UnexpectedValueException('Missing message results');
}
return $data['Result'];
} finally {
unset($ch);
}
}
// Example only: replace the template and destination before running.
$messages = sendPattern(
(string) getenv('PAYAM_RESAN_API_KEY'),
'verifycode',
9121112222,
'123456'
);
این تابع باید در لایه سرویس برنامه فراخوانی شود. استثناهای آن را در فراخواننده بگیرید، نتیجه را برای پیگیری ثبت کنید و پاسخ کنترل شده ای به کاربر بدهید. در پروژه عملیاتی، نوع خطا و اطلاعات تشخیصی را در استثناهای اختصاصی نگه دارید تا منطق برنامه به جست وجوی متن خطا وابسته نشود.
در PHP، موفق بودن curl_exec به معنی موفق بودن وضعیت HTTP نیست. همانطور که در php.net گفته شده: «Use the === operator for testing the return value of this function.»
ترجمه: برای بررسی مقدار بازگشتی این تابع از عملگر === استفاده کنید. بنابراین شرط $raw === false خطای انتقال را مشخص می کند و بررسی HTTP جداگانه انجام می شود.
تفکیک خطاها پیش از تصمیم برای تلاش مجدد

هر خطا به معنی نیاز به ارسال دوباره نیست. ابتدا مشخص کنید درخواست اصلاً به سرویس رسیده، رد شده یا نتیجه آن نامعلوم مانده است. جدول زیر الگوی تصمیم گیری عمومی است؛ کدهای اختصاصی ارائه دهنده باید از مستندات خودش خوانده شوند.
| نشانه | تفسیر اولیه | اقدام پیشنهادی |
| خطای DNS یا TLS | اشکال در برقراری ارتباط | بررسی شبکه و زنجیره گواهی |
| پایان مهلت انتظار | احتمال نامعلوم بودن نتیجه | بررسی وضعیت پیش از تکرار |
| HTTP 401 یا 403 | مشکل دسترسی یا مجوز | اصلاح کلید و تنظیمات دسترسی |
| HTTP 429 | محدودیت نرخ درخواست | زمان بندی مجدد با کنترل تکرار |
| پاسخ نامعتبر JSON | ناسازگاری پاسخ با قرارداد | ثبت مشخصات پاسخ و بررسی مقصد |
| نتیجه ناموفق سرویس | رد درخواست در منطق API | تحلیل کد خطای اختصاصی |
بر اساس RFC 6585 منتشرشده در آوریل ۲۰۱۲، پاسخ ۴۲۹ بیانگر درخواست های بیش ازحد در یک بازه زمانی است و ممکن است هدر Retry-After داشته باشد. وجود این هدر را بررسی کنید، اما پشتیبانی همه سرویس ها از آن را فرض نگیرید.
برای خطای کلید یا الگوی نامعتبر، تکرار همان ورودی مشکل را برطرف نمی کند. در مقابل، بعضی خطاهای موقت را می توان با فاصله افزایشی، کمی تصادفی سازی زمان و سقف تلاش مدیریت کرد. حتی در این حالت، تضمین جلوگیری از ارسال تکراری باید پیش از فعال کردن تلاش خودکار بررسی شود.
تعیین مهلت انتظار و اعتبارسنجی پاسخ
مهلت اتصال و مهلت کل درخواست دو مفهوم متفاوت اند. طبق مستندات رسمی libcurl، مقدار پیش فرض مهلت اتصال ۳۰۰ ثانیه است؛ این بازه مرحله برقراری اتصال، شامل DNS و مذاکره پروتکل را پوشش می دهد. چنین پیش فرضی را بدون ارزیابی وارد مسیر پاسخ گویی سایت نکنید.
در همان کتابخانه، مقدار پیش فرض CURLOPT_TIMEOUT برابر صفر است و محدودیت زمانی کلی برای انتقال اعمال نمی کند. این اعداد رفتار کتابخانه اند، نه زمان تضمین شده ارسال پیامک. مقادیر نمونه کد نیز انتخاب آموزشی هستند و باید با زمان پاسخ سرویس، تنظیمات صف و نیاز محصول تنظیم شوند.

پاسخ دریافتی همیشه JSON معتبر نیست؛ پراکسی یا درگاه واسط ممکن است صفحه HTML برگرداند. استفاده از JSON_THROW_ON_ERROR اجازه می دهد خطای رمزگشایی را صریح مدیریت کنید. پس از رمزگشایی نیز نوع داده و ساختار فیلدها را بسنجید؛ JSON معتبر لزوماً پاسخ معتبر سرویس نیست.
جلوگیری از ارسال تکراری و پیگیری تحویل
فرض کنید سفارش ثبت شده، API درخواست را پذیرفته و ارتباط پیش از دریافت پاسخ قطع شده است. ارسال فوری مجدد می تواند پیام مشابه دیگری تولید کند. برای هر اعلان، شناسه داخلی و وضعیت پردازش داشته باشید؛ پایان مهلت انتظار پس از ارسال را بی درنگ به وضعیت «قطعاً ارسال نشده» تبدیل نکنید.
در پایگاه داده، روی ترکیب شناسه رویداد و نوع اعلان محدودیت یکتا بگذارید تا اجرای دوباره رویداد، کار تکراری نسازد. این کنترل محلی، به تنهایی تکرار در سرویس بیرونی را حل نمی کند. اگر API سازوکار مستند idempotency دارد از آن استفاده کنید؛ در غیر این صورت، نتیجه نامعلوم را با استعلام یا سیاست مشخص بازبینی کنید.
شناسه پیام را از پاسخ معتبر استخراج و کنار اعلان ذخیره کنید. برای اطلاع از نتیجه نهایی، از متد گزارش تحویل استفاده کنید و وضعیت های میانی را با وضعیت نهایی یکی نگیرید. طبق RFC 9110، پاسخ HTTP ۲۰۲ نیز صرفاً پذیرش برای پردازش را نشان می دهد؛ پردازش هنوز تکمیل نشده است. این تعریف عمومی را با قرارداد وب سرویس پیامک مورد استفاده تطبیق دهید.
در ساختار پاسخ این مثال، شناسه هر پیام در فیلد Id اعضای خروجی قرار دارد. پیش از ذخیره، وجود و قالب آن را بررسی کنید. شناسه داخلی اعلان را هم حفظ کنید تا در صورت نیاز، ارتباط رویداد سفارش با نتیجه ارسال قابل بازیابی باشد.
اتصال به رویدادهای واقعی و آزمایش پیش از انتشار
برای اعلان سفارش، کار ارسال را پس از ثبت موفق تغییرات پایگاه داده وارد صف کنید. اگر از الگوی outbox استفاده می کنید، رویداد اعلان همراه تغییر سفارش ثبت می شود و پردازشگر جداگانه آن را ارسال می کند. به این ترتیب، شکست ارسال پیامک نباید وضعیت پرداخت موفق را به شکست پرداخت تبدیل کند.
در ارسال کد ورود، مقدار ثابت نمونه را با تولید تصادفی امن، انقضا و محدودیت تلاش جایگزین کنید. کد و کلید دسترسی را لاگ نکنید و نتیجه فراخوانی را معادل اعتبارسنجی کاربر ندانید. برای بررسی کد، شماره، هدف درخواست و نشست مرتبط نیز باید کنترل شوند.
پیش از انتشار، این سناریوها را بررسی کنید:
- ارسال واقعی به شماره آزمایشی و پیگیری شناسه پیام تا وضعیت قابل تفسیر.
- شبیه سازی کلید نامعتبر، پاسخ خراب و پایان مهلت انتظار با پاسخ های ساختگی.
- اجرای دوباره یک رویداد و بررسی کنترل اعلان های تکراری.
- بررسی لاگ ها برای نبود کلید، کد ورود و شماره کامل گیرنده.
در ارسال پیامک با api، برای پایش، شناسه داخلی اعلان، زمان پاسخ، کد HTTP و دسته خطا را ثبت کنید. با این اطلاعات می توانید ایراد اتصال را از رد درخواست جدا کنید و برای هرکدام اقدام مشخصی داشته باشید. معیار آماده بودن اتصال، فقط دریافت نخستین پیامک نیست؛ مسیر خطا و پیگیری نیز باید قابل بررسی باشد.
پرسش های متداول
خیر. اگر API درخواست HTTP می پذیرد، cURL برای ساخت درخواست کافی است. SDK می تواند کدنویسی را ساده تر کند، اما باید سازگاری و نحوه مدیریت خطای آن بررسی شود.
پذیرش درخواست با تحویل به گوشی متفاوت است. شناسه پیام را نگه دارید و گزارش تحویل، وضعیت گیرنده و شرایط مسیر ارسال را بررسی کنید.
این نمونه برای متد الگویی است. برای متن آزاد، باید متد، فیلدهای بدنه و الزامات شماره فرستنده را مطابق مستندات تغییر دهید.
ابتدا نامعلوم بودن نتیجه را در نظر بگیرید. پیش از تکرار، از استعلام یا سازوکار مستند جلوگیری از تکرار استفاده کنید؛ قطع ارتباط اثبات نمی کند پیام ارسال نشده است.
کلید را در تنظیمات امن سمت سرور یا مخزن اسرار نگه دارید و به فرایند PHP برسانید. آن را در مرورگر، مخزن کد و لاگ عمومی قرار ندهید. آیا برای ارسال پیامک با PHP نصب SDK ضروری است؟
چرا پاسخ موفق دریافت می کنم اما پیامک نمی رسد؟
آیا کد نمونه برای ارسال متن آزاد کاربرد دارد؟
پس از پایان مهلت انتظار درخواست را تکرار کنم؟
کلید api پیامک را کجا نگهداری کنم؟















ارسال پاسخ