مستندات وبسرویس پیامک کاپنل؛ ۱۶ متد API، نمونهکد و Webhook
همه اطلاعات موردنیاز برای اتصال سایت، نرم‌افزار یا اپلیکیشن شما به سامانه پیامک کاپنل؛ از ارسال پیامک و دریافت اعتبار تا گزارش وضعیت، دفترچه، ارسال بر اساس کدپستی و مشاغل، نمونه‌کدهای برنامه‌نویسی و دریافت وضعیت دلیوری با Webhook.
مستندات API برای اتصال سریع و مطمئن
این صفحه مستندات فنی وبسرویس پیامک کاپنل را در یک ساختار یکپارچه ارائه میکند. در ادامه، ۱۶ متد اصلی، کاربرد هر متد، پارامترهای مهم، نمونه‌کدهای آماده و الزامات Webhook را می‌بینید تا توسعه‌دهنده بتواند مسیر اتصال را بدون جست‌وجوی پراکنده دنبال کند.
قبل از اتصال API چه چیزهایی لازم است؟
اطلاعات دسترسی
بسیاری از متدها به نام کاربری و پسورد نیاز دارند. سایر پارامترها بسته به نوع عملیات مشخص می‌شوند.
متد مناسب عملیات را انتخاب کنید
برای ارسال ساده از Send و برای گزارش وضعیت از Delivery استفاده می‌شود. عملیات‌های دفترچه، کدپستی، مشاغل و مدیریت کاربر نیز متد اختصاصی دارند.
برای دلیوری از Webhook استفاده کنید
در صورت نیاز به دریافت وضعیت ارسال، می‌توانید سرور خود را برای دریافت درخواست POST از طریق Webhook آماده کنید.
این صفحه بیشتر برای درک سریع ساختار API و انتخاب متد مناسب طراحی شده است. برای جزئیات بسیار فنی هر پارامتر، نمونه‌کدهای زبان موردنظر و فایل PDF فنی نیز در همین صفحه در دسترس هستند.
متدهای وبسرویس API؛ ۱۶ متد
فهرست زیر متدهای اصلی مستندات را به همراه کاربرد و پارامترهای کلیدی نمایش میدهد.
01
Send
ارسال پیامک
POST
متد اصلی برای ارسال پیامک به شماره یا فهرست شماره‌های دریافت‌کننده است.
02
Credit
دریافت اعتبار
GET
برای دریافت میزان اعتبار حساب پیامکی استفاده می‌شود.
03
Delivery
گزارش وضعیت ارسال
GET
وضعیت ارسال پیام‌ها را بر اساس شناسه بالک دریافت میکند.
04
Inboxlist
دریافت پیام‌های خوانده‌شده
GET
برای دریافت پیام‌های موجود در بخش پیام‌های خوانده‌شده استفاده می‌شود.
05
Accesslist
دریافت بسته‌های در دسترس
GET
اطلاعات بسته‌ها یا دسترسی‌های در دسترس را دریافت میکند.
06
Newuser
ساخت کاربر جدید
POST
برای ساخت کاربر جدید و ثبت اطلاعات پایه کاربر استفاده می‌شود.
07
Booksend
ارسال از دفترچه
POST
برای ارسال پیامک بر اساس شماره‌های موجود در دفترچه استفاده می‌شود.
08
Booklist
گزارش وضعیت ارسال از دفترچه
GET
وضعیت عملیات ارسال از دفترچه را دریافت میکند.
09
Postalcodecount
تعداد شماره‌ها در یک کدپستی
GET
تعداد شماره‌های قابل شناسایی بر اساس کدپستی را دریافت میکند.
10
Postalcodearea
دریافت محله‌های تهران
GET
برای دریافت اطلاعات محله‌های تهران بر اساس ساختار تعریف‌شده در سرویس استفاده می‌شود.
11
Postalcodesend
ارسال بر اساس کدپستی
POST
برای ارسال پیامک به گروهی از شماره‌ها بر اساس کدپستی و فیلترهای مشخص‌شده استفاده می‌شود.
12
Jobssend
ارسال بر اساس مشاغل
POST
برای ارسال پیامک به گروه‌های شغلی و گرایش‌های تعریف‌شده در سرویس استفاده می‌شود.
13
Jobslist
دریافت فهرست شغل‌ها
GET
فهرست مشاغل قابل استفاده در عملیات مبتنی بر شغل را دریافت میکند.
14
Jobstrenlist
دریافت فهرست گرایش‌ها
GET
فهرست گرایش‌های مرتبط با ساختار مشاغل را دریافت میکند.
15
Jobscount
تعداد شماره‌های مشاغل
GET
تعداد شماره‌های مرتبط با مشاغل و گرایش‌های مشخص‌شده را دریافت میکند.
16
Checkmessage
دریافت گزارش وضعیت پیام
GET
برای بررسی وضعیت خود پیام ارسالی و مشاهده وضعیت پردازش آن استفاده می‌شود.
صفحه فعلی آزمایشگاه در سایت ۱۵ عنوان متد را مستقیماً نمایش میدهد. در PDF فنی رسمی، متد checkmessage نیز مستند شده و در این صفحه به‌عنوان متد شانزدهم اضافه شده است. همین PDF قدیمی متدی با نام sendsociol را نیز دارد که در فهرست فعلی آزمایشگاه نمایش داده نمی‌شود؛ بنابراین آن را وارد فهرست اصلی ۱۶ متد نکرده‌ایم.
API را بر اساس عملیات موردنیاز انتخاب کنید
متدهای کاپنل فقط به ارسال پیامک محدود نیستند؛ می‌توانید اعتبار، دلیوری، پیام‌های خوانده‌شده، دفترچه، کدپستی، مشاغل و ساخت کاربر را نیز از طریق وبسرویس مدیریت کنید.
نمونه‌کدهای آماده برای شروع توسعه
نمونههای آماده وبسرویس کاپنل برای زبانها و روش‌های متداول در اختیار توسعه‌دهنده قرار گرفته‌اند.
از مستندات تا اتصال واقعی
ابتدا متد موردنظر را انتخاب کنید، سپس نمونهکد زبان خود را بردارید و پارامترهای سرویس را مطابق مستندات تنظیم کنید. برای گزارش وضعیت لحظه‌ای نیز می‌توانید Webhook را در معماری خود قرار دهید.
مشاهده شرایط Webhook ←دریافت وضعیت دلیوری از طریق Webhook
اگر می‌خواهید وضعیت ارسال پیامک را به‌صورت خودکار و مستقیم داخل نرم‌افزار خود دریافت کنید، Webhook می‌تواند درخواست POST را به endpoint تعریف‌شده شما ارسال کند.
شرایط Endpoint
نکات مهم برای آماده‌سازی سرور دریافت‌کننده
ساختار پیشنهادی اتصال سایت و نرم‌افزار
معماری اتصال معمولاً از نرم‌افزار شما، لایه API و عملیات ارسال یا دریافت وضعیت تشکیل می‌شود.
سوالات متداول درباره API پیامک کاپنل
پاسخ‌های کوتاه برای سوالاتی که پیش از اتصال وبسرویس معمولاً مطرح می‌شوند.
وبسرویس پیامک کاپنل چه کاری انجام میدهد؟ +
وبسرویس کاپنل چند متد API دارد؟ +
چه زبانها و روشهایی برای اتصال نمونهکد دارند؟ +
برای دریافت وضعیت دلیوری چه گزینهای وجود دارد؟ +
Webhook باید چه شرایطی داشته باشد؟ +
آیا برای ساخت سایت وردپرسی یا نرم‌افزار الزاماً باید API را از صفر پیاده‌سازی کنم؟ +
آماده اتصال سایت یا نرم‌افزار خود هستید؟
از مستندات API شروع کنید، نمونهکد زبان موردنظر را دریافت کنید و بعد سرویس پیامکی متناسب با نیازتان انتخاب کنید.
