CONNECT CARRIER TUTORIAL

I. Chuẩn bị

1. Access_token

- Cần chuẩn bị access_token trước khi làm việc với API Carrier Service.

- Scope: com.write_shippings, com.read_shippings.

- Tham khảo các tài liệu sau để biết thêm về cách truyền scope và lấy access_token:

+ https://docs.haravan.com/blogs/omni/create-app-and-connect-api

+ https://docs.haravan.com/blogs/omni/tutorial-use-scope

+ https://docs.haravan.com/blogs/omni/connect-webhook

2. Ngrok (Dùng ngork nếu không có tên miền online)

- Ngrok (https://ngrok.com/) là tool tạo ra cổng kết nối từ public internet đến port máy tính local.

- Sau khi tải ngrok về, chạy file ngrok.exe.

- Chạy lệnh ngrok http 3000 (port tùy ý, ví dụ ở đây dùng port 3000).

Lưu ý:

+ 1 tên miền ngrok có thể tồn tại 8h, sau đó phải chạy lệnh lại để lấy tên miền mới.

+ Và tên miền sử dụng bắt buộc phải là https://

+ Có thể truy cập http://localhost:4040/inspect/http để xem thông tin các request chạy trên ngrok.

Ngrok

II. Tạo và sử dụng kết nối nhà vận chuyển

1. Bước 1: Tạo kết nối với nhà vận chuyển:

- Ví dụ, dùng postman để demo việc tạo kết nối.

- Tạo request

Method

URL

POST

https://apis.haravan.com/com/carrier_services.json

Header:  
  Content-Type: application/json
  Authorization: Bearer #{access_token} 
Body raw json:
{
    "carrier_service": {
       "active": true,
       "tracking_url": "https://caed9339b51c.ngrok.io/tracking_url",
       "create_order_url": " https://caed9339b51c.ngrok.io/create_order_url",
       "get_order_detail_url": "https://caed9339b51c.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url":"https://caed9339b51c.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://caed9339b51c.ngrok.io/cancel_order_url",
        "get_by_external_code_url": "https://caed9339b51c.ngrok.io/get_by_external_code_url",        
        "name": "My Carrier",
        "carrier_service_type": "api",
        "service_discovery": false
      }
 }

Tạo nhà kết nối với nhà vận chuyển

- Response nhận được (chú thích các field tham khảo ở đây).

Tạo nhà kết nối với nhà vận chuyển

- Các lỗi có thể xảy ra

Status

Response

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

2. Bước 2: Chuẩn bị môi trường nhận request từ Haravan

- Ở các bước sau, Haravan sẽ gửi request qua những URL mà nhà vận chuyển đã cung cấp khi tạo kết nối ở bước 1.

- Vì vậy bên phía nhà vận chuyển cũng sẽ phải chuẩn bị trước một môi trường để nhận và xử lý request từ Haravan.

- Ở ví dụ này, sẽ dựng một app nhận request và xử lý trong môi trường nodejs.

- Tham khảo bộ source demo ở link.

3. Bước 3: Chứng thực data từ Haravan

- Sau khi đã có môi trường, nhà vận chuyển cần phải có phương thức chứng thực data được gửi từ Haravan đến để bảo đảm rằng data được truyền đến là chính xác.

- Nhà vận chuyển cần lưu lại App ID (đây là id có được từ việc tạo app và get access_token).

Chứng thực data từ Haravan

- Để xác thực data từ phía haravan post vào app, sử dùng hàm HMAC với thuật toán “sha256” mã hóa data + App ID ra được mã hash, sau đó lấy mã hash mã hóa lần nữa với Base64 sẽ ra được một chuỗi kết quả.

- Lấy chuỗi kết quả có được so sánh X-Haravan-Hmac-Sha256 nằm ở header của request đến từ Haravan.

Chứng thực data từ Haravan

- Nếu bằng là true thì tiếp tục xử lý, nếu không bằng là false trả về 401.

4. Bước 4: Tạo đơn hàng và sử dụng chức năng giao hàng

- Tạo một đơn hàng trên seller và sử dụng chức năng giao hàng.

Tạo đơn hàng và sử dụng chức năng giao hàng

- Sau khi chọn giao hàng thì chọn nhà vận chuyển.

Tạo đơn hàng và sử dụng chức năng giao hàng

5. Bước 5: App nhận request từ Haravan lấy gói vận chuyển

- Khi bấm vào chọn nhà vận chuyển, Haravan sẽ hiện danh sách các nhà vận chuyển đã tạo kết nối, và request tới nhà vận chuyển (app demo) để lấy các gói vận chuyển thông qua get_shipping_rates_url.

App nhận request từ Haravan lấy gói vận chuyển

- Request đến nhà vận chuyển (chú thích các field tham khảo ở đây).

Method

URL

POST

get_shipping_rates_url

Body raw json
{
  "origin": {
   "country": null,
   "country_code": null,
   "country_name": null,
   "province": "Hồ Chí Minh",
   "province_code": "HC",
   "district": "Quận 7",
   "district_code": "HC472",
   "ward": "Phường Tân Phong",
   "ward_code": "27490",
   "address1": null,
   "address2": null,
   "zip": null,
   "city": null,
   "phone": null,
   "name": null
  },
  "destination": {
   "country": null,
   "country_code": null,
   "country_name": null,
   "province": "Hồ Chí Minh",
   "province_code": "HC",
   "district": "Quận 11",
   "district_code": "HC476",
   "ward": null,
   "ward_code": null,
   "address1": null,
   "address2": null,
   "zip": null,
   "city": null,
   "phone": null,
   "name": null
  },
  "items": null,
  "cod_amount": 500000,
  "total_grams": 10
}

- Nếu dùng ngrok, có thể truy cập http://localhost:4040/inspect/http để xem các thông tin của các request dùng trên URL của ngrok.

App nhận request từ Haravan lấy gói vận chuyển

- Nhà vận chuyển (app demo) nhận được thông tin đơn hàng sẽ tiến hành xử lý.

- Sau đó response về Haravan (chú thích các field tham khảo ở đây).

Status

Response

200

{
“error”: true/false,
“message”: “message lỗi nếu có”,
“data”: {
  "rates": [
    {
      "service_id": 123456,
      "service_name": "Fast shipping",
      "service_code": "fast",
      "currency": "vnd",
      "total_price": 1111,
      "phone_required": true,
      "min_delivery_date": new Date(),
      "max_delivery_date": new Date(),
      "description": "description"
    },
    {
      "service_id": 456789,
      "service_name": "Save shipping ",
      "service_code": "save",
      "currency": "vnd",
      "total_price": 1112,
      "phone_required": false,
      "min_delivery_date": null,
      "max_delivery_date": null,
      "description": "description"
    }
  ]
 }
}    

6. Bước 6: Chọn gói vận chuyển

- Haravan nhận được danh sách gói vận chuyển và hiển thị ở seller.

Chọn gói vận chuyển

- Sau khi chọn gói phù hợp, chọn “Giao hàng”.

Chọn gói vận chuyển

7. Bước 7: Kiểm tra vận đơn bằng external code

- Khi chọn “Giao hàng”, Haravan gửi request để kiểm tra vận đơn của đơn hàng ở nhà vận chuyển (app demo) bằng external_code. Việc này giúp tránh trường hợp một đơn hàng có nhiều vận đơn.

- Việc kiểm tra vận đơn sẽ thông qua get_by_external_code_url

Method

URL

GET

get_by_external_code_url

Query :
external_code=200000007877_1042708389_1050341700

Ví dụ: 
https://caed9339b51c.ngrok.io/get_by_external_code_url?external_code=200000007877_1042708389_1050341700

- Nếu dùng ngrok, có thể truy cập http://localhost:4040/inspect/http để xem các thông tin của các request dùng trên URL của ngrok.

Kiểm tra vận đơn bằng external code

- Nhà vận chuyển (app demo) nhận được thông tin external_code sẽ tiến hành kiểm tra trong hệ thống. Lúc này sẽ có hai trường hợp xảy ra :

+ Trường hợp 1: Đơn hàng đã có vận đơn thì sẽ response thông tin vận đơn.

200

// Thành công
{
"error": false,
"message": "",
"data": {
      "tracking_number": "123456",
      "shipping_fee": 123123,
      "tracking_url": "https://abc.com/tracking_url",
      "cod_amount": 500000
 }
}								

200

// Thất bại
{
"error": true,
"message": "Đã có lỗi xảy ra ...... ",
"data": null
}

+ Trường hợp 2: Đơn hàng chưa có vận đơn thì trả status 200 và data null để Haravan nhận biết. Haravan sau đó sẽ all tiếp link create_order_url.

200

// Thành công
{
"error": false,
"message": "",
"data": null
}

200

// Thất bại
{
"error": true,
"message": "Đã có lỗi xảy ra ...... ",
"data": null
}

Lưu ý: Nếu response ra status 500 thì Haravan sẽ ngừng quá trình xử lý.

8. Bước 8: Tạo vận đơn

- Khi nhấn “Giao hàng”, Haravan sẽ gửi một request tạo vận đơn cho nhà vận chuyển (app demo) thông qua create_order_url.

- Request đến nhà vận chuyển (chú thích các field tham khảo ở đây).

Method

URL

POST

create_order_url

Body raw json
{
  "origin": {
    "country": null,
    "country_code": null,
    "country_name": null,
    "province": "Hồ Chí Minh",
    "province_code": "HC",
    "district": "Quận Tân Bình",
    "district_code": "HC479",
    "ward": "Phường 08",
    "ward_code": "26998",
    "address1": "ExampleShop",
    "address2": null,
    "zip": null,
    "city": null,
    "phone": "0901559123",
    "name": "Địa điểm mặc định"
  },
  "destination": {
    "country": null,
    "country_code": null,
    "country_name": null,
    "province": "Hồ Chí Minh",
    "province_code": "HC",
    "district": "Quận Bình Thạnh",
    "district_code": "HC480",
    "ward": "",
    "ward_code": "",
     "address1": "199 Điện Biên Phủ Quận Bình Thạnh TP.Hồ Chí Minh",
    "address2": null,
    "zip": null,
    "city": null,
    "phone": "0988081073",
    "name": "Dũng"
  },
  "items": [
    {
      "name": "Seiko 5  SNK809",
      "sku": "SNK809",
      "quantity": 1,
      "grams": 250,
      "price": 1800000,
      "product_id": 1141842719,
      "variant_id": 1052003974
    }
  ],
  "cod_amount": 1800000,
  "total_grams": 250,
  "external_order_id": 1122188249,
  "external_fulfillment_id": 1036984261,
  "location_id": 0,
  "note": null,
  "shipping_rate_id": 123456,
  "external_code": "1000406318_1122188249_1036984261",
  "insurance_price": 0,
  "payment_method": null,
  "package_length": 0,
  "package_width": 0,
  "package_height": 0,
  "coupon_code": null,
  "is_drop_off": false,
  "is_view_before": false
}

- Nếu dùng ngrok, có thể truy cập http://localhost:4040/inspect/ để xem các thông tin của các request dùng trên URL của ngrok.

Tạo vận đơn

- Nhà vận chuyển (app demo) nhận được thông tin đơn hàng và thông tin sản phẩm sẽ tiến hành tạo vận đơn.

- Response vận đơn về cho Haravan (chú thích các field tham khảo ở đây).

200

// Thành công
{
"error": false,
"message": "",
"data": {
         "tracking_number": "123456",
         "shipping_fee": 123123,
          "tracking_url": "https://abc.com/tracking_url",
          "cod_amount": 500000
}
}
	

200

// Thất bại
{
"error": true,
"message": "Đã có lỗi xảy ra ...... ",
"data": null
}

- Tạo vận chuyển thành công cho một đơn hàng.

Tạo vận đơn

9. Bước 9: Lấy chi tiết đơn hàng

- Tại một thời điểm nào đó, Haravan sẽ gọi đến nhà vận chuyển để lấy chi tiết đơn hàng, nhằm cập nhật trạng thái và thông tin vận đơn. Vì vậy bước này sẽ dùng postman để demo.

- Gửi request đến nhà vận chuyển kèm theo tracking_number thông qua get_order_detail_url.

Method

URL

POST

get_order_detail_url

Body raw json:
{
    "tracking_number":"123456"
}

Lấy chi tiết đơn hàng

- Nhà vận chuyển (app demo), sau khi nhận được request sẽ đem tracking_number đi query để lấy data của vận đơn và gửi lại cho Haravan.

- Response thông tin vận đơn về Haravan (chú thích các field tham khảo ở đây).

200

// Thành công
{
     "error":false,
     "message”: "",
     "data":{
           "tracking_number: 123456",
           "shipping_fee": 10000,
           "tracking_url": "https://abc.com/tracking_url",
           "cod_amount": 5000,
           "status": "Delivered",
          "cod_status": "CODPaid"
        }
}	

200

//Thất bại
{
      "error": true,
      "message": "message error",
      "data": null
}

Lấy chi tiết đơn hàng

10. Bước 10: Hủy vận đơn

- Trong trường hợp seller cập nhập trạng thái vận chuyển (fulfillment) thành hủy giao hàng thì đồng thời Haravan sẽ gửi request đến nhà vận chuyển (app demo) kèm theo tracking_number thông qua cancel_order_url.

Hủy vận đơn

- Request đến nhà vận chuyển.

Body raw json:
{
    "tracking_number":"123456"
}

- Nếu dùng ngrok, có thể truy cập http://localhost:4040/inspect/http để xem các thông tin của các request dùng trên URL của ngrok

Hủy vận đơn

- Nhà vận chuyển (app demo), sau khi nhận được request sẽ đem tracking_number đi query để cập nhật trạng thái cho vận đơn và gửi lại cho Haravan.

- Response về cho Haravan sau khi đã xử lý (chú thích các field tham khảo ở đây).

200

// Thành công
{
     "error":false,
      "message": "",
      "data":{
          "tracking_number": "123456",
          "shipping_fee": 10000,
          "tracking_url": "https://abc.com/tracking_url",
          "cod_amount": 5000,
          "status": "Cancel"
      }
}

200

//Thất bại
{
      "error": true,
      "message": "message error",
      "data": null
}

- Haravan sẽ nhận được data vận đơn với statuscancel như hình nếu request thành công.

Hủy vận đơn

11. Bước 11: Nhà vận chuyển cập nhật trạng thái vận chuyển

- Nhà vận chuyển có thể chủ động cập nhật trạng thái vận chuyển, bằng cách gửi request đến API Haravan.

- Note

+ Tạo đơn mới nếu đơn cũ đã bị hủy.

+ Cần order id và fulfillment id trước khi cập nhật.

+ Chuẩn bị access_control trước khi gọi API cập nhật.

+ Tìm hiểu chú thích của field fulfillment ở đây.

11.1 Update status picking

- API

Update status picking

- Response

Update status picking

11.2 Update status delivering

- API

Update status delivering

- Response

Update status delivering

11.3 Update status delivered

- API

Update status delivered

- Response

Update status delivered

11.4 Update status not_meet_customer

- API

Update status not_meet_customer

- Response

Update status not_meet_customer

11.5 Update status waiting_for_return

- API

Update status waiting_for_return

- Response

Update status waiting_for_return

11.6 Update status return:

- API

Update status return

- Response

Update status return

11.7 Update status paid

- API

Update status paid

- Response

Update status paid

11.8 Update status receipt

- API

Update status receipt

- Response

Update status receipt

11.9 Update status cancel:

- API

Update status cancel

- Response

Update status cancel

III. API carrier service:

1. Api lấy danh sách nhà vận chuyển

- API lấy danh sách các nhà vận chuyển đã tạo kết nối với Haravan.

- Bao gồm

+ Những nhà vận chuyển mặc định.

+ Những nhà vận chuyển đã tạo bằng API.

1.1 Request

Method

URL

GET

https://apis.haravan.com/com/carrier_services.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

1.2 Response

- Chú thích các field tham khảo ở đây

Status

Response

200

{
    "carrier_services": [
       {
            "id": 8175831,
            "carrier_service_id": 0,
            "carrier_name": "Khác",
            "carrier_code": "other",
            "is_connected": true,
            "view_before_items": false,
            "view_dimension": false,
            "view_coupon_code": false,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        },
        {
            "id": 8175813,
            "carrier_service_id": 11,
            "carrier_name": "Giao Hàng Nhanh",
            "carrier_code": "ghn2018",
            "is_connected": false,
            "view_before_items": true,
            "view_dimension": true,
            "view_coupon_code": true,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        },
        {
            "id": 8175846,
            "carrier_service_id": 15,
            "carrier_name": "ViettelPost2018",
            "carrier_code": "viettelpost2018",
            "is_connected": false,
            "view_before_items": true,
            "view_dimension": false,
            "view_coupon_code": false,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        },
        {
            "id": 8175843,
            "carrier_service_id": 8,
            "carrier_name": "Ninja Van",
            "carrier_code": "ninjavan",
            "is_connected": true,
            "view_before_items": false,
            "view_dimension": true,
            "view_coupon_code": false,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        }   
    ]
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

2. Api lấy thông tin kết nối với nhà vận chuyển

- API lấy thông tin nhà vận chuyển đã kết nối với Haravan theo id.

2.1 Request

Method

URL

GET

https://apis.haravan.com/com/carrier_services/#{id}.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

id

Tham số carrier_service_id nhận được từ API lấy danh sách nhà vận chuyển

2

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2.2 Response

- Chú thích các field tham khảo ở đây

Status

Response

200

{
    "carrier_service": {
        "active": true,
        "tracking_url": "https://caed9339b51c.ngrok.io/tracking_url",
        "create_order_url": "https://caed9339b51c.ngrok.io/create_order_url",
        "get_order_detail_url": "https://caed9339b51c.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://caed9339b51c.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://caed9339b51c.ngrok.io/cancel_order_url",
          "get_by_external_code_url ": "https://caed9339b51c.ngrok.io/get_by_external_code_url", 
        "name": " My Carrier",
        "carrier_service_type": "api",
        "service_discovery": false,
        "created_at": "2019-06-07T08:02:49.047Z",
        "updated_at": "2019-06-07T08:02:49.047Z",
        "id": 10115763,
        "options": {
            "has_drop_off": false,
            "has_insurance": false,
            "has_view_before": false,
            "has_payment_method": false,
            "has_dimension": false,
            "has_transport_type": false,
            "has_use_coupon_code": false
        }
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

3. Api tạo kết nối với nhà vận chuyển

- API tạo kết nối với nhà vận chuyển không có trong danh sách kết nối với Haravan.

- Lưu ý:

+ Mỗi access_token chỉ có thể tạo kết nối với một nhà vận chuyển.

+ Nếu muốn tạo kết nối với nhà vận chuyển khác thì phải xóa kết nối đã tạo trước đó.

3.1 Request

Method

URL

POST

https://apis.haravan.com/com/carrier_services.json

- Chú thích các field tham khảo ở đây

Header:  Content-Type: application/json
Authorization: Bearer #{access_token} 
Request raw json:
   { 
      "carrier_service": {
           "active": true,
            "tracking_url": "https://caed9339b51c.ngrok.io/tracking_url",
            "create_order_url": "https://caed9339b51c.ngrok.io/create_order_url",
            "get_order_detail_url": "https://caed9339b51c.ngrok.io/get_order_detail_url",
            "get_shipping_rates_url": "https://caed9339b51c.ngrok.io/get_shipping_rates_url",
            "cancel_order_url": "https://caed9339b51c.ngrok.io/cancel_order_url",
            "get_by_external_code_url": "https://caed9339b51c.ngrok.io/get_by_external_code_url", 
           "name": " My Carrier", 
            "carrier_service_type": "api",
            "service_discovery": false
         }
     }

3.2 Response

- Chú thích các field tham khảo ở đây

Status

Response

200

   {
    "carrier_service": {
        "active": true,
        "tracking_url": "https://caed9339b51c.ngrok.io/tracking_url",
        "create_order_url": "https://caed9339b51c.ngrok.io/create_order_url",
        "get_order_detail_url": "https://caed9339b51c.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://caed9339b51c.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://caed9339b51c.ngrok.io/cancel_order_url",
          "get_by_external_code_url ": "https://caed9339b51c.ngrok.io/get_by_external_code_url", 
        "name": "My Carrier",
        "carrier_service_type": "api",
        "service_discovery": false,
        "created_at": "2019-06-07T09:02:29.6164737Z",
        "updated_at": "2019-06-07T09:02:29.6164848Z",
        "id": 10116264,
        "options": {
            "has_drop_off": false,
            "has_insurance": false,
            "has_view_before": false,
            "has_payment_method": false,
            "has_dimension": false,
            "has_transport_type": false,
            "has_use_coupon_code": false
        }
     }
   }

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

4. Api cập nhật kết nối với nhà vận chuyển

- API cập nhật thông tin nhà vận chuyển đã kết nối với Haravan theo id.

- Lưu ý:

+ Mỗi access_token chỉ cập nhật được kết nối với nhà vận chuyển được tạo bởi access_token.

4.1 Request

Method

URL

PUT

https://apis.haravan.com/com/carrier_services/#{id}.json

- Chú thích các field tham khảo ở đây

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}
Request raw json:
   { 
      "carrier_service": {
           "active": true,
            "tracking_url": "https://caed9339b51c.ngrok.io/tracking_url",
            "create_order_url": "https://caed9339b51c.ngrok.io/create_order_url",
            "get_order_detail_url": "https://caed9339b51c.ngrok.io/get_order_detail_url",
            "get_shipping_rates_url": "https://caed9339b51c.ngrok.io/get_shipping_rates_url",
            "cancel_order_url": "https://caed9339b51c.ngrok.io/cancel_order_url",
            "get_by_external_code_url ": "https://caed9339b51c.ngrok.io/get_by_external_code_url", 
           "name": " My Carrier update", 
            "carrier_service_type": "api",
            "service_discovery": false
         }
   }

4.2 Response

- Chú thích các field tham khảo ở đây

Status

Response

200

{
    "carrier_service": {
        "active": true,
        "tracking_url": "https://caed9339b51c.ngrok.io/tracking_url",
        "create_order_url": "https://caed9339b51c.ngrok.io/create_order_url",
        "get_order_detail_url": "https://caed9339b51c.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://caed9339b51c.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://caed9339b51c.ngrok.io/cancel_order_url",
         "get_by_external_code_url ": "https://caed9339b51c.ngrok.io/get_by_external_code_url", 
        "name": " My Carrier update",
        "carrier_service_type": "api",
        "service_discovery": false,
        "created_at": "2019-06-07T09:51:12.832Z",
        "updated_at": "2019-06-07T09:55:29.8186851Z",
        "id": 10116582
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

5. Api xóa kết nối với nhà vận chuyển

- API xóa nhà vận chuyển đã kết nối với Haravan theo id.

- Lưu ý:

+ Mỗi access_token chỉ xóa được kết nối với nhà vận chuyển được tạo bởi access_token.

5.1 Request

- Chú thích các field tham khảo ở đây

Method

URL

DELETE

https://apis.haravan.com/com/carrier_services/#{id}.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

id

Tham số carrier_service_id nhận được từ API lấy danh sách nhà vận chuyển

2

access_token (string)

Lấy được khi cài ứng dụng và get access_token

5.2 Response

Status

Response

200

[]

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

IV. Chú thích các field:

1. Object carrier khi get list:

1.1 Object mẫu

{
    "carrier_services": [
        {
            "id": 16387308,
            "carrier_service_id": 16,
            "carrier_name": "My Carrier",
            "carrier_code": "",
            "is_connected": true,
            "view_before_items": false,
            "view_dimension": false,
            "view_coupon_code": false,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        }
    ]
}    

1.2 Chú thích

STT

Thuộc tính

Require

Maxlength

Mô tả

1

id (number)

 

20

id nhà vận chuyển

2

carrier_service_id (number)

 

20

Mã nhà vận chuyển

3

carrier_name (string)

 

200

Tên nhà vận chuyển

4

carrier_code (string)

 

255

Mã nhà vận chuyển

5

is_connected (bool)

 

 

Trạng thái kết nối:

+ true: đã kết nối

+ false: chưa kết nối

6

view_before_items (bool)

 

 

Cho xem trước

7

view_dimension (bool)

 

 

Cấu hình kích thước

8

view_coupon_code (bool)

 

 

Cấu hình mã khuyến mãi

9

view_sender_name (bool)

 

 

Hiện tên người gửi

10

view_sender_phone (bool)

 

 

Hiện số điện thoại người gửi

11

view_insurance (bool)

 

 

Có bảo hiểm

12

view_drop_off (bool)

 

 

Cho phép gửi hàng tại điểm

13

transport_types (array)

 

 

Hình thức vận chuyển

2. Object carrier khi get detail:

2.1 Object mẫu

{
    "carrier_services": {
        "active": true,
        "tracking_url": "https://a5e914256a19.ngrok.io/tracking_url",
        "create_order_url": "https://a5e914256a19.ngrok.io/create_order_url",
        "get_order_detail_url": "https://a5e914256a19.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://a5e914256a19.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://a5e914256a19.ngrok.io/cancel_order_url",
        "get_by_external_code_url": null,
        "name": "My Carrier",
        "carrier_service_type": "api",
        "service_discovery": false,
        "created_at": "2021-05-04T08:27:15.761Z",
        "updated_at": "2021-05-04T08:27:15.761Z",
        "id": 16387308,
        "options": {
            "has_drop_off": false,
            "has_insurance": false,
            "has_view_before": false,
            "has_payment_method": false,
            "has_dimension": false,
            "has_transport_type": false,
            "has_use_coupon_code": false
        }
    }
}

2.2 Chú thích

STT

Thuộc tính

Require

Maxlength

Mô tả

1

active (bool)

true

 

Có được hiển thị hay không

2

tracking_url (string)

true

500

Link xem chi tiết vận đơn

3

create_order_url (string)

true

500

Link tạo vận đơn

4

get_order_detail_url (string)

true

500

Link lấy chi tiết vận đơn

5

get_shipping_rate_url (string)

true

500

Link lấy danh sách gói vận chuyển

6

cancel_order_url (string)

true

500

Link hủy vận đơn

7

get_by_external_code_url (string)

true

500

Link lấy chi tiết vận đơn theo external_code

8

name (string)

true

200

Tên nhà vận chuyển

9

carrier_service_type (string)

true

255

Loại nhà vận chuyển

(default là api, không sửa được)

10

service_discovery (bool)

false

 

Có cho truyền dữ liệu để test API nhà vận chuyển hay không ( tạm thời lưu db chứ chưa dùng đến). Truyền vào: false

11

options (object)

false

 

Cấu hình vận chuyển

11.1

has_drop_off (bool)

false

 

Cho phép gởi hàng tại điểm

11.2

has_insurance (bool)

false

 

Có bảo hiểm

11.3

has_view_before(bool)

false

 

Cho xem trước

11.4

has_payment_method (bool)

false

 

Cấu hình phương thức thanh toán

11.5

has_dimension (bool)

false

 

Cấu hình kích thước

11.6

has_transport_type (bool)

false

 

Cấu hình phương thức vận chuyển

11.7

has_use_coupon_code (bool)

false

 

Cấu hình mã khuyến mãi

3. Object Haravan POST sang nhà vận chuyển:

3.1 Object mẫu

 {
  "origin": {
    "country": null,
    "country_code": null,
    "country_name": null,
    "province": "Hồ Chí Minh",
    "province_code": "HC",
    "district": "Quận Tân Bình",
    "district_code": "HC479",
    "ward": "Phường 08",
    "ward_code": "26998",
    "address1": "ExampleShop",
    "address2": null,
    "zip": null,
    "city": null,
    "phone": "0901559123",
    "name": "Địa điểm mặc định"
  },
  "destination": {
    "country": null,
    "country_code": null,
    "country_name": null,
    "province": "Hồ Chí Minh",
    "province_code": "HC",
    "district": "Quận Bình Thạnh",
    "district_code": "HC480",
    "ward": "",
    "ward_code": "",
     "address1": "199 Điện Biên Phủ Quận Bình Thạnh TP.Hồ Chí Minh",
    "address2": null,
    "zip": null,
    "city": null,
    "phone": "0988081073",
    "name": "Dũng"
  },
  "items": [
    {
      "name": "Seiko 5  SNK809",
      "sku": "SNK809",
      "quantity": 1,
      "grams": 250,
      "price": 1800000,
      "product_id": 1141842719,
      "variant_id": 1052003974
    }
  ],
  "cod_amount": 1800000,
  "total_grams": 250,
  "external_order_id": 1122188249,
  "external_fulfillment_id": 1036984261,
  "location_id": 0,
  "note": null,
  "shipping_rate_id": 123456,
  "external_code": "1000406318_1122188249_1036984261",
  "insurance_price": 0,
  "payment_method": null,
  "package_length": 0,
  "package_width": 0,
  "package_height": 0,
  "coupon_code": null,
  "is_drop_off": false,
  "is_view_before": false
}

3.2 Chú thích

STT

Thuộc tính

Require

Maxlength

Mô tả

1

shop_id (string)

 

20

Id shop tạo vận đơn

2

origin (object)

 

 

Nơi chuyển

2.1

country (string)

 

200

Quốc gia

2.2

country_code (string)

 

5

Mã quốc gia

2.3

country_name (string)

 

200

Tên quốc gia

2.4

province (string)

 

200

Tên tỉnh thành

2.5

province_code (string)

 

5

Mã Tỉnh/Thành

2.6

district (string)

 

200

Tên Quận/Huyện

2.7

district_code (string)

 

5

Mã Quận/Huyện

2.8

ward (string)

 

200

Tên Phường/Xã

2.9

ward_code (string)

 

100

Mã Phường/Xã

2.10

address1(string)

 

1000

Địa chỉ 1

2.11

address2 (string)

 

1000

Địa chỉ 2

2.12

zip (string)

 

100

Zip

2.13

city (String)

 

200

Thành phố

2.14

phone (string)

 

12

Số điện thoại

2.15

name (string)

 

200

Tên

3

destination (object)

 

 

Nơi nhận (Ý nghĩa các field trong destination tương tự như origin.)

4

items (array)

 

 

List sản phẩm cần vận chuyển

4.1

name (string)

 

200

Tên sản phẩm

4.2

sku (string)

 

100

Mã SKU

4.3

quantity (int)

 

11

Số lượng

4.4

grams (decimal)

 

Giá

Trọng lượng trên sản phẩm

4.5

price (decimal)

 

18

Giá

4.6

product_id (long)

 

18

Mã sản phẩm

4.7

variant_id (long)

 

20

Mã biến thể của sản phẩm

5

cod_amount (decimal)

 

18

Số tiền thu hộ COD

6

total_grams (decimal)

 

18

Tổng khối lượng các item

7

external_order_id (long)

 

20

Order id của shop

8

external_fulfillment_id (long)

 

20

Mã vận chuyển

9

external_store_id (long)

 

20

Mã shop

10

external_code (string)

 

70

= external_store_id + ”_” + external_order_id + “_” + external_fulfillment_id

11

note (string)

 

255

Ghi chú

12

shipping_rate_id (int)

 

11

Là service_id nhận được khi post lấy danh sách gói vận chuyển

4. Object danh sách gói vận chuyển:

4.1 Object mẫu

 {
    "error": false,
    "message": null,
    "data" : {
      "rates": [
        {
           "service_id": 123456,
           "service_name": "Fast shipping",
           "service_code": "fast",
           "currency": "vnd",
           "total_price": 10000,
           "phone_required": true,
           "min_delivery_date": "2021-05-04T08:27:15.761Z",
           "max_delivery_date": "2021-05-04T08:27:15.761Z",
           "description": ""
        },
        {
           "service_id": 456789,
           "service_name": "Save shipping",
           "service_code": "save",
           "currency": "vnd",
           "total_price": 5000,
           "phone_required": false,
           "min_delivery_date": null,
           "max_delivery_date": null,
           "description: ""
        }
      ]
    }
}

4.2 Chú thích

STT

Thuộc tính

Require

Maxlength

Mô tả

1

error (bool)

true

 

Status báo lỗi

2

message (string)

true

500

Thông báo

3

Data (object)

true

 

Dữ liệu trả về

3.1

Rates (array)

true

 

Danh sách gói vận chuyển

3.1.1

service_id (int)

true

11

Id gói vận chuyển

3.1.2

service_name (string)

true

200

Tên gói vận chuyển

3.1.3

service_code (string)

true

255

Mã gói vận chuyển

3.1.4

currency (string)

true

255

Loại tiền tệ

Default VNĐ

3.1.5

total_price (decimal)

true

18

Tổng tiền

3.1.6

phone_required (bool)

true

 

Có bắt buộc truyền số điện thoại không

3.1.7

min_delivery_date (datetime)

false

ISOString

Thời gian vận chuyển nhanh nhất Có thể null

3.1.8

Max_delivery_date (datetime)

false

ISOString

Thời gian vận chuyển chậm nhất Có thể null

3.1.9

description (string)

false

500

Miêu tả

5. Object vận đơn

5.1 Object mẫu

 {
    "error": false,
    "message": "",
    "data": {
       "tracking_number": "12345",
       "shipping_fee": 5000,
       "tracking_url": "https://abc.com/tracking_url/",
       "cod_amount": 5000,
       "status": "Delivered",
       "cod_status": "CODPaid"
    }
  }

										

5.2 Chú thích

STT

Thuộc tính

Require

Maxlength

Mô tả

1

error (bool)

true

 

Status lỗi

2

message (string)

true

500

Thông báo lỗi

3

data (object)

true

 

Dữ liệu trả

3.1

tracking_number (string)

true

200

Mã vận đơn

3.2

shipping_fee (decimal)

true

18

Phí vận chuyển

3.3

tracking_url (string)

true

400

Link xem chi tiết vận đơn

3.4

cod_amount (decimal)

true

18

Số tiền thu hộ COD

3.5

status (string)

true

18

Trạng thái vận đơn:

+ Pending: Chờ xử lý,

+ ReadyToPick: Chờ lấy hàng,

+ Picking: Đang đi lấy,

+ Delivering: Đang giao hàng,

+ Delivered: Đã giao hàng,

+ Cancel: Hủy giao hàng,

+ Return: Chuyển hoàn,

+ NotMeetCustomer: Không gặp khách,

+ WaitingForReturn: Chờ chuyển hoàn

3.6

cod_status (string)

true

16

Trạng thái thu hộ COD:

+ None: Không thu hộ,

+ CODPending: Chờ xử lý,

+ CODPaid: Đã thu hộ,

+ CODReceipt: Đã nhận tiền,

+ CODNotReceipt: Chưa nhận tiền

6. Object fulfillment:

6.1 Object mẫu

 {
    "fulfillments": [
        {
            "created_at": "2021-04-27T11:01:41.732Z",
            "id": 1036985263,
            "order_id": 1122188249,
            "receipt": null,
            "status": "success",
            "tracking_company": "My Carrier",
            "tracking_company_code": null,
            "tracking_numbers": [
                "796085"
            ],
            "tracking_number": "796085",
            "tracking_url": "https://caed9339b51c.ngrok.io/tracking_url",
            "tracking_urls": [
                "https://caed9339b51c.ngrok.io/tracking_url"
            ],
            "updated_at": "2021-04-27T17:39:20.352Z",
            "line_items": [
                {
                    "fulfillable_quantity": 0,
                    "fulfillment_service": "Thủ công",
                    "fulfillment_status": "Đã hoàn thành",
                    "grams": 250.0000,
                    "id": 1036985263,
                    "price": 1800000.0000,
                    "product_id": 1023131986,
                    "quantity": 1,
                    "requires_shipping": true,
                    "sku": "SNK809",
                    "title": "Seiko 5  SNK809",
                    "variant_id": 1052003974,
                    "variant_title": "Default Title",
                    "vendor": "Seiko",
                    "name": "Seiko 5  SNK809",
                    "variant_inventory_management": null,
                    "properties": null,
                    "product_exists": true
                }
            ],
            "province": "Hồ Chí Minh",
            "province_code": "HC",
            "district": "Quận Bình Thạnh",
            "district_code": "HC480",
            "ward": null,
            "ward_code": null,
            "cod_amount": 1800000.0000,
            "carrier_status_name": "Hủy giao hàng",
            "carrier_cod_status_name": "Chưa nhận",
            "carrier_status_code": "cancel",
            "carrier_cod_status_code": "codpending",
            "location_id": 782632,
            "note": null,
            "carrier_service_package": 0,
            "carrier_service_package_name": "Fast shipping",
            "is_new_service_package": false,
            "coupon_code": "",
            "ready_to_pick_date": "2021-04-27T11:01:36Z",
            "picking_date": null,
            "delivering_date": null,
            "delivered_date": null,
            "return_date": null,
            "not_meet_customer_date": null,
            "waiting_for_return_date": null,
            "cod_paid_date": null,
            "cod_receipt_date": null,
            "cod_pending_date": null,
            "cod_not_receipt_date": null,
            "cancel_date": "2021-04-27T17:39:20.35Z",
            "is_view_before": null,
            "country": "Vietnam",
            "country_code": "VN",
            "zip_code": "",
            "city": null,
            "real_shipping_fee": 5000.0000,
            "shipping_notes": null,
            "total_weight": 250.0000,
            "package_length": 0.00,
            "package_width": 0.00,
            "package_height": 0.00,
            "boxme_servicecode": null,
            "transport_type": 0,
            "address": "199 Điện Biên Phủ Quận Bình Thạnh TP. Hồ Chí Minh",
            "sender_phone": null,
            "sender_name": null,
            "carrier_service_code": null,
            "from_longtitude": 0.0,
            "from_latitude": 0.0,
            "to_longtitude": 0.0,
            "to_latitude": 0.0,
            "sort_code": null,
            "is_drop_off": false,
            "is_insurance": false,
            "insurance_price": 0.0,
            "is_open_box": false,
            "request_id": null,
            "carrier_options": null,
            "note_attributes": null,
            "first_name": "Dũng",
            "last_name": null,
            "shipping_address": "199 Điện Biên Phủ Quận Bình Thạnh TP. Hồ Chí Minh",
            "shipping_phone": "0988081073"
        }
    ]
}

6.2 Chú thích

STT

Thuộc tính

Require

Maxlength

Mô tả

1

created_at (dateTime)

 

ISOString

Ngày tạo

2

id (long)

 

20

Id giao hàng

3

order_id (long)

 

20

Id đơn hàng được giao

4

Receipt (string)

 

 

 

5

Status (string)

 

 

Trạng thái giao hàng chờ xử lý pending, đang xử lý cancel, xử lý lỗi error, thành công

6

tracking_company (string)

 

18

Tên công ty vận chuyển.

+ "Giao Hàng Nhanh"

+ "VNPost"

+ "Khác"

+ "Viettel Post"

+ "ShipChung.vn"

+ "ProShip.vn"

+ "FlexShip"

+ "Giao hàng nhanh"

+ "DHL"

+ "Ninja Van"

+ "GrabExpress"

+ "AhaMove"

+ "ViettelPost2018"

+ "HCMPost2019"

7

tracking_company_code (string)

 

18

Mã NVC.

+ "ghn": Giao Hàng Nhanh

+ "vnpost": VNPost

+ "other": Khác

+ "viettelpost": Viettel Post

+ "shipchung": ShipChung.vn

+ "proship": ProShip.vn

+ "flexship": FlexShip

+ "ghn2018": Giao hàng nhanh

+ "dhl": DHL

+ "ninjavan": Ninja Van

+ "grabexpress": GrabExpress

+ "ahamove": AhaMove

+ "viettelpost2018": ViettelPost2018

+ "hcmpost2019": HCMPost2019

8

tracking_numbers (array)

 

 

Danh sách các mã theo dõi. Được cung cấp bởi công ty vận chuyển.

9

tracking_number (string)

 

200

Mã theo dõi

10

tracking_url (string)

 

400

Link tìm kiếm bản đồ vận chuyển

11

tracking_urls(array)

 

 

List link tìm kiếm bản đồ vận chuyển

12

updated_at (long)

 

20 chữ số

Thời điểm cập nhật vận chuyển

13

province (string)

 

200

Tỉnh thành

14

province_code (string)

 

5

Mã tỉnh thành

15

district (string)

 

200

Quận/Huyện

16

district_code (string)

 

5

Mã Quận/Huyện

17

ward (string)

 

100

Phường/Xã

18

ward_code (string)

 

100

Mã Phường/Xã

19

cod_amount (number)

 

20

Tiền thu hộ

20

carrier_status_name (string)

 

18

Tên và mã trạng thái vận chuyển

+ readytopick : Chờ lấy hàng

+ picking : Đang đi lấy

+ delivering : Đang giao hàng

+ delivered : Đã giao hàng

+ cancel : Hủy giao hàng

+ return : Chuyển hoàn

+ pending : Chờ xử lý

+ notmeetcustomer: Không gặp khách

+ waitingforreturn: Chờ chuyển hoàn

21

carrier_status_code (string)

 

18

22

carrier_cod_status_name (string)

 

11

Tên và mã trạng thái cod

+ none: Không

+ codpending: Chưa nhận

+ codpaid: Chưa nhận (chủ shop chưa nhận)

+ codreceipt: Đã nhận

23

carrier_cod_status_code (string)

 

11

24

location_id (number)

 

20

Mã chi nhánh lấy hàng

25

note (string)

 

255

Ghi chú

26

carrier_service_package (number)

 

20

Gói vận chuyển

27

carrier_service_package_name (string)

 

255

Tên gói vận chuyển

28

is_new_service_package (bool)

 

true/false

Nếu sử dụng gói mặc định

=> False, ngược lại là True

29

coupon_code (string)

 

100

Mã khuyễn mãi

30

ready_to_pick_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Sẵn sàng giao”

31

picking_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Chọn giao hàng”

32

delivering_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Đang giao hàng”

33

delivered_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Đã giao hàng”

34

return_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Trả hàng”

35

not_meet_customer_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Không gặp khách hàng”

36

waiting_for_return_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Chờ chuyển hoàn”

37

cod_paid_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Chờ nhận tiền thu hộ COD”

38

cod_receipt_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD”

39

cod_pending_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Đợi thu hộ COD”

40

cod_not_receipt_date (dateTime)

 

ISOString

Thời điểm chuyển qua trạng thái “Không đối soát tiền thu hộ COD”

41

is_view_before (bool)

 

true/false

Được xem hàng trước

42

country (string)

 

200

Quốc gia

43

country_code (string)

 

5

Mã quốc gia

44

zip_code (string)

 

5

Mã zip code quốc gia

45

city (string)

 

200

Thành phố

46

real_shipping_fee (number)

 

20

Phí vận chuyển thực

47

shipping_notes (string)

 

200

Ghi chú vận chuyển

48

total_weight (number)

 

20

Tổng khối lượng

49

package_length (number)

 

20

Chiều dài gói hàng

50

package_width (number)

 

20

Chiều rộng gói hàng

51

package_height (number)

 

20

Chiều cao gói hàng

52

boxme_servicecode (string)

 

100

Gói giao hàng của Shipchung.vn (chỉ sử dụng khi giao bằng Shipchung.vn)

53

transport_type (number)

 

1

Phương thức vận chuyển

+ 1: đường bộ (default)

+ 2: đường bay

54

address (string)

 

1000

Địa chỉ giao hàng

55

sender_phone (string)

 

12

SĐT người gửi

56

sender_name (string)

 

200

Tên người gửi

57

carrier_service_code (number)

 

20

Mã NVC

58

line_items (array)

 

 

List sản phẩm được vận chuyển

58.1

fulfillable_quantity

 

11

Số lượng sản phẩm giao hàng

58.2

fulfillment_service (string)

 

11

Dịch vụ giao hàng: “Thủ công”

58.3

fulfillment_status (string)

 

16

Trạng thái giao hàng:

+ null: Không giao hàng

+ not_fulfilled: Chưa hoàn thành

+ partial: Hoàn thành một phần

+ fulfilled: Đã hoàn thành

58.4

grams (number)

 

20

Khối lượng của sản phẩm

58.5

id (string)

 

20

Id Line Item

58.6

price (number)

 

20

Giá của sản phẩm trong line item

58.7

product_id (string)

 

20

Id sản phẩm

58.8

quantity (number)

 

20

Số lượng sản phẩm

58.9

requires_shipping (bool)

 

 

True: Có giao hàng

False: Không giao hàng

58.10

sku (string)

 

100

Mã SKU của sản phẩm

58.11

title (string)

 

255

Tên của sản phẩm

58.12

variant_id (string)

 

20

Id biến thể của sản phẩm

58.13

variant_title (string)

 

200

Tên biến thể của sản phẩm

58.14

vendor (string)

 

200

Nhà sản xuất của sản phẩm

58.15

name (string)

 

200

Tên sản phẩm và tên biến thể của sản phẩm

58.16

variant_inventory_management

 

200

Quản lý tồn kho biến thể của sản phẩm

58.17

properties(string)

 

200

Thuộc tính của sản phẩm

58.18

product_exists (bool)

 

 

True: Còn sản phẩm

False: Hết sản phẩm