وب‌سرویس‌ها برای اشتراک‌گذاری منابع بین کامپیوترها بسیار مفید و کاربردی هستند. یک وب‌سرویس امکان فراخوانی و تبادل داده بین دو برنامه مستقل را از طریق پروتکل‌های شبکه و استانداردهای داده‌ای مانند XML فراهم می‌کند. واسط برنامه‌نویسیِ تحت وب (به‌اختصار، واسط وب) نوعی از وب‌سرویس است که صرفاً از استانداردهای وب و اینترنت مانند REST و JSON استفاده می‌کند. در این مستند روش فراخوانی واسط‌های وب برای ارسال پیامک با توکن‌های عادی و خدماتی تشریح می‌شود.
۱) درخواست (Request): یک درخواست HTTP(S) برای فراخوانی واسط وب.
نکته مهم: هر درخواست باید توکن اختصاصی مربوطه را به‌همراه داشته باشد (در سرآیند یا همان header).
۲) واسط برنامه‌نویسی تحت وب (Web API): یک پل ارتباطی میان برنامه‌های مستقل (روی سرورهای مستقل) است که از طریق پروتکل‌های شبکه و استانداردهای وب با هم تبادل اطلاعات می‌کنند. در این مستند به‌اختصار آن را «واسط وب» می‌نامیم.
۳) توکن (Token): یک قلم داده متشکل از یک رشته (توالی) از کاراکترها است که برای احراز هویت و تعیین سطح دسترسی کلاینت استفاده می‌شود. این توکن از بخش تعریف توکن قابل تعریف و دریافت است.
نکته مهم: به‌ازای هر فراخوانی یک واسط وب، بایستی توکن اختصاصی مربوطه در سرآیند یا همان header درخواست قرار بگیرد.
۴) متدهای HTTP: یکی از متدهای استاندارد در HTTP(S) است مانند GET یا POST.
نکته مهم: در این مستند فقط از متد POST استفاده می‌کنیم.
۵) استاندارد جِیسان (JSON): یک استاندارد اینترنت است که برای توصیف اشیاء داده‌ای (یا همان data objects) استفاده می‌شود. این استاندارد قابلیت توصیف انواع داده‌ها و روابط میان آن‌ها را دارد. واسط‌های وب که در بخش ۶ معرفی می‌شوند، از این استاندارد برای تبادل اطلاعات استفاده می‌کنند.
نکته مهم: داده‌ها در استاندارد جیسان در قالب یک شیء به زبان برنامه‌نویسی جاواسکریپت ارائه می‌شوند.
نمونه کد :
{
"message": "متن پیام شما",
"recipient": "0912xxxxxxx"
}
واسط‌های وب و همچنین وب‌سرویس‌ها اغلب از روش‌هایی برای حفاظت استفاده می‌کنند تا فقط کاربران مجاز امکان استفاده از منابع را داشته باشند. در این مستند، هر واسط وب یک توکن اختصاصی دارد که از بخش تعریف توکن قابل تعریف و دریافت است. هنگام فراخوانی واسط‌های وب، بایستی توکن اختصاصی و مربوط به آن واسط را در «سرآیند درخواست» یا همان
«HTTP(S) Request Header» قرار دهید تا فرآیند احراز هویت و تعیین سطح دسترسی شما به‌درستی انجام شود. بنابراین کافی است هنگام ارسال هر درخواست به سرور، یک سرآیند از نوع «Authorization Bearer» به آن اضافه نمایید و توکن اختصاصی را در آن قرار دهید.
فرآیند درخواست و پاسخ از استاندارد درخواست‌های HTTP(S) در قالب جیسان پیروی می‌کند.
فراخوانی یک واسط وب از طریق یک درخواست HTTP(S) با متد POST انجام می‌شود.
بایستی توکن اختصاصی را که از بخش مدیریت توکن ها دریافت کرده‌اید، در سرآیند درخواست یا همان «HTTP(S) header» درخواست خود قرار دهید.
نکته مهم: نوع این سرآیند «Authorization Bearer» است.
هر واسط وب با توجه به کارکرد خود، ورودی‌هایی را دریافت می‌کند (مانند شماره گیرنده پیام و متن پیام). ورودی‌ها در قالب استاندارد جیسان در بدنه درخواست HTTP(S) قرار می‌گیرند و به سرور فرستاده می‌شوند. چنانچه واسط وب مقادیر خروجی داشته باشد، آن‌ها را نیز در قالب یک شیء مبتنی بر استاندارد جیسان به کلاینت برمی‌گرداند.
پس از یک فراخوانی موفق، یک کد وضعیت HTTP(S) با مقدار ۲۰۰ به کلاینت برگردانده می‌شود که به‌معنای اجرای موفق درخواست است. هر کد غیر از ۲۰۰ به‌معنی اجرای ناموفق است. شرح کدهای خطا در جدول (۱) ارایه شده‌اند.
در صورت بروز خطا در فراخوانی واسط وب، یک شیء جیسان به کلاینت برگردانده می‌شود که توصیف‌کننده خطا است. در این شیء علاوه بر کد وضعیت خطا (status)، یک پیام جزئیات خطا (detail) نیز در کنار شناسه درخواست (traceId) وجود دارد.
نمونه کد:
{
"status": 461,
"detail": "متن پیام حاوی لینک نامعتبر است.",
"traceId": "0HMAUU3BB2N5K:00000003"
}
برای ارسال یک پیامک به یک شماره غیر لیست سیاه استفاده می‌شود.
آدرس واسط وب: https://app.sms1.ir:7001/api/service/send
| نام متغیر | نوع داده‌ای | ملاحظات |
|---|---|---|
| message | رشته‌ای | حداکثر ۱۵۳۰ کاراکتر انگلیسی یا ۶۶۰ کاراکتر فارسی |
| recipient | رشته‌ای | حداکثر ۲۰ رقم انگلیسی |
نتیجه فراخوانی: چنانچه فراخوانی موفقیت‌آمیز باشد، کد وضعیت ۲۰۰ در قالب پاسخ HTTP(S) برگردانده می‌شود. کد وضعیت غیر از ۲۰۰ به‌معنای بروز خطا در اجرای درخواست است.
برای ارسال یک پیامک به یک شماره عادی یا لیست سیاه استفاده می‌شود.
آدرس واسط وب: https://app.sms1.ir:7001/api/service/patternSend
| نام متغیر | نوع داده‌ای | ملاحظات |
|---|---|---|
| patternId | عددی | شناسه الگوی تایید شده در پنل کاربری |
| recipient | رشته‌ای | حداکثر ۲۰ رقم انگلیسی |
| pairs | شیء جیسان | متغیرهای ثبت و تایید شده در الگو بایستی در قالب «کلید-مقدار» در یک شیء جیسان با نام pairs قرار بگیرند. |
| کد خطا | نوع خطا | ملاحظات |
|---|---|---|
| ۴۰۰ | درخواست نامعتبر | درخواست نامعتبر است. |
| ۴۰۱ | هویت نامعتبر | هویت نامعتبر است. |
| ۴۰۳ | عملیات غیر مجاز | عملیات غیر مجاز |
| ۴۲۲ | مقادیر ورودی نامعتبر | مقادیر ورودی نامعتبر هستند. |
| ۴۶۰ | درخواست نامعتبر | متن پیام دارای کلمات غیر مجاز است. |
| ۴۶۱ | درخواست نامعتبر | متن پیام دارای لینک نامعتبر است. |
| ۴۶۲ | درخواست نامعتبر | لطفا حساب کاربری خود را شارژ نمایید. |
| ۴۶۳ | درخواست نامعتبر | شناسه الگو نامعتبر است. |
| ۴۶۴ | درخواست نامعتبر | الگوی وارد شده هنوز توسط مدیر سامانه تایید نشده است. |
| ۴۶۵ | درخواست نامعتبر | متن الگو با متغیرهای وارد شده در Pairs همخوانی ندارد. |
| ۵۰۰ | خطای سرور | خطایی در اجرای درخواست رخ داده است، لطفا با پشتیبانی تماس بگیرید. |
| ۵۷۰ | خطای سرویس‌دهنده خارجی | خطایی در اجرای درخواست رخ داده است، لطفا با پشتیبانی تماس بگیرید. |
| ۵۷۱ | خطای سرویس‌دهنده خارجی | شماره گیرنده مسدود یا در لیست سیاه است. |
| ۵۹۰ | خطای ناشناخته | خطایی در اجرای درخواست رخ داده است، لطفا با پشتیبانی تماس بگیرید. |