Vận chuyển — tổng quan

This content is not available in your language yet.

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.

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

Ư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).

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.

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

Tự động ship (autoShipIfEnabled)

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

Hệ thống tự gọi getRates() lấy báo giá Goship.
Tự chọn hãng rẻ nhất trong list.
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:

Webhook đến → TrolyPage upsert Shipment.
reconcileCarrierCost() tính lại markup (nếu platform gateway).
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.