راهنمای توسعه دهندگان

AKAM SMS Restful API

شماره بازنگریتاریخ بازنگریشرح بازنگریویرایش گر
0120/03/1394تدوین اولین ویرایشمجید رمضانی
0231/06/1394ارسال از طریق متد GETمجید رمضانی
0325/08/1394دریافت پیامک های ورودیمجید رمضانی
041395/03/18مدیریت دفترچه تلفنمجید رمضانی
0515/06/1397دریافت پیامک های ورودی مابین دوتاریخ مشخصمجید رمضانی

شروع به کار :

ﻣﺴﺘﻨﺪ ﺣﺎﺿﺮ جهت توسعه دهندگانی طراحی شده است که قصد ارسال و دریافت پیامک در نرم افزارهای خود، از طریق ﺳﻴﺴﺘﻤﻬﺎﻱ ﭘﻴﺎﻡ ﺩﻫﻲ آکام را دارند. در این راهنما کلیه متدها و دستورات موردنیاز توسعه دهندگان شرح داده شده است.

جهت استفاده از متدهای وب سرویس، ابتدا لازم است از طریق عقد قرارداد با واحد سیستم های پیام دهی شرکت، حساب خود را فعال نمایید. پس از فعالسازی، نام کاربری (username) و کلمه عبور (password)  در اختیار شما قرار خواهد گرفت که جهت استفاده در نرم افزار شخصی و نیز برای وارد شدن به صفحه اختصاصی کاربر بر روی سایت مورد استفاده قرار می گیرد. لازم بذکر است در کلیه متدها از آدرس وب سایت یا IP  استفاده میشود لذا در کلیه متدها می بایست [IP]  را با اطلاعات صحیح جایگزین نمایید.

مفاهیم پایه :

  • متن هر پیامک فارسی شامل 70 کاراکتر و پیامک انگلیسی 160 کاراکتر است. اگر تعداد کاراکتر ها بیش از تعداد مذکور باشد پیامک به 2 پیامک یا بیشتر تقسیم می شود.

در هنگام مقدار دهی پارامترها به نکات زیر توجه فرمایید:

  • تمام پارامترها Case Sensitive هستند.
  • شماره همراه باید به فرمت  989********* باشد .
  • شماره فرستنده بدون هیچگونه پیشوندی باشد.
  • در ارسال پیامک، پیامک ها به صورت بسته های 200 تایی ارسال می شوند. به این صورت که میتوان در هر درخواست 200 پیامک ارسال کرد. درخواست های 200 پیامکی بنا به اینکه متن پیامک چند پارتی است تغییر میکند، به این صورت که 200 تقسیم بر تعداد پارت های پیامک می شود و تعداد شماره ها در هر درخواست بدست می آید سپس تعداد کل شماره هایی که پیامک به آنها باید ارسال شود بر تعداد شماره های هر درخواست تقسیم میشود و تعداد درخواست ها بدست می آید. برای مثال اگر متن پیامک 2 پارت باشد، 200 تقسیم بر 2 می شود و به 100 شماره میتوان در هر درخواست پیامک را فرستاد. سپس تعداد کل شماره ها بر تعداد شماره ها(برای مثال 1000) بر 100 تقسیم می شود و تعداد درخواست ها بدست می آید. اگر تعداد شماره ها بیشتر از تعداد قابل ارسال باشد با کد خطای 9 مواجه خواهید شد.
  • جهت استفاده از متد ها باید آی پی های مجاز در پنل کاربری ست شود.

متدها و پارامترها :

متد send  : برای ارسال پیامک

آدرس متد :  http://[IP]:8080/Messages/Send

در متد موردنظر درخواست در قالب XML  و یا JSON  و از طریق متد POST   ارسال شود. در ادامه نمونه ای از ارسال به همراه شرح هر کدام از ورودی ها و همچنین خروجی دریافتی از سیستم ذکر گردیده است.

ورودی XML  :

<Sms>
<CheckId>C63DEE7C-7CD9-453F-8B58-357526D8A824 </CheckId>
 <SmsText>hi</SmsText>
<Receivers>98912xxxxxxx,98913xxxxxxx,… </Receivers>
<SenderId>6500</SenderId>
<IsFlash>true</IsFlash>
<UDH></UDH>
</Sms>

ورودی JSON  :

{"SmsText":"salam", "Receivers":"98913xxxxxxx,98912xxxxxxx,…", "SenderId":"6500",IsUnicode:true,IsFlash:false,UDH:" "”CheckId”:””,}

نام متدSend
نام پارامترنوع پارامتراجباری/اختیاریتوضیح
SenderIdstringاختیاریشماره فرستنده
SmsTextstringاجباریمتن پیامک
Receiversstringاجباریشماره گیرندگان پیامک با جداکننده کاما
CheckIdGuidاختیاریشناسه درنظر گرفته شده در سیستم کاربر
udhstringاختیاریسرآیند تعریف شده توسط کاربر
isflashboolاختیارینمایش بصورت فلش
ﺗﻮﺿﻴﺢ : پارامترهای  username و  password از روی  headerارسالی خوانده می شود.
خروجی
نام پارامترنوع پارامترتوضیح
IsSuccessfulboolنتیجه درخواست
StatusCodeintکد وضعیت
BatchIdGuidشناسه ثبت شده در سیستم پیام دهی شرکت

• در صورتی که پارامتر SenderId خالی باشد ارسال شما از طریق شماره پیش فرضی که برروی حساب کاربری تعریف شده است انجام میشود.

ارسال از طریق URL

در متد موردنظر پارامترها از طریق متد GET   به آدرس زیر ارسال شود.

http://[IP]:8080/Messages/SendViaURL

نام متدSendViaURL
نام پارامترنوع پارامتراجباری/اختیاریتوضیح
Usernamestringاجبارینام کاربری
Passwordstringاجباریکلمه عبور
SenderIdstringاختیاریشماره فرستنده
SmsTextStringاجباریمتن پیامک
ReceiversStringاجباریشماره گیرندگان پیامک با جداکننده کاما
CheckIdGuidاختیاریشناسه درنظر گرفته شده در سیستم کاربر
udhstringاختیاریسرآیند تعریف شده توسط کاربر
isflashboolاختیارینمایش بصورت فلش
خروجی
نام پارامترنوع پارامترتوضیح
IsSuccessfulboolنتیجه درخواست
StatusCodeintکد وضعیت
BatchIdGuidشناسه ثبت شده در سیستم پیام دهی شرکت

به طور مثال:


http://[IP]:8080/Messages/SendViaURL?Username=username&password=password&SenderId=6500&SmsText=salam&Receivers=
989111111111,989111111111

متد send  : برای ارسال پیامک ارزش افزوده

آدرس متد :  http://[IP]:8080/VASMessages/Send

در متد موردنظر درخواست از طریق متد POST   ارسال شود. در ادامه نمونه ای از ارسال به همراه شرح هر کدام از ورودی ها و همچنین خروجی دریافتی از سیستم ذکر گردیده است.

ورودی XML  :


<VAS>
<CheckId>C63DEE7C-7CD9-453F-8B58-357526D8A824</CheckId>
     <ServiceId>1234</ServiceId>
     <SmsText>salam</SmsText>
     <Receiver>[9891********]</Receiver>
     <GroupId>1100</GroupId>
</VAS>
نام متدSend
نام پارامترنوع پارامتراجباری/اختیاریتوضیح
SmsTextstringاجباریمتن پیامک
CheckIdGuidاختیاریشناسه درنظر گرفته شده در سیستم کاربر
ServiceIdstringاجباریشناسه سرویس ارزش افزوده
GroupIdintاجباریکد گروه ارزش افزوده
Receiverstringاختیاریشماره گیرنده (در صورت خالی بوده کل گروه در نظر گرفته میشود)
ﺗﻮﺿﻴﺢ : پارامترهای  username و  password از روی  headerارسالی خوانده می شود.
خروجی
نام پارامترنوع پارامترتوضیح
IsSuccessfulboolنتیجه درخواست
StatusCodeintکد وضعیت
BatchIdGuidشناسه ثبت شده در سیستم پیامدهی شرکت

در صورتی که عملیات با موفقیت انجام شود خروجی بشکل زیر خواهد بود.

<SendSms>
<IsSuccessful>true</IsSuccessful>
<StatusCode>0</StatusCode>
<BatchId>4cbac7e3-5b24-489c-96cf-057639e87c01</BatchId>
</SendSms>

پارامتر IsSuccessful : نتیجه عملیات را اعلام میکند در صورتی که با موفقیت انجام شده باشد True و در غیر اینصورت False برگردانده می شود.

پارامتر StatusCode : در صورتی که عملیات با شکست مواجه شود کد خطا در این پارامتر در دسترس خواهد بود.

لیست کد خطاها در انتهای مستندات قرار دارد.

پارامتر BatchId  : در صورتی که عملیات باموفقیت انجام شود شناسه درخواست شما بازگشت داده میشود.

در صورتی که عملیات با شکست مواجه شود خروجی به شکل زیر خواهد بود.

<ResponseMessage>
 <IsSuccessful>false</IsSuccessful>
 <StatusCode>7</StatusCode>
  <Message>حداقل طول گیرندگان 12 کاراکتر میباشد.</Message>
  <StackTrace>حداقل طول گیرندگان 12 کاراکتر میباشد.</StackTrace>
</ResponseMessage>

لازم به ذکر است فرمت صحیح گیرنده به صورت 98913xxxxxxx  می باشد.

متد GetMessage: دریافت پیامک های ورودی

آدرس متد :  http://[IP]:8080/Receive/GetMessage

در متد موردنظر درخواست از طریق متد POST   ارسال شود. در ادامه نمونه ای از ارسال به همراه شرح هر کدام از ورودی ها و همچنین خروجی دریافتی از سیستم ذکر گردیده است.

ورودی XML  :

<ReceiveInfo>
<Date>20150812</Date>
     <Receiver>30005086</Receiver >
</ReceiveInfo>
نام متدGetMessage
نام پارامترنوع پارامتراجباری/اختیاریتوضیح
Datestringاجباریتاریخ موردنظر جهت دریافت پیامک های ورودی می باشد. تاریخ شامل تاریخ میلادی بدون هیچگونه کاراکتر جداکننده ای میباشد بطور مثال 20150812
Receiverstringاختیاریشماره خط
خروجی
نام پارامترنوع پارامترتوضیح
IsSuccessfulboolنتیجه درخواست
StatusCodeintکد وضعیت
ReceivedMessagesArrayآرایه ای از آبجکت Sms

کلاس Sms شامل پارامترهای زیر می باشد:

From  : شماره فرستنده پیام بطور مثل 989131112233

To : شماره گیرنده که همان شماره خط می باشد.

Text  : متن پیام

ReceiveDateTime : زمان دقیق دریافت پیامک

متد GetReceivedMessages : دریافت پیامک های ورودی مابین دو تاریخ مشخص

آدرس متد :  http://[IP]:8080/Receive/GetReceivedMessages

در متد موردنظر درخواست از طریق متد POST   ارسال شود. در ادامه نمونه ای از ارسال به همراه شرح هر کدام از ورودی ها و همچنین خروجی دریافتی از سیستم ذکر گردیده است.

ورودی XML  :

<ReceiveInfo>
<BeginDate>2015-08-12</BeginDate>
<EndDate>2015-09-12</EndDate>
     <Receiver>30004630</Receiver >
</ReceiveInfo>
نام متدGetMessage
نام پارامترنوع پارامتراجباری/اختیاریتوضیح
BeginDateDateاجباریتاریخ شروع جهت دریافت پیامک های ورودی می باشد. تاریخ شامل تاریخ میلادی
EndDateDateاجباریتاریخ پایان جهت دریافت پیامک های ورودی می باشد. تاریخ شامل تاریخ میلادی
Receiverstringاختیاریشماره خط
خروجی
نام پارامترنوع پارامترتوضیح
IsSuccessfulboolنتیجه درخواست
StatusCodeintکد وضعیت
ReceivedMessagesArrayآرایه ای از آبجکت Sms

کلاس Sms شامل پارامترهای زیر می باشد:

From  : شماره فرستنده پیام بطور مثل 989131112233

To : شماره گیرنده که همان شماره خط می باشد.

Text  : متن پیام

ReceiveDateTime : زمان دقیق دریافت پیامک

متد GetPhoneBook : دریافت دفترچه تماس

آدرس متد :  http://[IP]:8080/PhoneBook/GetPhoneBook

در متد موردنظر درخواست از طریق متد POST   ارسال شود. در ادامه نمونه ای از ارسال به همراه شرح هر کدام از ورودی ها و همچنین خروجی دریافتی از سیستم ذکر گردیده است.

ورودی XML  :

<PhoneBookInfo>
<PhoneBookGuid>[PhoneBook Guid]</PhoneBookGuid>
</PhoneBookInfo>

در درخواست جهت دریافت لیست گروه های دفترچه تماس می بایست مقدار guid  مربوط به گروه دفترچه تماس لحاظ شود، در صورتی که این مقدار تعیین نشود و با مقدار empty  ارسال گردد لیست کلیه گروه ها در اختیار شما قرار خواهد گرفت.

خروجی XML

<ResponseMessage>
 <IsSuccessful>true</IsSuccessful>
 <StatusCode>0</StatusCode>
  <PhoneBooks>
	<PhoneBook>
		<PhoneBookGuid>[Guid]</PhoneBookGuid>
		<Name>[PhoneBook Name]</Name>
</PhoneBook>
  </PhoneBooks>
</ResponseMessage>
نام متدAddGroup
نام پارامترنوع پارامتراجباری/اختیاریتوضیح
PhoneBookGuidGuidاجباریGuid گروه دفترچه تماس
خروجی
نام پارامترنوع پارامترتوضیح
IsSuccessfulboolنتیجه درخواست
StatusCodeintکد وضعیت
PhoneBooksArrayآرایه ای از آبجکت PhoneBook

کلاس PhoneBook شامل پارامترهای زیر می باشد:

PhoneBookGuid : شناسه گروه ثبت شده.

Name : نام گروه ثبت شده.

متد AddGroup : افزودن گروه  به دفترچه تماس

آدرس متد :  http://[IP]:8080/PhoneBook/AddGroup

در متد موردنظر درخواست در قالب  xml و یا JSON  و از طریق متد POST  ارسال شود.

ورودی XML  :

<PhoneBookInfo>
<Name>[PhoneBook Name]</Name>
<PhoneBookInfo/>

خروجی XML :

<ResponseMessage>
 <IsSuccessful>true</IsSuccessful>
 <StatusCode>0</StatusCode>
  <PhoneBooks>
	<PhoneBook>
		<PhoneBookGuid>[Guid]</PhoneBookGuid>
		<Name>[PhoneBook Name]</Name>
</PhoneBook>
  </PhoneBooks>
</ResponseMessage>
نام متدAddGroup
نام پارامترنوع پارامتراجباری/اختیاریتوضیح
Namestringاجبارینام گروه
خروجی
نام پارامترنوع پارامترتوضیح
IsSuccessfulboolنتیجه درخواست
StatusCodeintکد وضعیت
PhoneBooksArrayآرایه ای از آبجکت PhoneBook که تنها شامل گروه ثبت شده می باشد

کلاس PhoneBook شامل پارامترهای زیر می باشد:

PhoneBookGuid : شناسه گروه ثبت شده.

Name : نام گروه ثبت شده.

متد RemoveGroup : حذف گروه دفترچه تماس

آدرس متد :  http://[IP]:8080/PhoneBook/RemoveGroup

در متد موردنظر درخواست در قالب  xml و یا JSON  و از طریق متد POST  ارسال شود.

ورودی XML  :

<PhoneBookInfo>
<PhoneBookGuid>[PhoneBook Guid]</PhoneBookGuid>
</PhoneBookInfo>

جهت حذف گروه میبایست guid گروه موردنظر در در قالبت xml  به فرمت بالا ارسال شود.

متد Register  : ثبت شماره در گروه دفترچه تماس

آدرس متد :  http://[IP]:8080/PhoneBook/Register

در متد موردنظر درخواست در قالب  xml و یا JSON  و از طریق متد POST  ارسال شود.

ورودی XML  :

<PhoneBookInfo>
<PhoneBookGuid>[PhoneBook Guid]</PhoneBookGuid>
<Numbers>
<Number>
<FirstName>[Ali]</FirstName>
<LastName>[Ahmadi]</LastName>
<BirthDate>[2016-06-06]</BirthDate>
<Telephone>03131111111</Telephone>
<Mobile>9891xxxxxxxx</Mobile>
<FaxNumber>021XXXXXX</FaxNumber>
<Job>[job]</Job>
<Address>[Tehran]</Address>
<ZipCode>8179</ZipCode>
<Email>[youremail]</Email>
<Gender>[1/2]</Gender>
<ZoneGuid>[Guid of zone]</ZoneGuid>
</Number>
…
</Numbers>
</PhoneBookInfo>

حداکثر تعداد شماره در هر بار فراخوانی متد مذکور 100 عدد می باشد.

فیلد Gender  مربوط به جنسیت مخاطب می باشد برای جنسیت مذکر عدد 1 و مونث عدد 2 لحاظ می شود.

درصورتی که لیست شماره ها خالی باشد با خطا مواجه خواهید شد.

متد UnSubscribe : حذف شماره از گروه دفترچه تماس

آدرس متد :  http://[IP]:8080/PhoneBook/UnSubscribe

در متد موردنظر درخواست در قالب  xml و یا JSON  و از طریق متد POST  ارسال شود.

ورودی XML  :

<PhoneBookInfo>
<PhoneBookGuid>[PhoneBook Guid]</PhoneBookGuid>
<Numbers>
<Number>
<Mobile>9891xxxxxxxx</Mobile>
</Number>
…
</Numbers>
</PhoneBookInfo>

متد GetPagedNumbers :  دریافت شماره های گروه دفترچه تماس

متد GetCredit  : دریافت اعتبار

آدرس متد :  http://[IP]:8080/PhoneBook/GetPagedNumbers

در متد موردنظر درخواست در قالب  xml و یا JSON  و از طریق متد POST  ارسال شود.

ورودی XML  :

<UserCredit>
<IsSuccessful>false</IsSuccessful>
<StatusCode>0</StatusCode>
<Credit>9954975744.84</Credit>
</UserCredit>

کد های خطا :

لیست کدهای خطا به شرح زیر می باشد

StatusCode
کد خطاعنوانشرحتوضیحات
0Noneبدون خطادر صورتی که عملیات با موفقیت انجام شود این مقدار در statuscode  قرار میگیرد.
1AccountIsInactiveحساب غیرفعال می باشد 
2AccountIsExpiredحساب منقضی شده است 
3AccountIsInvalidحساب نامعتبر است 
3BadRequestدرخواست نامعتبر میباشد 
4InternalServerErrorخطای سرور 
5ReceiversIsEmptyلیست گیرندگان خالی می باشدلازم بذکر است فرمت صحیح گیرنده به صورت 98913xxxxxxx  می باشد
6SenderIsInvalidفرستنده نامعتبر استشماره فرستنده نامعتبر یا خالی می باشد
7ValidationNotValidاطلاعات ورودی صحیح نمی باشدخطاهای موجود بر روی پارامترها
8IPInvalidآی پی نامعتبر می باشد 
9ReceiverCountNotValidشماره گیرندگان نامعتبر می باشدتعداد گیرندگان باید با طول پیامک همخوانی داشته باشد حداکثر 200 پیامک
10ServiceIdIsInvalidشماره فرستنده نامعتبر است 
11ReceiverIsInvalidشماره گیرنده نامعتبر است 
12ReceiveSmsIsEmptyبدون خطادر متد GetMessage زمانی که دریافتی وجود نداشته باشد

ورود / ثبت نام