Kết nối vận chuyển Viettel Post
Tài liệu này nối Odoo với API đối tác của Viettel Post. Nó giả định Nền tảng kết nối vận chuyển
nội địa Việt Nam đã được cài, việc này tự động xảy ra khi cài ứng dụng này.
Cài đặt
- Vào Ứng dụng, bỏ bộ lọc Ứng dụng mặc định, tìm Kết nối vận chuyển Viettel Post rồi bấm
Cài đặt.
Lấy thông tin đăng nhập
Viettel Post cấp tài khoản đối tác qua bộ phận kinh doanh chứ không cho tự đăng ký.
- Liên hệ Viettel Post theo số 0862 235 888 hoặc b2b@viettelpost.com.vn và đề nghị tích hợp API.
- Họ tạo tài khoản trên hệ thống Partner và đưa bạn tên đăng nhập - thường là số điện thoại - cùng
mật khẩu. Nếu bạn đã có tài khoản Viettel Post, hãy đề nghị họ đồng bộ tài khoản đó sang hệ thống
Partner thay vì tạo tài khoản thứ hai.
Cấu hình
- Vào Kho vận > Cấu hình > Phương thức Giao hàng và tạo một phương thức với Nhà cung cấp là
Viettel Post.
- Ở tab Vietnam Shipping, điền Tên đăng nhập Viettel Post và Mật khẩu.
- Cứ để Môi trường thử để nói chuyện với partnerdev.viettelpost.vn.
- Bấm Kiểm tra kết nối. Thao tác này thực hiện đăng nhập, và đó là lệnh gọi duy nhất thật sự
chứng minh được thông tin đăng nhập.
Không có token nào phải dán vào và cũng không có token nào phải xoay vòng. Viettel Post xác thực
bằng một token phiên có hạn; Odoo lấy khi cần, giữ lại tới sát lúc hết hạn và tự làm mới mà không ai
phải để ý. Nếu Viettel Post trả về hạn dùng mà Odoo không đọc được, hệ thống mặc định một vòng đời
ngắn thay vì coi token là vĩnh viễn.
Tên đăng nhập là số điện thoại trên tài khoản, không phải email bạn dùng đăng nhập website của
họ. Form web nhận email, còn API thì từ chối, kèm đúng câu "Username or password is not valid" như
khi sai mật khẩu - nên nếu thông tin trông có vẻ đúng mà vẫn hỏng, hãy thử số điện thoại.
Một lần đăng nhập bị từ chối sẽ không được thử lại trong năm phút. Mọi lệnh gọi đều đăng nhập
khi chưa có phiên, nên mật khẩu sai đồng nghĩa mỗi lần báo giá là một lần đăng nhập: Viettel Post
đáp lại bằng "too many attempts, try again after 1 minute" và có thể khoá thẳng tài khoản - chuyện
còn tệ hơn cả mật khẩu sai. Trong năm phút đó, lệnh gọi hỏng ngay lập tức và nói rõ lý do. Lưu lại
tên đăng nhập hoặc mật khẩu là xoá chặn tức thì.
Khi họ không báo giá được tuyến của bạn
Báo giá có thể trả về "Viettel Post returned no price for this route". Hai chuyện khác nhau nhìn từ
ngoài y hệt nhau: họ thật sự không phục vụ tuyến đó, hoặc hợp đồng của bạn chưa có dịch vụ và bảng
giá phủ tuyến đó. Câu trả lời của họ trong cả hai trường hợp đều là một danh sách dịch vụ rỗng - và
ở endpoint không dùng NLP thì là "Price does not apply to this itinerary". Tài khoản sandbox mới
tinh thì chưa có bảng giá nào cả, nên cứ gặp lỗi này cho tới khi đội kinh doanh của họ gắn bảng giá
vào.
Không bao giờ có báo giá bằng không. Dịch vụ nào Viettel Post định giá bằng không sẽ được coi là
không báo được giá, chứ không phải miễn phí ship - vì nếu không, bạn đang chào khách một chuyến giao
mà không ai trả tiền cho bạn.
Các tuỳ chọn đáng đặt
- Mã kho lấy hàng - kho đã đăng ký trên tài khoản Viettel Post mà bưu tá tới lấy hàng. Nút
Kiểm tra kết nối liệt kê sẵn những kho bạn có. Nên đặt: Viettel Post tính cước theo mã quận
cũ, mà một kho ghi theo phường lập từ 01/07/2025 thì không có chỗ nào trong danh mục cũ - thiếu
nó thì chính địa chỉ của bạn có thể không báo giá được, dù địa chỉ khách vẫn ổn.
- Để Viettel Post đọc địa chỉ - mặc định bật, và nên để bật. Viettel Post đưa địa chỉ tiếng Việt
viết thường qua mô hình ngôn ngữ của chính họ và tự nhận diện đơn vị hành chính, nên kiện hàng đẩy
được từ đúng địa chỉ khách đã ghi. Nút Đồng bộ tỉnh và phường vẫn nạp danh mục hai cấp 2025 cho
những trường hợp cần mã chính xác.
- Mã dịch vụ - dịch vụ Viettel Post cần đẩy, ví dụ VCN cho chuyển phát nhanh tiêu chuẩn. Để
trống thì dịch vụ rẻ nhất Viettel Post phục vụ tuyến đó sẽ được chọn.
- Bên trả phí giao, Người nhận được xem hàng - mặc định cho mọi kiện, đổi theo từng phiếu
giao trong khối Vận chuyển. ORDER_PAYMENT của Viettel Post được suy ra từ bên trả phí và
tiền thu hộ: không thu, thu tiền hàng, thu cước, hay thu cả hai. Quy tắc xem hàng được ghi ở đầu
ghi chú cho bưu tá, vì Viettel Post không có trường riêng.
- Loại hàng - hàng hoá hay tài liệu.
Webhook
Viettel Post chỉ báo hành trình bưu gửi qua webhook; API đối tác không có endpoint tra cứu theo từng
kiện. Vì vậy webhook không phải tuỳ chọn - không có nó, phiếu giao giữ nguyên trạng thái lúc đẩy đơn.
- Trên phương thức giao hàng, bấm Sinh khoá bí mật mới và sao chép Webhook URL.
- Đăng nhập cổng partner của Viettel Post ở môi trường development, mở Cấu hình tài khoản, và
đăng ký URL cùng khoá bí mật.
- Dùng chức năng Kiểm tra kết nối ở đó để xác nhận Viettel Post gọi được tới máy chủ của bạn.
Có hai điều đáng biết về callback của Viettel Post, và cả hai đều đã được xử lý: họ cảnh báo có thể
gửi trùng cùng một hành trình, và Odoo hấp thụ bản trùng mà không sinh mốc thời gian trùng; và họ chờ
phản hồi dưới một giây, nên sự kiện được ghi nhận và trả lời ngay chứ không xử lý chậm.
Mỗi tài khoản chỉ cấu hình được một webhook endpoint. Khi dùng cơ chế uỷ quyền, hành trình được gửi
về endpoint của tài khoản uỷ quyền, nên tài khoản được uỷ quyền không cần cấu hình gì.
Dùng hằng ngày
Bấm Gửi sang hãng trên phiếu giao. Số phiếu giao được gửi cho Viettel Post làm ORDER_NUMBER với
CHECK_UNIQUE bật sẵn, đây là cơ chế chống trùng của chính họ: gửi lại cùng một mã sẽ trả về đúng
bưu gửi đã có.
Viettel Post báo phí thu hộ và VAT theo từng bưu gửi, nên khoản họ thu để giữ và chuyển tiền mặt
nhìn thấy được theo từng lần giao chứ không phải một con số gộp cuối tháng.
Khi giao thất bại, mã lý do Viettel Post trả về được dịch ra trên dòng thời gian: "sai kích thước",
"khách từ chối tiền thu hộ", "không liên lạc được khách nhận", thay vì một con số trơ trọi.
Đối soát COD
API đối tác của Viettel Post không có báo cáo đối soát. Vì vậy bảng kê được dựng từ chính các
callback giao hàng - đã giao cái gì, Odoo yêu cầu thu bao nhiêu, và phí Viettel Post báo về - và việc
đối chiếu con số đó với tiền vào tài khoản ngân hàng chính là mục đích của bảng kê. Nút Lấy từ
hãng nói thẳng điều này chứ không ngụ ý rằng số liệu đến từ một báo cáo mà Viettel Post không có.
Xử lý sự cố
"Sai tài khoản" khi Kiểm tra kết nối
Sai tên đăng nhập hoặc mật khẩu, hoặc tài khoản chưa được đồng bộ sang hệ thống Partner. Tài khoản
Partner không phải là tài khoản khách hàng Viettel Post thông thường.
Địa chỉ bị cắt ngắn
Viettel Post giới hạn các trường địa chỉ ở 150 byte, mà ký tự tiếng Việt chiếm tới ba byte mỗi ký tự.
Odoo cắt theo byte chứ không theo ký tự để địa chỉ vẫn hợp lệ, nhưng dòng đường phố quá dài vẫn sẽ
mất phần đuôi. Hãy để dòng đường phố ngắn và để phường với tỉnh gánh phần còn lại.
Dòng thời gian không bao giờ chạy
Webhook chưa được đăng ký, hoặc khoá bí mật không khớp. Hãng này không có cơ chế tra cứu dự phòng.
