API پیامک و راهنمای اتصال سایت و نرم افزار

کاربر ثبت نام کرده اما کد تأیید به دستش نرسیده است. سفارش پرداخت شده اما مشتری هنوز نمی داند خریدش ثبت شده یا نه. با API پیامک می توانید این اعلان ها را به رویدادهای سایت یا نرم افزار متصل کنید؛ به شرطی که ارسال، خطا و وضعیت تحویل را درست مدیریت کنید.

برای اتصال سایت به سامانه پیامکی از کجا شروع کنیم

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

نیاز پروژه	قابلیت موردنیاز	نکته اجرایی
ورود با شماره موبایل	ارسال کد یک بارمصرف	محدودیت درخواست و انقضای کد
اطلاع رسانی سفارش	ارسال پیام تراکنشی	اجرا پس از تأیید پرداخت
یادآوری نوبت	ارسال زمان بندی شده یا زمان بند داخلی	بررسی لغو نوبت قبل از ارسال
اعلان در نرم افزار سازمانی	ارسال از بک اند	تعیین رویداد و گیرنده مجاز
دریافت پاسخ مشتری	دریافت پیامک ورودی	بررسی پشتیبانی سرویس و خط
پیگیری پیام ارسالی	گزارش تحویل	ذخیره شناسه پیام

پشتیبانی وب سرویس از دریافت پیام، زمان بندی و گزارش تحویل را جداگانه در مستندات بررسی کنید.

API پیامک چیست و چگونه کار می کند

API پیامک رابطی است که به برنامه شما اجازه می دهد با سامانه پیامکی ارتباط برقرار کند. برنامه، درخواست حاوی گیرنده و متن یا شناسه قالب را ارسال می کند. سرویس پس از بررسی دسترسی و داده ها، نتیجه درخواست را برمی گرداند.

برای مثال، در فروشگاه اینترنتی پس از تأیید پرداخت، بک اند شماره مشتری و شماره سفارش را آماده می کند. درخواست ارسال ثبت می شود و شناسه پیام در کنار سفارش قرار می گیرد. مشتری می تواند پیام «سفارش ۲۴۸۱ ثبت شد» را دریافت کند؛ بدون اینکه مدیر فروشگاه شماره را دستی وارد کند.

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

پیش از کدنویسی چه اطلاعاتی لازم داریم

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

• نشانی سرویس و نسخه API برای عملیات موردنیاز.
• روش احراز هویت مانند کلید در هدر یا توکن.
• خط ارسال یا شناسه قالب متناسب با نوع پیام.
• قالب شماره گیرنده مانند فرمت داخلی یا بین المللی.
• محدودیت تعداد گیرنده و نرخ درخواست.
• ساختار پاسخ و روش دریافت وضعیت تحویل.

وضعیت حساب و اعتبار را نیز بررسی کنید. برای ارسال قالبی، تأیید قالب و نام متغیرها اهمیت دارد. مقدار «شماره سفارش» را از داده تأییدشده سفارش بگیرید.

ارسال متنی یا ارسال با قالب را انتخاب کنیم

در ارسال متنی، متن کامل را برنامه تولید می کند. این روش برای پیام های متنوع کاربرد دارد، البته در محدوده امکانات و ضوابط سرویس.

در ارسال با قالب، شناسه متن تأییدشده و متغیرهای آن را می فرستید. برای کد ورود یا اعلان سفارش، این ساختار کنترل متن را ساده می کند. قالب به تنهایی تضمین تحویل نیست؛ مسیر ارسال، شرایط خط و وضعیت گیرنده نیز باید بررسی شود.

مراحل اتصال سایت و نرم افزار به API پیامک

مرحله اول کلید را در سرور نگهداری کنید

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

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

OWASP توصیه می کند کلید و توکن در URL قرار نگیرند، چون ممکن است در لاگ ها ثبت شوند. از HTTPS و محل احراز هویت تعیین شده در مستندات استفاده کنید.

مرحله دوم یک درخواست آزمایشی ارسال کنید

ابتدا یک درخواست به شماره خودتان بفرستید تا مشکلات دسترسی و ساختار درخواست را پیش از اتصال به برنامه پیدا کنید.

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

curl –request POST ‘https://sms.example.com/v1/messages’

  –header Authorization: Bearer ${SMS_API_KEY}

  –header ‘Content-Type: application/json’

  –connect-timeout 5

  –max-time 15

  –data ‘{

    sender: YOUR_SENDER,

    recipient: YOUR_TEST_MOBILE,

    text: پیام آزمایشی اتصال سایت

  }’

مقادیر زمان انتظار در این مثال صرفاً تنظیمات پیشنهادی برای آزمایش اند. پاسخ را از دو جهت بررسی کنید: کد HTTP و نتیجه عملیات داخل بدنه. بعضی سرویس ها خطای عملیاتی را با پاسخ HTTP موفق و کد خطای داخلی گزارش می کنند.

مرحله سوم ارسال را به رویداد درست وصل کنید

برای پیام ثبت سفارش، رویداد مناسب می تواند تأیید پرداخت در سرور باشد. نمایش صفحه «پرداخت موفق» در مرورگر کافی نیست؛ کاربر ممکن است صفحه را ببندد یا چند بار آن را بارگذاری کند.

پس از تأیید معتبر تراکنش، وضعیت سفارش را ذخیره کنید و کار ارسال را بسازید. برای جلوگیری از ایجاد چندباره این کار، ترکیب «شناسه سفارش و نوع اعلان» را در پایگاه داده یکتا کنید. اگر رویداد پرداخت دوباره رسید، همان اعلان نباید مجدداً ایجاد شود.

در نرم افزار سازمانی نیز پیام صدور فاکتور را پس از ثبت نهایی فاکتور ارسال کنید.

مرحله چهارم ارسال را در صف پردازش کنید

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

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

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

مرحله پنجم نتیجه ارسال را ذخیره کنید

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

موفقیت درخواست با تحویل پیامک تفاوت دارد. طبق تعریف HTTP، پاسخ ۲۰۲ یعنی درخواست برای پردازش پذیرفته شده و پردازش هنوز کامل نشده است. تفسیر دقیق پاسخ سرویس را از مستندات همان API بگیرید.

مرحله ششم وضعیت تحویل را پیگیری کنید

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

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

گزارش تحویل را به عنوان «خوانده شدن پیام» نمایش ندهید. وضعیت دریافت شده را با همان معنایی که سرویس تعریف کرده، در پنل پشتیبانی نشان دهید.

خطاهای رایج اتصال را چگونه رفع کنیم

در جدول زیر، کدها بر اساس معنای استاندارد HTTP توضیح داده شده اند. سرویس منتخب ممکن است برای جزئیات عملیات، کدهای اختصاصی در بدنه پاسخ داشته باشد.

مشکل	بررسی اولیه	اقدام پیشنهادی
پاسخ ۴۰۰	نام فیلدها و قالب داده	اصلاح درخواست مطابق مستندات
پاسخ ۴۰۱	کلید یا توکن ارسال شده	بررسی مقدار و روش احراز هویت
پاسخ ۴۰۳	مجوز انجام عملیات	بررسی دسترسی حساب و محدودیت های اعلام شده
پاسخ ۴۲۹	تعداد درخواست در بازه زمانی	کاهش نرخ و تنظیم صف
پاسخ ۵۰۰ یا ۵۰۳	وضعیت سرویس و نتیجه ثبت درخواست	بررسی وضعیت پیش از تکرار ارسال
پایان زمان انتظار	نامشخص بودن نتیجه درخواست	استعلام با شناسه پشتیبانی شده
ثبت موفق بدون تحویل	گزارش پیام و تنظیمات ارسال	پیگیری وضعیت نهایی و شرایط گیرنده

برای پاسخ ۴۲۹، اگر هدر Retry-After وجود دارد، زمان انتظار اعلام شده را رعایت کنید. این هدر می تواند زمان مجاز برای درخواست بعدی را مشخص کند.

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

اگر API از Idempotency Key پشتیبانی می کند، برای تلاش های مربوط به یک اعلان، کلید ثابت بفرستید. یکتا کردن کار در دیتابیس از ایجاد دوباره اعلان جلوگیری می کند، اما به تنهایی تکرار درخواست در سمت سرویس را حل نمی کند.

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

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

1. شماره را به فرمت مورد انتظار تبدیل و اعتبارسنجی کنید.
2. کد را با مولد تصادفی امن بسازید و به درخواست ورود مشخصی مرتبط کنید.
3. زمان انقضا و تعداد مجاز تلاش برای بررسی کد تعیین کنید.
4. درخواست ارسال مجدد را برای شماره و مبدأ محدود کنید.
5. پس از تأیید، کد را مصرف شده علامت بزنید و پذیرش دوباره را ببندید.

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

هزینه و عملکرد اتصال را چگونه کنترل کنیم

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

متن را بر اطلاعات ضروری متمرکز کنید: نام کسب وکار، رویداد و اقدام بعدی. جزئیات طولانی را در حساب کاربری نمایش دهید. برای یادآوری نوبت نیز پیش از اجرا بررسی کنید که نوبت لغو یا جابه جا نشده باشد.

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

قبل از انتشار چه آزمون هایی انجام دهیم

یک پیام موفق برای تأیید کل اتصال کافی نیست. این سناریوها را در محیط آزمایشی یا با داده و شماره تحت کنترل بررسی کنید:

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

ابتدا یک رویداد را فعال کنید. نتیجه را در لاگ و گزارش تحویل ببینید، سپس اعلان های بعدی را اضافه کنید.

سوالات متداول درباره API پیامک

آیا اتصال API پیامک به برنامه نویسی نیاز دارد

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

آیا می توان از جاوا اسکریپت مرورگر پیامک فرستاد

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

چرا API پاسخ موفق می دهد اما پیامک نمی رسد

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

آیا API پیامک به شماره های مسدود پیام می فرستد

این امکان به نوع پیام، مسیر خدماتی و شرایط سرویس وابسته است. برای کد تأیید و اعلان ضروری، شرایط مسیر مناسب را بررسی کنید. داشتن دسترسی API به تنهایی امکان ارسال به همه شماره ها را تضمین نمی کند.

اتصال پیامکی پروژه را شروع کنید

برای شروع، یک سناریوی مشخص مثل اعلان ثبت سفارش یا ارسال کد ورود انتخاب کنید. سپس حساب پیامکی بسازید، دسترسی وب سرویس و مستندات را دریافت کنید و یک پیام آزمایشی بفرستید.

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