Vd về API chung

Phong Mai viết ngày 07/11/2015

External API:

1. Tạo đơn hàng

   Bên mình sẽ POST sang cho bạn 1 request ở địa chỉ vd: supership.vn/api/order với các thông tin như sau:

   {
       "access_token": "Token bên bác cấp cho bên bạn, có thể là 1 chuỗi random",
       "customer_id": "id hoặc username của khách hàng bên bạn đang sử dụng bên mình",
       "shipping_speed": "Tiết kiệm/Trong ngày/Hoả tốc/Hẹn giờ tuỳ vào dịch vụ bên bạn nếu có",
       "delivery_address": "Địa chỉ nơi cần giao hàng",
       "delivery_commune": "Phường/xã nếu có",
       "delivery_district": "Quận/Huyện nếu có",
       "delivery_city": "Thành phố, bên bạn chỉ làm HCM nên mặc định mình sẽ để là HCM hoặc theo  1 code nào đấy để thống nhất với cả Viettel và các bên khác"
   }
   

   Sau đấy bạn trả cho mình 1 số giá trị như sau:

   • Nếu thành công:

   {
       "success": true,
       "tracking_id": "Mã vận đơn mới vừa được cập nhập vào hệ thống",
       "shipping_cost": "Giá vận chuyển nếu bên bạn có thể ước tính được",
       "estimated_delivery_time": "Ước tính thời gian vận chuyển được nếu có"
   }
   

   • Nếu thất bại:

   {
       "success": false,
       "reason": "Lý do thất bại. Vd sai token, user bị vô hiệu hoá, thông tin thiếu, không đúng..."
   }
   

2. Update đơn hàng:
   Vd khi khách hàng mình muốn huỷ 1 đơn do khách hàng yêu cầu hoặc vì lí do gì đấy, mình sẽ PUT sang cho bên bạn ở địa chỉ supership.vn/api/tracking/tracking_id_muon_update với nội dung:

   {
       "new_status": "Cancelled/1/CANCEL... tuỳ 2 bên quy ước",
       "access_token": "như trên",
       "reason": "Lý do bên khách hàng cung cấp nếu có",
       "messsage": "Thông báo nếu thành công"
   }
   

   Bên bạn sẽ kiểm tra mã vận đơn này và trả về các lý do như:

   {
       "success": true/false,
       "message": "Nếu thành công, chỉ cần để mình field success hoặc thêm message thông báo đã thành công",
       "error": "Nếu thất bại thì cung cấp lý do. Vd đơn hàng đã được giao, đang trên đường..."
   }
   

3. Cung cấp trạng thái đơn hàng:
   Khách hàng có thể truy vấn trạng thái đường đi của đơn hàng, trong trường bên bạn không update sang cho mình hoặc update thất bại vì lý do gì đấy. Mình sẽ gọi sang GET tới supership.vn/api/tracking/tracking_id_muon_check kèm access_token ở Authorization header.

   Bạn sẽ trả về với nội dung bên bạn. Vd:

   {
       "id": "Mã vận đơn",
       "error": "Lý lo lỗi nếu có, nếu thành công thì bỏ qua",
       "current_status": "billing_received/in_transit/out_for_delivery/delivered/undeliverable/in_return/returned",
       "updates": [
           {
               "type": "billing_received",
               "location": "vị trí nếu có",
               "updated_at": "ISO Datetime xảy ra sự kiện vd: 9AM 7/11/2015 GMT"
           },
           {
               "type": "in_transit",
               "location": "vị trí nếu có",
               "updated_at": "thời gian xảy ra sự kiện vd: 10AM 7/11/2015 GMT"
           },
           {
               "type": "out_for_delivery",
               "location": "vị trí nếu có",
               "updated_at": "thời gian xảy ra sự kiện 15PM, 7/11/2015 GMT"
           },
           {
               "type": "delivered",
               "location": "vị trí nếu có",
               "updated_at": "thời gian xảy ra sự kiện vd: 18PM, 7/11/2015 GMT"
           }
    ]
   
   }
   

4. Gửi update sang bên mình:
   Khi bạn update 1 trạng thái nào đấy vd đã giao được hay trả được thì PUT sang API bên mình ở địa chỉ vd: pancake.vn/api/tracking/tracking_id_muon_update.

   Mình sẽ trả về như sau:

   "success": true/false,
   "error": "Lý do thất bại nếu có",
   "message": "Thông báo cập nhập thành công"
   

5. Ghi chú về phần access_token
   Phần này ở số lượng ít như hiện tại bạn có thể random 1 đoạn string cố định và mình sẽ limit những user có thể được sử dụng trong app bên mình. Hoặc bạn có thể tạo access_token cho từng user riêng như các nhà vận chuyển nước ngoài càng tốt. Khi đấy tự động hoá các khâu sẽ tiện hơn :D