Vận chuyển — tổng quan

Tab Vận chuyển trong trang Kênh (/app/channels) là nơi cấu hình đối tác vận chuyển và quản lý kho lấy hàng.

Kiến trúc vận chuyển của TrolyPage

Đây là điểm nhiều shop nhầm — TrolyPage không tích hợp từng hãng (GHN, GHTK, J&T, NinjaVan…) như 4 app riêng. Thay vào đó dùng:

• Goship — một aggregator đa hãng. Một kết nối Goship = truy cập nhiều hãng (ViettelPost, GHN, GHTK, J&T, NinjaVan…) cùng lúc.
• ViettelPost — tích hợp riêng (BYOA), dùng cho AI tool track/price.

Goship là tổng đài đa nhà xe

“Goship là tổng đài đa nhà xe — một kết nối bao gồm ViettelPost, GHN, GHTK, J&T, NinjaVan…” — khi lấy báo giá, Goship trả về list nhiều hãng phục vụ tuyến đó, bạn chọn hãng rẻ/nhanh nhất.

2 mô hình vận chuyển

Mô hình	Ai lo Goship	Phù hợp
TrolyShip (platform gateway)	TrolyPage lo tài khoản Goship mặc định	Shop nhỏ/lớn không muốn cấu hình
BYOA (tài khoản riêng)	Shop tự nhập credentials Goship riêng	Shop có tài khoản Goship riêng, muốn lợi nhuận phí ship

TrolyShip = không cấu hình gì

Đa số shop chỉ cần dùng TrolyShip: không phải đăng ký Goship, không nhập credentials. Shop chỉ cần thêm kho lấy hàng (xem Quản lý kho) là ship được.

Ưu tiên khi cả 2 đều có

Nếu shop cấu hình cả BYOA và TrolyShip → TrolyPage ưu tiên BYOA. Không có BYOA → fallback platform gateway.

4 thành phần trong tab Vận chuyển

Thành phần	Mô tả
Viettel Post	Tích hợp riêng (BYOA) — list account VTP + form kết nối
TrolyShip	Platform gateway Goship mặc định — chỉ cần cấu hình kho
Kho (Warehouse)	Địa chỉ lấy hàng — bắt buộc ít nhất 1
Locations	Dropdown tỉnh/huyện/phường (data Goship static)

ViettelPost (BYOA)

Đối tác riêng, dùng cho:

• AI tool tra cứu giá + tracking trong chat.
• KHÔNG dùng trong modal tạo vận đơn chính (modal đó đi qua Goship).

ViettelPost không có webhook

VTP chỉ tra cứu chủ động — không có webhook cập nhật trạng thái tự động. Khi cần update, AI/operator gọi tool track → VTP trả về trạng thái tại thời điểm đó.

Kết nối VTP cần: tên cấu hình + UserName + Password VTP (từ tài khoản merchant ViettelPost của shop).

TrolyShip (Goship platform gateway)

Bảng TrolyShip hiển thị:

• “Đơn hàng sẽ được vận chuyển qua đối tác của nền tảng — bạn chỉ cần cấu hình kho lấy hàng.”
• Nút + Thêm kho (xem Quản lý kho).

Shop không cần credentials Goship cho TrolyShip — TrolyPage lo.

TrolyShip vs BYOA — giá khác nhau?

Cùng tuyến đường, cùng hãng → phí carrier là như nhau. Khác biệt ở markup:

• TrolyShip: TrolyPage có thể cộng markup phí ship (ghi rõ trong cấu hình platform).
• BYOA: Shop giữ 100% phí, không qua markup TrolyPage.

2 loại vận đơn

Loại	Hãng	Đặc điểm
Tiêu chuẩn (Standard)	ViettelPost, GHN, GHTK, J&T, NinjaVan (qua Goship)	Tạo async — trả 200 ngay, mã vận đơn + phí đến sau qua webhook
On-demand (Express)	AhaMove, GrabExpress	Tạo sync — có mã ngay, giao nội thành trong ngày, cần lat/lng

On-demand cho đơn hỏa tốc

Khách cần giao ngay trong ngày (nội thành HN/HCM) → dùng Express (AhaMove/GrabExpress). Modal tạo đơn có toggle “Giao hỏa tốc (on-demand)”. Cần tọa độ lat/lng người gửi + người nhận.

Tự động ship (autoShipIfEnabled)

Khi duyệt đơn hàng, nếu bật auto-ship:

1. Hệ thống tự gọi getRates() lấy báo giá Goship.
2. Tự chọn hãng rẻ nhất trong list.
3. Tự tạo vận đơn → lưu Shipment pending.

Auto-ship cần có kho

Auto-ship chỉ chạy nếu shop đã cấu hình ít nhất 1 kho lấy hàng. Không có kho → auto-ship skip, bạn phải tạo vận đơn tay.

Reconcile markup (cập nhật phí)

Khi webhook Goship cập nhật trạng thái + phí thật:

1. Webhook đến → TrolyPage upsert Shipment.
2. reconcileCarrierCost() tính lại markup (nếu platform gateway).
3. Ghi lại order.shipping_fee + order.total.

Tức là phí ship ban đầu là ước lượng, sau khi hãng báo phí thật → đơn tự điều chỉnh. Đừng ngạc nhiên nếu total đơn thay đổi sau khi ship xong.

Luồng đầy đủ: order → ship → track

sequenceDiagram
    participant Khách
    participant AI
    participant Order
    participant Goship
    participant Hãng

    Khách->>AI: đặt hàng
    AI->>Order: tạo đơn (chờ duyệt)
    Note over Order: owner duyệt
    Order->>Goship: getRates(kho, địa chỉ khách, weight)
    Goship-->>Order: list hãng + phí
    Order->>Goship: createShipment(rate chọn)
    Goship-->>Order: 200 OK (pending, status 900)
    Note over Order,Goship: webhook async cập nhật
    Goship->>Hãng: assign
    Hãng->>Khách: lấy + giao
    Hãng->>Goship: status updates
    Goship->>Order: webhook (HMAC verified)
    Note over Order: reconcile phí thật
    AI->>Khách: báo "đã giao"

Bước tiếp theo

• Quản lý kho lấy hàng — Warehouse CRUD, bắt buộc ít nhất 1.
• Vận đơn — trang /app/shipments xem list.
• Đơn hàng — nơi tạo vận đơn.
• Troubleshooting vận chuyển — webhook 401, không có notification.