شرکت توسعه عصر ارتباطات ماها

وبسرویس چیست؟

وبسرویس در واقع مجموعه ای از فرامین است که با استفاده از فرمت XML امکان برقراری ارتباط و انجام عملیات را به برنامه نویسان با هر زبان برنامه نویسی میدهد که استفاده از آن این امکان را به برنامه نویسان میدهد که تمامی عملیات ها را در وبسایت خود انجام دهد و کاربران را از جابه جایی بین صفحات و تکمیل کردن مجدد اطلاعات بی نیاز کند. عملیات های موجود در وبسرویس توسط زبان توضیحات وبسرویس (WSDL) نوشته میشوند و با استفاده از تکنولوژی SOAP به تبادل اطلاعات می پردازند. عملیات های موجود در سرویس خرید پستی ماها در صفحه نخست به همراه توضیحات ، ورودی ها و خروجی ها قابل مشاهده است. اجرای فرامین موجود در وبسرویس شرکت توسعه عصر ارتباطات ماها برای هر فردی امکان پذیر نیست و تنها کاربرانی که دارای نام کاربری و کلمه عبور هستند مجاز به انجام عملیات ها و دریافت خروجی هستند. جهت استفاده ساده تر و درک بهتر نمونه ای از کدهای اتصال وجود دارد که برنامه نویسان با استفاده از آنها میتوانند به سادگی ارتباط خود را با این سرویس برقرار کنند . در ورودی و خروجی برخی از این فرامین پارامتر استان و شهرستان وجود دارد که نیاز است برنامه نویس این پارامتر ها را با کدهای استاندارد پر کند، جهت دریافت کد استان و شهرستان میتواند از بخش دریافت کد استان استفاده کنید و برنام خود را تکمیل نمایید.

مراحل اتصال به وبسرویس

اتصال به آدرس WSDL برای دریافت توابع و پارامتر های ورودی و خروجی توسط توابع Soap

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

آماده سازی پارامتر های ورودی و ارسال داده های مورد نیاز برای اجرای توابع مورد نظر

دریافت خروجی تابع و تحلیل خروجی، در صورت وجود خطا پارامترهای خطا تعریف خواهد شد.

لیست توابع موجود در وبسرویس

change_status_ready

آماده به ارسال تکی و دسته ای

این تابع برای تغییر وضعیت مرسولات شما به آماده به ارسال مورد استفاده قرار میگیرد.
پس از اجرای این تابع سفارشات در صف ثبت قرار گرفته تا در سامانه گیتوی پست ثبت شده و کد رهگیری صادر شود.
ورودی های تابع :
order_idشناسه ویا شناسه های سفارش (در صورتی که بیشتر از یکی است با کاما جدا شود.)
خروجی آرایه ای با پارامتر های زیر :
order_idشناسه ارسال شده (همان شناسه ارسال شده کاربر)
stateوضعیت تغییر کرده (شامل خطاهای گیتوی نیست)
insert_order

ثبت سفارش جدید

این تابع برای درج سفارشات مورد استفاده قرار میگیرد که پرکاربرد ترین تابع در وبسرویس است
لطفا جهت درج سفارش به نکات زیر توجه فرمایید:
  • تمامی پارامتر ها میبایست دارای مقدار باشد
  • برای فیلد لیست محصولات حتما از فرمت استاندارد استفاده نمایید.
  • در صورتی که سفارش متعلق به فروشگاه اصلی است و هیچ کد همکاری وجود ندارد ، کد همکار را با مقدار 0 پر کنید
  • در صورتی که نمیخواهید آدرس IP خریدار را وارد کنید این فیلد را با مقدار 0.0.0.0 پر کنید
  • در صورت وجود نداشتن کد محصول در لیست محصولات همراه با ثبت سفارش در لیست محصولات درج خواهد شد.
ورودی های تابع :
o_name نام خریدار
o_family نام خانوادگی خریدار
o_phone شماره ثابت(در سابقه خرید استفاده خواهد شد)
o_mobile شماره همراه(مورد استفاده در بخش پیامک)
o_email ایمیل(این فیلد اجباری نیست)
o_postalcod کد پستی(کد پستی ده رقمی خریدار)
o_ostan کد استان(به بخش لیست استان مراجه شود)
o_shahr کد شهر(به بخش لیست استان مراجه شود)
o_address آدرس پستی(آدرس را کامل وارد کنید)
o_message پیغام خریدار(در فاکتور دیده میشود)
o_sendtype نوع ارسال(1 سفارشی و 2 پیشتاز)
o_product_list لیست محصولات(طبق دستورالعمل ساخته شود)
o_partner_code کد همکار(در صورت وجود نداشتن 0 وارد شود)
o_ip_address آدرس IP(عدم وجود 0.0.0.0 وارد شود)
o_extra_parametr پارامتر های اضافی(در صورت نیاز طبق دستورالعمل)
دستورالعمل پارامتر o_extra_parametr : در این پارامتر شما قادر به ارسال متغییر های مختلفی جهت اعمال تغییرات بر روی روند ثبت سفارش هستید
به عنوان مثال در صورتی که بخواهید تغییراتی در پارامتر های لیست محصولات اعمال شود میبایست این پارامتر را به صورت زیر تنظیم نمایید
plist=2 (در صورت وجود داشتن محصول در لیست محصولات مقدار وزن و قیمت ارسال شده محاسبه خواهد شد)
plist=3 (در صورتی که مقدار این پارامتر را 3 قرار دهید تغییرات پارامتر محصولات موجود در سفارش در لیست محصولات فروشگاه اعمال خواهد شد )
همچنین پارامتر pweight جهت اعمال وزن اضافه به سفارش مورد استفاده قرار میگیرد
مثال : plist=2&pweight=250
فرمت لیست محصولات: productcode^product title^product weight^product price^product number
درصورت وجود نداشتن محصول عنوان، وزن و قسمت حتما باید وارد شود ، در غیر اینصورت خالی وارد کنید :
مثال : 1001^my product title^120^25000^1 (کد محصول وجود ندارد)
(جهت جدا کردن محصولات از کاراکتر ';' استفاده کنید)
1001^^0^0^1 (کد محصول وجود دارد)
خروجی های تابع :
order_code شناسه سفارش(شناسه یکتا صادر میشود.)
post_code شناسه پستی(در صورت فعال بودن گیتوی 0 است)
gateway وضعیت گیتوی(وضعیت ثبت سفارش در گیتوی)
coupon_code کوپن تخفیف(در صورت فعال بودن صدور اتوماتیک کوپن ممکن است دارای مقدار باشد)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
نمونه کد :
 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
$soapClient = new soapclient("wsdl Address",array('login'=> 'username','password'=> 'Shop Password'));
$ap_param = array('o_name'=>'customer name'
,'o_family'=>'customer family'
,'o_phone'=>'55909090'
,'o_mobile'=>'09122222222'
,'o_email'=>'a@a.com'
,'o_postalcod'=>'11'
,'o_ostan'=>'21'
,'o_shahr'=>'122'
,'o_address'=>'this is your address'
,'o_message'=>''
,'o_sendtype'=>1
,'o_product_list'=>implode("^",array('9001','',0,0,1))
,'o_partner_code'=>0
,'o_ip_address'=>''
,'o_extra_parametr'=>'');
$myreturn = $soapClient->__soapCall("insert_order", $ap_param);
if (!isset($myreturn->error_code)){
echo 'Your Order ID : '.$myreturn->order_code.'<br>';
if (!isset($myreturn->coupon_code)){
echo 'Your Coupon ID : '.$myreturn->order_code.'<br>';
}
}else{
echo $myreturn->error_message;
}
calculation_send_price

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

این تابع برای محاسبه هزینه ارسال بسته از شهر مبدا (فروشگاه) به شهر مقصد (خریدار) مورد استفاده قرار میگیرد.
ورودی ها و خروجی های این تابع به شرح زیر است:
ورودی های تابع :
ostan_maghsadاستان مقصد (قاب دسترسی در لیست استانها)
shahr_maghsadشهر مقصد (قاب دسترسی در لیست استانها)
send_typeنوع ارسال بسته (1 برای سفارشی و 2 برای پیشتاز)
products_weightوزن بسته (میبایست به گرم وارد شود)
total_priceمبلغ کالا (جمع مبلغ کالاهای بسته به ریال)
خروجی های تابع :
send_priceهزینه ارسال (به همراه جزئیات)
maliyatمالیات بر ارزش افزوده (6 درصد مالیات)
khadamatمبلغ افزوده شده خدمات (هزینه خدمات)
codpriceمبلغ پرداخت در محل (هزینه های پستی)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
نمونه کد :
 1
2
3
4
5
6
7
8
9
10
11
12
$soapClient = new soapclient("wsdl Address",array('login'=> 'username','password'=> 'Shop Password'));
$ap_param = array('ostan_maghsad'=>'83'
,'shahr_maghsad'=>'258'
,'send_type'=>1
,'products_weight'=>' 170'
,'total_price'=>352400);
$myreturn = $soapClient->__soapCall("calculation_send_price", $ap_param);
if (!isset($myreturn->error_code)){
echo $myreturn->send_price;
}else{
echo $myreturn->error_message;
}
add_product

افزودن محصول جدید

جهت افزون محصول میتوانید از این تابع استفاده نمایید
توجه کنید که کد محصول وارد شده میبایست یکتا باشد و پس از درج محصول کد فروشگاه به صورت اتوماتیک به ابتدای کد فروشگاه اضافه خواهد شد.
ورودی های تابع :
p_codeکد محصول (میبایست یکتا باشد)
p_titleعنوان محصول (عنوان محصول در فاکتور قابل تغییر است)
p_weightوزن محصول (میبایست به گرم وارد شود)
p_priceقیمت محصول (میبایست به ریال وارد شود)
خروجی های تابع :
statusوضعیت ثبت (خروجی True , False)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
نمونه کد :
 1
2
3
4
5
6
7
8
9
10
11
$soapClient = new soapclient("wsdl Address",array('login'=> 'username','password'=> 'Shop Password'));
$ap_param = array('p_code'=>'213'
,'p_title'=>'عنوان محصول'
,'p_weight'=>'250'
,'p_price'=>'250000');
$myreturn = $soapClient->__soapCall("add_product", $ap_param);
if (!isset($myreturn->error_code)){
echo 'محصول درج شد.';
}else{
echo $myreturn->error_message;
}
get_bulk_status

دریافت دسته ای وضعیت سفارشات

این تابع جهت دریافت آخرین وضعیت مرسولات به صورت گروهی مورد استفاده قرار میگیرد.
توجه کنید از این تابع میتوانید وضعیت مرسولات را به صورت تکی نیز دریافت نمایید. ورودی های تابع :
order_idشناسه سفارشات (در صورتی که بیشتر از یکی است با کاما جدا شود.)
خروجی آرایه ای با پارامتر های زیر :
order_idشناسه محصولات (شناسه ای که در ورودی وارد کرده اید)
status_codeکد وضعیت شناسه (به لیست وضعیت ها مراجعه شود)
status_stringتوضیحات وضعیت (به لیست وضعیت ها مراجعه شود)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
جدول وضعیت های شناسه
کد وضعیت عنوان وضعیت توضیحات
1 تحت بررسی محصول تازه سفارش داده شده و در انتظار تایید فروشگاه است
2 آماده به ارسال فروشگاه محصول را تایید کرده و در انتظار دریافت واحد قبول پست است
3 انصرافی سفارش توسط فروشگاه تایید نشده
4 ارسال شده مسئول پست سفارش را از فروشگاه تحویل گرفته و به مقصد ارسال کرده
5 توزیع شده مسئول پست توزیع ، بسته را به گیرنده تحویل داده و در وجه را دریافت کرده
6 وصول شده مسئول پست هزینه سفارش را به حساب واریز کرده
7 برگشتی مقصد پست توزیع بسته را به مبدا ارسال کرده
8 برگشتی مبدا بسته به دست واحد قبول رسیده و به فروشگاه تحویل گردیده
9 ارسال توسط خودم زمانی که فروشگاه بسته را خود ارسال میکند از این حالت استفاده میکند
10 عدم قبول واحد پستی زمانی که واحد پستی از دریافت بسته به دلیل مشکل خودداری میکند و تنها قبل از حالت ارسال شده قابل انجام است
11 بلوک شده سفارشی که توسط واحد توزیع بلوکه شده و قابل توزیع نیست
12 برگشتی بدون اعلام اولیه در حالتی که واحد قبول بدون اعلام برگشتی واحد توزیع مرسوله را تایید برگشتی کند این حالت رخ میدهد و نیاز به تایید واحد توزیع دارد.
13 عدم حضور فروشگاه فروشگاه براي تحويل مرسولات به پست آماده نبود
14 باجه معطله خريدار در زمان تحويل سفارش حضور نداشته و سفارش 72 ساعت در واحد توزيع جهت مراجعه بعدي باقي مي ماند
15 توزیع شده مسئول پست توزیع ، بسته را به گیرنده تحویل داده و در وجه را دریافت کرده
16 اشتباه در آماده به ارسال فروشگاه اشتباها سفارش را به وضعیت آماده به ارسال تبدیل کرده
get_status

دریافت وضعیت سفارش

این تابع جهت دریافت آخرین وضعیت یک مرسوله مورد استفاده قرار میگیرد.
توجه کنید تفاوت این تابع با تابع دریافت گروهی سرعت انجام عملیات است. ورودی های تابع :
order_idشناسه سفارشات (شناسه باید به صورت تکی وارد شود)
خروجی آرایه ای با پارامتر های زیر :
status_codeکد وضعیت شناسه (به لیست وضعیت ها مراجعه شود)
status_stringتوضیحات وضعیت (به لیست وضعیت ها مراجعه شود)
status_descriptionتوضیحات وضعیت (به لیست وضعیت ها مراجعه شود)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
جدول وضعیت های شناسه
کد وضعیت عنوان وضعیت توضیحات
1 تحت بررسی محصول تازه سفارش داده شده و در انتظار تایید فروشگاه است
2 آماده به ارسال فروشگاه محصول را تایید کرده و در انتظار دریافت واحد قبول پست است
3 انصرافی سفارش توسط فروشگاه تایید نشده
4 ارسال شده مسئول پست سفارش را از فروشگاه تحویل گرفته و به مقصد ارسال کرده
5 توزیع شده مسئول پست توزیع ، بسته را به گیرنده تحویل داده و در وجه را دریافت کرده
6 وصول شده مسئول پست هزینه سفارش را به حساب واریز کرده
7 برگشتی مقصد پست توزیع بسته را به مبدا ارسال کرده
8 برگشتی مبدا بسته به دست واحد قبول رسیده و به فروشگاه تحویل گردیده
9 ارسال توسط خودم زمانی که فروشگاه بسته را خود ارسال میکند از این حالت استفاده میکند
10 عدم قبول واحد پستی زمانی که واحد پستی از دریافت بسته به دلیل مشکل خودداری میکند و تنها قبل از حالت ارسال شده قابل انجام است
11 بلوک شده سفارشی که توسط واحد توزیع بلوکه شده و قابل توزیع نیست
12 برگشتی بدون اعلام اولیه در حالتی که واحد قبول بدون اعلام برگشتی واحد توزیع مرسوله را تایید برگشتی کند این حالت رخ میدهد و نیاز به تایید واحد توزیع دارد.
13 عدم حضور فروشگاه فروشگاه براي تحويل مرسولات به پست آماده نبود
14 باجه معطله خريدار در زمان تحويل سفارش حضور نداشته و سفارش 72 ساعت در واحد توزيع جهت مراجعه بعدي باقي مي ماند
15 توزیع شده مسئول پست توزیع ، بسته را به گیرنده تحویل داده و در وجه را دریافت کرده
16 اشتباه در آماده به ارسال فروشگاه اشتباها سفارش را به وضعیت آماده به ارسال تبدیل کرده
register_coupon

ثبت کوپن برای سفارشات

این تابع برای نسبت دادن یک کوپن تخفیف به یک سفارش مورد استفاده قرار میگیرد.
ورودی های تابع :
order_idشناسه سفارش (پس از ثبت سفارش این شناسه در خروجی وجود دارد.)
coupon_idکوپن تخفیف (کوپن صادر شده برای کاربر.)
خروجی های تابع :
statusوضعیت ثبت (خروجی True , False)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
edit_product

ویرایش محصول

جهت ویرایش محصول میتوانید از این تابع استفاده نمایید
توجه کنید که درصورتی که نمیخواهید موجودی کالای مورد نظر تغییر کند کافی است یک رشته خالی به وبسرویس ارسال نمایید.
ورودی های تابع :
p_codeکد محصول (میبایست یکتا باشد)
p_weightوزن محصول (میبایست به گرم وارد شود)
p_priceقیمت محصول (میبایست به ریال وارد شود)
p_stockموجودی محصول (میبایست عدد وارد شود)
خروجی های تابع :
statusوضعیت ثبت (خروجی True , False)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
نمونه کد :
 1
2
3
4
5
6
7
8
9
10
11
$soapClient = new soapclient("wsdl Address",array('login'=> 'username','password'=> 'Shop Password'));
$ap_param = array('p_code'=>'213'
,'p_weight'=>'250'
,'p_price'=>'250000'
,'p_stock'=>'5');
$myreturn = $soapClient->__soapCall("edit_product", $ap_param);
if (!isset($myreturn->error_code)){
echo 'محصول درج شد.';
}else{
echo $myreturn->error_message;
}
calculation_coupon_offer

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

این تابع جهت محاسبه مبلغ تخفیف یک کوپن تخفیف بر روی لیست محصولات مورد استفاده قرار میگیرد.
ورودی های تابع :
product_listشناسه محصولات (در صورتی که بیشتر از یکی است با کاما جدا شود.)
coupon_idکوپن تخفیف (کوپن صادر شده برای کاربر.)
خروجی های تابع :
product_listشناسه محصولات (لیست شناسه کالاهای وارد شده در ورودی)
total_offerجمع مبلغ تخفیف (به ریال)
error_codeکد خطا (در صورت بروز خطا)
error_messageمتن خطا (در صورت بروز خطا)
دقت کنید جهت غیر فعال کردن سیستم کش در سرور از تکه کد های زیر استفاده نمایید
ini_set("soap.wsdl_cache_enabled", 0);
ویا از پارامتر زیر استفاده کنید
$client = new SoapClient('wsdl Address', array('cache_wsdl' => WSDL_CACHE_NONE) );

نمونه کد اتصال جهت برنامه نویسی

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

ماژول های اتصال به وبسرویس

در این بخش ماژول های آماده شده جهت اتصال سیستم های رایگان به وبسرویس شرکت ماها قرار داده خواهد شد، جهت دانلود کلیک کنید.


Logo
Logo
Logo
Logo

لیست فایل های مورد نیاز

لیست استان ها و شهرستان ها

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

لوگو