آموزش ارسال پیامک از طریق API
شاید تا به حال شنیده باشیدکه API مخفف عبارت Application Programming Interface می‌باشد که به برنامه نویسان امکان رد و بدل کردن اطلاعات مابین پلتفرم های مختلف را از طریق ارسال یک درخواست HTTP(S) ساده و فراخوانی متد های مورد نظر می‌دهد
در واقع REST یک روش ساده و انعطاف پذیری برای استفاده از API است و البته محبوب ترین و پر کاربرد ترین که می‌توان توسط این ساختار از هر کلاینت و پلتفرمی درخواست ساده HTTP(S) را ارسال و پاسخ آن را دریافت نمود.
حال فرض کنید در خواست مورد نظر اطلاعات مربوط به ارسال یک پیامک باشد و جواب آن نتیجه و وضعیت پیامک ارسالی باشد.
وب سرویس ارسال پیامک رایان آب نیرو شماره گیرنده ، متن پیامک و شماره فرستنده را از طریق پارامتر های ورودی در متد GET یا POST دریافت میکند و خروجی را در غالب فرمت های XML و JSON برگشت می‌دهد.
نکته : اگر با JSON آشنائی ندارید میتوانید با مراجعه به سایت json.org هم از ساختار فرمت آن مطلع شوید و هم درایور مربوط به زبان برنامه نویسی مورد نظر خود را دریافت نمائید.
مزایای استفاده از وب سرویس های ارسال پیامک
- پایداری وب سرویس
وب‌سرویس پیام کوتاه به لحاظ نوع عملکرد از حساسیت زیادی برخوردار است،
بنابراین
پایداری و حفظ کیفیت مطلوب برای سرویس های API یک مزیت محسوب می شود،شرکت رایان آب نیرو این پایداری را در سطح مطلوبی ایجاد نموده است.
- جایگزینی خودکار پوشش
همکاری با کلیه سرشماره ها و قابلیت تعیین خط جایگزین در شرایط اختلال می
تواند تضمین رسیدن پیامک های حساس شما با حداکثر سرعت به گیرندگان باشد
،
وب سرویس های ارائه شده توسط این شرکت
رسیدن پیام به گیرنده را در کمتر ۱ دقیقه
گارانتی میکند
.
- وب سرویس
ساختار RESTfull برای API پیامک امکان ارسال و دریافت پیامک را در پلتفرم
های مختلف امکان پذیر می کند، و API های ما بصورت تخصصی بر روی ارسال پیامک و
تماس صوتی
و ارسال کد تایید هویت
Verification
تمرکز دارد.
- خدمات تخصصی
درگاه ارسال و دریافت پیامک برای بستر سیستم های نرم افزاری
طراحی شده است و با توجه به ساختار REST API امکان ارسال و
دریافت پیامک در پلتفرم های مختلف را امکان پذیر میکند، سرویس های تخصصی ما بروی ارائه وب سرویس پیامک تمرکز دارد.
شروع ارتباط:
ابتدا برای ایجاد ارتباط شرکت با شما باید از طریق درگاه ثبت نام در سامانه ثبت نام نماییدو سپس یک پنل کاربری به شما تعلق خواهد گرفت که توسط این پنل یک کلمه عبور واسط بین شما و شرکت رایان آب نیرو باید ایجاد گردد، این کلمه عبور باعث می شود، تمام درخواست های پشتیبانی، پرداخت وجه ها، خطا ها، پشتیبانی های صورت گرفته و.. به صورت متمرکز در سامانه پشتیبانی شرکت رایان آب نیرو ثبت گردد، و ما می توانیم خدمات بهتری را به شما ارائه کنیم.
مراحل دریافت کد پشتیبانی
- ابتدا در سامانه پشتیبانی شرکت ثبت نام نمایید (آموزش ثبت نام در سامانه پشتیبانی)
- پس از ثبت نام باید وارد پنل کاربری پشتیبانی شده.(ورود به سامانه پشتیبانی)
- پس از ورود از طریق لینک زیر می توانید وارد سامانه پشتیبانی شوید.
- پس از ورود بر روی گذینه ای که تصویر آن در زیر قرار دارد کلیک نمایید.
- سامانه پشتیبانی شبیه به تصویر زیر است.
- کد منحصر به فرد را کپی نمایید.
لازم به توضیح است کلیه فرآخوانی ها API ارسال پیامک توسط این کد انحصاری صورت میگیرد.
نکات مهم قبل از فرآخوانی و ایجاد ارتباط با سامانه پیامکی
طول پیامک
طول استاندارد یک پیام کوتاه 140 ﺑﺎﻳﺖ که معادل 70 کاراکتر برای یک
پیامک فارسی و 140 کاراکتر برای یک پیامک لاتین و 140 بایت برای پیامک
باینری می‌باشد بنابراین هر کاراکتر فارسی معادل 2 بایت محاسبه می‌شود. این
موضوع به دلیل گنجاندن کاراکتر های فارسی در فرمت یونیکد می‌باشد که با
وجود حتی یک کاراکتر فارسی در پیامک باعث می‌شود تا طول آن بر حسب فرمت
یونیکد (هر کاراکتر 2 بایت) محاسبه شده و پیامک فارسی شود (پیامک های فارسی
ارزان تر از پیامک های لاتین هستند).
پیامک های چند بخشی
در صورتی که پیامک از طول استاندارد 140 بایت بیشتر شود باید به
بخش های 140 بایتی تقسیم شده و سپس به مقصد ارسال شود که البته این کار
توسط وب سرویس موجود انجام می‌شود و نیاز نیست برای این موضوع عملیاتی
انجام دهید کافیست کل پیام را در فراخوانی وب سرویس ارسال نمائید. البته به
این موضوع باید توجه داشت که به ازای هر بخش از یک پیامک فارسی طولانی، 3
کاراکتر و به ازای هر بخش از کی پیامک لاتین طولانی ،7 کاراکتر از فضای
استاندارد متین پیامک به کد UDH اختصاص پیدا میکند.یعنی در واقع هر بخش از
پیامک چند قسمتی فارسی حداکثر 67 کاراکتروهربخش ازپیامک چند قسمتی لاتین
حداکثر 153 کاراکتررادرخودجای می‌دهد.
ﺣﺪاﻛﺜﺮ ﻃﻮل پیامک
حداکثر طول کل متن پیامک 900 کاراکتر می باشد. درصورتی که بیشتر از
این مقدار ارسال شود مقدار پارامتر Status معادل 413 به معنای "متن پیام
خالی است و یا طول آن بیشتر از حد مجاز می‌باشد" را برگشت می‌دهد. علاوه بر
این موضوع در هر بار فراخوانی متدهای ارسال پیامک میتوانید حداکثر 200
پیامک ارسال کنید. این محدودیت برای حفظ کیفیت در ارسال و سرعت پاسخگوئی
قرارداده شده است همچنین در هر بار فراخوانی متدهای کنترل وضعیت Status و
انصراف از ارسال پیامک Cancel میتوانید حداکثر 500 شناسه را در ورودی قرار
دهید.
فرمت داده های ورودی
در طراحی وب سرویس کاوه نگار سعی شده تا جای ممکن نسبت به داده های
ورودی حساسیت وجود نداشته باشد در نهایت پارامتر ها با فرمت زیر قابل
تشخیص هستند در غیر اینصورت احتمال دریافت کد خطا در داده های ورودی وجود
دارد.
در هنگام ارسال درخواست با متد
HTTP GET حتما مقدار پارامتر ها را
URL Encode
نمائید.
فرمت درست خط اختصاصی فرستنده
(این شماره به عنوان مثال قید شده است)
+9810004346
009810004346
10004346
فرمت درست شماره گیرنده
(این شماره به عنوان مثال قید شده است)
09121234567
00989121234567
+989121234567
9121234567
شروع فرآخوانی:
شما توسط آدرس زیر می توانید فرآخوانی های خود را با توجه به نوع استاندارد برنامه نویسی خودتان تایید نمایید تا ارتباط بر قرار شود
لینک خروجی Json
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی
|
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی
|
Name
| string | نام شما در پنل پشتیبانی
|
Family
| string | نام خانوادگی شما در پنل پشتیبانی
|
Credit
| Int
| میزان اعتبار باقیمانده شما در سامانه
|
تابع دریافت اطلاعات GetDate
این تابع به منظور مطابقت دادن اطلاعات میان سرور شرکت رایان آب نیرو و سرور یا اپلیکیشن شما طراحی شده، شما با استفاده از این تابع میتوانید تاریخ و زمان سرور را به صورت کامل متوجه شوید.
پارامتر های ورودی
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی |
خروجی ها
نام
| نوع
| توضیحات
|
| Status | string
| کد وضعیت درخوایت به فرمت ریسپانس HTTP
|
| Message | string | پیام وضعیت درخواست
|
| Data | Object
| این مقدار یک آبجکت است که برای دارای فیلد های زیر می باشد.
| نام | نوع | توضیحات | | Datetime | string | ارسال تاریخ ، زمان و مختصات جغرافیایی برای Sync بهتر درصورت نیاز
| | Year | int
| سال در تقویم میلادی
| | Month | int | ماه در تقویم میلادی | | Day | int | روز در تقویم میلادی | | Hour | int | ساعت حال حاضر سرور
| | Minute | int | دقیقه
| | Second | int | ثانیه
|
|
| Outputs | Array
| یک آرایه است که در این فرمان هیچ استفاده ای ندارد
|
تابع دریافت اطلاعات Send
تمام ارسال پیامک ها از طریق این تابع انجام می شود و تنها کافی است طبق فرمت زیر اطلاعات مورد نیاز را به سمت این تابع ارسال نماییید تا فرآیند ارسال پیامک صورت گیرد.
پارامتر های ورودی
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی |
receptor
| Array | یک آرایه از نوع String است که شماره هایی که تمایل دارید برای آنها پیامک ارسال شود را در این آرایه قرار میدهید، این آرایه میتواند یک یا تعداد زیادی شما داشته باشد.
|
message
| string
| متنی که تمایل دارید ارسال شود
|
sender
| string
| اگر شماره انحصاری خریداری نموده اید و میخواهید از شماره خودتان یا یک شماره رزرو شده فرآیند ارسال صورت گیرد میتوانید شماره تلفن مورد نظر خود را در این مقدار قرار دهید.
|
خروجی ها
نام
| نوع
| توضیحات
|
| Status | string
| کد وضعیت درخوایت به فرمت ریسپانس HTTP
|
| Message | string | پیام وضعیت درخواست
|
| Data | Object
| این مقدار یک آبجکت است که برای دارای فیلد های زیر می باشد.
| نام | نوع | توضیحات | | Datetime | string | ارسال تاریخ ، زمان و مختصات جغرافیایی برای Sync بهتر درصورت نیاز
| | Year | int
| سال در تقویم میلادی
| | Month | int | ماه در تقویم میلادی | | Day | int | روز در تقویم میلادی | | Hour | int | ساعت حال حاضر سرور
| | Minute | int | دقیقه
| | Second | int | ثانیه
|
|
| Outputs | Array
| یک آرایه با سلول های مقدار های زیر است که هر خانه شامل Object زیر می شود
نام
| نوع
| توضیحات | messageid
| int
| هر پیامک در سامانه دارای کد انحصاری است که شما میتوانید وضعیت آن را با توجه به کد انحصاری آن استعلام بگیرید
| message
| string
| متنی که ارسال شده است
| status
| int
| وضعیت ارسال
| statustext
| string | متن وضعیت ارسال پیامک
| sender
| string | شماره ای که با آن برای کاربر ارسال شده است
| receptor
| string | شماره ای که به آن پیامک ارسال شده است
| date
| Int
| زمان ارسال شدن پیام
| cost
| Int | هزینه پیامک
|
|
تابع دریافت اطلاعات Status
توسط این تابع میتوانید وضعیت پیامک هایی که ارسال شده است را مورد بررسی قرار دهید
پارامتر های ورودی
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی |
messageid
| Array | هر
پیامک در سامانه دارای کد انحصاری است که شما میتوانید وضعیت آن را با
توجه به کد انحصاری آن استعلام بگیرید، , این کد پس از اجرای تابع ارسال Send برای شما در خروجی تابع مقدار Outputs قرار خواهد گرفت، تنها این کار کافی است یک آرایه از
نوع string برای این ورودی ارسال کنیدکه شامل کدهای منحصر به فرد پیامک
هایی باشد که ارسال شده است. |
خروجی ها
نام
| نوع
| توضیحات
|
| Status | string
| کد وضعیت درخوایت به فرمت ریسپانس HTTP
|
| Message | string | پیام وضعیت درخواست
|
| Data | Object
| این مقدار یک آبجکت است که برای دارای فیلد های زیر می باشد.
| نام | نوع | توضیحات | | Datetime | string | ارسال تاریخ ، زمان و مختصات جغرافیایی برای Sync بهتر درصورت نیاز
| | Year | int
| سال در تقویم میلادی
| | Month | int | ماه در تقویم میلادی | | Day | int | روز در تقویم میلادی | | Hour | int | ساعت حال حاضر سرور
| | Minute | int | دقیقه
| | Second | int | ثانیه
|
|
| Outputs | Array
| یک آرایه با سلول های مقدار های زیر است که هر خانه شامل Object زیر می شود
نام
| نوع
| توضیحات | messageid
| int
| هر پیامک در سامانه دارای کد انحصاری است که شما میتوانید وضعیت آن را با توجه به کد انحصاری آن استعلام بگیرید
| message
| string
| متنی که ارسال شده است
| status
| int
| وضعیت ارسال
| statustext
| string | متن وضعیت ارسال پیامک
| sender
| string | شماره ای که با آن برای کاربر ارسال شده است
| receptor
| string | شماره ای که به آن پیامک ارسال شده است
| date
| Int
| زمان ارسال شدن پیام
| cost
| Int | هزینه پیامک
|
|
تابع دریافت اطلاعات Cancel
درصورتی که هنوز پیامک از سرور های شرکت ما ارسال نشده باشد، شما میتوانید توسط این تابع ارسال آن را متوقف نمایید، برای این کار باید ورودی ها را به صورت زیر تعریف نمایید.
پارامتر های ورودی
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی |
messageid
| Array | هر
پیامک در سامانه دارای کد انحصاری است که شما میتوانید وضعیت آن را با
توجه به کد انحصاری آن استعلام بگیرید، , این کد پس از اجرای تابع ارسال Send برای شما در خروجی تابع مقدار Outputs قرار خواهد گرفت، تنها این کار کافی است یک آرایه از
نوع string برای این ورودی ارسال کنیدکه شامل کدهای منحصر به فرد پیامک
هایی باشد که ارسال شده است.
|
خروجی ها
نام
| نوع
| توضیحات
|
| Status | string
| کد وضعیت درخوایت به فرمت ریسپانس HTTP
|
| Message | string | پیام وضعیت درخواست
|
| Data | Object
| این مقدار یک آبجکت است که برای دارای فیلد های زیر می باشد.
| نام | نوع | توضیحات | | Datetime | string | ارسال تاریخ ، زمان و مختصات جغرافیایی برای Sync بهتر درصورت نیاز
| | Year | int
| سال در تقویم میلادی
| | Month | int | ماه در تقویم میلادی | | Day | int | روز در تقویم میلادی | | Hour | int | ساعت حال حاضر سرور
| | Minute | int | دقیقه
| | Second | int | ثانیه
|
|
| Outputs | Array
| یک آرایه با سلول های مقدار های زیر است که هر خانه شامل Object زیر می شود
نام
| نوع
| توضیحات | messageid
| int
| هر پیامک در سامانه دارای کد انحصاری است که شما میتوانید وضعیت آن را با توجه به کد انحصاری آن استعلام بگیرید
| message
| string
| متنی که ارسال شده است
| status
| int
| وضعیت ارسال
| statustext
| string | متن وضعیت ارسال پیامک
| sender
| string | شماره ای که با آن برای کاربر ارسال شده است
| receptor
| string | شماره ای که به آن پیامک ارسال شده است
| date
| Int
| زمان ارسال شدن پیام
| cost
| Int | هزینه پیامک
|
|
تابع دریافت اطلاعات Outbox
با تایین بازه های زمانی مورد نیاز میتوانید خروجی پیامکی خود را مشاهده نمایید برای این کار کافی است با فرآخوانی این تابع مقدار ها را به صورت زیر تعریف نمایید.
پارامتر های ورودی
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی |
startdate
| Int | تاریخ شروع بازه زمانی که استعلام آن را میخواهید به صورت مقدار عددی
|
enddate
| Int | تاریخ پایان بازه زمانی که استعلام آن را میخواهید به صورت مقدار عددی |
sender
| string | اگر استعلام خط خاصی را میخواهید شماره آن را اینجا وارد میکنید.
|
خروجی ها
نام
| نوع
| توضیحات
|
| Status | string
| کد وضعیت درخوایت به فرمت ریسپانس HTTP
|
| Message | string | پیام وضعیت درخواست
|
| Data | Object
| این مقدار یک آبجکت است که برای دارای فیلد های زیر می باشد.
| نام | نوع | توضیحات | | Datetime | string | ارسال تاریخ ، زمان و مختصات جغرافیایی برای Sync بهتر درصورت نیاز
| | Year | int
| سال در تقویم میلادی
| | Month | int | ماه در تقویم میلادی | | Day | int | روز در تقویم میلادی | | Hour | int | ساعت حال حاضر سرور
| | Minute | int | دقیقه
| | Second | int | ثانیه
|
|
| Outputs | Array
| یک آرایه با سلول های مقدار های زیر است که هر خانه شامل Object زیر می شود
نام
| نوع
| توضیحات | messageid
| int
| هر پیامک در سامانه دارای کد انحصاری است که شما میتوانید وضعیت آن را با توجه به کد انحصاری آن استعلام بگیرید
| message
| string
| متنی که ارسال شده است
| status
| int
| وضعیت ارسال
| statustext
| string | متن وضعیت ارسال پیامک
| sender
| string | شماره ای که با آن برای کاربر ارسال شده است
| receptor
| string | شماره ای که به آن پیامک ارسال شده است
| date
| Int
| زمان ارسال شدن پیام
| cost
| Int | هزینه پیامک |
|
تابع دریافت اطلاعات Inbox
در صورتی که شما خط اختصاصی داشته باشید و قابلیت دریافت پیامک برای شما فعال باشد میتوانید از این تنظیم استفاده نمایید، به این صورت که تنها کافی است این تابع را با فرمت های خواسته شده فرآخوانی نمایید و محتویات Inbox خود را دریافت نمایید.
پارامتر های ورودی
نام
| نوع
| توضیحات
|
CRMID
| string
| کد منحصر به فردشما در سامانه پشتیبانی |
startdate
| Int | تاریخ شروع بازه زمانی که استعلام آن را میخواهید به صورت مقدار عددی
|
enddate
| Int | تاریخ پایان بازه زمانی که استعلام آن را میخواهید به صورت مقدار عددی |
Receiver
| string | شماره خط اختصاصی شما که میخواهید Inbox آن را مشاهده نمایید.
|
isread
| bool
| در صورتی که این مقدار برابر با True باشد پیام هایی را می آورد که توسط شما خوانده شده است، و در صورتی که False باشد پیام هایی را می آورد که توسط شما خوانده نشده است. |
خروجی ها
نام
| نوع
| توضیحات
|
| Status | string
| کد وضعیت درخوایت به فرمت ریسپانس HTTP
|
| Message | string | پیام وضعیت درخواست
|
| Data | Object
| این مقدار یک آبجکت است که برای دارای فیلد های زیر می باشد.
| نام | نوع | توضیحات | | Datetime | string | ارسال تاریخ ، زمان و مختصات جغرافیایی برای Sync بهتر درصورت نیاز
| | Year | int
| سال در تقویم میلادی
| | Month | int | ماه در تقویم میلادی | | Day | int | روز در تقویم میلادی | | Hour | int | ساعت حال حاضر سرور
| | Minute | int | دقیقه
| | Second | int | ثانیه
|
|
| Outputs | Array
| یک آرایه با سلول های مقدار های زیر است که هر خانه شامل Object زیر می شود
نام
| نوع
| توضیحات | messageid
| int
| هر پیامک در سامانه دارای کد انحصاری است که شما میتوانید وضعیت آن را با توجه به کد انحصاری آن استعلام بگیرید
| message
| string
| متنی که ارسال شده است
| status
| int
| وضعیت ارسال
| statustext
| string | متن وضعیت ارسال پیامک
| sender
| string | شماره ای که با آن برای کاربر ارسال شده است
| receptor
| string | شماره ای که به آن پیامک ارسال شده است
| date
| Int
| زمان ارسال شدن پیام
| cost
| Int | هزینه پیامک |
|
لازم به توضیح است در صورت بروز هرگونه مشکل یا سوال میتوانید از طریق سامانه تیکتی درخواست های خود را با واحد پشتیبانی مطرح نمایید. و واحد پشتیبانی موظف است تا حصول نتیجه در کنار شما باشد.
جدول کدهای خطا مربوط به status ها
کد توضیحات
400 پارامترها ناقص هستن
401 حساب کاربری غیر فعال است
402 عملیات ناموفق بود
403 حساب کاربری معتبر نمی‌باشد. این خطا در صورتی
که کد شناسائی API-Key اشتباه ارسال شود رخ می‌دهد
404 متدی با این نام پیدا نشده است
405 متد فراخوانی Get یا Post اشتباه است
409 سرور قادر به پاسخگوئی نیست بعدا تلاش کنید
411 شماره گیرنده پیام معتبر نمی باشد
412 شماره فرستنده معتبر نمی‌باشد ویا تعداد دریافت
کننده ها بیشتر از 200 می‌باشد .
413 پیام خالی است و یا طول پیام بیش از حد مجاز می‌باشد.حداکثر
طول کل متن پیامک 900 کاراکتر می باشد
414 حجم درخواست بیشتر از حد مجاز است
414 تعداد رکورد ها بیشتر از حد مجاز است.در ارسال
پیامک حداکثر 200 گیرنده در کنترل وضعیت حداکثر 500 شناسه
417 تاریخ ارسال اشتباه است یا تاریخ آن گذشته و یا
به فرمت درست ارسال نشده است
418 اعتبار حساب شما کافی نیست
419 تعداد اعضای آرایه متن و گیرنده و ارسال کننده
هم اندازه نیست .در ارسال پیامک هر فراخوانی 200 رکورد و کنترل وضعیت هر فراخوانی 500
رکورد