Tích hợp 247Express vào EzyDelivery
Back to ezydeliveryBài viết này hướng dẫn cách kết nối EzyDelivery với 247Express để tạo đơn chuyển phát nhanh trực tiếp từ trang quản trị, nhận mã vận đơn 247Express, và tự động cập nhật trạng thái đơn khi 247Express giao hàng.
Sau khi tích hợp xong, luồng làm việc sẽ như sau:
- Nhân viên tạo đơn giao hàng trong EzyDelivery với phương thức giao hàng Chuyển phát nhanh và chọn dịch vụ 247Express.
- EzyDelivery gửi đơn sang 247Express, nhận về mã vận đơn 247Express và in tem.
- Trong quá trình giao, 247Express gọi lại (webhook) về hệ thống, EzyDelivery cập nhật trạng thái đơn theo thời gian thực.
Chuẩn bị
Trước khi cấu hình, cần có:
| Thứ cần có | Ghi chú |
|---|---|
| Tài khoản khách hàng 247Express có quyền dùng API | Liên hệ 247Express để được cấp tên đăng nhập, mật khẩu và địa chỉ API. Tài khoản này phải có ít nhất một kho lấy hàng (hub) đã khai báo trên 247Express. |
| Đã hoàn thành phần Cài đặt ban đầu cho EzyDelivery | Đặc biệt là quốc gia nhận (Việt Nam) có đủ tỉnh/thành phố, quận/huyện, phường/xã, và kho nhận hàng có địa chỉ, số điện thoại đầy đủ. |
Tiền tệ VND đã được kích hoạt | 247Express chỉ nhận tiền VND. Nếu đơn dùng tiền tệ khác (ví dụ CNY), cần có tỉ giá quy đổi sang VND, nếu không đơn sẽ gửi thất bại. |
| Trang web (web plugin) truy cập được từ Internet | Để 247Express gọi lại cập nhật trạng thái đơn. |
Cấu hình dịch vụ 247Express
Vào Thương mại điện tử → Các dịch vụ vận chuyển (
/ecommerce/delivery-services), tìm dòng 247_EXPRESS và bấm sửa (hoặc mở thẳng /ecommerce/delivery-services/247_EXPRESS/edit).Điền các ô như sau:
| Ô | Giá trị | Ghi chú |
|---|---|---|
| Tên | 247Express | Tên hiển thị trong ô chọn dịch vụ khi tạo đơn. Không được trùng tên với dịch vụ khác. |
| Phiên bản | Để trống | 247Express không dùng ô này. |
| Đường dẫn dịch vụ | Địa chỉ trang web của 247Express | Dùng để tạo đường dẫn tra cứu hành trình đơn cho khách hàng (xem phần Cập nhật trạng thái đơn). Không thêm dấu / ở cuối. |
| Đường dẫn API dịch vụ | Địa chỉ API do 247Express cung cấp | Ví dụ https://<địa-chỉ-api-247express>. Khi chạy thử với môi trường thử nghiệm thì dùng địa chỉ thử nghiệm mà 247Express cung cấp. Không thêm dấu / ở cuối. |
| Đường dẫn gọi lại | https://<tên-miền-web-của-bạn>/callback/247_EXPRESS | Để ghi nhớ địa chỉ đã khai báo với 247Express (xem phần Cấu hình webhook). |
| Khoá máy khách | Một chuỗi bí mật do bạn tự đặt | 247Express sẽ gửi kèm chuỗi này trong trường ApiKey mỗi lần gọi lại. EzyDelivery dùng nó để xác thực, bắt buộc điền nếu muốn nhận cập nhật trạng thái. |
| Tên đăng nhập | Tên đăng nhập tài khoản 247Express | |
| Mật khẩu | Mật khẩu tài khoản 247Express | |
| Khoá bí mật | Để trống | Hệ thống tự điền sau khi đăng nhập thành công (xem lưu ý bên dưới). |
| Dịch vụ giao hàng mặc định | Mã loại dịch vụ của 247Express | Được gửi sang 247Express làm loại dịch vụ của đơn. Để trống thì dùng DE. Muốn dùng gói dịch vụ khác thì hỏi 247Express mã tương ứng. |
| Trạng thái | ACTIVATED | Chỉ dịch vụ đang ACTIVATED mới xuất hiện khi tạo đơn. |
Các ô còn lại (logo, ảnh bìa, tiền tệ phí vận chuyển, phí vận chuyển tối thiểu, giá trị hàng hoá mặc định, ...) không bắt buộc cho 247Express.
Bấm Lưu. Khi lưu, hệ thống sẽ đăng nhập thử vào 247Express bằng tên đăng nhập và mật khẩu vừa nhập, rồi tự lấy các thông tin cần thiết để gửi đơn:
| Thông tin | Cách lấy |
|---|---|
| Token đăng nhập | Lưu vào ô Khoá bí mật (hiển thị dạng ẩn). Mỗi lần gửi đơn, token được gửi trong header Token. |
Mã khách hàng (ClientID) | Lưu kèm cấu hình dịch vụ. Mỗi lần gửi đơn, mã này được gửi trong header ClientID. |
Kho lấy hàng (ClientHubID) | Hỏi 247Express danh sách kho của tài khoản, chọn kho chính. Nếu không có kho nào được đánh dấu là kho chính thì chọn kho đầu tiên. |
Kết quả:
- Nếu đúng: lưu thành công.
- Nếu sai: hiện lỗi ở ô Tên đăng nhập và Mật khẩu, kiểm tra lại thông tin tài khoản và Đường dẫn API dịch vụ.
Về token, mã khách hàng và kho lấy hàng
Token, mã khách hàng và kho lấy hàng chỉ được lấy mỗi lần bấm Lưu với đủ tên đăng nhập và mật khẩu, hệ thống không tự đăng nhập lại khi gửi đơn. Vì vậy:
- Khi 247Express báo token không hợp lệ hoặc hết hạn, vào trang sửa dịch vụ và bấm Lưu lại để đăng nhập lại.
- Khi đổi mật khẩu tài khoản 247Express, nhớ cập nhật lại mật khẩu ở trang này.
- Khi thêm kho mới hoặc đổi kho chính trên 247Express, bấm Lưu lại để hệ thống lấy lại kho lấy hàng.
- Khi sửa các ô khác, cứ để nguyên ô Mật khẩu và Khoá bí mật đang hiển thị dạng ẩn, hệ thống sẽ giữ giá trị cũ.
- Sau lần đăng nhập thành công đầu tiên, mã khách hàng được ghi nhớ cố định. Nếu sau đó đăng nhập bằng một tài khoản 247Express khác (mã khách hàng khác), hệ thống sẽ báo sai tên đăng nhập / mật khẩu để tránh gửi nhầm đơn sang tài khoản khác. Muốn chuyển hẳn sang tài khoản mới, cần nhờ quản trị viên xoá mã khách hàng (
client_id) đã lưu của dịch vụ247_EXPRESStrước.
Đặt làm dịch vụ mặc định (tuỳ chọn)
Ở trang danh sách Các dịch vụ vận chuyển, có thể đặt
247_EXPRESS làm dịch vụ mặc định. Dịch vụ mặc định sẽ được chọn sẵn khi tạo đơn giao hàng.Địa chỉ gửi sang 247Express
Khác với Viettel Post, GHTK và SPX, 247Express không dùng mẫu ánh xạ tiền tố đơn vị hành chính. EzyDelivery gửi nguyên tên hiển thị của tỉnh/thành phố, quận/huyện, phường/xã như đã nhập trên trang quốc gia, kèm theo địa chỉ đầy đủ của người nhận.
Vì vậy cần lưu ý:
- Tên hiển thị của tỉnh, quận, phường nên đúng với tên mà 247Express đang dùng.
- Người nhận nên được chọn đầy đủ tỉnh, quận, phường. Nếu thiếu, ô tương ứng sẽ để trống và 247Express chỉ còn dựa vào địa chỉ đầy đủ để nhận diện.
Địa chỉ người gửi được lấy như sau:
| Thông tin | Cách lấy |
|---|---|
| Tên người gửi | Tên người gửi của đơn nếu có, nếu không thì dùng tên cửa hàng. |
| Số điện thoại người gửi | Số điện thoại người gửi của đơn nếu có, nếu không thì dùng số điện thoại của kho gửi hàng. |
| Địa chỉ người gửi | Địa chỉ người gửi của đơn nếu có, nếu không thì dùng địa chỉ đầy đủ của kho gửi hàng. |
Điểm lấy hàng thực tế vẫn là kho lấy hàng (
ClientHubID) đã lấy khi lưu cấu hình.Cấu hình webhook trên 247Express
Để trạng thái đơn tự cập nhật, cần khai báo webhook với 247Express (trên trang quản lý khách hàng nếu có, hoặc gửi thông tin cho bộ phận kỹ thuật của 247Express):
| Thông tin | Giá trị |
|---|---|
| Đường dẫn (URL) | https://<tên-miền-web-của-bạn>/callback/247_EXPRESS |
| Phương thức | POST, dữ liệu dạng JSON |
| API Key | Giống hệt giá trị ô Khoá máy khách đã điền ở trang cấu hình dịch vụ. 247Express gửi kèm giá trị này trong trường ApiKey của dữ liệu gọi lại. |
Một số điểm cần biết về webhook:
- Đường dẫn trên thuộc trang web (web plugin), không phải trang quản trị. Tên miền phải truy cập được từ Internet và nên dùng
https. - Dữ liệu 247Express gửi về phải có
OrderCode,ExternalCodevàStatus, nếu thiếu sẽ bị từ chối (OrderCode: required,ExternalCode: required,Status: required). - Mỗi lần nhận webhook, EzyDelivery kiểm tra trường
ApiKey. ThiếuApiKeysẽ bị từ chối với lỗiApiKey: required,ApiKeykhông khớp Khoá máy khách sẽ bị từ chối với lỗiApiKey: invalid. - Nếu chưa điền Khoá máy khách mà 247Express vẫn gọi webhook, hệ thống sẽ báo lỗi
no 247 express api key. - EzyDelivery chỉ chấp nhận cập nhật cho đơn mà nó đã tạo, nhận diện qua
ExternalCodevà mã vận đơn khớp vớiOrderCode247Express gửi về. Các đơn tạo trực tiếp trên trang 247Express sẽ bị bỏ qua (trả vềdeliveryOrder: notFound).
Tạo đơn giao hàng qua 247Express
Khi khách hàng có yêu cầu giao hàng với phương thức Chuyển phát nhanh:
- Vào Các yêu cầu giao hàng (
/ezydelivery/shipping-requests) và mở yêu cầu cần giao. - Bấm Tạo vận đơn, kiểm tra Tổng số cân (kg).
- Ở ô Dịch vụ vận chuyển, chọn 247Express (chỉ hiện khi phương thức giao hàng là chuyển phát nhanh).
- Bấm Tạo hoặc Tạo và hoàn thành.
Khi gửi đơn, EzyDelivery tự xử lý các việc sau:
| Việc | Cách làm |
|---|---|
| Loại dịch vụ | Dùng giá trị ô Dịch vụ giao hàng mặc định, để trống thì dùng DE. |
| Kho lấy hàng | Dùng kho lấy hàng đã lấy khi lưu cấu hình. |
| Mã đơn gửi sang 247Express | Ghép từ mã đơn trong EzyDelivery và thời điểm gửi, nên mỗi lần gửi lại là một mã mới, không bị 247Express báo trùng. |
| Loại hàng | Nếu tất cả sản phẩm là tài liệu thì gửi là tài liệu (TL), ngược lại gửi là hàng hoá (HH). |
| Khối lượng | Tổng khối lượng của các sản phẩm nhân số lượng, đổi sang kg, làm tròn lên 3 chữ số thập phân. |
| Kích thước | Cả đơn được gửi là 1 kiện: chiều dài và chiều rộng lấy theo sản phẩm lớn nhất, chiều cao bằng tổng chiều cao các sản phẩm (xếp chồng lên nhau). Đổi từ mm sang cm, làm tròn xuống. |
| Giá trị khai giá | Giá trị hàng hoá của đơn, quy đổi sang VND. |
| Ghi chú | Lấy từ ghi chú của người nhận. |
| Thu hộ (COD) | Xác định theo bảng bên dưới. |
Cách xác định tiền thu hộ:
| Đơn đã thanh toán? | 247Express thu của người nhận |
|---|---|
| Đã thanh toán | Không thu tiền hàng |
| Chưa thanh toán | Tiền thu hộ của đơn, quy đổi sang VND |
EzyDelivery không gửi thông tin người trả phí vận chuyển sang 247Express, phí vận chuyển được tính theo thoả thuận giữa bạn và 247Express.
Kết quả gửi đơn
- Thành công: đơn chuyển sang trạng thái Đã gửi yêu cầu, mã vận đơn 247Express (
OrderCode) được lưu làm mã vận đơn của đơn, và tem được in ngay. Các thông tin 247Express trả về (tổng cước dịch vụ, dịch vụ cộng thêm, loại thời gian giao, mã tham chiếu, ...) được lưu kèm đơn. - Thất bại: đơn chuyển sang trạng thái Gửi yêu cầu thất bại, nội dung lỗi 247Express trả về (mã lỗi, thông báo lỗi, danh sách lỗi) được lưu vào đơn để xem lại. Sau khi sửa nguyên nhân có thể gửi lại.
Cập nhật trạng thái đơn
Mỗi lần 247Express gọi webhook, EzyDelivery cập nhật trạng thái đơn theo
Status, thời điểm cập nhật theo Time, đồng thời lưu thêm tên bưu tá (Mailman) và ghi chú giao hàng (DeliveryNotes). Các thông tin gốc của 247Express (mã và tên trạng thái, mô tả, mã và ghi chú chậm trễ, mã giao dịch) cũng được lưu kèm đơn để tiện đối chiếu. Nếu 247Express báo đơn đang hoàn hàng hoặc đã hoàn hàng, đơn được đánh dấu là đang hoàn hàng.Bảng ánh xạ trạng thái 247Express sang trạng thái trong EzyDelivery:
| Mã 247Express | Trạng thái trong EzyDelivery |
|---|---|
16 | Dịch vụ vận chuyển đang xử lý |
18 | Bị huỷ |
19 | Đã có sự cố |
21 | Đã nhận yêu cầu |
23 | Đã lấy hàng |
24 | Đang giao hàng |
25 | Sẵn sàng giao hàng |
27 | Đang trả hàng |
28 | Bị trả lại |
30 | Đã giao hàng |
32 | Đã có sự cố |
Mã trạng thái không có trong bảng sẽ được ghi nhận là không xác định.
Khách hàng có thể tra cứu hành trình đơn qua đường dẫn dạng:
<đường-dẫn-dịch-vụ>/tracking?ordercode=<mã-vận-đơn>
Phần đầu của đường dẫn lấy từ ô Đường dẫn dịch vụ đã cấu hình.
Xử lý sự cố thường gặp
| Hiện tượng | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| Lưu cấu hình báo sai tên đăng nhập / mật khẩu | Sai tài khoản, sai Đường dẫn API dịch vụ, hoặc đang đăng nhập bằng tài khoản 247Express khác với tài khoản đã dùng trước đó | Kiểm tra đăng nhập với 247Express. Kiểm tra URL API không có / ở cuối. Nếu đổi tài khoản, xem lại phần Về token, mã khách hàng và kho lấy hàng. |
| Không thấy 247Express khi tạo đơn | Dịch vụ chưa ACTIVATED, hoặc phương thức giao hàng không phải chuyển phát nhanh | Kích hoạt dịch vụ, kiểm tra lại phương thức giao hàng của yêu cầu. |
Gửi đơn thất bại với lỗi deliveryServiceNotSetup | Thiếu Đường dẫn API dịch vụ, hoặc chưa đăng nhập thành công nên chưa có token và mã khách hàng | Điền đủ các ô, nhập tên đăng nhập, mật khẩu và lưu lại cấu hình. |
| Gửi đơn thất bại, 247Express báo token không hợp lệ | Token đã hết hạn hoặc đã bị thay đổi | Vào trang sửa dịch vụ và bấm Lưu lại để đăng nhập lại. |
| Gửi đơn thất bại, 247Express báo sai kho lấy hàng | Tài khoản chưa có kho lấy hàng, hoặc kho đã bị xoá sau khi lưu cấu hình | Tạo hoặc kiểm tra kho trên 247Express, sau đó bấm Lưu lại cấu hình. |
Gửi đơn thất bại với lỗi noCurrencyVND | Chưa có tiền tệ VND | Kích hoạt tiền tệ VND. |
Gửi đơn thất bại với lỗi noProduct | Đơn không có sản phẩm nào | Thêm sản phẩm vào đơn. |
| Gửi đơn thất bại do không quy đổi được tiền | Thiếu tỉ giá từ tiền tệ của đơn sang VND | Thêm tỉ giá trong Thương mại điện tử. |
| Gửi đơn thất bại, 247Express báo sai địa chỉ | 247Express không nhận diện được tỉnh, quận, phường của người nhận | Kiểm tra người nhận đã chọn đủ tỉnh, quận, phường, và tên hiển thị khớp với tên 247Express đang dùng. |
| Gửi đơn thất bại, 247Express báo lỗi khối lượng hoặc kích thước | Sản phẩm chưa khai báo khối lượng hoặc kích thước | Khai báo khối lượng, kích thước cho sản phẩm. |
| Trạng thái đơn không tự cập nhật | Chưa khai báo webhook, ApiKey không khớp Khoá máy khách, hoặc tên miền web không truy cập được từ Internet | Kiểm tra lại phần Cấu hình webhook. |