Vận chuyển
Báo giá cước hãng vận chuyển
Lấy giá cước và thời gian giao dự kiến các dịch vụ của một carrier
Endpoint
POST /v1/shippingbillgateways/quote
Quyền:
inventory.dispatchprocess
Gọi sang hãng để báo giá các dịch vụ của một carrier cho một kiện hàng. Không ghi dữ liệu.
Hãng hỗ trợ
Hiện hỗ trợ báo giá: GHN và ViettelPost. Các hãng khác trả lỗi error_not_supported.
Request Body
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
company_id | int | Có | ID công ty |
shipping_carrier_id | int | Có | ID carrier |
from | object | Không | Địa chỉ gửi (xem cấu trúc địa chỉ). Bỏ trống thì dùng địa chỉ người gửi trong cấu hình carrier |
to | object | Có | Địa chỉ nhận. Cần ít nhất province_id, province hoặc address |
parcel | object | Có | Kiện hàng: weight (gram, bắt buộc > 0), length, width, height (cm) |
cod | int | Không | Tiền thu hộ (VND) |
insurance_value | int | Không | Giá trị khai báo bảo hiểm (VND) |
service_code | string | Không | Chỉ báo giá cho một dịch vụ cụ thể của hãng |
Cấu trúc địa chỉ (from, to):
| Trường | Kiểu | Mô tả |
|---|---|---|
province_id, district_id, ward_id | int | ID địa chính Hubport |
province, district, ward | string | Tên địa chính (dùng khi không có ID) |
address | string | Số nhà, đường |
Response Schema
HTTP 200 - JSON Object
| Trường | Kiểu | Mô tả |
|---|---|---|
carrier_id | int | ID carrier |
api_type | int | Loại hãng |
services | array | Danh sách dịch vụ có giá |
services[].service_code | string | Mã dịch vụ của hãng |
services[].service_name | string | Tên dịch vụ |
services[].fee | int | Tổng cước (VND) |
services[].fee_detail | object | Chi tiết cước theo khoản. GHN: total, main, insurance, cod, coupon, remote_area, pick_station, return |
services[].estimated_delivery_from | int | Thời gian giao dự kiến sớm nhất (Unix timestamp, 0 = không rõ) |
services[].estimated_delivery_to | int | Thời gian giao dự kiến muộn nhất (Unix timestamp, 0 = không rõ) |
Error Codes
| Mã lỗi | Mô tả |
|---|---|
error_parcel_weight_required | Thiếu parcel.weight (HTTP 422) |
error_to_address_required | Thiếu địa chỉ nhận (HTTP 422) |
error_not_supported | Hãng chưa hỗ trợ báo giá (HTTP 422) |
error_quote_failed | Hãng không trả được báo giá (HTTP 422) |
error_ghn_service_code_invalid | GHN: service_code không hợp lệ (HTTP 422) |
error_not_found | Carrier không tồn tại hoặc không thuộc công ty của bạn (HTTP 404) |
error_role_not_available | Không có quyền inventory.dispatchprocess (HTTP 403) |
Lỗi chi tiết do hãng trả về (sai địa chỉ, vượt giới hạn kích thước/khối lượng...) cũng được trả trong mảng error.
Ví dụ
curl -X POST "https://api.hubport.vn/v1/shippingbillgateways/quote" \
-H "Authorization: <JWT>" \
-H "Content-Type: application/json" \
-d '{
"company_id": 1001,
"shipping_carrier_id": 12,
"to": { "province_id": 1, "district_id": 9, "address": "25 Lý Thường Kiệt" },
"parcel": { "weight": 800, "length": 20, "width": 15, "height": 10 },
"cod": 350000
}'{
"carrier_id": 12,
"api_type": 19,
"services": [
{
"service_code": "2",
"service_name": "Hàng nhẹ",
"fee": 32000,
"fee_detail": { "total": 32000, "main": 30000, "insurance": 0, "cod": 2000, "coupon": 0, "remote_area": 0, "pick_station": 0, "return": 0 },
"estimated_delivery_from": 1760140800,
"estimated_delivery_to": 1760227200
}
]
}