> For the complete documentation index, see [llms.txt](https://apidocs.nhanh.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.nhanh.vn/v3/ship/rate.md). # 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](/v3/readme.md#request-params). * Xem [Postman sample](/v3/ship/rate.md). ```curl 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](#sender) | | receiver | object $$^{\color{red}\*}$$ | Thông tin người nhận. Xem [Receiver](#receiver) | | products | array | Danh sách sản phẩm trong đơn hàng. Xem [Products](#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](#package-dimensions) | | packageDimensions | object | Kích thước kiện hàng (cm). Xem [Package Dimensions](#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](#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](#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](#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) | ### 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ỉ](/v3/ship/location.md) | | districtId | int | ID quận/huyện [Lấy từ danh sách địa chỉ](/v3/ship/location.md) | | wardId | int | ID phường/xã [Lấy từ danh sách địa chỉ](/v3/ship/location.md) | | 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](/v3/readme.md#response). ### Failed response * Xem các mã lỗi chung [tại đây](/v3/readme.md#failed-response). 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 ```json { "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.