وب سرویس سامانه پیامکی  

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

 شروع به کار :

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

 در این راهنما کلیه متدها و دستورات موردنیاز توسعه دهندگان شرح داده شده است.

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

 پس از فعالسازی، نام کاربری (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  ارسال شود.

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

                   <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”:"",
              }            

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

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

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

• پارامترهای خروجی متد SendViaURL

به طور مثال:

  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:

پارامترهای خروجی متد GetMessage:

کلاس 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>

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

پارامترهای خروجی متد GetReceivedMessages:

متد 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>

پارامتر ورودی متد GetPhoneBook:

پارامترهای خروجی متد GetPhoneBook:

متد 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:

پارامترهای خروجی متد AddGroup:

متد 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

ورودی XML:

  <Sms>
   <SmsText>hi</SmsText>
   <PhoneBook>Guid,Guid,....</PhoneBook>    
   <SenderId>6500</SenderId> 
  .
  . 
  </Sms>

کدهای خطا