وب سرویس USSD

shape
shape
shape
shape
shape
shape
shape
shape
USSD Webservice

وب سرویس USSD


 

راهنمای جامع Webservice سرویس USSD

برای استفاده از سرویس USSD ابتدا باید وب سرویس شما در سیستم شناسایی شود , برای این منظور پارامتر های “API” و “Username” و “Password” و “Number” دریافتی از احسان سرور را برای اولین بار به URL زیر برای انجام احراز هویت ارسال گردد

 

پارامتر های برگشتی به شرح زیر خواهند بود :

WSRS : لینک وب سرویس شما با موفقیت ثبت شده است.

WSUE : لینک ب سرویس قبلا وجود داشته است و برای تغییر می بایست دستور RESETWSU ارسال گردد

ERROR : معمولا خطا با دلیل آن ارسال میگردد , دلایل خطا به شرح زیر است :

1. Wrong action : مقادیر ارسالی معتبر و صحیح نمی باشد

2. Wrong Username Or Password : رمز عبور یا نام کاربری اشتباه است

3. Wrong API With Number : شماره با API همخوانی ندارد

4. No SSL : پارامتر های ارسالی بدون SSL ارسال شده است و یا درخواست به لینک غیر ایمن ارسال شده است.

 

برای استفاده از سرویس USSD احسان سرور در هر مرحله موارد زیر به وب سرویس شما به عنوان پارامترهای ورودی ارسال می شود.

1 شماره همراه گیرنده ی کد USSD:

شماره ی همراه گیرندهی کد در هر مرحله به وب سرویس شما ارسال می شود. از آنجایی که شماره موبایل برای هر کاربر منحصر بفرد میباشد، این مورد میتواند به عنوان کلید اصلی نگه داری بسیاری از اطلاعات Content Provider مورد استفاده قرار گیرد.

2-شناسه Session :

شناسه ی session معرف یک نشست ارتباطی بین کاربر و Content Provider می باشد. از زمانی که کاربر شروع به گرفتن اولین کد USSD می کند تا زمانی که به هر دلیلی این ارتباط به یک نتیجه ی نهایی می رسد یک نشست به حساب می آید. دلایل اتمام ارتباط می تواند مواردی چون رسیدن به حالت نهایی )حالتی که سناریوی مورد نظر به اتمام رسیده باشد(، وقوع اشکال در خط ارتباطی، اتمام زمان نشست (Session Timeout) و … باشد.

  • مسیر USSD طی شده توسط کاربر در یک نشست:

این مورد به صورت یک رشته از لحظهی شروع نشست، تا اتمام آن به هر دلیلی، به Content Provider ارسال میشود. به عنوان مثال کاربر ابتدا کد 6060 را شماره گیری می نماید. سپس از منوی موجود عدد 1 را انتخاب می کند. تا این لحظه رشته ی 6060*1 برای CP ارسال می شود. سپس کاربر عدد 2 را از گزینه های موجود در منوی موجود انتخاب میکند. پس از ارسال درخواست رشته ی 6060*1*2 برای CP ارسال می شود. دلیل وجود این رشته در پارامترهای ورودی این است که CP از نحوه ی پیمایش کاربر آگاه باشد و منوهای مرتبط را به عنوان خروجی به وی برگرداند.

  • موارد ورودی توسط کاربر در هر مرحله:

در مواردی که درخواست ارسال ورودی به کاربر داده میشود این مقدار که توسط وی وارد شده است نیز به CP ارسال میشود. به عنوان مثال تصور کنید در یک مرحله نام خانوادگی کاربر به عنوان ورودی از وی خواسته میشود. پس از ارسال کاربر مقدار وارد شده توسط وی برای CP ارسال میشود .

 

مواردی که در ارسال نتیجه فراخوانی وب سرویس شما باید مورد نظر قرار گرفته شود به شرح زیر است:

نحوهی ارسال ورودی ها به وب سرویس شما در قسمت قبل توضیح داده شد. در این قسمت توضیح داده میشود که وب سرویس شما با چه قالبی بایستی خروجی خود را ایجاد نماید.

  • خروجی به صورت یک رشته است که در قالب XML فراهم میشود. تگ تگِ اصلی آن باید به اسم response باشد، به این صورت:

  • در تگی به اسم USSDResult که فرزند response محسوب میشود رشته ی منو و یا هر محتوای دیگری که بایستی در همراه کاربر نشان داده شود می آید. به عنوان مثال:

  • در تگی به اسم SMSResult که فرزند response محسوب میشود محتوایی که بایستی به کاربر به صورت پیامک فرستاده شود می آید. به عنوان مثال:

 

  • در تگی به اسم USSDServiceId که فرزند response محسوب میشود شناسه ی سرویسی که در تراکنش فعلی USSD استفاده میشود آورده میشود. این شناسه نشان دهنده ی این است که انجام شدن سرویس مورد نظر چه هزینهای برای کاربر دربر دارد.
  • در تگی به اسم USSDSchema که فرزند response محسوب میشود اعداد 6 یا 1 قرار داده میشوند .6 به معنای این است که صفحه ی USSD نمایش داده شده شامل فقط کاراکترهای انگلیسی باید باشد .1 نیز به معنای این است که صفحه شامل فقط کاراکترهای فارسی باید باشد.

به دو مثال زیر توجه کنید:

 

– دو تگ به نام های SMSOrigin و SMSServiceId که فرزند response محسوب میشوند در خروجی قرار داده میشوند .SMSOrigin نشان دهندهی پیش شماره ای است که پیامک توسط آن به کاربر فرستاده میشود .SMSServiceId نیز دقیقا مانند USSDServiceId پر میشود و اطلاعات هزینهی مربوط به SMS را در خود نگه میدارد.

به عنوان مثال:

 

– و نهایتاً در تگ دیگری به اسم intention که فرزند response محسوب میشود، اعداد 6 یا 1 قرار داده میشوند .6 به معنای این است که سناریوی مورد نظر به اتمام رسیده و کاربر پیغام نهایی را دریافت نموده است. اما 1 برعکس این قضیه است. در واقع با قرار دادن عدد 1 در این تگ به درگاه  USSD اطلاع میدهید که سناریوی کاربر هنوز به اتمام نرسیده است.

مثال برای حالت اتمام سناریو:

 

مثال برای حالت ادامه ی سناریو:

 

وب سرویس میبایست توسط سرویس دهنده ( سفارش دهنده ) تهیه و به همراه مستندات ارسال گردد.