Tính cước phí

• Lấy danh sách dịch vụ vận chuyển và phí vận chuyển tương ứng từ một hoặc nhiều hãng vận chuyển, dựa trên thông tin người gửi, người nhận và kiện hàng.

• Hỗ trợ: Lấy bảng giá từ một hoặc nhiều hãng vận chuyển trong cùng một request.

• Mặc định: Nếu không truyền carrierIds, hệ thống sẽ tự động lấy bảng giá từ tất cả các hãng hỗ trợ (Ahamove, Grab Express, GreenSM ...).

Request

• Xem common request params.

• Xem Postman sample.

curl --location 'https://ship.open.nhanh.vn/v3.0/shipment/rate?businessId={{businessId}}&appId={{appId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "sender": {
        "name": "Nguyễn Văn A",
        "mobile": "0901234567",
        "shippingLocation": {
            "locationVer": "v2",
            "provinceId": 1,
            "wardId": 100,
            "address": "123 Nguyễn Trãi, Thanh Xuân, Hà Nội",
            "longitude": 105.804567,
            "latitude": 21.001234
        }
    },
    "receiver": {
        "name": "Trần Thị B",
        "mobile": "0912345678",
        "shippingLocation": {
            "locationVer": "v2",
            "provinceId": 48,
            "wardId": 12345,
            "address": "456 Lê Lợi, Hải Châu, Đà Nẵng",
            "longitude": 108.212345,
            "latitude": 16.067890
        }
    },
    "products": [
        {
            "name": "Áo thun cotton",
            "quantity": 2,
            "price": 150000,
            "weight": 300
        }
    ],
    "weight": 1500,
    "packageDimensions": {
        "width": 30,
        "height": 20,
        "length": 40
    },
    "codAmount": 650000,
    "description": "Thời trang nam nữ",
    "carrierIds": [31, 18, 37],
    "serviceTypes": [5],
    "carrierExtraServices": {
        "allowTest": true,
        "declaredSetting": true,
        "declaredAmount": 500000
    },
    "shipFeeBy": "sender"
}'

Body

Key	Type	Description
sender	object $^{\color{red}*}$	Thông tin người gửi. Xem Sender
receiver	object $^{\color{red}*}$	Thông tin người nhận. Xem Receiver
products	array	Danh sách sản phẩm trong đơn hàng. Xem Products
weight	int $^{\color{red}*}$	Khối lượng thực tế của đơn hàng (gram). Xem Quy tắc tính khối lượng
packageDimensions	object	Kích thước kiện hàng (cm). Xem Package Dimensions
codAmount	int	Số tiền thu hộ (COD), đơn vị VND. Mặc định: 0
description	string	Mô tả đơn hàng
carrierIds	array[int]	Danh sách ID hãng vận chuyển. Không bắt buộc - nếu không truyền sẽ lấy tất cả hãng Express delivery
serviceTypes	array[int]	Loại dịch vụ vận chuyển (type từ bảng carrier_services). Xem Service Types. Không bắt buộc - khuyến nghị truyền [5] (Express/Hỏa tốc)
carrierExtraServices	object	Các dịch vụ bổ sung. Xem Carrier Extra Services
shipFeeBy	string	Người trả phí: "sender" (mặc định) hoặc "receiver"

Service Types

Loại dịch vụ vận chuyển.

Value	Type	Description
5	Instant	Giao hỏa tốc (khuyến nghị)
10	Fast	Giao nhanh
15	Nomal	Giao tiêu chuẩn

Sender

Key	Type	Description
name	string $^{\color{red}*}$	Tên người gửi
mobile	string $^{\color{red}*}$	Số điện thoại người gửi
shippingLocation	object	Địa chỉ lấy hàng. Xem Shipping Location

Receiver

Key	Type	Description
name	string $^{\color{red}*}$	Tên người nhận
mobile	string $^{\color{red}*}$	Số điện thoại người nhận
shippingLocation	object	Địa chỉ giao hàng. Xem Shipping Location

Shipping Location

Đối tượng mô tả địa điểm (dùng cho cả sender và receiver).

Key	Type	Description
locationVer	string	Phiên bản dữ liệu địa chỉ: "v1" (3 cấp: provinceId + districtId + wardId) hoặc "v2" (2 cấp: provinceId + wardId). Mặc định: "v2"
provinceId	int	ID tỉnh/thành phố Lấy từ danh sách địa chỉ
districtId	int	ID quận/huyện Lấy từ danh sách địa chỉ
wardId	int	ID phường/xã Lấy từ danh sách địa chỉ
address	string	Địa chỉ chi tiết (số nhà, tên đường)
longitude	number	Kinh độ (dùng thay thế cho provinceId/districtId/wardId)
latitude	number	Vĩ độ (dùng thay thế cho provinceId/districtId/wardId)

Lưu ý:

• locationVer của sender và receiver phải giống nhau (cùng là "v1" hoặc cùng là "v2").

• Nếu dùng locationVer = "v1": bắt buộc truyền đủ provinceId, districtId, wardId.

• Nếu dùng locationVer = "v2": chỉ cần provinceId và wardId (không bắt buộc districtId).

• Nếu không truyền locationVer: mặc định là "v2".

Products

• Cấu trúc products được pass-through trực tiếp đến từng hãng vận chuyển. Các field con có thể khác nhau tùy hãng.

Key	Type	Description
name	string	Tên sản phẩm
quantity	int	Số lượng. Mặc định: 1
price	number	Đơn giá sản phẩm (VND)
weight	int	Khối lượng 1 sản phẩm (gram)

Package Dimensions

Key	Type	Description
width	int	Chiều rộng kiện hàng (cm)
height	int	Chiều cao kiện hàng (cm)
length	int	Chiều dài kiện hàng (cm)

Quy tắc tính khối lượng quy đổi:

Để đảm bảo tính phí vận chuyển chính xác dựa trên khối lượng thực tế của kiện hàng, hệ thống sử dụng quy tắc so sánh giữa:

• weight: Khối lượng thực tế của kiện hàng (gram).

• weightConverted: Khối lượng quy đổi từ kích thước kiện hàng (gram).

Công thức tính khối lượng quy đổi:

weightConverted = (length × width × height) / 6

(Đơn vị: cm → kết quả quy đổi ra gram)

Quy tắc lấy khối lượng tính phí:

billableWeight = max(weight, weightConverted)

Ví dụ:

• weight = 1500 (gram)

• packageDimensions: length=40, width=30, height=20 (cm)

• weightConverted = (40 × 30 × 20) / 6 = 4000 (gram)

• billableWeight = max(1500, 4000) = 4000 (gram)

Mục đích: Đảm bảo kiện hàng cồng kềnh (nhiều diện tích nhưng nhẹ) vẫn được tính phí hợp lý, tránh tình trạng vận chuyển kiện hàng lớn nhưng chỉ trả phí theo cân nặng thực tế.

Carrier Extra Services

Key	Type	Description
allowTest	bool	Cho phép người nhận thử hàng trước khi thanh toán. Mặc định: false
declaredSetting	bool	Bật khai giá hàng hóa. Mặc định: false
declaredAmount	int	Số tiền khai giá (VND). Mặc định: 0. Chỉ có hiệu lực khi declaredSetting = true
declaredService	object	Cấu hình chi tiết dịch vụ khai giá (tùy hãng). Pass-through trực tiếp

• Không phải tất cả hãng vận chuyển đều hỗ trợ mọi dịch vụ bổ sung.

Response

• Xem cấu trúc chung tại đây.

Failed response

• Xem các mã lỗi chung tại đây.

Các mã lỗi riêng của API này:

Mã lỗi	Ý nghĩa
ERR_CANNOT_CONNECT_CARRIER	Lỗi kết nối với hãng vận chuyển
ERR_CARRIER_RATE	Lỗi khi tính phí từ hãng vận chuyển

Successful response

{
  "code": 1,
  "data": [
    {
      "carrierId": "(int) ID hãng vận chuyển",
      "serviceId": "(int) ID dịch vụ trong hệ thống (dùng để đặt hàng sau này)",
      "serviceName": "(string) Tên dịch vụ hiển thị (VD: \"Siêu Tốc\", \"Giao hàng 4 giờ\")",
      "serviceCode": "(string) Mã dịch vụ từ hãng vận chuyển (VD: \"INSTANT\", \"SAME_DAY\")",
      "totalFee": "(int) Tổng phí vận chuyển từ hãng (chưa tính giảm giá, phụ phí setting). Đơn vị: VND",
      "shipFee": "(int) Phí ship gốc từ hãng. Đơn vị: VND",
      "customerShipFee": "(int) Phí khách hàng thực tế phải trả (đã tính KM, setting hệ thống). Đơn vị: VND",
      "totalCod": "(int) Số tiền thu hộ (COD). Đơn vị: VND",
      "logo": "(string) URL logo hãng vận chuyển",
      "totalPay": "(int) Tổng thanh toán = customerShipFee + totalCod. Đơn vị: VND",
      "serviceType": "(string) Loại dịch vụ (VD: \"INSTANT\", \"SAME_DAY\")",
      "serviceDescription": "(string) Mô tả chi tiết dịch vụ",
      "valuePromotionCode": "(int) Giá trị khuyến mãi / voucher đã áp dụng. Đơn vị: VND",
      "promoMessage": "(string) Thông báo về khuyến mãi (lỗi áp dụng KM, v.v.)"
    },
    {
      "carrierId": "(int) ID hãng vận chuyển",
      "serviceId": "(int) ID dịch vụ trong hệ thống",
      "serviceName": "(string) Tên dịch vụ hiển thị",
      "serviceCode": "(string) Mã dịch vụ từ hãng",
      "totalFee": "(int) Tổng phí vận chuyển từ hãng. Đơn vị: VND",
      "shipFee": "(int) Phí ship gốc từ hãng. Đơn vị: VND",
      "customerShipFee": "(int) Phí khách hàng thực tế phải trả. Đơn vị: VND",
      "totalCod": "(int) Số tiền thu hộ (COD). Đơn vị: VND",
      "logo": "(string) URL logo hãng vận chuyển"
    }
  ],
  "messages": [],
  "errorCode": null
}

Lưu ý: Kết quả trả về là mảng các dịch vụ từ tất cả các hãng được yêu cầu (hoặc tất cả hãng instant delivery nếu không truyền carrierIds). Mỗi item trong mảng chứa thông tin phí của một dịch vụ cụ thể từ một hãng vận chuyển.