Mỗi thao tác giao vận thủ công là một khoản thuế hằng ngày. Sao chép địa chỉ vào cổng của hãng vận chuyển, chọn dịch vụ, yêu cầu lấy hàng, in vận đơn, dán mã vận đơn vào tin nhắn — hai mươi đơn mỗi ngày nghĩa là một giờ gõ phím và ít nhất một lỗi sao chép. API đối tác của ViettelPost cho phép bạn xóa sổ toàn bộ nghi thức đó: một đơn Shopify mới trở thành một lượt lấy hàng đã đặt tại kho đã đăng ký của bạn, một vận đơn đã in, và một tin nhắn tracking gửi cho khách, không cần bàn tay con người. Đây là luồng chúng tôi xây dựng, cùng những cạm bẫy production mà tài liệu sẽ không cảnh báo bạn.
Đường đi suôn sẻ, từ đầu đến cuối
- Xác thực. API đối tác cấp token dựa trên thông tin tài khoản ViettelPost của bạn. Hãy đối xử với nó như mọi thông tin xác thực có hạn: lưu tập trung, làm mới chủ động, và không bao giờ để hai worker đua nhau làm mới cùng lúc.
- Tạo đơn vận chuyển. Ánh xạ đơn Shopify sang đơn ViettelPost: tên và số điện thoại người nhận, mã địa chỉ đã chuẩn hóa, khối lượng và kích thước, mã dịch vụ bạn chọn (tiết kiệm hay hỏa tốc, cùng các tùy chọn như giao một phần), và số tiền COD nếu khách thanh toán khi nhận hàng.
- Yêu cầu lấy hàng tại kho của bạn. Địa chỉ kho đã đăng ký là nơi shipper đến gom hàng. Hãy đặt theo khung giờ gom hàng kế tiếp thay vì "ngay bây giờ" — shipper chạy theo tuyến, không theo yêu cầu tức thời.
- In vận đơn. API trả về dữ liệu vận đơn; một print agent nhỏ chạy tại máy ở kho nhận dữ liệu qua hàng đợi và in vận đơn nhiệt A6. Người đóng gói không bao giờ phải mở trình duyệt.
- Tiêu thụ webhook trạng thái. ViettelPost đẩy các thay đổi trạng thái; handler của bạn ánh xạ trạng thái của hãng sang một tập nhỏ sự kiện hướng khách hàng — đã lấy hàng, đang vận chuyển, đang giao, đã giao, giao thất bại — và kích hoạt thông báo Zalo ZNS hoặc Messenger cho những sự kiện khách quan tâm.
Nếu bạn vận hành không có kho riêng và giao hàng cho shipper từ nhà hoặc một điểm lấy hàng thuê, cùng luồng này vẫn áp dụng với một chút biến tấu — xem hướng dẫn lấy hàng ViettelPost không cần kho của chúng tôi.
Chuẩn hóa địa chỉ: nỗi đau tích hợp số 1 tại Việt Nam
ViettelPost — như mọi hãng vận chuyển Việt Nam — không chấp nhận địa chỉ dạng văn bản tự do. Họ cần mã số cho tỉnh/thành phố, quận/huyện và phường/xã, cộng với phần địa chỉ đường phố còn lại dưới dạng văn bản. Khách hàng của bạn gõ "P. Bến Nghé, Q1, HCM" hoặc "quận 1 tp hcm" hoặc bỏ hẳn phường. Giữa bàn phím của khách và lệnh gọi đặt lấy hàng là một tầng chuẩn hóa:
- Phân tích địa chỉ tự do thành các thành phần ứng viên tỉnh/quận/phường (không phân biệt dấu, nhận biết viết tắt: HCM, TPHCM, Sài Gòn là một thành phố).
- Đối chiếu các thành phần với chính bảng mã của hãng vận chuyển — lấy từ API của họ và cache lại, không bao giờ hard-code.
- Chấm điểm độ tin cậy. Độ tin cậy cao thì đặt tự động; độ tin cậy thấp thì đưa vào hàng đợi xem xét hoặc kích hoạt câu hỏi xác nhận qua bot chăm sóc khách hàng của bạn, nhờ khách xác nhận phường của họ.
COD: điền đúng các trường, rồi đối soát tiền
Với đơn COD, trường số tiền thu hộ phải bằng đúng số khách còn nợ — tổng đơn trừ các khoản đã trả trước — chứ không phải cứ máy móc lấy tổng đơn. Thanh toán hỗn hợp (đặt cọc chuyển khoản, phần còn lại COD) là nơi tự động hóa chứng minh giá trị, vì con người sai chỗ này liên tục. Và thu tiền mới chỉ là một nửa câu chuyện: tiền về sau, theo đợt, và việc khớp các dòng chuyển tiền ngược về đơn hàng là một bài toán tự động hóa riêng — được trình bày đầy đủ trong bài phân tích chuyên sâu về đối soát COD của chúng tôi.
Những cạm bẫy chỉ xuất hiện trong production
1. Đặt lấy hàng lỗi trong im lặng
API chấp nhận lượt đặt của bạn, trả về mã vận đơn — và không shipper nào đến. Không lỗi, không webhook, không gì cả. Cách khắc phục là một job đối soát ngầm: cứ vài giờ, so sánh các lượt đã đặt với các cập nhật trạng thái đã nhận. Bất kỳ lô hàng nào vẫn không có trạng thái sau khung giờ lấy hàng sẽ được đặt lại tự động, và ở lần thất bại thứ hai, chuyển lên cho người thật kèm số hotline của hãng. Chính job nền này là khác biệt giữa "tự động hóa" và "tự động hóa mà bạn tin được".
2. Token hết hạn vào thời điểm tệ nhất
Token sẽ hết hạn; đợt đặt hàng dồn dập lúc 18:00 chính là lúc nó cắn bạn. Hãy làm mới chủ động theo lịch, giữ các lượt đặt trong hàng đợi retry khi xác thực thất bại, và không bao giờ để rơi một đơn hàng chỉ vì một lỗi 401.
3. Sandbox không phải là production
Môi trường sandbox khác production ở những điểm quan trọng: chuỗi trạng thái đến theo thứ tự khác hoặc không đến, một số mã dịch vụ hành xử khác, thời gian webhook không thực tế. Hãy coi sandbox là bước kiểm tra schema, rồi chạy thí điểm có kiểm soát trong production — mười đơn thật với một người theo dõi — trước khi bạn tin tưởng pipeline.
4. Webhook đến sai thứ tự, hoặc đến hai lần
Thiết kế handler trạng thái sao cho idempotent và chịu được sai thứ tự: lưu toàn bộ lịch sử trạng thái, suy ra trạng thái hướng khách hàng từ trạng thái có thứ hạng cao nhất đã thấy, và không bao giờ gửi cùng một thông báo hai lần cho một cặp (lô hàng, sự kiện).
Điều này mang lại gì cho bạn
Khi tầng này chạy, giao vận không còn là một công việc mà trở thành một thuộc tính của hệ thống: đơn chảy ra, trạng thái chảy về, khách luôn được cập nhật, và việc giao vận duy nhất còn lại là đóng gói hộp hàng bằng tay. Đây là giai đoạn đầu tiên chúng tôi cố tình xây trong hệ thống tự động hóa trọn gói, vì nó kích hoạt trên từng đơn hàng một — không thứ gì khác bạn tự động hóa hoàn vốn nhanh hơn.