راهنمای توسعه دهندگان
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
متد 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>
متد SendGroup : برای ارسال به گروه های دفترچه تماس
آدرس متد : http://api.asiasms.ir:8080/Messages/SendGroup
<Sms>
<SmsText>hi</SmsText>
<PhoneBook>Guid,Guid,....</PhoneBook> <SenderId>6500</SenderId>
.
.
</Sms>
کد های خطا :
لیست کدهای خطا به شرح زیر می باشد
| 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 زمانی که دریافتی وجود نداشته باشد |