1

بسم اهلل الرحمن الرحیم

راهنمای استفاده از وب سرویس سامانه صدور قبض

59پاییز

آدرس وب سرویس :

http://ws24.shenase.net/BillPayerService.svc

http://ws24.shenase.net/BillPayerService.svc?wsdl

2

ابتدا یک رفرنس از آدرس وب سرویس به پروژه خود اضافه کنید.

متدهای این سرویس بشرح زیر می باشد :

( صدور قبضCreateBill)

. پارامترهای این متد در جدول زیر آمده اند.برای ایجاد و صدور یک قبض جدید استفاده می شود

توسط پس از اتمام فرایند ایجاد قبض شروع می شوند ، از نوع ارجاعی بوده و refکه با عبارت : متغیرهایی نکته

وب سرویس می باشند. وحاوی مقادیر بازگشتی ازوب سرویس پر می شوند

شرح مثال نوع عنوان پارامتر

username string “ali” )نام کاربری فرد در سامانه قبوض می باشد )اجباری

password string “ali12@34” )کلمه عبور فرد در سامانه قبوض می باشد )اجباری

receiverName string "نام پرداخت کننده قبض است )اجباری( "محمد

receiverFamily string "نام خانوادگی پرداخت کننده قبض است )اجباری( "علیپور

receiverMobile string "95395555555" شماره همراه پرداخت کننده قبض است )در صورتی

که تمایل به ارسال پیامک به پرداخت کننده داشته

باشید این پارامتر اجباری است وگرنه اختیاری(

title string "عنوان قبض می باشد )اجباری( "قبض عوارض

price double 120999 این مبلغ نباید کمتر از –مبلغ قبض )اجباری

ریال باشد( 19999

billDescription string "توضیحات قبض است )اختیاری( "شرح دلخواه

isWageByCreator boolean false اگرtrue ارسال شود به این معنی است که کارمزد

صدور قبض باید از حساب صادر کننده کسر شود و به

باشد یعنی falseمبلغ قبض اضافه نشود و اگر

کارمزد به مبلغ قبض اضافه شود و توسط پرداخت

کننده ، پرداخت شود

sendSms boolean true اگرtrue باشد یعنی پیامک به پرداخت کننده قبض

پیامکاین یعنی عدم ارسال falseو سال شودار

billGroupId long 4 در آن گروهی است که می خواهید قبض شماشناسه

باشد اولین گروه 9اگر این مقدار گروه قرار گیرد.

مورد استفاده ، توسط مشتریتعریف شده در سامانه

گیرد. ر میقرا

3

ref billId long 645865470247 شناسه قبض تولید شده می باشد

ref paymentId long 56872010 شناسه پرداخت قبض تولید شده می باشد

ref billSerial long 785 سریال قبض تولید شده می باشد

ref newPrice double 12900 سال ارمبلغ جدید قبض است )این مبلغ زمانی با مبلغ

شده فرق میکند که پرداخت کارمزد با پرداخت کننده

ز .بنابراین پس اباشد و یا مبلغ قبض رند شده نباشد

(ایجاد قبض این مبلغ مالک می باشد

کند پس شما باید مبلغ بازگشتی از وب سرویس : پس از فراخوانی متد صدور قبض ، احتماال مبلغ تغییر مینکته

ه این مبلغ مالک سامانه می باشد.را ذخیره کنید ، چراک

، از طریق استفاده می شود (مقداردهی شود trueبا sendSms پارمتر اگرارسال پیامک )متنی که در : 2 نکته

پنل شناسه قابل تغییر می باشد.

شناسه گروه مورد نظر خود ، می توانید به پنل کاربری خود وارد شوید و از بخش گروه های برای دریافت: 3 نکته

ابید.قبوض شناسه گروه مورد نظر خود را بی

می باشد( enum)نوع خروجی حالت زیر می باشد. 13خروجی این متد یکی از

شرح فارسی شرح انگلیسی کد کد

1- UsernameOrPasswordIncorrect نام کاربری یا کلمه عبور اشتباه است

0 Succeed صدور قبض موفقیت آمیز بود

1 ValidationFailed اجباری وارد نشده اند مقادیر

2 MinimumPriceNotCorrect ریال است 19999مبلغ ارسالی کمتر از

3 CreditForSendingSmsIsLow اعتبار شما برای ارسال پیامک کافی نیست

4 MobileNumberNotEntered برای ارسال پیامک( شماره همراه پرداخت کننده مشخص نشده است(

5 MobileNumberIsNotCorrect )شماره همراه پرداخت کننده معتبر نمی باشد )برای ارسال پیامک

6 PriceLengthIsTooLong رقم است 8تعداد ارقام مبلغ بیش از

7 CreatingBillIsNotPossibleNow موقتا نمی توانید قبض صادر کنید

8 PriceNotCorrect مبلغ وارده معتبر نمی باشد

9 DefaultBillGroupNotAvailable ا ی گروه قبضی بعنوان پیشفرض مشخص نشده است ، برای استفاده از سرویس

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

10 SmsTemplateNotDefined تعریف نشده است در سامانه متن قالب پیامک

11 InternalError خطای داخلی سرور

12 SmsSendingFailed خطا در ارسال پیامک

4

باشد ، می توان گفت که صدور قبض موفقیت آمیز بوده است. Succeedیا 9فقط زمانیکه خروجی این متد

متد می 3با ی که در دست دارید ،تبسته به اطالعا اگر قبضی را قبال صادر کرده اید و می خواهید از آخرین وضعیت آن مطلع شوید ،

توانید این کار را انجام دهید :

خروجی تمام این متدها یکسان است.: 1نکته

متد اجباری است. 3تمامی پارامترها در این : 2نکته

( بررسی وضعیت قبض با استفاده از شناسه هاCheckBillStatusByIds)

از وضعیت قبض مطلع شوید از این متد استفاده شناسه پرداختو شناسه قبضخواهید با استفاده از میاگر

این متد بشرح زیر است : پارامتر هایکنید.

شرح مثال نوع عنوان پارامتر

username string “ali26” نام کاربری فرد در سامانه است

password string “al@26P2ass” کلمه عبور فرد در سامانه است

billId long 5647886004852 شناسه قبض مورد نظر

paymentId long 6980124 نظرشناسه پرداخت قبض مورد

سریال بررسی وضعیت قبض با استفاده از(CheckBillStatusBySerial)

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

این متد بشرح زیر است :

شرح مثال نوع عنوان پارامتر

username string “ali26” در سامانه استنام کاربری فرد

password string “al@26P2ass” کلمه عبور فرد در سامانه است

serial long 4587 می باشد قبض مورد نظر سریال

5

کد رهگیریبررسی وضعیت قبض با استفاده از (CheckBillStatusByTrackingCode)

زم به الاز وضعیت قبض مطلع شوید از این متد استفاده کنید. قبض کد رهگیریخواهید با استفاده از اگر می

ذکر است که این متد زمانی کاربرد دارد که قبض پرداخت شده باشد.

پارامتر های این متد بشرح زیر است :

شرح مثال نوع عنوان پارامتر

username string “ali26” نام کاربری فرد در سامانه است

password string “al@26P2ass” کلمه عبور فرد در سامانه است

trackingCode string "28422759" قبض مورد نظر می باشدکد رهگیری

می باشد( enum)نوع خروجی ، یکی از چند حالت زیر می باشد. مذکورمتد 3خروجی هر

شرح فارسی شرح انگلیسی کد کد

1- UsernameOrPasswordIncorrect یا کلمه عبور اشتباه استنام کاربری

0 UnPaymented پرداخت نشده

1 PaymentedByGateway پرداخت شده از درگاه بانکی

2 PaymentedBySupport پرداخت شده توسط مدیر سامانه

3 Voided باطل شده

4 PaymentedByATM کارتخوان و عابربانک و ...(به بانک پرداخت شده از دستگاههای متصل(

5 BillNotFound قبضی با مشخصات ارسال شده پیدا نشد

6 InternalError خطای داخلی سرور

همگی پرداخت شده هستند و فقط نوع پرداخت آنها متفاوت است. 7و 2و 1: حالتهای نکته

6

( ابطال قبضVoidBill)

پرداخت نباشد ، می توانید از که قابل بطوریاگر می خواهید قبضی که قبال صادر کرده اید را باطل کنید

این متد استفاده کنید.

: فقط قبض هایی قابلیت باطل شدن را دارند که وضعیت انها پرداخت نشده باشد.نکته

پارامتر های این متد بشرح زیر است :

شرح مثال نوع عنوان پارامتر

username string “ali26” نام کاربری فرد در سامانه است

password string “al@26P2ass” کلمه عبور فرد در سامانه است

billId long 5647886004852 شناسه قبض مورد نظر

paymentId long 6980124 شناسه پرداخت قبض مورد نظر

می باشد( enum)نوع خروجی خروجی متد فوق ، یکی از چند حالت زیر می باشد.

شرح فارسی شرح انگلیسی کد کد

1- UsernameOrPasswordIncorrect نام کاربری یا کلمه عبور اشتباه است

0 Succeed ابطال قبض موفقیت آمیز بود

1 BillNotFound قبض مورد نظر پیدا نشد

2 BillIsNotUnpaymented قبض مورد نظر در وضعیت پرداخت نشده نیست

3 InternalError خطای داخلی سرور

7

(#Cمثال هایی از متدها )به زبان

(CreateBillایجاد قبض )

private void BtnCreateBill_Click(object sender, EventArgs e) { var clientSrv = new BillService.BillPayerServiceClient(); long billId = 0, paymentId = 0, billSerial = 0; double newBillPrice = 0; var billResult = clientSrv.CreateBill("aaa", "111111", "زارع" ,"محسن", ,true, false,0 ,"شرح قبض" ,142000 ,"عنوان قبض" ,"90990000000" ref billId, ref paymentId, ref billSerial, ref newBillPrice); if (billResult == BillService.CreateBillResults.Succeed) { MessageBox.Show("قبض ایجاد شد\r\n" + + "billId + "\r\n + " : شناسه قبض" + "paymentId + "\r\n + " : شناسه پرداخت" + "billSerial + "\r\n + " :سریال قبض" ;(newBillPrice + " : مبلغ جدید قبض" } else { MessageBox.Show("Error => \r\n " + billResult); } }

نتیجه اجرای کد فوق :

8

(CheckBillStatusByIdsچک کردن وضعیت قبض )

private void btnCheckBillStatus_Click(object sender, EventArgs e) { var clientSrv = new BillService.BillPayerServiceClient(); var result = clientSrv.CheckBillStatusByIds("aaa", "111111", long.Parse(txtBillId.Text), long.Parse(txtpayId.Text)); MessageBox.Show("وضعیت قبض : " + result); }

(VoidBill) ابطال قبض

private void BtnVoidBill_Click(object sender, EventArgs e) { var clientSrv = new BillService.BillPayerServiceClient(); var voidingResult = clientSrv.VoidBill("aaa", "111111", long.Parse(txtBillId.Text), long.Parse(txtpayId.Text)); if (voidingResult == BillService.BillVoidingResults.Succeed) { MessageBox.Show(" قبض باطل شد "); } else { MessageBox.Show("Error => r\n" + voidingResult); } }