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

AKAM SMS Restful API

شماره بازنگری تاریخ بازنگری شرح بازنگری ویرایش گر
01 20/03/1394 تدوین اولین ویرایش مجید رمضانی
02 31/06/1394 ارسال از طریق متد GET مجید رمضانی
03 25/08/1394 دریافت پیامک های ورودی مجید رمضانی
04 1395/03/18 مدیریت دفترچه تلفن مجید رمضانی
05 15/06/1397 دریافت پیامک های ورودی مابین دوتاریخ مشخص مجید رمضانی

شروع به کار :

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

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

مفاهیم پایه :

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

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

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

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

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

آدرس متد :  http://api.asiasms.ir: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
نام پارامتر نوع پارامتر اجباری/اختیاری توضیح
SenderId string اختیاری شماره فرستنده
SmsText string اجباری متن پیامک
Receivers string اجباری شماره گیرندگان پیامک با جداکننده کاما
CheckId Guid اختیاری شناسه درنظر گرفته شده در سیستم کاربر
udh string اختیاری سرآیند تعریف شده توسط کاربر
isflash bool اختیاری نمایش بصورت فلش
ﺗﻮﺿﻴﺢ : پارامترهای  username و  password از روی  headerارسالی خوانده می شود.
خروجی
نام پارامتر نوع پارامتر توضیح
IsSuccessful bool نتیجه درخواست
StatusCode int کد وضعیت
BatchId Guid شناسه ثبت شده در سیستم پیام دهی شرکت

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

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

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

http://api.asiasms.ir:8080/Messages/SendViaURL

نام متد SendViaURL
نام پارامتر نوع پارامتر اجباری/اختیاری توضیح
Username string اجباری نام کاربری
Password string اجباری کلمه عبور
SenderId string اختیاری شماره فرستنده
SmsText String اجباری متن پیامک
Receivers String اجباری شماره گیرندگان پیامک با جداکننده کاما
CheckId Guid اختیاری شناسه درنظر گرفته شده در سیستم کاربر
udh string اختیاری سرآیند تعریف شده توسط کاربر
isflash bool اختیاری نمایش بصورت فلش
خروجی
نام پارامتر نوع پارامتر توضیح
IsSuccessful bool نتیجه درخواست
StatusCode int کد وضعیت
BatchId Guid شناسه ثبت شده در سیستم پیام دهی شرکت

به طور مثال:


?http://api.asiasms.ir:8080/Messages/SendViaURL
Username=username&password=password
&SenderId=6500&SmsText=salam&Receivers 989111111111,989111111111

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

آدرس متد :  http://api.asiasms.ir: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
نام پارامتر نوع پارامتر اجباری/اختیاری توضیح
SmsText string اجباری متن پیامک
CheckId Guid اختیاری شناسه درنظر گرفته شده در سیستم کاربر
ServiceId string اجباری شناسه سرویس ارزش افزوده
GroupId int اجباری کد گروه ارزش افزوده
Receiver string اختیاری شماره گیرنده (در صورت خالی بوده کل گروه در نظر گرفته میشود)
ﺗﻮﺿﻴﺢ : پارامترهای  username و  password از روی  headerارسالی خوانده می شود.
خروجی
نام پارامتر نوع پارامتر توضیح
IsSuccessful bool نتیجه درخواست
StatusCode int کد وضعیت
BatchId Guid شناسه ثبت شده در سیستم پیامدهی شرکت

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

<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://api.asiasms.ir:8080/Receive/GetMessage

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

ورودی XML  :

<ReceiveInfo>

<Date>20150812</Date>
<Receiver>30005086</Receiver >
</ReceiveInfo>
نام متد GetMessage
نام پارامتر نوع پارامتر اجباری/اختیاری توضیح
Date string اجباری تاریخ موردنظر جهت دریافت پیامک های ورودی می باشد. تاریخ شامل تاریخ میلادی بدون هیچگونه کاراکتر جداکننده ای میباشد بطور مثال 20150812
Receiver string اختیاری شماره خط
خروجی
نام پارامتر نوع پارامتر توضیح
IsSuccessful bool نتیجه درخواست
StatusCode int کد وضعیت
ReceivedMessages Array آرایه ای از آبجکت Sms

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

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

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

Text  : متن پیام

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

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

آدرس متد :  http://api.asiasms.ir:8080/Receive/GetReceivedMessages

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

ورودی XML  :

<ReceiveInfo>

<BeginDate>2015-08-12</BeginDate>
<EndDate>2015-09-12</EndDate>
<Receiver>30004630</Receiver >
</ReceiveInfo>
نام متد GetMessage
نام پارامتر نوع پارامتر اجباری/اختیاری توضیح
BeginDate Date اجباری تاریخ شروع جهت دریافت پیامک های ورودی می باشد. تاریخ شامل تاریخ میلادی
EndDate Date اجباری تاریخ پایان جهت دریافت پیامک های ورودی می باشد. تاریخ شامل تاریخ میلادی
Receiver string اختیاری شماره خط
خروجی
نام پارامتر نوع پارامتر توضیح
IsSuccessful bool نتیجه درخواست
StatusCode int کد وضعیت
ReceivedMessages Array آرایه ای از آبجکت Sms

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

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

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

Text  : متن پیام

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

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

آدرس متد :  http://api.asiasms.ir: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
نام پارامتر نوع پارامتر اجباری/اختیاری توضیح
PhoneBookGuid Guid اجباری Guid گروه دفترچه تماس
خروجی
نام پارامتر نوع پارامتر توضیح
IsSuccessful bool نتیجه درخواست
StatusCode int کد وضعیت
PhoneBooks Array آرایه ای از آبجکت PhoneBook

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

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

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

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

آدرس متد :  http://api.asiasms.ir: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
نام پارامتر نوع پارامتر اجباری/اختیاری توضیح
Name string اجباری نام گروه
خروجی
نام پارامتر نوع پارامتر توضیح
IsSuccessful bool نتیجه درخواست
StatusCode int کد وضعیت
PhoneBooks Array آرایه ای از آبجکت PhoneBook که تنها شامل گروه ثبت شده می باشد

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

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

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

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

آدرس متد :  http://api.asiasms.ir:8080/PhoneBook/RemoveGroup

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

ورودی XML  :

<PhoneBookInfo>

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

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

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

آدرس متد :  http://api.asiasms.ir: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://api.asiasms.ir:8080/PhoneBook/UnSubscribe

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

ورودی XML  :

<PhoneBookInfo>

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

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

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

آدرس متد :  http://api.asiasms.ir:8080/PhoneBook/GetPagedNumbers

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

ورودی XML  :

<UserCredit>

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

کد های خطا :

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

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

 

ورود / ثبت نام