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.

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偏远 (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高峰).
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

• 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.