وب سرويس فروشندگان

محاسبه هزینه

در این مرحله شما باید جمع کل مبلغ سفارش , وزن کل سفارش , شهر مقصد , روش های ارسال و روش های پرداخت را به این متد ارسال نمایید تا هزینه ارسال , مالیات ارسال و هزینه خدمات فروتل به شما برگردانده شود. اين وبسرويس براي فروش كالاهاي حقيقي كه هزينه ارسال دارند، كاربرد دارد.
آدرس وب سرويس :
براي پايداري وب سرويس ها سه سرور داريم كه يكي از اين سه آدرس را به دلخواه مي توانيد استفاده نمائيد.

روش ارسال داده ها آدرسهاي وب سرویس
POST http://webservice1.link/ws/v1/rest/order/getPrices.json
http://webservice2.link/ws/v1/rest/order/getPrices.json
http://webservice3.link/ws/v1/rest/order/getPrices.json

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

پارامتر نوع توضیحات اجباری
api string کلید API *
price int جمع کل هزینه سفارش به ریال *
weight int وزن کل سفارش به گرم *
des_city int شناسه شهر مقصد *
send_type array لیست روش های ارسال
1 = پیشتاز
2 = سفارشی
3 = مطبوعات
4 = پیک شهری
*
buy_type array لیست روش های پرداخت
1 = پرداخت در محل
2 = پرداخت نقدی
*

پارامترهاي خروجی :
خروجی این متد ساختاری مانند ساختار زیر دارد.

{
  "code": 0,
  "message": "",
  "result": {
    "naghdi": {					// هزینه های روش پرداخت نقدی
      "1": {					// هزینه های روش ارسال پیشتاز - نقدی
        "post": 52000,				// هزینه ارسال
        "tax": 4680,				// مالیات ارسال
        "frotel_service": 2000			// هزینه خدمات فروتل
      },
      "2": {					// هزینه های روش ارسال سفارشی - نقدی
        "post": 26000,
        "tax": 2340,
        "frotel_service": 2000
      }
    },
    "posti": {					// هزینه های روش پرداخت در محل
      "1": {					// هزینه های روش ارسال پیشتاز - پرداخت در محل
        "post": 58000,
        "tax": 5220,
        "frotel_service": 2000
      },
      "2": {					// هزینه های روش ارسال سفارشی - پرداخت در محل
        "post": 36000,
        "tax": 3240,
        "frotel_service": 2000
      }
    }
  }
}

نکته :
برای نمایش هزینه ارسال شما باید هر سه مقدار post , tax و frotel_servicce را با هم جمع زده و به خریدار نمایش دهید.

ثبت سفارش

(registerOrder و  registerOrderVirtual   و  registerOrderService)

در این مرحله شما باید يك سبد خرید + اطلاعات خریدار + يك روش پرداخت + يك روش ارسال را بر اساس نوع خريد محصول(حقيقي يا مجازي يا خدمات) را به يكي از سه متد registerOrder (ثبت سفارش محصول حقيقي)يا متد registerOrderVirtual (ثبت سفارش محصول مجازي) يا registerOrderService (ثبت سفارش خدمات) ارسال نمایید. بسته به نياز و نوع محصول شما از هر يك از اين سه متد مي توانيد براي ثبت سفارش استفاده نمائيد.(البته تعيين يك روش ارسال فقط براي كالاهاي حقيقي است كه بايد حمل و ارسال شوند و طبيعتاً براي خدماتي و مجازي وجود ندارد).
آدرس وب سرويس :
براي پايداري وب سرويس ها سه سرور داريم كه يكي از اين سه آدرس را به دلخواه مي توانيد استفاده نمائيد.

روش ارسال داده ها آدرس وب سرویس « محصولات حقيقي »
POST http://webservice1.link/ws/v1/rest/order/registerOrder.json
http://webservice2.link/ws/v1/rest/order/registerOrder.json
http://webservice3.link/ws/v1/rest/order/registerOrder.json
روش ارسال داده ها آدرس وب سرویس « محصولات مجازي »
POST http://webservice1.link/ws/v1/rest/order/registerOrderVirtual.json
http://webservice2.link/ws/v1/rest/order/registerOrderVirtual.json
http://webservice3.link/ws/v1/rest/order/registerOrderVirtual.json
روش ارسال داده ها آدرس وب سرویس « خدمات و محصولات خدماتي»
POST http://webservice1.link/ws/v1/rest/order/registerOrderService.json
http://webservice2.link/ws/v1/rest/order/registerOrderService.json
http://webservice3.link/ws/v1/rest/order/registerOrderService.json

پارامترهای ورودی برای ثبت سفارش محصولات حقیقی به وسیله متد registerOrder :

پارامتر نوع توضیحات اجباری
api string کلید API *
name string نام خریدار *
family string نام خانوادگی خریدار *
phone string تلفن خریدار *
mobile string موبایل خریدار *
gender int جنسیت خریدار
0 = زن
1 = مرد
*
email string ایمیل خریدار  
address string آدرس خریدار ( آدرس محل دریافت سفارش ) *
code_posti string کد پستی *
province int شناسه استان مقصد *
city int شناسه شهر مقصد *
buy_type int

روش پرداخت:

1 = پرداخت پس از تحويل(COD)(ويژه كالاهاي حقيقي)

2 = پرداخت آنلاين نقدي (تراكنش آنلاين بانكي)

*
send_type int

روش ارسال (ويژه كالاهاي حقيقي)

1 = پیشتاز

2 = سفارشی

4 = مطبوعات

5 = پیک شهری

10- چابك

 *
ip string آي پي خريدار در لحظه ثبت سفارش  
pm string پیام خریدار  
basket array اطلاعات محصولات داخل سبد خرید *
free_send int

* ارسال رایگان

0 = غیر فعال ارسال رایگان

1 = فعال کردن ارسال رایگان

 

نکته: در مورد ارسال رایگان (پارامتر free_send) توجه داشته باشید که اگر تمام کالاهای سبد خرید از نوع ارسال رایگان باشد ، مرسوله ارسال رایگان خواهد شد ولی اگر بین تمام کالاها، حتی یکی از کالاها ارسال رایگان نباشد، کلاً ارسال رایگان برای آن مرسوله لغو می شود و عمل نخواهد کرد. در این حالت ارسال رایگان روی تک تک محصولات سبد تنظیم می شود.

پارامترهای ورودی برای ثبت سفارش محصولات مجازی به وسیله متد registerOrderVirtual:

پارامتر نوع توضیحات اجباری
api string کلید API *
name string نام خریدار *
family string نام خانوادگی خریدار *
phone string تلفن خریدار *
mobile string موبایل خریدار *
gender int جنسیت خریدار
0 = زن
1 = مرد
*
email string ایمیل خریدار  
ip string آي پي خريدار در لحظه ثبت سفارش *
pm string پیام خریدار *
basket array اطلاعات محصولات داخل سبد خرید *

پارامترهای ورودی برای ثبت سفارش خدماتی به وسیله متد registerOrderService :

پارامتر نوع توضیحات اجباری
api string کلید API *
name string نام خریدار *
family string نام خانوادگی خریدار *
phone string تلفن خریدار *
mobile string موبایل خریدار *
gender int جنسیت خریدار
0 = زن
1 = مرد
*
email string ایمیل خریدار  
address string آدرس خریدار ( آدرس محل دریافت سفارش ) *
code_posti string کد پستی *
province int شناسه استان مقصد *
city int شناسه شهر مقصد *
ip string آي پي خريدار در لحظه ثبت سفارش  
pm string پیام خریدار  
basket array اطلاعات محصولات داخل سبد خرید *

در تمام متدهاي ثبت سفارش ، فیلد basket آرایه ای ازشناسه محصولات يا خدمات است که ساختاری آن مانند زیر است :

پارامتر نوع توضیحات اجباری
pro_code string کد محصول *
name string نام محصول *
price int قیمت هر واحد محصول به ریال *
count int تعداد محصول خریداری شده *
weight int وزن هر واحد محصول به گرم *
porsant float پورسانت محصول به درصد  
bazaryab int شناسه بازاریاب  
discount float میزان تخفیف به درصد  
free_send int

**ارسال رایگان

0 = غیر فعال کردن ارسال رایگان

1 = فعال کردن ارسال رایگان

 
tax float مالیات کالا به درصد  
options array آپشن های انتخاب شده توسط خریدار در سايت شما (فعلاً كاربردي ندارد. در اين حالت بايد اطلاعات آپشن و كالاي آپشن دار قبلاً با وبسرويس دريافت جزئيات محصول از فروتل دريافت شود و در اينجا تحويل اين وبسرويس شود)  

نکته مهم :

1- شما باید متناسب با نوع محصولات سبد خرید ،يكي از اين سه متد را بدرستي فراخوانی کنید.

2- برای ثبت سفارشات مجازی حتما باید محصولات شما در پنل مركزي فروتل ثبت شده باشد و برای محصولات فایل مورد نظر آپلود شده باشد. در صورتی که مشخصات محصول ثبت شده باشد اما فایلی برای آن آپلود نشده باشد سیستم اجازه ثبت سفارش را نخواهد داد.

نکته مهم :

** غیر از ارسال رایگان جزئی که روی تک تک محصولات سبد قابل تنظیم است که دو صفحه قبل در مورد آن توضیح دادیم، امکان تعریف ارسال رایگان (پارامتر free_send) روی کل سبد و سفارش هم وجود دارد یعنی شما می توانید به جای اینکه روی تک تک کالاها ارسال رایگان تنظیم کنید، روی کل سبد ارسال رایگان را تنظیم که با اینکار سفارش کلاً از نوع ارسال رایگان ثبت خواهد شد.

پارامترهاي خروجی :

ساختار خروجی متد ثبت سفارش كالاي حقيقي با روش پرداخت در محل (COD) به صورت زیر است.

{
code: 0,
message: "",
result: {
factor: {
id: "22000000000000000000",	// شماره فاکتور
view: "",				// کدهای HTML فاکتور
total: 748300			// جمع کل سفارش
      },
items: [				// لیست محصولات داخل فاکتور
         {
name: "موبایل اسمبلی",
num: 1,
price: 670000,
pro_code: "mobile888",
weight: 200,
option: ""
         }
      ]
   }
}

ساختار خروجي برای سفارشات نقدی (حقيقي يا مجازي يا خدماتي) به صورت زیر است :

{
code: 0,
message: "",
result: {
factor: {
id: "22000000000000000000",	// شماره فاکتور
view: "",				// کدهای HTML فاکتور
total: 748300			// جمع کل سفارش,
banks: [				// لیست درگاه ها بانک برای پرداخت هزینه سفارش
         {
id: 1,
name: "ملت",
icon: "http://fpanel.ir/banks/mellat.png"
         }
	// ...
      ]
      },
items: [				// لیست محصولات داخل فاکتور
         {
name: "موبایلاسمبلی",
num: 1,
price: 670000,
pro_code: "mobile888",
weight: 200,
option: ""
         }
      ]
   }
   }
}

نکته مهم :

اگر سفارش پرداخت پس از تحويل در محل (COD) باشد در اين مرحله كار به اتمام رسيده است ولي اگر سفارش نقدي آنلاين باشد دو حالت پيش مي آيد:
1- در خروجي پايان ثبت سفارش ما ليست درگاه هاي بانكها را براي شما ارسال كنيم كه در اين حالت ادامه مراحل پرداخت با متدهاي پرداخت آنلاين بايد استفاده شوند و شما باید لیست درگاه ها را به کاربر نمایش داده تا کاربر بتواند درگاه مورد نظر را انتخاب کرده و بتواند از طریق درگاهبانك و با متدهاي پرداخت كه در ادامه همين مستندات آمده است هزینه سفارش را آنلاين پرداخت نماید.
2- در خروجي پايان ثبت سفارش ما ليست درگاه هاي بانكها را تحويل ندهيم و خالي باشد كه در اين حالت كار ثبت سفارش نقدي به اتمام رسيده است و در اين حالت قرار است مراحل خريد و پرداخت آنلاين بانكي بعداً براي خريدار از طرف فروشنده پيگيري شود و پس از تأييد فروشنده لينك ادامه پرداخت به خريدار اطلاعرساني خواهد شد.

دریافت فرم ارجاع به درگاه (pay)

در این مرحله شما باید شناسه درگاه بانكي كه در مرحله ثبت سفارش نقدي توسط خريدار انتخاب شده است ( مقدار فیلد id درگاه های بانکی ) و شماره فاکتور و یک آدرس به عنوان آدرس callback (براي برگشت از سايت بانك به سايت فروشنده) ، به متد pay ارسال کنید تا وب سرویس فرم ارجاع به درگاه را ایجاد و برای شما برگرداند.

آدرس وب سرويس :

براي پايداري وب سرويس ها سه سرور داريم كه يكي از اين سه آدرس را به دلخواه مي توانيد استفاده نمائيد.

روش ارسال داده ها آدرسهاي وب سرویس
POST http://webservice1.link/ws/v1/rest/payment/pay.json
http://webservice2.link/ws/v1/rest/payment/pay.json
http://webservice3.link/ws/v1/rest/payment/pay.json

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

پارامتر نوع توضیحات اجباری
api string کلید API *
factor int شناسه سفارش *
bank int شناسه بانک *
callback string آدرس برگشت از سايت بانک به سايت فروشنده *

پارامترهاي خروجي :

{
  "code": 0,
  "message": "",
  "result": "<form><!--   --></form>"	// فرم ارجاع کاربر به درگاه
}

در صورتی که اجرای متد به صورت موفقیت آمیز بود شما باید مقدار result رو در صفحه چاپ کنید تا فرم ارجاع کاربر به درگاه نمایش داده شود و خريدار روي دكمه انجام تراكنش آنلاين بانكي كليك خواهد كرد و وارد سايت بانك خواهد شد تا مراحل پرداخت را در سايت بانك انجام دهد.

بررسی صحت پرداخت (checkPay)

بعد از اتمام پرداخت توسط خریدار, خریدار از سايت بانك به آدرسی که شما در مرحله ی قبل به عنوان callback به وب سرویس پاس داده اید , برگشت داده می شود و شما حتماًبايد از متد checkPay استفاده کنید تا تراكنش آنلاين بانكي با موفقيت به پايان برسد ودر نتيجه کد رهگیری سفارش و در صورتی که سفارش مجازی باشد , لیست فایل هابراي كاربر نمايش داده خواهد شد.

آدرس وبسرويس :
براي پايداري وب سرويس ها سه سرور داريم كه يكي از اين سه آدرس را به دلخواه مي توانيد استفاده نمائيد.

روش ارسال داده ها آدرسهاي وب سرویس
POST http://webservice1.link/ws/v1/rest/payment/checkPay.json
http://webservice2.link/ws/v1/rest/payment/checkPay.json
http://webservice3.link/ws/v1/rest/payment/checkPay.json

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

در هنگام برگشت خریدار از درگاه بانکی دو پارامتر _i و sb نیز به آدرس callback شما پاس داده می شود که برای بررسی پرداخت نیاز به این پارامتر ها دارید.

پارامتر نوع توضیحات اجباری
api string کلید API *
paymentId int شناسه پرداخت (پارامتر _i) *
ref string کد ارجاع(پارامتر sb) *
factor string شماره فاكتور سفارش *

پارامترهاي خروجي :

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

{
  "code": 0,
  "message": "",
  "result": {
    "id": "00000",					// شناسه پرداخت
    "verify": 1,					// وضعیت پرداخت
    "message": "تراکنش باموفقیت انجام شد",		// پیغام وضعیت
    "code": "109314767064"			// کد رهگیری برای پرداخت های موفق
  }
}

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

{
  "code": 0,
  "message": "",
  "result": {
    "id": "14116",
    "verify": 1,
    "message": "تراکنش باموفقیت انجام شد",
    "code": "109314767064",			// کد رهگیری برای پرداخت های موفق
"links": {
         "error": 0,
         "message": [
	{
	      "name": "file name",
	      "size": "200 KB",
	      "mime": "pdf",
	      "count": "بدونمحدودیت",
	      "expire": "1394/04/24 10:25:00",
	      "link": "http://DOWNLOAD_LINK"
	}
           ]
     }
  }
}

verify : در صورتی که پرداخت موفقیت آمیز باشد مقدار 1 و در صورت عدم موفقیت در تراكنش آنلاين بانكي مقدار 0 برخواهد گرداند.

در سفارشات محصولات مجازي در صورتی که پرداخت با موفقیت انجام شده باشد لینک دانلود محصولات مجازی خریداری شده در اندیس links اطلاعات مربوط به لینک ها نمایش داده می شود. این اندیس دارای بخش error و message است که اگر به هر دلیلی برای ایجاد لینک خطایی رخ داده باشد مقدار error برابر 1 می شود و مقدار message متن خطا است و در صورتی که لینک با موفقیت ایجاد شده باشند مقدار error برابر 0 و مقدار message آرایه از اطلاعات لینک ها است.

ادامه پرداخت (سعي مجدد)

سفارشات نقدي آنلاين (orderPay و continuePay)

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

قبل از استفاده از این متدcontinuePay شما باید با استفاده از متد orderPay شرایط سفارش برای ادامه پرداخت را بررسی کنید. در صورتی که می توان برای ادامه پرداخت سفارش اقدام کرد كه در خروجی این متد لیست درگاه ها به عنوان جواب بازگردانده شود

آدرس وب سرویس orderPay برای بررسی شرایط سفارش :

براي پايداري وبسرويسها سه سرور داريم كه يكي از اين سه آدرس را به دلخواه مي توانيد استفاده نمائيد.

روش ارسال داده ها آدرسهاي وب سرویس
POST http://webservice1.link/ws/v1/rest/order/orderPay.json
http://webservice2.link/ws/v1/rest/order/orderPay.json
http://webservice3.link/ws/v1/rest/order/orderPay.json

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

پارامتر نوع توضیحات اجباری
api string کلید API *
factor string شناسه سفارش *

پارامترهای خروجي :

{
  "code": 0,
  "message": "",
  "result": {
    "vaziat": "معلق",				// وضعیت فعلی سفارش
    "factor": "22-00000-000000-000000",		// شماره فاکتور
    "barcode": "",				// بارکد پستی سفارش
    "order_type": "product",			// نوع سفارش
    "price": 886970,				// جمع کل هزینه سفارش
    "remainder_price": 886970,			// مبلغ باقیمانده
    "pay_price": 0,				// جمع کل مبلغ پرداخت شده
    "banks": [					// لیست درگاه ها
      {
        "id": 1,
        "name": "بانك ملت",
        "logo":"http://fpanel.ir/themes/frotel/images/logo/bank/mellat-logo.png"
      },
      {
        "id": 2,
        "name": "بانك ملي",
        "logo": "http://fpanel.ir/themes/frotel/images/logo/bank/melli-logo.png"
      }
    ]
  }
}

در صورتی که سفارش شرایط لازم برای ادامه پرداخت را دارا بود شما باید لیست درگاه ها را به خریدار نشان بدهید تا خریدار برای ادامه پرداخت ، يك درگاه مورد نظرش را انتخاب کند.
بعد از انتخاب درگاه توسط خریدار شما باید متد continuePay را فراخوانی کنید.

آدرس وب سرويس continuePay برای ادامه پرداخت:

براي پايداري وبسرويسها سه سرور داريم كه يكي از اين سه آدرس را به دلخواه مي توانيد استفاده نمائيد.

روش ارسال داده ها آدرسهاي وب سرویس
POST http://webservice1.link/ws/v1/rest/payment/continuePay.json
http://webservice2.link/ws/v1/rest/payment/continuePay.json
http://webservice3.link/ws/v1/rest/payment/continuePay.json

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

پارامتر نوع توضیحات اجباری
api string کلید API *
factor string شماره فاکتور *
bank int شناسه بانک *
callback string آدرس بازگشت از بانک *

پارامترهای خروجي :

{
  "code": 0,
  "message": "",
  "result": "<form><!--   --></form>"	// فرم ارجاع کاربر به درگاه
}

نکته مهم :
برای بررسی صحت پرداخت پس از برگشت از سايت بانك حتماً بايد از متد checkPay كه در صفحات قبلي كامل توضيح داده شد، استفاده شود وگرنه تراكنش خطادار ثبت خواهد شد و پول به حساب خريدار برگشت خواهد خورد.

رهگيري سفارشات (tracking)

با استفاده از این متد شما می توانید وضعیت یک سفارش را با جزئيات كامل رهگيري و دریافت نمایید.

آدرس وب سرويس:

براي پايداري وبسرويس ها سه سرور داريم كه يكي از اين سه آدرس را به دلخواه مي توانيد استفاده نمائيد.

روش ارسال داده ها آدرسهاي وب سرویس
POST http://webservice1.link/ws/v1/rest/order/tracking.json
http://webservice2.link/ws/v1/rest/order/tracking.json
http://webservice3.link/ws/v1/rest/order/tracking.json

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

پارامتر نوع توضیحات اجباری
api string کلید API *
factor string شماره سفارش *

پارامترهای خروجي :

{
  "code": 0,
  "message": "",
  "result": {
    "customer": "تست اپراتورفروتل",			// اطلاعات خریدار
    "order": {
      "factor": "22-000000-000000-000000",		// شماره فاکتور
      "barcode": "",					// بارکد رهگیری پست
      "status": "معلق",					// وضعیت فعلی سفارش
      "date": "1394/05/03 - 10:57",			// تاریخ ثبت سفارش
      "change_date": "1394/05/03 - 10:57",		// تاریخ آخرین تغییر وضعیت
      "price": 906590,					// جمع کل سفارش
      "buy_type": 1,					// نوع پرداخت - 0= پرداخت در محل , 1 = نقدی
      "desc": "",
      "type": 1						// نوع سفارش 
    },
    "seller": [],						// اطلاعات فروشنده
    "payment": {
      "message": "پرداخت شماانجام نشده است.",
      "pay_link": "http://byst.ir/payment/ContinuePay?factor=22000000000000000000"
    }
  }
}

نکته :
اطلاعات فروشنده در صورتی نمایش داده می شود که سفارش ارسال شده باشد.
در صورتی که سفارش نقدی باشد و خطایی در پرداخت هزینه سفارش رخ داده باشد اطلاعات مورد نیاز در قسمت payment قرار می گیرد , که pay_link لینک ادامه پرداخت است و باید به خریدار این لینک نمایش داده شود.