v2.shipping-order.preview
POST/shiip/public-api/v2/shipping-order/previewGọi qua 360: POST https://partner.quantri360.com/v1/ghn/shiip/public-api/v2/shipping-order/preview
Sắp mở. API này đã chạy thật qua 360 và đang được chốt giá — bạn có thể đọc tài liệu và chuẩn bị tích hợp trước.
Mô tả API
Xem trước vận đơn: cùng body và cùng cách kiểm tra như tạo đơn, trả phí vận chuyển chi tiết và thời gian giao dự kiến nhưng KHÔNG tạo đơn. Dùng để báo phí ship cho khách trước khi chốt đơn; nhận cả địa chỉ mới 2 cấp.
- Người gửi và địa chỉ hoàn mặc định theo hồ sơ cửa hàng của ShopId đã nối — 360 tự gắn header Token và ShopId.
- Gửi
shop_idtrong body thì phải trùng cửa hàng của kết nối; khác → 404. - Địa chỉ cũ 3 cấp: gửi đủ to_province_name / to_district_name / to_ward_name và
is_new_to_address = false.
Request
Địa chỉ
POST https://partner.quantri360.com/v1/ghn/shiip/public-api/v2/shipping-order/preview
Xác thực & gian hàng
| Tên | Vị trí | Kiểu | Mẫu | Mô tả |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 196560 | ShopId GHN đã nối (GET /v1/platforms). Mỗi brand một cửa hàng — có thể bỏ. shop_id trong body (vd available-services) phải trùng. |
Tham số request
| Tên | Vị trí | Kiểu | Bắt buộc | Mẫu | Mô tả |
|---|---|---|---|---|---|
| to_name | body | string | Có | nguoimua123 | Tên người nhận (≤ 1024). |
| to_phone | body | string | Có | 0901234567 | SĐT người nhận. |
| to_address | body | string | Có | Số 1 đường ABC | Địa chỉ đầy đủ (≤ 1024). |
| to_province_name | body | string | Có | Hồ Chí Minh | Tên tỉnh — hệ mới lấy name ở API tỉnh / thành v3. |
| to_ward_name | body | string | Có | Phường Vũng Tàu | Tên phường / xã — hệ mới lấy name ở API phường / xã v3. |
| to_district_name | body | string | Không | Tên quận / huyện — bắt buộc khi is_new_to_address = false, bỏ trống khi true. | |
| is_new_to_address | body | bool | Không | true | true = địa chỉ người nhận theo địa giới mới 2 cấp · false (mặc định) = địa giới cũ 3 cấp. |
| from_name | body | string | Không | Người gửi — mặc định theo hồ sơ cửa hàng (ShopId). Tương tự from_phone, from_address, from_ward_name, from_district_name, from_province_name, is_new_from_address. | |
| return_phone | body | string | Không | Thông tin hoàn hàng — mặc định người gửi / kho mặc định. Tương tự return_name, return_address, return_ward_name, return_district_name, return_province_name, is_new_return_address. | |
| client_order_code | body | string | Không | DH1001 | Mã đơn của bạn (≤ 50, duy nhất theo cửa hàng). |
| weight | body | int | Có | 500 | Khối lượng (gram, ≤ 50.000). |
| length | body | int | Có | 20 | cm (≤ 200). |
| width | body | int | Có | 15 | cm (≤ 200). |
| height | body | int | Có | 10 | cm (≤ 200). |
| service_type_id | body | int | Có | 2 | 2 = hàng dưới 20 kg · 5 = từ 20 kg hoặc nhiều kiện. |
| payment_type_id | body | int | Có | 1 | Bên trả phí ship: 1 người bán · 2 người nhận. |
| required_note | body | string | Có | CHOXEMHANGKHONGTHU | KHONGCHOXEMHANG · CHOXEMHANGKHONGTHU (xem, không thử) · CHOTHUHANG (xem và thử). |
| cod_amount | body | int | Không | 299000 | Tiền thu hộ (VND, ≤ 50.000.000). |
| cod_failed_amount | body | int | Không | 0 | Tiền thu khi giao thất bại. |
| insurance_value | body | int | Không | 299000 | Khai giá bảo hiểm (VND, ≤ 5.000.000). |
| order_value | body | int | Không | 299000 | Giá trị đơn (VND). |
| coupon | body | string | Không | Mã khuyến mãi GHN. | |
| content | body | string | Không | Quần kaki x1 | Mô tả hàng (≤ 2000) — bắt buộc khi không gửi items. |
| note | body | string | Không | Ghi chú cho tài xế (≤ 5000). | |
| pick_station_id | body | int | Không | 0 | Bưu cục shop mang hàng ra gửi; 0 = GHN đến lấy tại địa chỉ shop. |
| pick_shift | body | int[] | Không | Ca lấy hàng; mặc định ca sớm nhất. | |
| items | body | object[] | Không | [{"name":"Quần kaki","code":"SQKBC03M-Màu 3-35/28","quantity":1,"price":299000}] | Sản phẩm: name (≤ 512, bắt buộc), code, quantity (≥ 1, bắt buộc), price, và length / width / height / weight — bắt buộc khi service_type_id = 5. |
Ví dụ request
curl -s -X POST "https://partner.quantri360.com/v1/ghn/shiip/public-api/v2/shipping-order/preview" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"to_name":"nguoimua123","to_phone":"0901234567","to_address":"Số 1 đường ABC","to_province_name":"Hồ Chí Minh","to_ward_name":"Phường Vũng Tàu","is_new_to_address":true,"weight":500,"length":20,"width":15,"height":10,"service_type_id":2,"payment_type_id":1,"required_note":"CHOXEMHANGKHONGTHU","cod_amount":299000,"insurance_value":299000,"items":[{"name":"Quần kaki","code":"SQKBC03M-Màu 3-35/28","quantity":1,"price":299000}]}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/ghn/shiip/public-api/v2/shipping-order/preview",
params={},
json={
"to_name": "nguoimua123",
"to_phone": "0901234567",
"to_address": "Số 1 đường ABC",
"to_province_name": "Hồ Chí Minh",
"to_ward_name": "Phường Vũng Tàu",
"is_new_to_address": True,
"weight": 500,
"length": 20,
"width": 15,
"height": 10,
"service_type_id": 2,
"payment_type_id": 1,
"required_note": "CHOXEMHANGKHONGTHU",
"cod_amount": 299000,
"insurance_value": 299000,
"items": [
{
"name": "Quần kaki",
"code": "SQKBC03M-Màu 3-35/28",
"quantity": 1,
"price": 299000
}
]
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/ghn/shiip/public-api/v2/shipping-order/preview');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"to_name":"nguoimua123","to_phone":"0901234567","to_address":"Số 1 đường ABC","to_province_name":"Hồ Chí Minh","to_ward_name":"Phường Vũng Tàu","is_new_to_address":true,"weight":500,"length":20,"width":15,"height":10,"service_type_id":2,"payment_type_id":1,"required_note":"CHOXEMHANGKHONGTHU","cod_amount":299000,"insurance_value":299000,"items":[{"name":"Quần kaki","code":"SQKBC03M-Màu 3-35/28","quantity":1,"price":299000}]}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/ghn/shiip/public-api/v2/shipping-order/preview' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"to_name":"nguoimua123","to_phone":"0901234567","to_address":"Số 1 đường ABC","to_province_name":"Hồ Chí Minh","to_ward_name":"Phường Vũng Tàu","is_new_to_address":true,"weight":500,"length":20,"width":15,"height":10,"service_type_id":2,"payment_type_id":1,"required_note":"CHOXEMHANGKHONGTHU","cod_amount":299000,"insurance_value":299000,"items":[{"name":"Quần kaki","code":"SQKBC03M-Màu 3-35/28","quantity":1,"price":299000}]}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Tham số phản hồi (nguyên của GHN)
| Tên | Kiểu | Mẫu | Mô tả |
|---|---|---|---|
| code | int | 200 | 200 = thành công; lỗi xem `message` / `code_message_value`. |
| message | string | Success | |
| data | object | ||
| order_code | string | Luôn rỗng — xem trước không tạo đơn. | |
| total_fee | int | 20900 | Tổng phí (VND). |
| fee | object | Chi tiết phí (VND). | |
| main_service | int | 20900 | Cước chính. |
| insurance | int | 0 | Bảo hiểm. |
| cod_fee | int | 0 | Phí thu hộ. |
| station_do | int | 0 | Giao tại bưu cục. |
| station_pu | int | 0 | Lấy tại bưu cục. |
| return | int | 0 | |
| r2s | int | 0 | Hoàn về người gửi. |
| coupon | int | 0 | Giảm giá (số âm). |
| pick_remote_areas_fee | int | 0 | Phụ phí lấy vùng xa. |
| deliver_remote_areas_fee | int | 0 | Phụ phí giao vùng xa. |
| cod_failed_fee | int | 0 | |
| … | Các khoản khác: return_again, document_return, double_check, double_check_deliver, *_return, change_to_address_fee, change_return_address_fee. | ||
| expected_delivery_time | string | 2026-07-16T16:59:59Z | Thời gian giao dự kiến (ISO 8601, UTC — cộng 7 giờ ra giờ Việt Nam). |
Mẫu phản hồi
{
"code": 200,
"message": "Success",
"data": {
"order_code": "",
"fee": {
"main_service": 20900,
"insurance": 0,
"cod_fee": 0,
"station_do": 0,
"station_pu": 0,
"return": 0,
"r2s": 0,
"return_again": 0,
"coupon": 0,
"document_return": 0,
"double_check": 0,
"double_check_deliver": 0,
"pick_remote_areas_fee": 0,
"deliver_remote_areas_fee": 0,
"pick_remote_areas_fee_return": 0,
"deliver_remote_areas_fee_return": 0,
"cod_failed_fee": 0,
"change_to_address_fee": 0,
"change_return_address_fee": 0
},
"total_fee": 20900,
"expected_delivery_time": "2026-07-16T16:59:59Z"
}
}
Bắt đầu dùng
- Đăng ký tài khoản Partner
- Mở loại dữ liệu thuộc nhóm Vận đơn ở trang nền tảng
- Tạo API key (tick kênh GHN)
- Gọi theo ví dụ ở trên