VI | EN
Nhắn Messenger
Dành cho developer

Xem trước đơn: phí + ETA (nhận địa chỉ mới 2 cấp) — API GHN

v2.shipping-order.preview · gọi qua Quantri360 bằng một API key cho chính tài khoản / tài sản bạn đã kết nối và ủy quyền — 360 lo việc ký request và làm mới phiên đăng nhập bạn đã cấp.

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_id trong 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ênVị tríKiểuMẫuMô tả
AuthorizationheaderheaderBearer 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_idquerystring196560ShopId 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ênVị tríKiểuBắt buộcMẫuMô tả
to_namebodystringCónguoimua123Tên người nhận (≤ 1024).
to_phonebodystringCó0901234567SĐT người nhận.
to_addressbodystringCóSố 1 đường ABCĐịa chỉ đầy đủ (≤ 1024).
to_province_namebodystringCóHồ Chí MinhTên tỉnh — hệ mới lấy name ở API tỉnh / thành v3.
to_ward_namebodystringCóPhường Vũng TàuTên phường / xã — hệ mới lấy name ở API phường / xã v3.
to_district_namebodystringKhôngTên quận / huyện — bắt buộc khi is_new_to_address = false, bỏ trống khi true.
is_new_to_addressbodyboolKhôngtruetrue = đị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_namebodystringKhôngNgườ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_phonebodystringKhôngThô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_codebodystringKhôngDH1001Mã đơn của bạn (≤ 50, duy nhất theo cửa hàng).
weightbodyintCó500Khối lượng (gram, ≤ 50.000).
lengthbodyintCó20cm (≤ 200).
widthbodyintCó15cm (≤ 200).
heightbodyintCó10cm (≤ 200).
service_type_idbodyintCó22 = hàng dưới 20 kg · 5 = từ 20 kg hoặc nhiều kiện.
payment_type_idbodyintCó1Bên trả phí ship: 1 người bán · 2 người nhận.
required_notebodystringCóCHOXEMHANGKHONGTHUKHONGCHOXEMHANG · CHOXEMHANGKHONGTHU (xem, không thử) · CHOTHUHANG (xem và thử).
cod_amountbodyintKhông299000Tiền thu hộ (VND, ≤ 50.000.000).
cod_failed_amountbodyintKhông0Tiền thu khi giao thất bại.
insurance_valuebodyintKhông299000Khai giá bảo hiểm (VND, ≤ 5.000.000).
order_valuebodyintKhông299000Giá trị đơn (VND).
couponbodystringKhôngMã khuyến mãi GHN.
contentbodystringKhôngQuần kaki x1Mô tả hàng (≤ 2000) — bắt buộc khi không gửi items.
notebodystringKhôngGhi chú cho tài xế (≤ 5000).
pick_station_idbodyintKhông0Bưu cục shop mang hàng ra gửi; 0 = GHN đến lấy tại địa chỉ shop.
pick_shiftbodyint[]KhôngCa lấy hàng; mặc định ca sớm nhất.
itemsbodyobject[]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ênKiểuMẫuMô tả
codeint200200 = thành công; lỗi xem `message` / `code_message_value`.
messagestringSuccess
dataobject
order_codestringLuôn rỗng — xem trước không tạo đơn.
total_feeint20900Tổng phí (VND).
feeobjectChi tiết phí (VND).
main_serviceint20900Cước chính.
insuranceint0Bảo hiểm.
cod_feeint0Phí thu hộ.
station_doint0Giao tại bưu cục.
station_puint0Lấy tại bưu cục.
returnint0
r2sint0Hoàn về người gửi.
couponint0Giảm giá (số âm).
pick_remote_areas_feeint0Phụ phí lấy vùng xa.
deliver_remote_areas_feeint0Phụ phí giao vùng xa.
cod_failed_feeint0
…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_timestring2026-07-16T16:59:59ZThờ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

  1. Đăng ký tài khoản Partner
  2. Mở loại dữ liệu thuộc nhóm Vận đơn ở trang nền tảng
  3. Tạo API key (tick kênh GHN)
  4. Gọi theo ví dụ ở trên