Viettel Post Sandbox giúp bạn phát triển và kiểm thử luồng kết nối Viettel Post ngay trên EzyPlatform trước khi chuyển sang môi trường thật. Plugin không tạo vận đơn thật và không phát sinh hoạt động giao nhận thực tế.

Trước khi bắt đầu

Hướng dẫn này giả định rằng bạn đã tải Viettel Post Sandbox từ chợ EzyPlatform, cài đặt thành công cả admin plugin và web plugin, sau đó khởi động lại EzyPlatform.
Plugin phụ thuộc vào Ecommerce. Hãy bảo đảm Ecommerce đã được cài đặt và hoạt động trước khi sử dụng Viettel Post Sandbox.
Trong các ví dụ bên dưới, <WEB_URL> là địa chỉ web EzyPlatform của bạn, chẳng hạn http://localhost:8080 hoặc https://example.com.

Kiểm tra plugin đã hoạt động

Đăng nhập EzyPlatform Admin, mở menu Viettel Post Sandbox, sau đó chọn Settings.
Tại đây bạn có thể mở:
  • tài liệu Swagger: <WEB_URL>/viettel-post-sandbox/swagger;
  • danh sách vận đơn sandbox: <WEB_URL>/viettel-post-sandbox/delivery-orders.
Screenshot 2026-09-12 at 09.20.46.png
Nếu cả hai trang đều truy cập được thì plugin đã sẵn sàng để sử dụng.
Để tự gọi API và tạo vận đơn đầu tiên, xem Cách tạo đơn Viettel Post.

Cấu hình Ecommerce/EzyDelivery sử dụng sandbox

Nếu bạn sử dụng module giao vận của EzyPlatform thay vì tự gọi API, mở cấu hình dịch vụ Viettel Post trong Ecommerce và thiết lập:
  • Phiên bản: v2;
  • Service API URL: <WEB_URL>/viettel-post-sandbox/v2;
  • Username: số điện thoại sandbox bạn muốn sử dụng;
  • Password: mật khẩu sandbox không rỗng;
  • Client Key: webhook token do bạn tự đặt;
  • Callback URL: URL callback của dịch vụ Viettel Post do Ecommerce cung cấp.
Screenshot 2026-09-12 at 09.25.13.png
Screenshot 2026-09-12 at 09.25.44.png
Bạn không cần tạo tài khoản sandbox trước. Ở lần kết nối đầu tiên, plugin tự động tạo tài khoản từ Username và Password được cấu hình.
Module giao vận sẽ tự:
  1. đăng nhập và làm mới token khi cần;
  2. tìm dịch vụ phù hợp theo địa chỉ;
  3. lấy thông tin cửa hàng;
  4. tạo vận đơn qua sandbox;
  5. lưu mã vận đơn và thông tin phí vào đơn giao hàng.
Không thêm /viettel-post-sandbox/v2 lần thứ hai vào URL. Ví dụ, nếu Service API URL là https://example.com/viettel-post-sandbox/v2, module sẽ tự nối thêm /user/login, /order/getPriceAllNlp hoặc /order/createOrder.

Cấu hình và kiểm thử webhook

Webhook giúp ứng dụng kiểm thử việc nhận thay đổi trạng thái vận đơn từ Viettel Post.
Mở trang danh sách vận đơn tại:
<WEB_URL>/viettel-post-sandbox/delivery-orders
Cấu hình:
  • Receive API URL: endpoint nhận callback của ứng dụng, ví dụ <WEB_URL>/delivery/callback/viettel-post;
  • Token: một chuỗi bí mật do bạn tự đặt.
Screenshot 2026-09-12 at 09.18.31.png
Webhook token không phải số điện thoại và không phải access token nhận được từ API đăng nhập. Nếu hệ thống nhận webhook là Ecommerce/EzyDelivery, giá trị này phải giống Client Key trong cấu hình dịch vụ Viettel Post của Ecommerce.
Webhook Token trong Viettel Post Sandbox
                    =
Client Key của dịch vụ Viettel Post trong Ecommerce
Sau khi lưu cấu hình, chọn một vận đơn, mở chức năng gửi webhook, chọn hoặc sửa trạng thái rồi gửi. Sandbox sẽ gọi Receive API URL với payload có dạng:
{
  "DATA": {
    "ORDER_NUMBER": "ORDER-SANDBOX-001",
    "ORDER_REFERENCE": "DELIVERY-REFERENCE",
    "ORDER_STATUS": 200,
    "ORDER_STATUSDATE": "11/09/2026 10:30:00",
    "STATUS_NAME": "Nhận từ bưu tá - Bưu cục gốc"
  },
  "TOKEN": "your-webhook-secret"
}
Screenshot 2026-09-12 at 09.18.58.png
Ứng dụng nhận webhook nên kiểm tra trường TOKEN trước khi xử lý dữ liệu. EzyDelivery chấp nhận token trong header Token hoặc trường TOKEN của JSON; Viettel Post Sandbox gửi token trong JSON.

Lỗi thường gặp

Không mở được Swagger hoặc trang vận đơn

  • Kiểm tra cả admin plugin và web plugin đã được cài.
  • Kiểm tra dependency Ecommerce đã được cài.
  • Khởi động lại EzyPlatform sau khi cài plugin.
  • Kiểm tra lại <WEB_URL> và cấu hình domain của EzyPlatform.

EzyDelivery không tạo được vận đơn

  • Kiểm tra Service API URL kết thúc bằng /viettel-post-sandbox/v2.
  • Kiểm tra Username và Password không để trống.
  • Kiểm tra thông tin kho, sản phẩm, người nhận và địa chỉ trên đơn hàng.
  • Mở Swagger và thử luồng API trực tiếp để xác định bước gặp lỗi.

Webhook trả lỗi token

Đảm bảo webhook token trong Viettel Post Sandbox giống chính xác Client Key của dịch vụ Viettel Post trong Ecommerce. Giá trị này khác với token đăng nhập sandbox.

Khi chuyển sang môi trường Viettel Post thật

Sandbox chỉ phục vụ phát triển và kiểm thử. Trước khi chạy production, bạn cần:
  • thay Service API URL bằng URL chính thức của Viettel Post;
  • sử dụng tài khoản hoặc token do Viettel Post cấp;
  • đăng ký callback URL với Viettel Post;
  • cấu hình đúng client key dùng để xác thực webhook;
  • kiểm tra lại mã dịch vụ, địa giới hành chính, cửa hàng và quy tắc tính phí;
  • kiểm thử lại toàn bộ request, response, timeout, retry và xử lý lỗi;
  • không chuyển dữ liệu mẫu hoặc token sandbox sang production.