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

Tạo vận đơn J&T Express — API J&T Express

order.addOrder · 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.

order.addOrder

POST/order/addOrderGọi qua 360: POST https://partner.quantri360.com/v1/jtexpress/order/addOrder
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.
Endpoint ghi — thay đổi dữ liệu trên J&T Express. Key phải được tạo với tick "Cho phép gọi API ghi", nếu không sẽ nhận 403 write_not_allowed. Mỗi lần gọi được ghi nhật ký.
Mô tả API

Tạo vận đơn J&T: người gửi, người nhận, gói hàng, tiền thu hộ, bảo hiểm — trả mã vận đơn (billCode), mã phân loại (sortLine) và các khoản phí. Hỗ trợ một đơn nhiều kiện (childOrders).

  • Địa chỉ hệ mới 2 cấp: để trống city; area là phường / xã theo kho địa chỉ J&T.
  • Một đơn nhiều kiện: billCodes trả cả mã kiện mẹ và kiện con (JT000012-1/3, -2/3…).
  • Hành trình sau khi tạo đơn: J&T đẩy về URL bạn đăng ký trực tiếp với J&T (callback) — 360 không chuyển tiếp; hoặc tự tra bằng /logistics/trace.

Request

Địa chỉ

POST https://partner.quantri360.com/v1/jtexpress/order/addOrder

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_idquerystringTEST001apiAccount J&T đã nối (GET /v1/platforms). Có thể bỏ.

Tham số request

TênVị tríKiểuBắt buộcMẫuMô tả
txlogisticIdbodystringCóDH1001Mã đơn của bạn — KHÔNG được trùng (dùng để hủy / in / tra cứu).
orderTypebodyintCó11 = đơn thường · 2 = đơn hoàn.
serviceTypebodyintCó11 = J&T đến lấy hàng · 6 = gửi tại bưu cục.
deliveryTypebodyintCó11 = giao tận nơi · 2 = khách tự đến lấy.
payTypebodystringCóPP_PMPP_PM = người gửi trả, thanh toán theo tháng · PP_CASH = người gửi trả tiền mặt · CC_CASH = người nhận trả tiền mặt.
productTypebodystringCóEXPRESSEXPRESS · FAST · SUPER.
goodsTypebodystringCóbm000010bm000001 tài liệu · bm000010 hàng hóa · bm000011 hàng tươi sống.
isInsuredbodyintCó01 = mua bảo hiểm.
goodsValuebodynumberCó200000Giá trị hàng khai báo (VND, 0 – 30.000.000) — phí bảo hiểm thường 1%.
codMoneybodystringKhông200000Tiền thu hộ (VND).
remarkbodystringKhôngGhi chú cho bưu tá / khách (tối đa 200) — đơn đổi / trả hàng bắt buộc ghi rõ.
selfAddressbodyintKhông00 kho địa chỉ J&T · 1 ánh xạ địa giới hành chính.
sender.provbodystringCóHồ Chí MinhTỉnh / thành.
sender.citybodystringKhôngQuận 1Quận / huyện — địa chỉ hệ mới 2 cấp để trống / null.
sender.areabodystringCóPhường Nguyễn Thái Bình-028QQ107Phường / xã theo kho địa chỉ J&T (tên kèm mã, vd Phường Bến Nghé-028QQ101).
sender.namebodystringCóNguyễn Văn AHọ tên (tối đa 40).
sender.mobilebodystringCó0378456963Số điện thoại.
sender.addressbodystringCó1 Nguyễn Thái BìnhĐịa chỉ chi tiết (tối đa 250).
sender.brandnamebodystringKhôngTên viết tắt thương hiệu người gửi (≤ 5 ký tự).
receiver.provbodystringCóHồ Chí MinhTỉnh / thành.
receiver.citybodystringKhôngQuận 1Quận / huyện — địa chỉ hệ mới 2 cấp để trống / null.
receiver.areabodystringCóPhường Nguyễn Thái Bình-028QQ107Phường / xã theo kho địa chỉ J&T (tên kèm mã, vd Phường Bến Nghé-028QQ101).
receiver.namebodystringCóNguyễn Văn AHọ tên (tối đa 40).
receiver.mobilebodystringCó0378456963Số điện thoại.
receiver.addressbodystringCó1 Nguyễn Thái BìnhĐịa chỉ chi tiết (tối đa 250).
receiver.companynamebodystringKhôngTên cửa hàng nhận (in trên nhãn, ≤ 25 ký tự).
packageInfo.weightbodystringCó1Tổng trọng lượng (kg, 0,01 – 999).
packageInfo.lengthbodystringKhông20cm (1 – 320).
packageInfo.widthbodystringKhông15cm (1 – 100).
packageInfo.heightbodystringKhông10cm (1 – 180).
itemsbodyobject[]KhôngHàng hóa: [{ itemName (tên, ≤ 500), englishName (tên tiếng Anh, ≤ 100), number (số lượng), itemValue (đơn giá VND) }].
partSignbodystringKhông1 = cho phép nhận một phần (phần còn lại hoàn, mã hoàn dạng {billCode-001}) · 0 = nhận toàn bộ.
isCallBeforeReturnbodyintKhông1 = gọi người gửi xác nhận trước khi hoàn khi giao thất bại.
stayWarehouseDaysbodyintKhôngSố ngày lưu kho thêm trước khi hoàn (≤ 7; 3 ngày đầu miễn phí, sau đó 2.000đ / ngày).
sendStartTimebodystringKhôngLấy hàng sớm nhất (yyyy-MM-dd HH:mm:ss).
sendEndTimebodystringKhôngLấy hàng muộn nhất.
childOrdersbodyobject[]KhôngMột đơn nhiều kiện (< 999 kiện): [{ txlogisticId (mã kiện, không trùng), weight, length, width, height, items[] }].
senderbodystringCóBắt buộc.
receiverbodystringCóBắt buộc.

Ví dụ request

curl -s -X POST "https://partner.quantri360.com/v1/jtexpress/order/addOrder" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"txlogisticId":"DH1001","orderType":1,"serviceType":1,"deliveryType":1,"payType":"PP_PM","productType":"EXPRESS","goodsType":"bm000010","isInsured":0,"goodsValue":200000,"codMoney":"200000","sender":{"name":"Shop ABC","mobile":"0901234567","prov":"Hồ Chí Minh","city":"Quận 1","area":"Phường Nguyễn Thái Bình-028QQ107","address":"1 Nguyễn Thái Bình"},"receiver":{"name":"Nguyễn Văn A","mobile":"0378456963","prov":"Hà Nội","city":"Huyện Mê Linh","area":"Thị trấn Chi Đông-024HML01","address":"Số 5 đường X"},"packageInfo":{"weight":"1","length":"20","width":"15","height":"10"},"items":[{"itemName":"Áo thun","englishName":"T-shirt","number":"1","itemValue":"200000"}]}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/jtexpress/order/addOrder",
    params={},
    json={
        "txlogisticId": "DH1001",
        "orderType": 1,
        "serviceType": 1,
        "deliveryType": 1,
        "payType": "PP_PM",
        "productType": "EXPRESS",
        "goodsType": "bm000010",
        "isInsured": 0,
        "goodsValue": 200000,
        "codMoney": "200000",
        "sender": {
            "name": "Shop ABC",
            "mobile": "0901234567",
            "prov": "Hồ Chí Minh",
            "city": "Quận 1",
            "area": "Phường Nguyễn Thái Bình-028QQ107",
            "address": "1 Nguyễn Thái Bình"
        },
        "receiver": {
            "name": "Nguyễn Văn A",
            "mobile": "0378456963",
            "prov": "Hà Nội",
            "city": "Huyện Mê Linh",
            "area": "Thị trấn Chi Đông-024HML01",
            "address": "Số 5 đường X"
        },
        "packageInfo": {
            "weight": "1",
            "length": "20",
            "width": "15",
            "height": "10"
        },
        "items": [
            {
                "itemName": "Áo thun",
                "englishName": "T-shirt",
                "number": "1",
                "itemValue": "200000"
            }
        ]
    },
    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/jtexpress/order/addOrder');
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({"txlogisticId":"DH1001","orderType":1,"serviceType":1,"deliveryType":1,"payType":"PP_PM","productType":"EXPRESS","goodsType":"bm000010","isInsured":0,"goodsValue":200000,"codMoney":"200000","sender":{"name":"Shop ABC","mobile":"0901234567","prov":"Hồ Chí Minh","city":"Quận 1","area":"Phường Nguyễn Thái Bình-028QQ107","address":"1 Nguyễn Thái Bình"},"receiver":{"name":"Nguyễn Văn A","mobile":"0378456963","prov":"Hà Nội","city":"Huyện Mê Linh","area":"Thị trấn Chi Đông-024HML01","address":"Số 5 đường X"},"packageInfo":{"weight":"1","length":"20","width":"15","height":"10"},"items":[{"itemName":"Áo thun","englishName":"T-shirt","number":"1","itemValue":"200000"}]}),
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/jtexpress/order/addOrder' . '?' . 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, '{"txlogisticId":"DH1001","orderType":1,"serviceType":1,"deliveryType":1,"payType":"PP_PM","productType":"EXPRESS","goodsType":"bm000010","isInsured":0,"goodsValue":200000,"codMoney":"200000","sender":{"name":"Shop ABC","mobile":"0901234567","prov":"Hồ Chí Minh","city":"Quận 1","area":"Phường Nguyễn Thái Bình-028QQ107","address":"1 Nguyễn Thái Bình"},"receiver":{"name":"Nguyễn Văn A","mobile":"0378456963","prov":"Hà Nội","city":"Huyện Mê Linh","area":"Thị trấn Chi Đông-024HML01","address":"Số 5 đường X"},"packageInfo":{"weight":"1","length":"20","width":"15","height":"10"},"items":[{"itemName":"Áo thun","englishName":"T-shirt","number":"1","itemValue":"200000"}]}');
$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 J&T Express)

TênKiểuMẫuMô tả
codestring1`"1"` = thành công; mã khác = lỗi, xem `msg` (J&T trả HTTP 200 kèm mã lỗi).
msgstringsuccessThông báo kết quả.
dataobjectDữ liệu.
billCodestring802400616352Mã vận đơn J&T.
txlogisticIdstringDH1001Mã đơn của bạn.
sortLinestring800-028A04-Mã phân loại (in trên nhãn).
inquiryFeenumberTổng cước (VND, đã gồm bảo hiểm nếu có).
codFeenumberPhí thu hộ (VND).
insuranceFeenumberPhí bảo hiểm (VND).
billCodesstring[]Đơn nhiều kiện: mã kiện mẹ + kiện con.

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 J&T Express)
  4. Gọi theo ví dụ ở trên