Tính phí vận chuyển

• Nhanh.vn hỗ trợ 2 hình thức kết nối với các hãng vận chuyển:

  • Dùng bảng giá qua cổng vận chuyển của Nhanh.vn

  • Dùng bảng giá do shop tự đăng ký riêng với hãng vận chuyển.

• Tùy theo shop đang sử dụng hình thức kết nối vận chuyển nào, bạn cần gọi đúng API tính phí phù hợp, để lấy các thông tin cần thiết dùng cho API tạo đơn hàng

Dùng cổng Nhanh.vn

• /api/shipping/fee: Tính năng này dùng để tính phí vận chuyển cho một đơn hàng. Mỗi khi khách hàng vào trang Giỏ hàng, hoặc ở bước thanh toán, website của bạn có thể call API này để tính phí vận chuyển cho đơn hàng và hiển thị chi tiết tổng tiền của đơn hàng bao gồm cả phí vận chuyển và phí thu tiền hộ (nếu khách hàng chọn hình thức thanh toán khi nhận hàng).

• Mặc định hệ thống sẽ trả về bảng giá của tất cả các hãng vận chuyển, chú ý 1 hãng vận chuyển có thể có nhiều bảng giá (VD Giao nhanh / Giao chậm).

Request

• Xem common request params.

• Xem Postman sample - Tính phí theo cân nặng

• Xem Postman sample - Tính phí theo sản phẩm

• Các key của mảng data array dùng để tạo data json string:

Key	Type	Description
fromCityName	string ${\color{red}*}$	Tên thành phố của kho gửi hàng (Lấy từ /api/shipping/location).
fromDistrictName	string ${\color{red}*}$	Tên quận huyện của kho gửi hàng (Lấy từ /api/shipping/location)
toCityName	string ${\color{red}*}$	Tên thành phố của khách nhận hàng (Lấy từ /api/shipping/location)
toDistrictName	string ${\color{red}*}$	Tên quận huyện của khách nhận hàng (Lấy từ /api/shipping/location)
codMoney	int	Giá trị tiền cần thu hộ của đơn hàng (Tổng giá nhân số lượng sản phẩm trong đơn hàng), set 0 nếu đơn hàng này không cần thu tiền hộ (VD tình huống khách đã chuyển khoản trước)
shippingWeight	int	Tổng trọng lượng các sản phẩm của đơn hàng tính bằng gram. Hiện tại Nhanh.vn hỗ trợ đơn hàng tối đa 100000 gr (100 kg).
productIds	array	Danh sách các ID sản phẩm được đồng bộ từ Nhanh.vn sang website của bạn (idNhanh), dùng để tính khối lượng đơn hàng theo giá trị sản phẩm khai báo bên Nhanh (Truyền biến này thì không cần truyền shippingWeight), cấu trúc: [productId1 => quantity, productId2 => quantity, ...], hệ thống sẽ lấy quantity nhân với khối lượng sản phẩm khai báo trên Nhanh.vn để tính tổng khối lượng của đơn hàng
carrierIds	array	Dùng để giới hạn các hãng vận chuyển muốn dùng (Lấy từ /api/shipping/carrier). VD: [5,7,8,9]
length	int	Chiều dài gói hàng tính theo cm.
width	int	Chiều rộng gói hàng tính theo cm.
height	int	Chiều cao gói hàng tính theo cm.

Chú ý: API này có 2 tình huống:

• Nếu các sản phẩm được đồng bộ từ Nhanh.vn sang website của bạn (Nhanh.vn đã có thông tin shippingWeight của các sản phẩm này): website của bạn có thể gửi sang 1 mảng productIds, Nhanh.vn sẽ tự tính toán tổng trọng lượng của đơn hàng này.

• Website của bạn tự tính tổng trọng lượng shippingWeight của đơn hàng này.

  Nếu bạn có truyền sang các tham số length, width, height: Nhanh.vn sẽ tính toán trọng lượng của đơn hàng theo công thức quy ra kg: A = dài * rộng * cao / 6000 (so sánh số A và shippingWeight tham số nào lớn hơn sẽ lấy theo tham số đó để tính toán cước phí) và trả về kết quả đánh dấu nếu gói hàng thuộc loại hàng cồng kềnh.

Response

• JSON string: mảng danh sách các dịch vụ vận chuyển

Key	Type	Description
code	int	1 = success or 0 = failed
messages	array	is an array of error messages if code = 0
data	array	is an array of all supported shipping services

• data is an array of all supported shipping services

data = [
    // service 1
    {
        "carrierId" => int, // id hãng vận chuyển
        "carrierName" => string, // tên hãng vận chuyển
        "logo" => string, // image src, logo hãng vận chuyển
        "serviceId" => int, // id dịch vụ vận chuyển
        "serviceTypeName" => string, // loại dịch vụ (Giao nhanh | Giao chậm)
        "serviceName" => string, // tên dịch vụ vận chuyển
        "serviceDescription" => string, // mô tả dịch vụ vận chuyển
        "estimatedDeliveryTime" => int, // Thời gian dự kiến giao hàng
        "shipFee" => int, // phí vận chuyển
        "codFee" => int, // phí thu tiền hộ (phát sinh khi bạn cần giao hàng thu tiền), mỗi hãng vận chuyển có quy định riêng về việc được miễn phí hoặc mức phí khác nhau.
        "declaredFee" => int, // phí bảo hiểm (khi mua dịch vụ khai giá để đền bù trong tình huống hãng vận chuyển làm mất hàng)
        "isBulkyGoods" => 1 | 0 // Biến đánh dấu hàng cồng kềnh nếu cân nặng hoặc kích thước của đơn hàng đạt tới mức hàng cồng kềnh theo quy định của từng hãng
        "isRequiredInsurance" => 1 | 0 // Biến đánh dấu bảng giá có bắt buộc mua bảo hiểm hay không
    },
    {
      // service 2
    },
    // service 3, 4, 5 ...
  ]

Chú ý:

• Khi isRequiredInsurance == 1, nghĩa là dịch vụ đó luôn bắt buộc mua bảo hiểm, dù đơn hàng không chọn mua bảo hiểm thì tổng tiền cước phải trả cho hãng vận chuyển luôn có khoản phí bảo hiểm này, nên bạn cần chú ý cộng thêm khoản tiền này vào tổng cước.

Dùng tự kết nối

• /api/shipping/feeselfconnect: Tính năng này dùng để tính phí vận chuyển của 1 hãng vận chuyển mà doanh nghiệp của bạn đã cấu hình kết nối trên trang quản trị của Nhanh.vn. Mỗi khi khách hàng vào trang Giỏ hàng, hoặc ở bước thanh toán, website của bạn có thể call API này để tính phí vận chuyển cho đơn hàng và hiển thị chi tiết tổng tiền của đơn hàng bao gồm cả phí vận chuyển (nếu khách hàng chọn hình thức thanh toán khi nhận hàng).

Request

• Xem các common request params

• Các key của mảng data array dùng để tạo data json string:

Key	Type	Description
carrierId	int $^{{\color{red}*}}$	ID hãng vận chuyển cần tính phí vận chuyển (Lấy từ /api/shipping/carrier).
fromMobile	string	Số điện thoại của kho gửi hàng (required khi carrierId = 5 (Giao hàng nhanh) ).
fromCityName	string $^{{\color{red}*}}$	Tên thành phố của kho gửi hàng (Lấy từ /api/shipping/location).
fromDistrictName	string $^{{\color{red}*}}$	Tên quận huyện của kho gửi hàng (Lấy từ /api/shipping/location)
fromWardName	string	Tên phường/xã của kho gửi hàng (Lấy từ /api/shipping/location)
fromAddress	string	Địa chỉ của kho gửi hàng (Bắt buộc truyền khi tính phí vận chuyển hãng vận chuyển Giao hàng nhanh)
toCityName	string $^{{\color{red}*}}$	Tên thành phố của khách nhận hàng (Lấy từ /api/shipping/location)
toDistrictName	string $^{{\color{red}*}}$	Tên quận huyện của khách nhận hàng (Lấy từ /api/shipping/location)
toWardName	string	Tên phường/xã của khách nhận hàng (Lấy từ /api/shipping/location). Bắt buộc truyền khi tính phí vận chuyển của một trong các hãng vận chuyển: Giao hàng nhanh, JT Express, Shopee Express
toAddress	string	Địa chỉ của khách nhận hàng
codMoney	int	Giá trị tiền cần thu hộ của đơn hàng (Tổng giá nhân số lượng sản phẩm trong đơn hàng), set 0 nếu đơn hàng này không cần thu tiền hộ (VD tình huống khách đã chuyển khoản trước)
shippingWeight	int	Tổng trọng lượng các sản phẩm của đơn hàng tính bằng gram.
productIds	array	Danh sách các ID sản phẩm được đồng bộ từ Nhanh.vn sang website của bạn (idNhanh), dùng để tính khối lượng đơn hàng theo giá trị sản phẩm khai báo bên Nhanh (Truyền biến này thì không cần truyền shippingWeight), cấu trúc: [productId1 => quantity, productId2 => quantity, ...], hệ thống sẽ lấy quantity nhân với khối lượng sản phẩm khai báo trên Nhanh.vn để tính tổng khối lượng của đơn hàng

Chú ý:

• Nếu các sản phẩm được đồng bộ từ Nhanh.vn sang website của bạn (Nhanh.vn đã có thông tin shippingWeight của các sản phẩm này): website của bạn có thể gửi sang 1 mảng productIds, Nhanh.vn sẽ tự tính toán tổng trọng lượng của đơn hàng này.

• Website của bạn tự tính tổng trọng lượng shippingWeight của đơn hàng này.

Response

• JSON string: mảng danh sách các dịch vụ vận chuyển

Key	Type	Description
code	int	1 = success or 0 = failed
messages	array	is an array of error messages if code = 0
data	array	is an array of all supported shipping services

• data is an array of all supported shipping services

data = [
    // service 1
    {
        "carrierAccountId" => int, // ID tài khoản kết nối
        "carrierAccountName" => string, // Tên gợi nhớ kết nối
        "carrierShopId" => int, // ID cửa hàng trên hệ thống hãng vận chuyển (nếu có)
        "carrierName" => string, // Tên hãng vận chuyển
        "logo" => string, // Image src, logo hãng vận chuyển
        "serviceCode" => string, // Mã dịch vụ vận chuyển
        "serviceName" => string, // Tên dịch vụ vận chuyển
        "customerShipFee" => int, // Phí ship báo khách
        "totalFee" => int, // Tổng phí
        "shipFee" => int, // Phí vận chuyển
    },
    {
      // service 2
    },
    // service 3, 4, 5 ...
  ]