راهنمای استفاده از وب سرویس آسمان وب - نسخه 2


وب سرویس آسمان وب، با استفاده از Json تهیه شده است. برای استفاده از این وب سرویس، شما میتوانید از هر کدام از زبان های برنامه نویسی که قابلیت شیء گرایی داشته باشد، استفاده نمایید.


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

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

برای استفاده بصورت POST میتوانید از آدرس http://www.webskyiran.ir/json/webservice.php استفاده نمایید.

انواع ارسال:

در حال حاضر دو نوع ارسال در سیستم آسمان وب وجود دارد. برای استفاده از ارسال بصورت پیشتاز، از عدد 0 و برای استفاده از ارسال بصورت سفارشی، از عدد 1 استفاده میشود.


انواع پرداخت:

در حال حاضر دو نوع پرداخت برای وب سرویس وجود دارد. برای استفاده از پرداخت در محل مقدار COD و برای پرداخت آنلاین مقدار CASH استفاده میشود.


وضعیت سفارش در سیستم آسمان وب:

در سیستم آسمان وب هر سفارش میتواند در یکی از 12 حالت زیر قرار داشته باشد.

  1. معلق
  2. آماده به ارسال
  3. ارسال شده
  4. توزیع شده
  5. انصراف شده
  6. برگشت شده
  7. برگشت تایید شده
  8. انصراف از ارسال توسط پست
  9. توقیف شده
  10. باجه معطله
  11. نقدی ناموفق
  12. واگذار شده

شناسه سفارش:

برای استفاده از شناسه سفارش در وب سرویس، شما باید شناسه سفارش را بصورت عددی ارسال نمایید. بعنوان مثال شناسه 33/1111-222222-333333 برای استفاده در وب سرویس باید بصورت 331111222222333333 استفاده شود. همچنین در صورت تمایل به استفاده از بیش از یک شناسه، باید شناسه ها را با کاراکتر ; از هم جدا کنید.


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

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

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

مقادیر الزامی جهت ارسال به صفحه وب سرویس:

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


مقادیر مجاز برای action:

با توجه به نوع عملیات درخواستی خود، شما باید مقداری را تحت عنوان action به وب سرویس ارسال نمایید. این مقادیر بصورت زیر میباشند.


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

برای محاسبه هزینه ارسال از متد sendPrice استفاده نمایید. مقادیری که میتوانند ارسال شوند بصورت زیر میباشد. مقادیری که با رنگ قرمز مشخص شده اند، الزامی هستند.

در صورت موفقیت آمیز بودن عملیات، مقادیر زیر بازگشت داده خواهند شد.


ثبت سفارش:

برای ثبت سفارش از متد registerOrder استفاده نمایید. مقادیری که میتوانند ارسال شوند بصورت زیر میباشد. مقادیری که با رنگ قرمز مشخص شده اند، الزامی هستند.

در صورت موفقیت آمیز بودن عملیات، مقادیر زیر بازگشت داده خواهند شد.


لیست محصولات برای سفارشات عادی:

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

ID1^NAME1^WEIGHT1^PRICE1^COUNT1;ID2^NAME2^WEIGHT2^PRICE2^COUNT2

توجه داشته باشید که مشخصات هر کالا با کاراکتر ^ از هم جدا شوند. همچنین در صورت تمایل به ثبت بیش از یک کالا، کالاها را با کاراکتر ; از هم جدا کنید.


لیست محصولات برای سفارشات سیستم تبلیغاتی:

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

ID1^COUNT1;ID2^COUNT2

توجه داشته باشید که مشخصات هر کالا با کاراکتر ^ از هم جدا شوند. همچنین در صورت تمایل به ثبت بیش از یک کالا، کالاها را با کاراکتر ; از هم جدا کنید. همچنین شناسه محصول استفاده شده باید واقعی، تایید شده و فعال باشد.


لیست محصولات برای سفارشات سیستم همکار:

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

ID1^COUNT1;ID2^COUNT2

توجه داشته باشید که مشخصات هر کالا با کاراکتر ^ از هم جدا شوند. همچنین در صورت تمایل به ثبت بیش از یک کالا، کالاها را با کاراکتر ; از هم جدا کنید. همچنین شناسه محصول استفاده شده باید واقعی، تایید شده، فعال و اختصاص داده شده به همکار باشد.


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

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

در صورت موفقیت آمیز بودن عملیات، مقادیر زیر بازگشت داده خواهند شد.

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


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

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

در صورت موفقیت آمیز بودن عملیات، مقادیر زیر بازگشت داده خواهند شد.

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


درخواست پرداخت آنلاین وجه سفارش:

در صورتی که نوع پرداخت سفارش در زمان فراخوانی تابع ثبت سفارشات، بصورت CASH ارسال شده باشد، شما باید پس از ثبت سفارش، پس از دریافت لیست بانکهای فعال، درخواست پرداخت وجه سفارش را ارسال نمایید. برای این کار از متد payCashOrder استفاده نمایید. مقادیری که میتوانند ارسال شوند بصورت زیر میباشد. مقادیری که با رنگ قرمز مشخص شده اند، الزامی هستند.

در صورت موفقیت آمیز بودن عملیات، مقادیر زیر بازگشت داده خواهند شد.

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


درخواست بررسی وضعیت پرداخت وجه سفارش:

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

در صورت موفقیت آمیز بودن عملیات، مقادیر زیر بازگشت داده خواهند شد.


مراحل مورد نیاز برای ثبت سفارش بصورت آنلاین:

  1. ثبت سفارش با استفاده از متد registerOrder و ارسال مقدار paytype برابر با CASH
  2. دریافت لیست بانک های فعال با استفاده از متد getBankList و نمایش آن به خریدار
  3. ارسال درخواست پرداخت وجه سفارش با استفاده از متد payCashOrder و ارسال مقدار bank_id برابر با شناسه بانک انتخاب شده توسط خریدار
  4. ارجاع خریدار به صفحه http://www.webskyiran.ir/json/payOrder.php?order_key=xxx که به جای xxx باید شناسه سفارش قرار داده شود.
  5. بررسی وضعیت پرداخت وجه سفارش با استفاده از متد checkPaymentStatus

خطاهای وب سرویس:

در صورت بروز خطا در هر کدام از متد های وب سرویس، مقدار result برابر با false و مقادیر زیر نیز جهت توضیح شرح خطای رخ داده، بازگشت داده خواهند شد.


نکات:

  1. کلیه قیمتها در وب سرویس بر مبنای ریال میباشند.
  2. کلیه وزنها در وب سرویس بر مبنای گرم میباشند.
  3. اعتبارسنجی اطلاعات باید قبل از ارسال به وب سرویس انجام شوند. اطلاعاتی که مربوط به سیستم آسمان وب باشند، توسط وب سرویس اعتبارسنجی خواهند شد.
  4. هر فروشنده فقط از یک IP میتواند به وب سرویس دسترسی داشته باشد.
  5. برای نمایش هزینه نهایی ارسال، لازم است کلیه هزینه هایی که در نوع ارسال و نوع پرداخت مورد نظر بازگشت داده شده است را با یکدیگر جمع کنید.
  6. در صورت استفاده از وب سرویس، امکان تشخیص IP خریدار توسط آسمان وب وجود ندارد. لذا در صورت تمایل به ثبت IP خریدار، الزاما باید در فراخوانی تابع ثبت سفارش، مقدار IP خریدار نیز ارسال گردد. در غیر اینصورت IP خریدار ثبت نخواهد گردید.
  7. کلیه تنظیمات ثبت شده در قسمت "تنظیمات سبد خرید" در پنل فروشنده، شامل تخفیف، اطلاع رسانی و ... در وب سرویس نیز اعمال خواهند شد.
  8. مقادیر advertiser و partner در تابع ثبت سفارش اجباری نیستند. در صورت عدم ارسال این دو پارامتر، سفارش بصورت عادی ثبت خواهد شد.
  9. کلیه مقادیر فارسی، باید بصورت UTF-8 ارسال شوند. عدم رعایت این نکته ممکن است اجرای توابعی نظیر ثبت سفارش را با اشکال مواجه کند.
  10. با توجه به اینکه استعلام هزینه ارسال از سامانه دلیوری پست، نیازمند اتصال به سرور این سامانه میباشد، در صورت تمایل به دریافت هزینه ارسال از سامانه دلیوری، زمانی بیشتری برای دریافت پاسخ نیاز خواهد بود. بنابراین پیشنهاد میشود در صورتی که تمایل به فروش به روش پرداخت در محل دارید، هزینه ارسال را از این سامانه استعلام نگیرید.
  11. در صورت تمایل به ثبت سفارش بصورت پرداخت آنلاین، اکیدا توصیه میگردد پیش از ارسال کاربر به صفحه پرداخت، مجددا هزینه ارسال را از سامانه دلیوری استعلام نمایید تا مغایرتی در مبلغ نمایش داده شده به خریدار و مبلغ واقعی سفارش ایجاد نشود.

نمونه کد برای PHP:
در زیر نمونه کد استفاده از وب سرویس برای زبان PHP قرار داده شده است.

<?php
$options 
= array(
    
'action' => 'sendPrice',
    
'username' => 'demo',
    
'password' => 'demo',
    
'state' => 1,
    
'city' => 1,
    
'weight' => 1,
    
'amount' => 1
);

$ch curl_init();
curl_setopt($chCURLOPT_FRESH_CONNECTTRUE);
curl_setopt($chCURLOPT_POSTTRUE);
curl_setopt($chCURLOPT_RETURNTRANSFERTRUE);
curl_setopt($chCURLOPT_POSTFIELDS$options);
curl_setopt($chCURLOPT_URL'http://www.webskyiran.ir/json/webservice.php');
$result curl_exec($ch);
curl_close($ch);
var_dump(json_decode($result));
?>