راهنمای وب‌سرویس REST پیامک: مفاهیم پایه و رفع خطاهای ۴۰۳ و ۴۲۲
اتصال نرم‌افزار، سایت یا اپلیکیشن به سامانهٔ پیامکی از طریق وب‌سرویس انجام می‌شود؛ از ارسال کد تأیید ورود گرفته تا اطلاع‌رسانی خودکار سفارش‌ها. بیشتر مشکلاتی که برنامه‌نویسان در این مسیر با آن روبه‌رو می‌شوند نه پیچیده‌اند و نه به خود سامانه مربوط‌اند؛ معمولاً یک رقم فارسی، فرمت تاریخ اشتباه یا آی‌پی ثبت‌نشده علت ماجراست. در این مقاله مفاهیم اصلی وب‌سرویس REST و رایج‌ترین خطاها را مرور می‌کنیم. مستندات کامل، شامل نشانی‌ها و فهرست متدها، در بخش برنامه‌نویسان پنل در دسترس است.
کلید API: هویت درخواست‌های شما
هر درخواست به وب‌سرویس با یک کلید API (api-key) شناسایی می‌شود. این کلید را در بخش برنامه‌نویسان پنل می‌بینید. چند نکتهٔ مهم:
- کلید API مثل رمز عبور است؛ آن را در کد سمت کاربر (مثلاً جاوااسکریپت مرورگر یا اپلیکیشن موبایل) قرار ندهید و فقط در سرور نگه دارید.
- هنگام کپی‌کردن، مراقب فاصله یا کاراکتر اضافه در ابتدا و انتهای کلید باشید.
- اگر حسابتان را عوض کردید یا کلید را تغییر دادید، همهٔ سرویس‌ها و افزونه‌هایی را که از کلید قبلی استفاده می‌کردند به‌روز کنید.
دو شیوهٔ ارسال: معمولی و نظیربه‌نظیر
ارسال معمولی
یک متن ثابت به یک یا چند گیرنده فرستاده می‌شود؛ مثلاً اطلاعیه‌ای یکسان برای فهرستی از مشتریان.
ارسال نظیربه‌نظیر
برای هر گیرنده متن مخصوص به خودش ارسال می‌شود؛ مثلاً پیام «سفارش شمارهٔ X شما ارسال شد» که شمارهٔ سفارش برای هر مشتری فرق دارد. در این حالت آرایهٔ گیرندگان و آرایهٔ متن‌ها متناظر با هم ارسال می‌شوند. به جای فراخوانی صدها درخواست تکی، از این شیوه استفاده کنید تا هم سرعت بیشتر شود و هم بار شبکه کمتر.
GET یا POST؟
آرایه‌ها را می‌توان به‌صورت JSON یا urlencoded فرستاد. برای متن‌های طولانی یا تعداد زیاد گیرنده، روش POST بر GET ترجیح دارد. اگر از GET استفاده می‌کنید، متن پیام حتماً باید URL Encode شود؛ وگرنه کاراکترهای فارسی و فاصله‌ها متن را خراب می‌کنند.
شمارهٔ درگاه (gateway)
شمارهٔ درگاه همان شمارهٔ خط پیامکی (اختصاصی یا اشتراکی) است که پیام از آن ارسال می‌شود و فهرست آن را در بخش خطوط پنل می‌بینید. این عدد در پارامتر مربوط به درگاه قرار می‌گیرد. اگر چند خط دارید، مثلاً یکی خدماتی و یکی تبلیغاتی، برای جابه‌جایی بین آن‌ها فقط کافی است همین پارامتر را عوض کنید و نیازی به تغییر کلید API نیست، مگر این‌که خط متعلق به حساب دیگری باشد.
خطای ۴۲۲: داده‌ها معتبر نیستند
این خطا یعنی درخواست به سرور رسیده اما مقدار یکی از پارامترها قابل قبول نیست. دو علت بسیار رایج:
- ارقام فارسی: شمارهٔ درگاه و شمارهٔ گیرنده باید حتماً با ارقام لاتین باشند. اگر داده‌ها از فرم فارسی سایت می‌آیند، پیش از ارسال آن‌ها را به ارقام لاتین تبدیل کنید؛ وگرنه پیامی مبنی بر نامعتبر بودن درگاه دریافت می‌کنید.
- فرمت نادرست تاریخ: در متدهای استعلامی، تاریخ باید دقیقاً با فرمت مستندات باشد؛ مثلاً
2024-04-27 23:54:43، یعنی تاریخ میلادی با ارقام لاتین، خط تیره میان اجزای تاریخ و ساعت کامل.
نکته: یک تابع کوچک «نرمال‌سازی» بنویسید که پیش از هر فراخوانی، ارقام فارسی و عربی را به لاتین تبدیل و فاصله‌های اضافه را حذف کند. همین تابع بخش بزرگی از خطاهای ۴۲۲ را از بین می‌برد.
خطای ۴۰۳: آدرس IP غیرمجاز
اگر در تنظیمات وب‌سرویس محدودیت آی‌پی مجاز را فعال کرده باشید، فقط درخواست‌هایی پذیرفته می‌شوند که از آی‌پی‌های ثبت‌شده بیایند. رایج‌ترین علت خطای ۴۰۳ این است که آی‌پی واقعی سرور برنامهٔ شما در فهرست نیست. موقعیت‌های متداول:
- آی‌پی رایانهٔ محلی توسعه‌دهنده ثبت شده، نه آی‌پی سرور اصلی.
- سرور یا هاست جابه‌جا شده و آی‌پی قدیمی هنوز در فهرست است.
- سرور از طریق یک آی‌پی خروجی متفاوت (مثلاً پشت NAT یا پراکسی) درخواست می‌فرستد.
راه‌حل: آی‌پی خروجی فعلی سرور را پیدا و به فهرست اضافه کنید، یا در صورت نیاز محدودیت را غیرفعال کنید. اگر پس از اصلاح فهرست باز هم خطا ادامه داشت، کلید API را در تنظیمات برنامه یا افزونه یک‌بار پاک و دوباره وارد کنید تا مطمئن شوید کاراکتر اضافه‌ای در آن نیست.
صفحه‌بندی نتایج استعلام
متدهای استعلام، مثل فهرست پیام‌های ارسالی یا دریافتی، در هر فراخوانی حداکثر ۱۰۰ رکورد برمی‌گردانند. برای دریافت بقیهٔ نتایج از پارامتر صفحه (page) با مقدارهای ۱، ۲، ۳ و … استفاده کنید تا جایی که نتیجهٔ خالی یا کمتر از ۱۰۰ رکورد برگردد.
اشتباه رایج: فرض این‌که اولین پاسخ استعلام همهٔ داده‌هاست. اگر گزارش شما همیشه دقیقاً ۱۰۰ ردیف دارد، تقریباً مطمئن باشید صفحه‌بندی را پیاده نکرده‌اید.
وضعیت پیام را دوباره استعلام کنید
پاسخ لحظهٔ ارسال فقط نشان می‌دهد درخواست ثبت شده و وضعیت اولیهٔ پیام «در صف» است. وضعیت نهایی، مثل تحویل به گیرنده یا بلک‌لیست، بعداً مشخص می‌شود. شناسهٔ پیام را ذخیره کنید و پس از مدتی وضعیت را دوباره استعلام کنید.
جمع‌بندی
بیشتر خطاهای وب‌سرویس با سه عادت ساده از بین می‌روند: ارقام لاتین، فرمت دقیق تاریخ و ثبت آی‌پی درست سرور. مستندات کامل و نمونه‌ها را در بخش برنامه‌نویسان پنل ببینید و اگر خطایی همچنان برطرف نشد، با ثبت تیکت پشتیبانی و ارسال بدنهٔ درخواست (بدون کلید API) و پاسخ دریافتی، از کارشناسان فنی وب‌سرویس کمک بگیرید.
