Trước khi bắt đầu

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

1. Menu Viettel Post Sandbox > Cài đặt trong EzyPlatform Admin.
2. Hai đường dẫn Xem mở tài liệu Swagger (<WEB_URL>/viettel-post-sandbox/swagger) và trang quản lý vận đơn sandbox (<WEB_URL>/viettel-post-sandbox/quan-ly-van-don).

Tài khoản sandbox

Tài khoản được tạo tự động

• ứng dụng của bạn gọi API /user/login hoặc /user/ownerconnect với USERNAME và PASSWORD;
• hoặc bạn đăng nhập trên trang web sandbox bằng một số điện thoại chưa tồn tại.

Đăng nhập trang web sandbox

• Số điện thoại/Email: đúng USERNAME mà ứng dụng của bạn gửi tới API /user/login;
• Mật khẩu: đúng PASSWORD mà ứng dụng đã gửi.

1. Ô Số điện thoại/Email và Mật khẩu: nhập đúng USERNAME và PASSWORD mà ứng dụng gửi tới API /user/login.
2. Ghi chú của sandbox: lần đăng nhập đầu tiên bằng một số điện thoại chưa có sẽ tự động tạo tài khoản.

Quản lý vận đơn

Danh sách vận đơn

1. Ô tìm kiếm theo mã vận đơn, mã đơn hàng hoặc số điện thoại người nhận.
2. Thanh công cụ: chọn một hoặc nhiều vận đơn ở cột đầu tiên rồi bấm Cập nhật trạng thái hoặc Hủy đơn; Tài liệu API mở Swagger.
3. Số đơn theo từng nhóm: Tổng số đơn, Chờ lấy, Lấy thành công, Giao thành công, Hủy lấy.
4. Lọc theo nhóm trạng thái: Chờ lấy hàng, Đang lấy hàng, Đã lấy hàng, Đang vận chuyển, Đang giao hàng, Giao thành công, Đang chuyển hoàn, Đã chuyển hoàn, Đã hủy.
5. Mã vận đơn và liên kết Xem chi tiết của từng vận đơn.

Chi tiết vận đơn

1. Nơi nhận webhook của vận đơn kèm Nguồn cấu hình của nơi nhận đó, và liên kết tới Cấu hình webhook.
2. Hành trình đơn: lịch sử các trạng thái đã cập nhật, mới nhất ở trên cùng.
3. Cập nhật trạng thái cho vận đơn này. Nút Hủy đơn cũng xuất hiện ở đây khi vận đơn còn hủy được.

Cập nhật trạng thái và gửi webhook

1. Trạng thái mới: một trong các mã trạng thái của Viettel Post, ví dụ 105 Bưu tá đã lấy hàng, 200 Bưu cục gốc đã nhận từ bưu tá, 501 Giao hàng thành công.
2. Tên trạng thái (STATUS_NAME): tự điền theo trạng thái đã chọn, có thể sửa lại.
3. Vị trí hiện tại, Ghi chú, Tên bưu tá, SĐT bưu tá: không bắt buộc, được gửi kèm trong webhook.
4. Cập nhật và gửi webhook.

Cài đặt tài khoản

Thông tin tài khoản

Quản lý token

1. Mục Quản lý token.
2. Thêm mới token: nhập tên token rồi tạo.
3. Mỗi token có tên và giá trị được ẩn mặc định; bấm biểu tượng con mắt để hiện hoặc ẩn. Các nút bên phải lần lượt là Làm mới token (tạo token mới, token cũ không dùng được nữa), Sao chép token và Xóa token.

Cấu hình webhook

1. URL nhận webhook tự động cùng nguồn cấu hình và token xác thực.
2. Cấu hình riêng: Đường dẫn API nhận webhook và Token xác thực webhook (TOKEN), bấm Lưu để áp dụng.
3. Xóa cấu hình riêng để quay lại dùng URL tự động.

• Callback URL của dịch vụ đó làm URL nhận webhook; nếu để trống thì dùng <WEB_URL>/delivery/callback/<mã dịch vụ>, ví dụ <WEB_URL>/delivery/callback/VIETTEL_POST;
• Client Key của dịch vụ đó làm token xác thực webhook.

• Đường dẫn API nhận webhook: endpoint nhận callback của ứng dụng;
• Token xác thực webhook (TOKEN): chuỗi bí mật do bạn tự đặt.

1. cấu hình riêng của tài khoản, nếu có;
2. nơi nhận đã được lưu vào vận đơn lúc tạo đơn;
3. URL nhận webhook tự động từ cấu hình Viettel Post của Ecommerce.

{
  "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",
    "LOCALION_CURRENTLY": "Bưu cục Mễ Trì - Hà Nội",
    "NOTE": "",
    "MONEY_COLLECTION": 200000,
    "MONEY_TOTAL": 16500,
    "ORDER_SERVICE": "PHS",
    "EMPLOYEE_NAME": "",
    "EMPLOYEE_PHONE": ""
  },
  "TOKEN": "your-webhook-secret"
}

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

1. Phiên bản: v2.
2. Đường dẫn API dịch vụ (Service API URL): <WEB_URL>/viettel-post-sandbox/v2.
3. Đường dẫn gọi lại (Callback URL): URL callback của dịch vụ do Ecommerce cung cấp; để trống thì dùng <WEB_URL>/delivery/callback/<mã dịch vụ>.
4. Khoá máy khách (Client Key): webhook token do bạn tự đặt.
5. Tên đăng nhập và Mật khẩu: số điện thoại sandbox bạn muốn sử dụng và một mật khẩu sandbox không rỗng.

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.

Lỗi thường gặp

Không mở được Swagger hoặc trang quản lý 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.

Đăng nhập trang web sandbox nhưng không thấy vận đơn

• Đăng nhập bằng đúng USERNAME và PASSWORD mà ứng dụng hoặc Ecommerce dùng để gọi /user/login.
• Nếu ứng dụng kết nối bằng token qua /user/LoginVTP, đăng nhập bằng tài khoản đã tạo token đó.
• Nếu bị báo sai mật khẩu, số điện thoại đó đã có tài khoản sandbox với mật khẩu khác.

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.

Không gửi được webhook

• Nếu báo chưa xác định được URL nhận webhook, cấu hình dịch vụ Viettel Post của Ecommerce dùng sandbox làm Service API URL, hoặc nhập cấu hình riêng trong Cài đặt tài khoản > Cấu hình webhook.
• Xem mã HTTP và nội dung phản hồi trong kết quả gửi webhook để biết hệ thống nhận trả lỗi gì.
• Nếu hệ thống nhận báo lỗi token, kiểm tra token xác thực webhook 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

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