Nhanh.vn Open API
v2
Trang chủHướng dẫn sử dụngApps
Search
⌃K
Links

Tính phí vận chuyển

Tính phí cho 1 đơn

  • /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

Key
Type
Description
fromCityName
string (required)
Tên thành phố của kho gửi hàng (Lấy từ /api/shipping/location).
fromDistrictName
string (required)
Tên quận huyện của kho gửi hàng (Lấy từ /api/shipping/location)
toCityName
string (required)
Tên thành phố của khách nhận hàng (Lấy từ /api/shipping/location)
toDistrictName
string (required)
Tên quận huyện của khách nhận hàng (Lấy từ /api/shipping/location)
codMoney
int (optional)
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 (optional)
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 (optional)
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 (optional)
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 (optional)
Chiều dài gói hàng tính theo cm.
width
int (optional)
Chiều rộng gói hàng tính theo cm.
height
int (optional)
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.

Tính phí cho nhiều đơn

  • /api/shipping/multifee: Tính năng này dùng để tính phí vận chuyển cho nhiều đơn hàng (thường dùng nếu website của bạn là mô hình sàn, cho phép khách mua từ nhiều shop khác nhau). 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.

Request

data = [
// Đơn hàng 1
[
"fromCityName" => "TP. HCM",
"fromDistrictName" => "Quận 1",
"toCityName" => "Hà nội",
"shippingWeight" => 800,
"toDistrictName" => "Hoàn Kiếm",
"codMoney" => 1250000
],
// Đơn hàng 2
[
"fromCityName" => "TP. HCM",
"fromDistrictName" => "Quận 3",
"toCityName" => "Hà nội",
"shippingWeight" => 2000, // 2000 gr = 2 kg
"toDistrictName" => "Hoàn Kiếm",
"codMoney" => 4950000
],
...
]
Chú ý: Hỗ trợ tối đa tính phí cho 10 đơn hàng cùng lúc.
Param
Type
Description
fromCityName
string (required)
Tên thành phố của kho gửi hàng (Lấy từ /api/shipping/location)
fromDistrictName
string (required)
Tên quận huyện của kho gửi hàng (Lấy từ /api/shipping/location)
toCityName
string (required)
Tên thành phố của khách nhận hàng (Lấy từ /api/shipping/location)
toDistrictName
string (required)
Tên quận huyện của khách nhận hàng (Lấy từ /api/shipping/location)
codMoney
int (optional)
Giá trị của đơn hàng (Tổng giá nhân số lượng sản phẩm trong đơn hàng) dùng để tính phí thu tiền hộ, 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 (optional)
Tổng trọng lượng của đơn hàng tính bằng gram (Tổng toàn bộ shipping weight của các sản phẩm trong đơn hàng). Hiện tại Nhanh.vn hỗ trợ đơn hàng tối đa 100000 gr (100 kg).
productIds
array (optional)
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.vn.
carrierIds
array (optional)
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], mặc định nếu bạn không truyền carrierIds thì hệ thống sẽ trả về bảng giá của tất cả các hãng
length
int (optional)
Chiều dài gói hàng tính theo cm (Dùng cho hàng cồng kềnh, có kích thước >= 30cm).
width
int (optional)
Chiều rộng gói hàng tính theo cm (Dùng cho hàng cồng kềnh, có kích thước >= 30cm).
height
int (optional)
Chiều cao gói hàng tính theo cm (Dùng cho hàng cồng kềnh, có kích thước >= 30cm).
API này có 2 tình huống:
  • Website của bạn tự tính tổng trọng lượng shippingWeight của đơn hàng này.
  • 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.
    Chú ý: 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.
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

Response

  • The response: JSON decode the response to get the structure:
data = [
// kết quả tính phí cho đơn hàng 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ộ
"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
"isRequiredInsurance" => 1 | 0 // Biến đánh dấu bảng giá có bắt buộc mua bảo hiểm hay không
},
// kết quả tính phí cho đơn hàng 2
{
"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ộ
"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
"isRequiredInsurance" => 1 | 0 // Biến đánh dấu bảng giá có bắt buộc mua bảo hiểm hay không
}
// ...
]
Shipping - Previous
Thành phố, quận huyện
Next - Bill
Phiếu xuất nhập kho
Last modified 3mo ago