Vận chuyển — troubleshooting

Lỗi vận chuyển phổ biến + cách xử lý. Hệ thống ship đi qua Goship aggregator — nên đa số lỗi liên quan tới Goship.

Bảng tra cứu nhanh

Tìm theo thông báo bạn thấy hoặc theo tình huống. Mỗi dòng dẫn tới phần fix chi tiết bên dưới.

Dấu hiệu / thông báo	Mã/trạng thái	Nguyên nhân chính	Đi tới
“Không tính được phí ship”	Không trả phí	Chưa có kho / địa chỉ sai / carrier không phục vụ	Triệu chứng 1
“401 Unauthorized” khi tạo vận đơn	HTTP 401	Webhook/token Goship sai hoặc hết hạn	Triệu chứng 2
Tạo đơn xong nhưng không có mã vận đơn	Status 900	Goship chưa assign carrier	Triệu chứng 5
Đơn giao hỏa tốc (on-demand) fail	AhaMove/Grab fail	Thiếu tọa độ / ngoài vùng / giá cao	Triệu chứng 6
Không nhận notification trạng thái đơn	—	Webhook carrier chưa đăng ký / token hết hạn	Triệu chứng 3
Dropdown tỉnh/huyện/phường trống	—	Cache / Goship API down / khu vực mới	Triệu chứng 7
Không huỷ được vận đơn	—	Đã lấy hàng / đang giao	Triệu chứng 8
Phí ship lệch giữa báo và thực thu	—	Trọng lượng/kích thước khai sai	Triệu chứng 4

Triệu chứng 1: “Không tính được phí ship”

1a. Chưa có kho lấy hàng

Phổ biến nhất

Mới setup hay quên thêm kho → không tính phí ship, không tạo vận đơn được.

Fix:

1. Kênh (/app/channels) → tab Vận chuyển → section TrolyShip.
2. Bấm + Thêm kho → nhập tên + liên hệ + SĐT + địa chỉ (tỉnh/huyện/phường dropdown Goship).
3. Đánh dấu Mặc định.
4. Thử tạo vận đơn lại.

Xem chi tiết: Quản lý kho.

1b. Địa chỉ khách không hợp lệ

Khách nhập địa chỉ text tự do (vd “P.12 Q.Bình Thạnh”) → không match code Goship.

Fix:

• Sửa địa chỉ khách trong CustomerPanel / form đơn → chọn từ dropdown Goship (tỉnh → huyện → phường) thay vì gõ text.
• Hoặc: nếu khách ở khu vực mới, manually chọn dropdown gần nhất.

1c. Carrier không phục vụ tuyến

Một số tuyến đường xa (vùng núi, hải đảo) → Goship trả “Không có nhà xe nào phục vụ tuyến này.”

Fix:

• Dùng on-demand (AhaMove/GrabExpress) nếu khách ở nội thành gần.
• Liên hệ support TrolyPage — một số khu vực có carrier khác.
• Báo khách tự đến lấy.

Không có carrier “đổi”

TrolyPage chỉ dùng Goship (aggregator) + ViettelPost. Không có nút “đổi carrier GHN → GHTK” — tất cả carrier trong list báo giá đều từ Goship. Chọn hãng khác trong cùng list là đủ.

Triệu chứng 2: Webhook Goship trả 401

Webhook gọi về TrolyPage nhưng bị reject vì HMAC-SHA256 không khớp.

BYOA (tài khoản Goship riêng)

1. Kênh → tab Vận chuyển → Goship config.
2. Kiểm tra credentials (mã KH, API key, webhook secret) còn hiệu lực không.
3. Re-register webhook Goship (bấm nút nếu có, hoặc vào Goship).
4. Test: tạo đơn thử → xem có update không.

TrolyShip (platform gateway)

Nhân viên TrolyPage lo phần đăng ký webhook + HMAC secret. Liên hệ hotro@trolypage.com với mã đơn + thời gian lỗi.

Cách nhận biết TrolyShip vs BYOA

• TrolyShip: webhook kiểu POST /webhook/platform-shipping/{gatewayId} — TrolyPage lo.
• BYOA: webhook kiểu POST /webhook/goship/{configId} — bạn lo + có HMAC secret riêng.

Triệu chứng 3: Không nhận notification trạng thái đơn

Webhook chưa đăng ký hoặc fail → đơn không update.

Fix:

1. Kênh → tab Vận chuyển → chi tiết Goship config.
2. Re-register webhook.
3. Test: tạo đơn thử → Làm mới trạng thái tay (gọi API search) → xem có update không.
4. Nếu search OK nhưng webhook không → vấn đề webhook (xem Triệu chứng 2).

Làm mới trạng thái tay

Trong trang Vận đơn → click vào vận đơn → nút Làm mới trạng thái → gọi GoshipApiService::searchShipment() → cập nhật timeline + reconcile phí. Đây là fallback khi webhook fail.

Triệu chứng 4: Phí ship thay đổi sau khi giao

Đây không phải lỗi — đây là cơ chế reconcile markup:

1. Khi tạo đơn, phí ship là ước lượng (lúc Goship mới nhận).
2. Carrier giao xong → báo phí thật qua webhook.
3. reconcileCarrierCost() tính lại markup + ghi lại order.shipping_fee + order.total.

TrolyShip thì có markup

Nếu dùng TrolyShip → markup TrolyPage cộng được áp dụng → phí có thể cao hơn phí carrier gốc. BYOA → phí = phí carrier, không có markup.

Triệu chứng 5: Đơn tạo xong (status 900) mãi không update

Đơn Đang tạo đơn (code 900) kéo dài > 30 phút → Goship chưa assign carrier.

Fix:

1. Bấm Làm mới trạng thái tay trong trang Vận đơn.
2. Vẫn 900 → đợi 1-2 giờ (Goship đôi khi chậm vào giờ cao điểm).
3. Vẫn 900 → liên hệ support với mã đơn + mã Goship.

Triệu chứng 6: On-demand (AhaMove/Grab) fail

6a. Thiếu tọa độ lat/lng

On-demand cần tọa độ chính xác người gửi + người nhận. Nếu form không nhập đủ lat/lng → fail.

Fix: trong modal tạo vận đơn, bật Giao hỏa tốc (on-demand) → nhập tọa độ (hoặc pick trên map).

6b. Ngoài vùng phục vụ

AhaMove/GrabExpress chỉ phục vụ nội thành lớn (HN, HCM, ĐN, Cần Thơ…). Khách ở tỉnh khác → fail.

Fix: đổi sang standard (qua Goship aggregator).

6c. Phí on-demand đắt bất thường

On-demand tính theo khoảng cách + thời gian thực. Mưa giờ cao điểm → giá gấp 3-5 lần.

Fix: báo khách trước, hoặc dùng standard nếu khách không gấp.

Triệu chứng 7: Địa chỉ dropdown không load

Dropdown tỉnh/huyện/phường không hiển thị gì.

Nguyên nhân:

• Cache locations cũ → clear cache browser.
• Goship API down → đợi + reload.
• Khu vực mới chưa có data → chọn gần nhất + báo support.

Triệu chứng 8: Huỷ vận đơn không được

• Đã lấy hàng → carrier không cho huỷ. Chờ giao hoặc yêu cầu hoàn hàng.
• Đang giao → huỷ qua Goship → carrier báo lại → confirm.

Refund khác huỷ

Huỷ vận đơn ≠ refund tiền ship. Carrier có chính sách refund riêng — một số giữ phí xử lý.

Liên hệ support

Nếu đã thử hết, gửi cho hotro@trolypage.com:

1. Mã vận đơn (carrier_code hoặc mã Goship).
2. Mã đơn TrolyPage (#1024).
3. Thời gian tạo + thời gian lỗi.
4. Screenshot lỗi/modal.
5. Hãng + Nguồn (TrolyShip/BYOA).

Bước tiếp theo

• Webhook — troubleshooting — nếu lỗi 401/notification liên quan webhook.
• Tổng quan vận chuyển — kiến trúc.
• Vận đơn — tạo + theo dõi.
• Quản lý kho — setup kho.
• FAQ — câu hỏi khác.