واسط موجود بر مبنای متد دسترسی SOAP بر روی پروتکل HTTP و HTTPS طراحی و پیاده سازی شده است که یکی از انواع وب سرویس های نسبتا سنتی برای ارتباط بین نرم افزارها می باشد که از آن در جهت برقراری ارتباط با سرور کاوه نگار برای ارسال و دریافت پیامک استفاده شده است .
لینک مطلق نسخه اول این وب سرویس :
http://api.kavenegar.com/soap/v1.asmx
لینک WSDL :
http://api.kavenegar.com/soap/v1.asmx?WSDL
ساختار کلی متد ها
ساختار کلی متدها به این شکل است که کلیه آنها دارای دو پارامتر با خاصیت ByRef با نام های :
نام
نوع
توضیحات
Status
Integer
حاوی کد حاصل از اجرای دستور میباشد، در صورتی که
200
باشد به معنی اجرای موفق متد است
StatusMessage
String
توضیح مربوط به مقدار
Status است
نکته :
کد مربوط به اجرای دستور فقط در مقدار پارامتر
Status قرار می گیرید و کد وضعیت پروتکل
( http status code )
همواره
200
میباشد.
بنابراین نتیجه اجرای موفق متد را فقط از مقدار پارامتر
Status
که به صورت
by Reference
تعریف شده میتوانید متوجه شوید.
نکته :
پارامتر
StatusMessage
برای راحتی
قرار داده شده است تا در هنگام
Debug
نیازی به مراجعه به بخش خطا ها نداشته باشند و توضیح فارسی مربوط به کد
( Status )
را در مقدار این پارامتر مشاهده نمایند.
خطاهای کلی در اجرای متد ها
کد
توضیحات
402
عملیات ناموفق بود
409
سرور قادر به پاسخگوئی نیست بعدا تلاش کنید
در مواقعی که این خطا ها را دریافت کردید متد را دوباره فراخوانی کنید.
ساختار تائید هویت کاربری در کاوه نگار
برای تائید هویت یا
Authentication
سه راه حل کلی ارئه شده است :
راه حل سنتی با امنیت کمتر در آن نام کاربری و رمز عبور دو پارامتر آغازین متد هستند و در ادامه مابقی پارامترها قرار می گیرند
راه حل نسبتا جدیدی که در آن API-Key یکتای حساب شما پارامتر آغازین هر متد هستند
شناسائی از طریق ارسال نام کاربری و رمز عبور بر روی هدر و قرار گیری آن در خصوصیت
Authentication
کلاس
SOAP
فراخوانی شده
در حال حاضر متناسب با نیاز مشتریان 2 متد اولی در توابع اعلان شده است.
بنابراین هر متد دارای دو Overload میباشد که اولی با عنوان LoginInfo و دیگری با API-Key در انتهای نام توابع قرار داده شده است.
بنابراین هر متد با عنوان در دسترس است , برای مثال متد
SendSimple
با عنوان های :
وجود دارد که در اولی دو پارامتر اولی این متد نام کاربری و رمز عبور بوده و در دومی پارامتر اولی API-Key حساب کاربری شما میباشد.
در صورتی که API-Key خود را نمی دانید میتوانید با ورود به حساب از آدرس :
https://panel.kavenegar.com/
به بخش کاربری مراجعه و نسبت به ایجاد یا تغییر آن اقدام نمائید.
خطاهای مربوط به تائید هویت کاربری
401
حساب کاربری غیرفعال شده است
403
حساب کاربری معتبر نمیباشد. این خطا در زمانی که مشخصات ورود به حساب
(نام کاربری و رمز عبور ) و یا کد شناسائی (API-Key) اشتباه ارسال شود رخ می دهد
ساختار پیام کوتاه
طول پیامک
طول استاندارد یک پیام کوتاه 140 ﺑﺎﻳﺖ که معادل 70 کاراکتر برای یک پیامک فارسی و 140 کاراکتر برای یک پیامک لاتین و 140 بایت برای پیامک باینری میباشد بنابراین هر کاراکتر فارسی معادل 2 بایت محاسبه میشود. این موضوع به دلیل گنجاندن کاراکتر های فارسی در فرمت یونیکد میباشد که با وجود حتی یک کاراکتر فارسی در پیامک باعث میشود تا طول آن بر حسب فرمت یونیکد (هر کاراکتر 2 بایت) محاسبه شده و پیامک فارسی شود (پیامک های فارسی ارزان تر از پیامک های لاتین هستند).
پیامک های چند بخشی
در صورتی که پیامک از طول استاندارد 140 بایت بیشتر شود باید به بخش های 140 بایتی تقسیم شده و سپس به مقصد ارسال شود که البته این کار توسط وب سرویس موجود انجام میشود و نیاز نیست برای این موضوع عملیاتی انجام دهید کافیست کل پیام را در فراخوانی وب سرویس ارسال نمائید. البته به این موضوع باید توجه داشت که به ازای هر بخش از یک پیامک فارسی طولانی، 3 کاراکتر و به ازای هر بخش از کی پیامک لاتین طولانی ،7 کاراکتر از فضای استاندارد متین پیامک به کد UDH اختصاص پیدا میکند.یعنی در واقع هر بخش از پیامک چند قسمتی فارسی حداکثر 67 کاراکتروهربخش ازپیامک چند قسمتی لاتین حداکثر 153 کاراکتررادرخودجای میدهد.
ﺣﺪاﻛﺜﺮ ﻃﻮل پیامک
حداکثر طول کل متن پیامک 900 کاراکتر می باشد. درصورتی که بیشتر از این مقدار ارسال شود مقدار پارامتر Status معادل 413 به معنای "متن پیام خالی است و یا طول آن بیشتر از حد مجاز میباشد" را برگشت میدهد. علاوه بر این موضوع در هر بار فراخوانی متدهای ارسال پیامک میتوانید حداکثر 200 پیامک ارسال کنید. این محدودیت برای حفظ کیفیت در ارسال و سرعت پاسخگوئی قرارداده شده است همچنین در هر بار فراخوانی متدهای کنترل وضعیت Status و انصراف از ارسال پیامک Cancel میتوانید حداکثر 500 شناسه را در ورودی قرار دهید.
خطای مربوط به حداکثر رکورد درخواستی در هر بار فراخوانی
414
حجم درخواست بیشتر از حد مجاز است
در ارسال پیامک هر فراخوانی
200 رکورد و کنترل وضعیت
هر فراخوانی 500 رکورد
توجه :
شما میتوانید با فراخوانی متد ها از طریق ساختار
Multi-Threaded
میزان درخواست همزمان خود را افزایش دهید.
موضوع محدودیت مربوط به تعداد در هر بار فراخوانی
(Per Request)
میباشد.
فرمت داده های ورودی
در طراحی وب سرویس کاوه نگار سعی شده تا جای ممکن نسبت به داده های ورودی حساسیت وجود نداشته باشد در نهایت پارامتر ها با فرمت زیر قابل تشخیص هستند در غیر اینصورت احتمال دریافت کد خطا در داده های ورودی وجود دارد.
در هنگام ارسال درخواست با متد
HTTP GET حتما مقدار پارامتر ها را
URL Encode
نمائید.
فرمت درست خط اختصاصی فرستنده
(این شماره به عنوان مثال قید شده است)
+9810004346
009810004346
10004346
فرمت درست شماره گیرنده
(این شماره به عنوان مثال قید شده است)
خطاهای مربوط به فرمت اشتباه گیرنده و فرستنده و متن پیامک
411
شماره گیرنده پیام معتبر نمی باشد
412
شماره فرستنده معتبر نمیباشد
413
پیام خالی است و یا طول پیام بیش از حد مجاز میباشد
حداکثر طول کل متن پیامک 900 کاراکتر می باشد
414
تعداد رکورد ها بیشتر از حد مجاز است
در ارسال پیامک حداکثر
200
گیرنده در کنترل وضعیت حداکثر
500
شناسه
Sendارسال ساده
ارسال پیامک از یک خط اختصاصی با یک متن برای یک یا چندین گیرنده.
پارامتر های ورودی
نام
نوع
توضیحات
Sender
String
خط اختصاصی ارسال کننده پیامک
Message
String
متن پیامک
Receptor
Array of String
شماره های دریافت کننده پیامک
UnixDate
Long
زمان ارسال پیامک ، در صورتی که مقدار 0 را ارسال کنید پیامک در همان لحظه به صورت خودکار ارسال میشود .
Type
Integer
نحوه نمایش پیامک در موبایل گیرنده (فرمت معمولی مقدار 1) در غیر اینصورت به جدول شماره 3در انتهای سند مراجعه کنید.
مقادیر خروجی
نوع
توضیحات
Array of Long
شناسه پیامک ها (در صورتی که
null
باشد ارسال ناموفق بوده و باید به مقدار پارامتر
Status
مراجعه کنید).
توصیه میشود برای دریافت وضعیت پیامک ها مقادیر خروجی را ذخیره نمائید. درواقع شناسه پیامک همان شناسه رکورد متناظر در پایگاه داده کاوه نگار است.
یادداشت
برای واکشی وضعیت پیامک به متد
GetStatus
مراجعه نمائید
برای دریافت اطلاعات و نحوه کار با فرمت UnixTime به
اینجا
مراجعه نمائید
برای اطلاع از نحوه نمایش پیامک در موبایل گیرنده به جدول شماره 3 مراجعه نمائید
خطاها
417
تاریخ ارسال اشتباه است و فرمت آن صحیح نمی باشد.
418
اعتبار حساب کافی نیست .
SendArrayارسال گروهی
در صورتی می خواهید پیامک های مختلفی از شماره های مختلف ارسال کنید ، این متد کارائی زیادی برای شما دارد . نکته قابل توجه در استفاده از این متد آن است که کلیه پارامتر آرایه بوده و باید طول آنها باهم برابر باشد و حداکثر تعداد گیرندگان در هر بار فراخوانی 200 عدد میباشد.
پارامتر های ورودی
نام
نوع
توضیحات
Sender
Array of String
خط اختصاصی ارسال کننده پیامک
Message
Array of String
متن پیام کوتاه
Receptor
Array of String
شماره های دریافت کننده پیامک
UnixDate
Long
زمان ارسال پیامک ، در صورتی که مقدار 0 را ارسال کنید پیامک در همان لحظه به صورت خودکار ارسال میشود .
Type
Array of Integer
نحوه نمایش پیامک در موبایل گیرنده (فرمت معمولی مقدار 1) در غیر اینصورت به جدول شماره 3 در انتهای سند مراجعه کنید.
مقادیر خروجی
نوع
توضیحات
Array of Long
شناسه پیامک ها (در صورتی که
null باشد ارسال ناموفق بوده و باید به مقدار پارامتر
Status مراجعه کنید) .
توصیه میشود برای دریافت وضعیت پیامک ها مقادیر خروجی را ذخیره نمائید. درواقع شناسه پیامک همان شناسه رکورد متناظر در پایگاه داده کاوه نگار است.
یادداشت
برای دریافت اطلاعات و نحوه کار با فرمت
UnixTime
به
اینجا
مراجعه نمائید
طول آرایه های ورودی باید با هم برابر باشد
برای اطلاع از نحوه نمایش پیامک در موبایل گیرنده به جدول شماره 3 مراجعه نمائید
خطاها
417
تاریخ ارسال اشتباه است و فرمت آن صحیح نمی باشد.
418
اعتبار حساب کافی نیست
419
طول آرایه متن و گیرنده و ارسال کننده هم اندازه نیست
Selectانتخاب پیامک
در صورتی که میخواهید اطلاعات پیامک ارسالی را بازیابی نمائید، میتوانید با
MessageId
و استفاده از این متد اطلاعات رکورد را
دریافت کنید.
در هر بار اجرای این متد میتوانید از وضعیت ۳۰۰۰ پیامک با
خبر شوید.
کافیست شناسه یکتای پیامک ها را از طریق کاراکتر ویرگول
« , »
از هم جدا کنید .
در صورتی که شناسه پیامک
( MessageID )
معتبر نباشد و یا در پایگاه داده ثبت نشده باشد، مقدار
خروجی معادل 100 ( معتبر نبودن شناسه پیامک) میباشد.
تفاوت این متد با متد
Status
در نوع خروجی است، این متد اطلاعات بیشتر همراه خود دارد ولی بهتر است برای کنترل وضعیت پیامک از متد
Status
استفاده کنید زیرا حجم اطلاعات خروجی کمتر و سرعت آن بیشتر است.
برای استفاده از این متد اقدام به تنظیم IP در بخش تنظیمات امنیتی نمایید
خطاها
400
پارامترها ناقص هستند.
407
دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
استفاده از این متد نیاز به تنظیم IP در بخش تنظیمات امنیتی دارد
411
حجم درخواست بیشتر از حد مجاز است ، هر فراخوانی 500 شناسه پیامک
SelectOutBoxلیست ارسال ها
گاهی پیش می آید نیاز داریم فهرست پیامک های ارسال شده را در بازه زمانی مشاهده کنیم،
در این حالت از این متد استفاده کنید. برای این کار کافیست تاریخ شروع و پایان بازه زمانی مورد نظر را به فرمت
UnixTime
ارسال کنید.
برای دریافت اطلاعات و نحوه کار با فرمت
UnixTime
به
اینجا
مراجعه نمائید
طول آرایه های ورودی باید با هم برابر باشد
برای اطلاع از نحوه نمایش پیامک در موبایل گیرنده به جدول شماره 3 مراجعه نمائید
برای استفاده از این متد اقدام به تنظیم IP در بخش تنظیمات امنیتی نمایید
خطاها
407
دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
استفاده از این متد نیاز به تنظیم IP در بخش تنظیمات امنیتی دارد
417
تاریخ ارسال اشتباه است و فرمت آن صحیح نمی باشد.
418
اعتبار حساب کافی نیست .
419
طول آرایه متن و گیرنده و ارسال کننده هم اندازه نیست .
SelectLatestلیست آخرین ارسال ها
برای دریافت آخرین پیامک های ارسال شده میتوانید از این متد استفاده نمائید . با ارسال مقدار پارامتر
Pagesize
میتوانید تعداد رکورد های مورد نیاز را مشخص نمائید .
پارامتر های ورودی
نام
نوع
توضیحات
pagesize
Long
تعداد آخرین رکورد های مورد نیاز (حداکثر 500 رکورد)
در صورتی که شناسه پیامک
( MessageID )
معتبر نباشد و یا در پایگاه داده ثبت نشده باشد، مقدار
خروجی معادل 100 ( معتبر نبودن شناسه پیامک) میباشد.
در هر بار فراخوانی این متد میتوانید حداکثر 200 شناسه پیامک ارسال کنید
Cancelانصراف از ارسال
برای انصراف از ارسال پیام های زمانبندی شده میتوانید از این متد استفاده نمائید . این متد بعد از کنترل معتبر بودن شناسه پیامک در صورتی که زمانبندی شده باشد آن را از صف خارج کرده و مقدار 13 معادل "ارسال لغو شد " را در خروجی قرار می دهد. لغو ارسال پیامک فقط به شرطی امکان پذیر است که پیامک مورد نظر برای تاریخ مشخصی زمانبندی شده باشد. در غیر اینصورت وضعیت عادی پیامک را در خروجی قرار می دهد.
در صورتی که شناسه پیامک
( MessageID )
معتبر نباشد و یا در پایگاه داده ثبت نشده باشد، مقدار
خروجی معادل 100 ( معتبر نبودن شناسه پیامک) میباشد.
در هر بار فراخوانی این متد میتوانید حداکثر 200 شناسه پیامک ارسال کنید
در صورتی که هیچ پیامک دریافت شده ای نداشته باشید خروجی
null
خواهد بود
Receiveدریافت پیامک
واکشی پیامک های دریافتی از خط های اختصاصی توسط این متد انجام میشود
.با هر بار فراخوانی این متد پیامک هایی که در خروجی برگشت داده می شوند وضعیت "خوانده شده" معادل 1 را به خود می گیرند.
به این معنا که شما پیامک ر ا خوانده اید.
بنابراین برای واکشی پیامک های جدید همیشه مقدار 0 را در پارامتر
isRead
قرار دهید.
پارامتر های ورودی
نام
نوع
توضیحات
LineNumber
String
خط اختصاصی مورد نظر
isRead
Byte
وضعیت پیامک ( که خوانده نشده 0 و خوانده شده 1 میباشد )
مقادیر خروجی
خروجی آرایه ای از شئ زیر خواهد بود :
نام
نوع
توضیحات
MessageID
Array Of Long
شناسه پیامک مورد نظر که از جنس آرایه می باشد.
Message
String
متن پیام دریافتی
Sender
String
شماره ارسال کننده پیامک
Receptor
String
شماره گیرنده پیامک ( معادل پارامتر
LineNumber
است )
Date
Long
زمان دریافت پیامک به فرمت
UnixTime
نکات
در هر بار فراخوانی این متد 200 پیامک دریافت شده در خروجی قرار می گیرد ، برای ادامه کافیست یکبار این متد را فراخوانی نمائید .بنابراین مادامی که تعداد اجزاء شیء خروجی 200 است باید متد دوباره فراخوانی شود تا پیامک های جدید را به طور کامل واکشی نمائید.
در صورتی که هیچ پیامک دریافت شده ای نداشته باشید خروجی null خواهد بود.
خطاها
411
دریافت کننده نامعتبر میباشد .به معنای اینکه مالکیت خط اختصاصی برای شما نیست یا فرمت ورودی خط اختصاصی نادرست است.
دریافت اعتبارRemainCredit
دریافت اعتبار باقی مانده حساب مورد نظر ، که در آن کافیست اطلاعات اولیه
(LoginInfo
و یا
API Key )
را ارسال کنید.
مقادیر خروجی
نوع
توضیحات
Long
معادل ریالی اعتبار باقی مانده حساب مورد نظر میباشد
جدول ۱ - کدهای برگشتی
کد
توضیحات
200
درخواست تایید شد
400
پارامترها ناقص هستند
401
حساب کاربری غیرفعال شده است
402
عملیات ناموفق بود
403
کد شناسائی API-Key معتبر نمیباشد
404
متد نامشخص است
405
متد Get/Post اشتباه است
406
پارامترهای اجباری خالی ارسال شده اند
407
دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
برای استفاده از متدهای Select، SelectOutbox و LatestOutBox و یا ارسال با خط بین المللی نیاز به تنظیم IP در بخش تنظیمات امنیتی می باشد
409
سرور قادر به پاسخگوئی نیست بعدا تلاش کنید
411
دریافت کننده نامعتبر است
412
ارسال کننده نامعتبر است
413
پیام خالی است و یا طول پیام بیش از حد مجاز میباشد. حداکثر طول کل متن پیامک 900 کاراکتر می باشد
414
حجم درخواست بیشتر از حد مجاز است ،ارسال پیامک :هر فراخوانی حداکثر 200 رکورد و کنترل وضعیت :هر فراخوانی 500 رکورد
415
اندیس شروع بزرگ تر از کل تعداد شماره های مورد نظر است
416
IP سرویس مبدا با تنظیمات مطابقت ندارد
417
تاریخ ارسال اشتباه است و فرمت آن صحیح نمی باشد.
418
اعتبار شما کافی نمیباشد
419
طول آرایه متن و گیرنده و فرستنده هم اندازه نیست
420
استفاده از لینک در متن پیام برای شما محدود شده است
422
داده ها به دلیل وجود کاراکتر نامناسب قابل پردازش نیست
424
الگوی مورد نظر پیدا نشد
426
استفاده از این متد نیازمند سرویس پیشرفته میباشد
427
استفاده از این خط نیازمند ایجاد سطح دسترسی می باشد
428
ارسال کد از طریق تماس تلفنی امکان پذیر نیست
429
IP محدود شده است
431
ساختار کد صحیح نمیباشد
432
پارامتر کد در متن پیام پیدا نشد
451
فراخوانی بیش از حد در بازه زمانی مشخص IP محدود شده
501
فقط امکان ارسال پیام تست به شماره صاحب حساب کاربری وجود دارد
جدول ۲ - وضعیت پیامک ها
مقدار
توضیحات
1
در صف ارسال قرار دارد
2
زمان بندی شده (ارسال در تاریخ معین)
4
ارسال شده به مخابرات
5
ارسال شده به مخابرات (همانند وضعیت 4)
6
خطا در ارسال پیام که توسط سر شماره پیش می آید و به معنی عدم رسیدن پیامک میباشد (Failed)
10
رسیده به گیرنده (Delivered)
11
نرسیده به گیرنده ، این وضعیت به دلایلی از جمله خاموش یا خارج از دسترس بودن گیرنده اتفاق می افتد (Undelivered)
13
ارسال پیام از سمت کاربر لغو شده یا در ارسال آن مشکلی پیش آمده که هزینه آن به حساب برگشت داده میشود
14
بلاک شده است، عدم تمایل گیرنده به دریافت پیامک از خطوط تبلیغاتی که هزینه آن به حساب برگشت داده میشود
100
شناسه پیامک نامعتبر است ( به این معنی که شناسه پیام در پایگاه داده کاوه نگار ثبت نشده است یا متعلق به شما نمیباشد)
جدول ۳ - نوع نمایش پیام
کد
توضیحات
0
پیامک بصورت مستقیم برروی صفحه موبایل شخص گیرنده ظاهرمیشود.این حالت پیامک درموبایل یا سیم کارت شخص گیرنده بصورت اتوماتیک ذخیره نمیشود و با خروج از آن حذف میشود(پیامک خبری)
1
در حافظه ﻣﻮﺑﺎﻳﻞ ﺷﺨﺺ گیرنده ذخیره میشود. (پیامک عادی) در صورتی که پارامتر مربوطه خالی ارسال شود به صورت پیش فرض پیامک مورد نظر با این نوع ارسال میشود
2
پیامک برروی حافظه سیمکارت گوشی گیرنده ذخیره میشود
3
درصورتی که موبایل شخص گیرنده دارای یک نرم افزار کابردی خاص برای ذخیره پیامک باشد و یا به یک نرم افزار کاربردی خاص برروی یک کامپیوترمتصل باشد، پیامک دریافتی درآن نرم افزارها ذخیره میشود