# Getting Started Hướng dẫn chi tiết các bước tích hợp API 247 ## CÁC BƯỚC TÍCH HỢP * Bước 1: Đăng nhập lấy ClientID và Token theo[ API đăng nhập](/sso/sso-dang-nhap). Username và Password đăng nhập sẽ được cấp khi là khách hàng của 247. * Bước 2: Lấy [danh sách các ClientHubID](/customer/danh-sach-dia-chi), đấy chính là danh sách mã định danh (ID) của các địa chỉ gửi hàng của khách hàng. Khi tạo đơn hàng cần gửi, phải điền đúng mã định danh (ClientHubID) tương ứng địa chỉ gửi hàng đi của đơn hàng đó. * Bước 3: Lấy [danh sách dịch vụ chính](/customer/danh-sach-dich-vu-chinh) đã được đăng ký bởi khách hàng. * Bước 4: Lấy danh sách các [dịch vụ giá trị gia tăng](/customer/danh-sach-dich-vu-gtgt) mà khách hàng có thể sử dụng. * Bước 5: Tạo đơn hàng sử dụng [API tạo đơn hàng](/customer/tao-don-hang) với các thông tin cần thiết sau: * ClientID và Token lấy ở bước 1. * ClientHubId lấy ở bước 2. * Dịch vụ chính/dịch vụ giá trị gia tăng lấy bước 3 và 4 (nếu sử dụng). #### THÔNG TIN API {% hint style="success" %} Môi trường staging: [https://customerapi-stg.247tech.vn](https://customerapi-stg.247tech.vn/)\ Môi trường production: {% endhint %} #### **RATE LIMIT** {% hint style="warning" %} Api đăng nhập: 5 lần/phút/IP \ Các api còn lại: 360 lần/phút/IP {% endhint %} #### NOTES {% hint style="info" %} Bắt buộc phải nhập các trường có đánh dấu.\ Các API đều yêu cầu Headers có Token và ClientID. {% endhint %} # ChangeLog ## 1.0.7 - 2026-07-17 Bổ sung api [Kiểm tra địa chỉ phát](/customer/kiem-tra-dia-chi-phat) ## 1.0.6 - 2024-07-24 Bổ sung api [Feedback](/customer/feedback) Thêm tham số tiền COP (COPAmt) và Địa chỉ gửi (SenderAddress) vào api [Tạo đơn hàng](/customer/tao-don-hang) và [Cập nhật đơn hàng](/customer/cap-nhat-don-hang) ## 1.0.5 - 2024-02-27 Thêm tham số danh sách chi tiết kiện hàng (Packages) cho api [Tạo đơn hàng ](/customer/tao-don-hang)và [Cập nhật đơn hàng](/customer/cap-nhat-don-hang) ## 1.0.4 - 2023-07-12 Bổ sung API [Lịch sử cập nhật trạng thái](/webhooks/lich-su-cap-nhat-trang-thai). ## 1.0.3 - 2020-10-16 247Express triển khai hỗ trợ API trên nền tảng nodejs tương thích với các framework phổ biến hiện nay như ReactJS, Angular, VueJS... ## 1.0.2 - 2020-03-26 ### Changed Thêm tham số về thông tin chuyển hoàn hàng cho API tạo đơn hàng:\ Chi tiết thay đổi vui lòng tham khảo [tại đây](/customer/tao-don-hang). \ Mẫu ví dụ thay đổi: ``` "ReturnInfo": { "FRPhone":"0909123456", "FRProvinceName": "Hồ Chí Minh", "FRDistrictName": "Quận Tân Bình", "FRWardName": "Phường 12", "FRDetailAddress" : "18A Cộng Hòa", "FRFullAddress": "18A Cộng Hòa, Phường 12, Quận Tân Bình, Hồ Chí Minh" } ``` ## 1.0.1 - 2020-01-09 ### Fixed * Sửa lỗi tên thuộc tính Quantity trong đối tượng đơn hàng. ### Changed * Thay đổi giao diện. ## 1.0.0 - 2019-11-20 ### Added * Xuất phiên bản 1.0.0 # Support ## Làm thế nào để có tài khoản đăng nhập? Vui lòng liên hệ với bộ phận hỗ trợ kinh doanh để được cung cấp tài khoản kiểm thử. ## Tôi gặp vấn đề liên quan với API đăng nhập thì có thể liên hệ ở đâu? Nếu trong quá trình login bằng API gặp vấn đề, vui lòng liên hệ với bộ phận kỹ thuật hỗ trợ online qua các kênh được cung cấp. {% hint style="info" %} Kênh hỗ trợ online:\ SKYPE: hotro.247post\ ZALO: 19006980\ EMAIL: {% endhint %} # Header Request Mô tả cấu hình header cho request API ## API `POST` `https://api.247post.vn/api/API` Tất cả Customer API đều sử dụng mẫu header bên dưới để xác thực #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------- | | Content-Type\* | string | application/json | | ClientID\* | string | Mã khách hàng | | token\* | string | Token được lấy từ API đăng nhập | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} # Luồng trạng thái nhận phát
# Danh sách dịch vụ chính API lấy danh sách dịch vụ chính của 247Express được cung cấp ## GetServiceTypes `POST` `/Api/Customer/GetServiceTypes` {% tabs %} {% tab title="200 " %} ``` { "ServiceTypes": [ { "ServiceTypeID": "DE", "ServiceTypeName": "Chuyển phát nhanh", "CalculateVolumetric": 6000 }, { "ServiceTypeID": "TF", "ServiceTypeName": "Dịch vụ Chuyển phát đường bộ", "CalculateVolumetric": 4000 }, { "ServiceTypeID": "TH", "ServiceTypeName": "Chuyển phát 55h", "CalculateVolumetric": 4000 }, { "ServiceTypeID": "IE", "ServiceTypeName": "Chuyển phát nhanh quốc tế", "CalculateVolumetric": 5000 }, { "ServiceTypeID": "IM", "ServiceTypeName": "Chuyển phát tiết kiệm quốc tế", "CalculateVolumetric": 5000 } ], "ErrorMessage": null, "IsError": false, "ErrorCode": null, "StatusCode": 0, "IsPassError": false } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ``` {} ``` ### Mô tả kết quả trả về | Trường | Mô tả | | ------------------- | ---------------------------------------------------------------------- | | ServiceTypeID | Mã dịch vụ chính | | ServiceTypeName | Tên dịch vụ chính | | CalculateVolumetric | Tính trọng lượng quy đổi Length x Width x Height / CalculateVolumetric | # Danh sách dịch vụ GTGT API lấy danh sách các dịch vụ giá trị gia tăng được cung cấp bởi 247Express ## Services `POST` `/api/Customer/Services` {% tabs %} {% tab title="200 " %} ``` { "Services": [ { "ServiceID": "HDL", "ServiceName": "Hàng đông lạnh" }, { "ServiceID": "BP", "ServiceName": "Báo phát" }, { "ServiceID": "HQK", "ServiceName": "DV hàng quá khổ" } ], "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ``` {} ``` # Danh sách địa chỉ gửi hàng API lấy danh sách các điểm lấy hàng của khách hàng(client hub) ## CustomerGetClientHubs `POST` `/Api/Customer/CustomerGetClientHubs` Lấy danh sách các địa chỉ (ClientHubs). #### Request Body | Name | Type | Description | | -------------- | ------- | ----------------------------------------------------------------------------------------------------- | | GetFullAddress | boolean |

True: Lấy tất cả địa chỉ bao gồm đã duyệt và chưa duyệt
False: chỉ lấy các địa chỉ đã duyệt

| {% tabs %} {% tab title="200 " %} ``` { "Errors": [], "ErrorMessage": "", "Hubs": [ { "ClientHubID": 1158, "Address": "nguyễn huệ", "ContactName": "SAIGONBPO", "ContactPhone": "0963225098", "ManagerName": null, "ManagerPhone": null, "IsMain": true, "DistrictName": "Quận Một", "ProvinceName": "HỒ CHÍ MINH", "WardName": "Phường Bến Nghé", "StatusName": "Đã duyệt", "Phone": "0963225098", "IsEnable": false } ] } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ``` { "GetFullAddress": true } ``` # Tạo đơn hàng API tạo đơn hàng 247 ## Địa chỉ người nhận * Đối với địa chỉ có cấu trúc 3 cấp (Tỉnh/thành, quận/huyện, phường/xã theo cấu trúc địa giới Việt Nam trước ngày 01.07.2025) truyền thông tin như sau: * ReceiverProvinceName: tên tỉnh/thành người nhận. * ReceiverDistrictName: tên quận/huyện người nhận. * ReceiverWardName: tên phường/xã người nhận. * Đối với địa chỉ có cấu trúc 2 cấp (Tỉnh/thành, phường/xã theo cấu trúc địa giới Việt Nam từ ngày 01.07.2025) truyền thông tin như sau: * ReceiverProvinceName: tên tỉnh/thành người nhận. * ReceiverDistrictName: không truyền. * ReceiverWardName: tên phường/xã người nhận. ## CustomerAPICreateOrder `POST:``/Api/Customer/CustomerAPICreateOrder` **Headers** | Name | Value | | -------- | -------------------- | | ClientID | Lấy từ api đăng nhập | | Token | Lấy từ api đăng nhập | **Body**
NameTypeDescription
ClientHubIDnumberMã địa chỉ khách hàng (Bắt buộc khi không truyền CusWareHouseID và KH có địa chỉ gửi cố định)
CusWareHouseIDstringMã kho/shop (Bắt buộc khi không truyền ClientHubID và KH có địa chỉ gửi cố định)
ContactNamestringTên người liên hệ gửi hàng
ContactPhonestringSĐT người liên hệ gửi hàng (bắt buộc khi KH có địa chỉ gửi không cố định)
DirectSenderNamestringNgười đi gửi Thư/Hàng (bắt buộc khi KH có địa chỉ gửi không cố định)
SenderAddressstringĐịa chỉ đầy đủ người gửi, bao gồm: số nhà, tên đường, tên xã, tên huyện, tên tỉnh. (bắt buộc khi KH có địa chỉ gửi không cố định)
ReceiverPhone*stringSố điện thoại người nhận
ReceiverNamestringTên người nhận
ReceiverAddress*stringĐịa chỉ đầy đủ của người nhận (Cấu trúc địa chỉ 3 cấp: số nhà, tên đường, tên xã, tên huyện, tên tỉnh/ Cấu trúc địa chỉ 2 cấp: Số nhà, tên đường, tên xã, tên tỉnh)
ReceiverProvinceName*stringTên Tỉnh/Thành phố người nhận
ReceiverDistrictName*stringTên Quận/Huyện người nhận (null nếu sử dụng địa chỉ 2 cấp Tỉnh/thành phố, Phường/xã)
ReceiverWardNamestringTên Phường/Xã người nhận
ReceiveCompanyNamestringCông ty nhận
RealWeightnumberTrọng lượng thực tế (kg)
LengthnumberChiều dài (cm)
WidthnumberChiều rộng (cm)
HeightnumberChiều cao (cm)
QuantitynumberSố lượng kiện
NotestringGhi chú
ServiceTypeID*stringMã dịch vụ
MailerTypestringMã loại hàng hóa vận chuyển: HH - Hàng hóa. TL - Tài liệu.
CODAmountnumberTiền thu người nhận
ExternalCodestringMã vận đơn khách hàng (tối đa 20 ký tự)
ReferenceCodestringMã tham chiếu khách hàng
SpecialInstructionIdnumberMã ghi chú đặc biệt chỉ đối với đơn hàng COD: 1 - Cho xem hàng. 0 - Không cho xem hàng.
InformFeestringGiá trị kê khai. Các trường hợp lưu ý khi kê khai: 1 - Trọng lượng tính giá >= 2.5kg bắt buộc chọn Loại hình = HH(hàng hóa) 2 - Loại hình = HH bắt buộc nhập giá trị kê khai 3 - Đơn chọn DVBH (Dịch vụ bảo hiểm) thì bắt buộc nhập giá trị kê khai.
ExtraServicesarrayDanh sách các dịch vụ gia tăng
Packagesarray
{
    "PackageID": "", //Mã kiện,
    "Length": 100, // Kích thước (Dài - bắt buộc khi có nhập Rộng, Cao)(cm),
    "Width": 50, // Kích thước (Rộng - bắt buộc khi có nhập Dài, Cao)(cm),
    "Height": 80,// Kích thước (Cao - Bắt buộc khi có nhập Dài, Rộng)(cm),
    "RealWeight": 25// Trọng lượng thực của kiện (kg)
}

(*)Số lượng Packages phải khớp với Quantity. Trường hợp Quantity = 1 thì Packages = []

COPAmtnumberTiền COP (Cash on pickup)
RequestedDeliveryTimeDateTimeThời gian hẹn phát (*chỉ áp dụng cho các DVGT có hẹn giờ phát)
RequestedDeliveryTypestringLoại hẹn phát:
"DUNGGIO" : Đúng giờ
"TRUOCGIO" : Trước giờ
(*chỉ áp dụng cho các DVGT có hẹn giờ phát)
**Response** {% tabs %} {% tab title="200" %} ```json { "Errors": [], "ErrorCode": "0", "OrderInfo": { "OrderCode": "HD000003", "ReferenceCode": "HD000003", "ExternalCode": "HD000003", "TotalServiceCost": 44176, "ExtraServices": [ { "ServiceName": "Chuyển phát nhanh", "ServiceID": "DE", "Cost": 16800 }, { "ServiceName": "Hàng đông lạnh", "ServiceID": "HDL", "Cost": 15000 }, { "ServiceName": "Báo phát", "ServiceID": "BP", "Cost": 5000 }, { "ServiceName": "Phí xăng dầu", "ServiceID": "Fuel", "Cost": 3360 }, { "ServiceName": "Phí VAT", "ServiceID": "VAT", "Cost": 4016 } ], "DeliveryType": "1" }, "ErrorMessage": "" } ``` {% endtab %} {% tab title="401" %} ```json { "IsError": true, "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này." } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ---------------- | ------------ | ----------------------------------------------------------------------- | | Errors | array object | Mảng các lỗi trả về | | ErrorCode | string | Mã lỗi | | ErrorMessage | string | Thông báo lỗi | | **OrderInfo** | object | Thông tin đơn hàng tạo thành công | | OrderCode | string | Mã đơn hàng | | ReferenceCode | string | Mã tham chiếu khách hàng | | ExternalCode | string | Mã đơn hàng khách hàng | | TotalServiceCost | number | Tổng phí | | **ExtraService** | array object | Danh sách các dịch vụ của đơn hàng | | ServiceName | string | Tên dịch vụ | | ServiceID | string | Mã dịch vụ | | Cost | number | Phí dịch vụ | | DeliveryTimeType | string |

Đơn vị thực hiện phát:
"1" - 247 phát
"2" - Bên thứ 3 phát

| ### Mẫu ví dụ ```json5 { "OrderInfo":{ "ClientHubID":11583, "CusWareHouseID":"30984", "ContactName": "Trần Văn B", "ContactPhone": "0332318317", "DirectSenderName": "Nguyễn Văn A", "SenderAddress": "145/6C Trần Bá Giao, Phường 5, Gò Vấp, HCM", "ReceiverPhone":"0345555777", "ReceiverName":"Trương Chí Nhân", "ReceiverAddress":"326 Võ Văn Kiệt, phường Cầu Ông Lãnh, Hồ Chí Minh, Việt Nam", "ReceiverProvinceName":"Hồ Chí Minh", "ReceiverDistrictName": null, "ReceiverWardName":"Phường Cầu Ông Lãnh", "RealWeight":1, "Length":0, "Width":0, "Height":0, "Quantity":1, "Note":"Tài liệu", "ServiceTypeID":"DE", "MailerType":"TL", "CODAmount":0, "ExternalCode":"HD000003", "ReferenceCode": "HD000003", "SpecialInstructionId":1, "ExtraServices":[ { "ServiceID":"PTN", "Type":2 }, { "ServiceID":"BP", "Type":2 } ] } } ``` ### Thông tin mã lỗi {% hint style="danger" %} * 1: Thông tin Phường/Xã không chính xác * 2: Thông tin Quận/Huyện không chính xác * 3: Thông tin Tỉnh/Thành không chính xác * 4: Trùng mã đơn hàng * 5: Server error * 6: Có lỗi xảy ra trong quá trình xử lý * 9: Lỗi chưa cập nhật ghi chú đặc biệt * 10: Lỗi chưa truyền dịch vụ * 11: Địa chỉ gửi hàng không hợp lệ * 12: Tài khoản khách hàng không hợp lệ * 15: Chưa truyền mã đơn hàng * 16: Đơn hàng không hợp lệ * 17: Địa chỉ người nhận không hợp lệ * 18: Mã loại hàng hóa vận chuyển không hợp lệ * 19: Số lượng kiện không hợp lệ * 20: Chi tiết kiện không hợp lệ * 21: Thông tin người gửi chưa đầy đủ * 25: Tiền COP không hợp lệ {% endhint %} # Cập nhật đơn hàng API cập nhật thông tin đơn hàng ## Địa chỉ người nhận * Đối với địa chỉ có cấu trúc 3 cấp (Tỉnh/thành, quận/huyện, phường/xã theo cấu trúc địa giới Việt Nam trước ngày 01.07.2025) truyền thông tin như sau: * ReceiverProvinceName: tên tỉnh/thành người nhận. * ReceiverDistrictName: tên quận/huyện người nhận. * ReceiverWardName: tên phường/xã người nhận. * Đối với địa chỉ có cấu trúc 2 cấp (Tỉnh/thành, phường/xã theo cấu trúc địa giới Việt Nam từ ngày 01.07.2025) truyền thông tin như sau: * ReceiverProvinceName: tên tỉnh/thành người nhận. * ReceiverDistrictName: không truyền. * ReceiverWardName: tên phường/xã người nhận. ## CustomerAPIUpdateOrder `POST` `/api/Customer/CustomerAPIUpdateOrder` #### Request Body
NameTypeDescription
OrderCode*stringMã vận đơn, lấy từ response của api tạo đơn hàng
ClientHubIDintegerMã địa chỉ gửi hàng (bắt buộc khi không truyền CusWareHouseID và KH có địa chỉ gửi cố định)
CusWareHouseIDstringMã kho/shop (bắt buộc khi không truyền ClientHubID và KH có địa chỉ gửi cố định)
ContactNamestringTên người liên hệ gửi hàng
ContactPhonestringSĐT người liên hệ gửi hàng (bắt buộc khi KH có địa chỉ gửi không cố định)
SenderAddressstringĐịa chỉ đầy đủ người gửi, bao gồm: số nhà, tên đường, tên xã, tên huyện, tên tỉnh (bắt buộc khi KH có địa chỉ gửi không cố định)
DirectSenderNamestringNgười đi gửi Thư/Hàng (bắt buộc khi KH có địa chỉ gửi không cố định)
NotestringGhi chú
ExtraServicearrayDanh sách dịch vụ GTGT
InformFeenumberGiá trị kê khai. Các trường hợp lưu ý khi kê khai:
1 - Trọng lượng tính giá >=2.5kg bắt buộc chọn loại hình = HH (hàng hóa).
2 - Loại hình = HH bắt buộc nhập giá trị kê khai.
3 - Đơn chọn DVBH (Dịch vụ bảo hiểm) thì bắt buộc nhập giá trị kê khai.
SpecialInstructionIdstringMã ghi chú đặc biệt đối với đơn hàng COD:
1 - Cho xem hàng.
0 - Không cho xem hàng.
MailerType*stringMã loại hàng hóa vận chuyển:
HH - Hàng hóa.
TL - Tài liệu.
ExternalCodestringMã đơn hàng khách hàng (tối đa 20 ký tự)
ReferenceCodestringMã tham chiếu khách hàng
CODAmountnumberTiền COD thu người nhận
ServiceTypeID*stringMã dịch vụ chính
HeightnumberChiều cao (cm)
WidthnumberChiều rộng (cm)
LengthnumberĐộ dài (cm)
QuantityintegerSố lượng kiện
RealWeightnumberCân nặng (kg)
ReceiverWardNamestringPhường xã người nhận
ReceiverDistrictName*stringQuận huyện người nhận
ReceiverProvinceName*stringTỉnh thành người nhận
ReceiverAddress*stringĐịa chỉ người nhận
ReceiverNamestringTên người nhận
ReceiverPhone*stringSố điện thoại người nhận
ReceiveCompanyNamestringCông ty nhận
PackagesArray
{
    "PackageID": "", //Mã kiện,
    "Length": 100, // Kích thước (Dài - bắt buộc khi có nhập Rộng, Cao)(cm),
    "Width": 50, // Kích thước (Rộng - bắt buộc khi có nhập Dài, Cao)(cm),
    "Height": 80,// Kích thước (Cao - Bắt buộc khi có nhập Dài, Rộng)(cm),
    "RealWeight": 25// Trọng lượng thực của kiện (kg)
}

(*)Số lượng Packages phải khớp với Quantity. Trường hợp Quantity = 1 thì Packages = []

COPAmtnumberTiền COP (Cash on pickup)
RequestedDeliveryTimedatetimeThời gian hẹn phát (*chỉ áp dụng cho các DVGT có hẹn giờ phát)
RequestedDeliveryTypestringLoại hẹn phát:
"DUNGGIO" : Đúng giờ
"TRUOCGIO" : Trước giờ
(*chỉ áp dụng cho các DVGT có hẹn giờ phát)
{% tabs %} {% tab title="200 " %} ```json5 { "Errors": [], "ErrorCode": "0", "OrderInfo": { "OrderCode": "HD000003", "ReferenceCode": "HD000004", "ExternalCode": "HD000003", "TotalServiceCost": 44176, "ExtraServices": [ { "ServiceName": "Chuyển phát nhanh", "ServiceID": "DE", "Cost": 16800 }, { "ServiceName": "Hàng đông lạnh", "ServiceID": "HDL", "Cost": 15000 }, { "ServiceName": "Báo phát", "ServiceID": "BP", "Cost": 5000 }, { "ServiceName": "Phí xăng dầu", "ServiceID": "Fuel", "Cost": 3360 }, { "ServiceName": "Phí VAT", "ServiceID": "VAT", "Cost": 4016 } ], "DeliveryType": "1" }, "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ```json5 { "OrderInfo":{ "OrderCode":"HD000003", "ClientHubID":11583, "CusWarehouseID":"30984", "ContactName": "Trần Văn B", "ContactPhone": "0332318317", "SenderAddress": "145/6C Trần Bá Giao, Phường 5, Gò Vấp, HCM", "DirectSenderName": "Nguyễn Văn A", "ReceiverPhone":"0345555777", "ReceiverName":"Nguyễn Thành Đạt", "ReceiverAddress":"12 Tân Trào, phường Tân Phú, Quận 7, Hồ Chí Minh, Việt Nam", "ReceiverProvinceName":"Hồ Chí Minh", "ReceiverDistrictName":"Quận 7", "ReceiverWardName":"Phường Tân Phú", "RealWeight":1, "Length":0, "Width":0, "Height":0, "Quantity":1, "Note":"Tài liệu", "ServiceTypeID":"DE", "MailerType":"TL", "CODAmount":0, "ExternalCode":"HD000003", "SpecialInstructionId":1, "ReferenceCode":"HD000004", "ExtraServices":[ { "ServiceID":"PTN", "Type":2 }, { "ServiceID":"BP", "Type":2 } ] } } ``` ### Thông tin mã lỗi {% hint style="danger" %} * 1: Thông tin Phường/Xã không chính xác * 2: Thông tin Quận/Huyện không chính xác * 3: Thông tin Tỉnh/Thành không chính xác * 4: Trùng mã đơn hàng * 5: Server error * 6: Có lỗi xảy ra trong quá trình xử lý * 8: Lỗi cập nhật đơn hàng * 9: Lỗi chưa cập nhật ghi chú đặc biệt * 10: Lỗi chưa truyền dịch vụ * 11: Địa chỉ gửi hàng không hợp lệ * 12: Tài khoản khách hàng không hợp lệ * 13: Đơn hàng không tồn tại trong hệ thống * 15: Chưa truyền mã đơn hàng * 16: Đơn hàng không hợp lệ * 17: Địa chỉ người nhận không hợp lệ * 18: Mã loại hàng hóa vận chuyển không hợp lệ * 19: Số lượng kiện không hợp lệ * 20: Chi tiết kiện không hợp lệ * 21: Thông tin người gửi chưa đầy đủ * 25: Tiền COP không hợp lệ {% endhint %} # Kiểm tra địa chỉ phát Api kiểm tra địa chỉ phát(địa chỉ người nhận) ## CheckAddressInfo `POST` /api/Customer/CheckAddressInfo **Headers** | Name | Value | | -------- | -------------------- | | ClientID | Lấy từ api đăng nhập | | Token | Lấy từ api đăng nhập | **Body** | Name | Type | Description | | ------- | ------ | ------------ | | Address | string | Địa chỉ phát | **Response** {% tabs %} {% tab title="200" %} ```json { "DeliveryArea": "IN", "IsError": false, "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% tab title="401" %} ```json { "IsError": true, "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này." } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DeliveryArea | string |

| | IsError | bool | Lỗi nếu có | | ErrorMessage | string | Thông báo lỗi | | | | | ### Mẫu ví dụ ```json { "Address": "326 Võ Văn Kiệt, Phường Cầu Ông Lãnh, HCM" } ``` # Hủy đơn hàng Hủy đơn hàng khi đơn hàng mới tạo hoặc đang ở trạng thái đã tiếp nhận. ## CancelOrder `POST` `/Api/Customer/CancelOrder` #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | OrderCode\* | string | Mã đơn hàng | {% tabs %} {% tab title="200 " %} ``` { "ErrorCode": "0", "IsError": false, "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ``` { "OrderCode":"WKH091808-00002" } ``` ### Thông tin mã lỗi {% hint style="danger" %} 6: Có lỗi xảy ra trong quá trình xử lý. 12: Tài khoản khách hàng không hợp lệ. 13: Đơn hàng không tồn tại trong hệ thống. 14: Trạng thái không hợp lệ để xóa. 15: Chưa truyền mã đơn hàng. 16: Đơn hàng không hợp lệ. {% endhint %} # Tạo địa chỉ gửi hàng Tạo điểm gửi hàng cho khách hàng ## Địa chỉ * Đối với địa chỉ có cấu trúc 3 cấp (Tỉnh/thành, quận/huyện, phường/xã theo cấu trúc địa giới Việt Nam trước ngày 01.07.2025) truyền thông tin như sau: * ProvinceName: tên tỉnh/thành người nhận. * DistrictName: tên quận/huyện người nhận. * WardName: tên phường/xã người nhận. * Đối với địa chỉ có cấu trúc 2 cấp (Tỉnh/thành, phường/xã theo cấu trúc địa giới Việt Nam từ ngày 01.07.2025) truyền thông tin như sau: * ProvinceName: tên tỉnh/thành người nhận. * DistrictName: không truyền. * WardName: tên phường/xã người nhận. ## CustomerInsertClientHub `POST` `/Api/Customer/CustomerInsertClientHub` #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------- | | Address\* | string | Địa chỉ khách hàng theo định dạng Số nhà/đường, Phường/Xã, Quận/Huyện, Tỉnh/Thành phố | | ContactName\* | string | Tên liên hệ | | ContactPhone\* | string | Số điện thoại liên hệ | | ProvinceName\* | string | Tên Tỉnh/Thành phố | | DistrictName\* | string | Tên Quận/Huyện | | WardName | string | Tên Phường/Xã | | CusWarehouseID | string | Mã Shop/Kho | | CusWarehouseName | string | Tên Shop/Kho | {% tabs %} {% tab title="200 Cake successfully retrieved" %} ``` { "HubInfo": { "Address": "HH1, Yên Hòa, Cầu Giấy, Hà Nội", "WardID": "CYGYHO", "ClientHubID": "248", "ContactName": "Nguyễn Thành Trung", "ContactPhone": "0986226622", "DistrictID": "CGY", "IsMain": "true", "ProvinceID": "HNI", "CustomerID": "15", "Status": "Init", "StatusName": "Chờ duyệt", "CusWarehouseName": "Chi nhánh HN1" }, "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ``` { "HubInfo": { "Address": "326 Võ Văn Kiệt, Phường Cầu Ông Lãnh, Hồ Chí Minh", "ContactName": "Nguyễn Văn A", "ContactPhone": "0909123456", "ProvinceName": "Thành phố Hồ Chí Minh", "WardName": "Phường cầu ông lãnh", "CusWarehouseID": "30984", "CusWarehouseName": "Chi nhánh số 3" } } ``` # Lấy ảnh vận đơn API lấy danh sách ảnh của một vận đơn ## GetOrderImages `POST` `/Api/Customer/GetOrderImages` #### Request Body | Name | Type | Description | | --------- | ------ | ----------- | | OrderCode | string | Mã vận đơn | {% tabs %} {% tab title="200 " %} ``` { "Items": [ { "No": 1, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/39raazlyjhotdi/123456789-1-image-1892fa10-61db-4446-8679-fcbede8ff542.jpg?dl=1" }, { "No": 2, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/8nntd5rgidma4n/123456789-1-image-a3ba444b-e6d4-48c3-a4b0-d419d2e96979.jpg?dl=1" }, { "No": 3, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/qyfr0kkhqajsbw/123456789-1-image-25dfed28-6885-48d1-b2eb-638e389146a4.jpg?dl=1" }, { "No": 4, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/elzsazr502ijkq/123456789-1-image-93fc383a-90eb-4c41-ac62-50ea58ad3e74.jpg?dl=1" }, { "No": 5, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/j63171se6m6sxs/123456789-1-image-e770a911-f81b-41c7-be53-af90976b7146.jpg?dl=1" } ], "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ``` { "OrderCode": "123456789" } ``` # Tính giá API tính giá cước dịch vụ của 247. Giá cước mang tính chất tham khảo. ## GetPriceForCustomerAPI `POST` `/Api/Customer/GetPriceForCustomerAPI` #### Request Body | Name | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------------------------- | | ServiceTypeID | string | Mã dịch vụ | | ClientHubID | number | Mã điểm lấy hàng (Không truyền hoặc truyền giá trị 0 khi KH có địa chỉ gửi không cố định) | | RealWeight | string | Trọng lượng thực (trọng lượng sau khi đã đóng gói) (kg) | | Height | number | Chiều cao (truyền 0 nếu chưa xác định được kích thước) (cm) | | Width | number | Độ rộng (truyền 0 nếu chưa xác định được kích thước) (cm) | | Length | number | Chiều dài (truyền 0 nếu chưa xác định được kích thước) (cm) | | FromProvinceName | string | Tỉnh thành gửi (bắt buộc khi KH có địa chỉ gửi không cố định) | | ToWardName | string | Phường xã đến | | ToProvinceName | string | Tỉnh thành đến | {% tabs %} {% tab title="200 " %} ``` { "ExtraServices": [ { "ServiceName": "Chuyển phát nhanh", "ServiceID": "DE", "Cost": 1184800.0 }, { "ServiceName": "Phí xăng dầu", "ServiceID": "Fuel", "Cost": 236960.0 }, { "ServiceName": "Phí VAT", "ServiceID": "VAT", "Cost": 142176.0 } ], "TotalServiceCost": 1563936.0, "IsError": false, "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ: ``` { "ToProvinceName": "Hồ Chí Minh", "ToWardName": "Phường Cầu Ông Lãnh", "Length": 60, "Width": 60, "Height": 60, "RealWeight": 60, "ClientHubID": "5590", "ServiceTypeID": "DE" } ``` # Cập nhật địa chỉ gửi hàng Cập nhật tên, số điện thoại liên hệ điểm gửi hàng cho khách hàng ## CustomerUpdateClientHub `POST` `/api/Customer/CustomerUpdateClientHub` #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | ----------------- | | ClientHubID\* | int | Mã địa chỉ | | ContactName\* | string | Tên người liên hệ | | ContactPhone\* | string | SĐT người liên hệ | {% tabs %} {% tab title="200: OK " %} ```javascript { "IsError": false, "Errors": [], "ErrorMessage": "", "DepositChangeAmount": 0.0 } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ``` { "HubInfo": { "ClientHubID": 1285, "ContactName": "Tran Van B", "ContactPhone": "0909123123" } } ``` # Feedback Khách hàng phản hồi các vận đơn phát chưa thành công ## CustomerConfirmDelivery `POST` `/api/Customer/CustomerConfirmDelivery` **Headers** | Name | Value | | -------- | ------------------------------------------ | | ClientID | lấy từ [api đăng nhập](/sso/sso-dang-nhap) | | Token | lấy từ [api đăng nhập](/sso/sso-dang-nhap) | **Body** | Name | Type | Description | | ------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- | | OrderCode\* | string | Mã đơn hàng | | ConfirmID\* | string | Mã xác nhận [*(chi tiết)*](#thong-tin-ma-xac-nhan-confirmid) | | Notes | string | Ghi chú | | **DeliveryInfo** | object | Thông tin giao hàng | | ReceiverName | string | Tên người nhận | | ReceiverAddress | string | Địa chỉ đầy đủ người nhận, bao gồm: số nhà, tên đường, tên phường/xã, tên quận/huyện, tên tỉnh thành | | ReceiverPhone | string | Số điện thoại người nhận | | DeliveryTime | DateTime | Thời gian hẹn phát | **Response** {% tabs %} {% tab title="200" %} ```json { "IsError": false, "Errors": [], "ErrorMessage": "", "ErrorCode": "" } ``` {% endtab %} {% tab title="200" %} ```json { "IsError": true, "Errors": [ { "ErrorMessage": "Số điện thoại không hợp lệ (09871111231)", "PropertyName": "ReceiverPhone" } ], "ErrorMessage": "Số điện thoại không hợp lệ (09871111231)", "ErrorCode": "24" } ``` {% endtab %} {% tab title="401" %} ```json { "IsError": true, "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này." } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------------- | ------------ | ---------------------------------------- | | IsError | bool | Có lỗi xảy ra? | | ErrorMessage | string | Thông báo lỗi | | ErrorCode | string | Mã lỗi [*(chi tiết)*](#thong-tin-ma-loi) | | **Errors** | array object | Mảng các lỗi trả về | | Errors.PropertyName | string | Tên trường lỗi | | Errors.ErrorMessage | string | Thông báo cụ thể theo trường lỗi | ### Thông tin mã xác nhận (ConfirmID) {% hint style="info" %} * 1: Hẹn phát lại * 2: Chuyển hoàn về địa chỉ gửi * 3: Chuyển hoàn về địa chỉ khác * 4: Chuyển tiếp * 5: Tiêu hủy {% endhint %} ### Thông tin mã lỗi {% hint style="danger" %} * 1: Không tìm thấy tỉnh thành từ địa chỉ * 2: Không tìm thấy quận huyện từ địa chỉ * 3: Không tìm thấy tỉnh thành từ địa chỉ * 6: Có lỗi xảy ra trong quá trình xử lý * 13: Đơn hàng không có trên hệ thống * 14: Trạng thái vận đơn không hợp lệ * 15: Chưa truyền mã vận đơn * 17: Địa chỉ không hợp lệ * 22: ConfirmID không hợp lệ * 23: Chưa truyền DeliveryInfo * 24: Thông tin giao hàng không hợp lệ {% endhint %} ### Mẫu ví dụ ```json { "OrderCode" : "HD00001", "ConfirmID" : 3, "DeliveryInfo" : { "ReceiverName" : "Thành", "ReceiverAddress" : "326 Võ Văn Kiệt, Cô Giang, Quận 1", "ReceiverPhone" : "09871111231" }, "Notes": "Chuyển hoàn về kho" } ``` # SSO - Đăng nhập Hướng dẫn tạo API đăng nhập ## SSO Đăng nhập `POST` `/api/Client/ClientLogin` NOTE: vui lòng sử dụng tài khoản được 247 cung cấp #### Headers | Name | Type | Description | | ------------ | ------ | ------------ | | Content-Type | string | Content Type | #### Request Body | Name | Type | Description | | -------- | ------ | ----------- | | UserName | string | UserName | | Password | string | Mật khẩu | {% tabs %} {% tab title="200 Đăng nhập thành công" %} ``` Mẫu ví dụ khi đăng nhập thành công: { "ClientID": 2876, "ClientName": "Lê Thanh Tùng", "Token": "e93e4ad62b8b35d5361bb12f2de77330e834ac0a1e6a6fa39f4c920d0646e198", "Errors": [], "ErrorMessage": "" } Mẫu ví dụ khi đăng nhập không thành công: { "ClientID": 0, "ClientName": null, "Token": null, "Errors": [ { "ErrorMessage": "Tên tài khoản hoặc mật khẩu không đúng!", "PropertyName": null } ], "ErrorMessage": " | Tên tài khoản hoặc mật khẩu không đúng! | Tên tài khoản hoặc mật khẩu không đúng! | Tên tài khoản hoặc mật khẩu không đúng!" } ``` {% endtab %} {% endtabs %} ### Mẫu đăng nhập 
{
      "UserName": "TXN-KH18-0059",
      "Password": "456123@"
}
[^1]: # Tracking đơn hàng Tracking đơn hàng. Số lần tracking không vượt quá 200.000 lần/ngày. Thời gian tra cứu là 6 tháng kể từ ngày tiếp nhận đơn hàng. Vui lòng cung cấp địa chỉ IP để tiến hành tra cứu. ### TRẠNG THÁI ĐƠN {% hint style="info" %} API Staging: [https://tracking-stg.247tech.vn](https://tracking-stg.247tech.vn/)\ API Pro : {% endhint %} {% hint style="info" %} Các trạng thái đơn hàng: * DATIEPNHAN: Đơn hàng vừa tạo qua API hoặc web khách hàng.. * DALAYHANG: Đơn hàng đã được nhân viên giao nhận của 247Express tới lấy hàng. * DANGVANCHUYEN: Đơn hàng đang được vận chuyển bởi 247. * DANGDIPHAT: Đơn hàng đang phát. * PHATTHANHCONG: Đơn hàng đã được phát thành công. * CHOXULY: Đơn hàng phát chưa thành công, đang chờ xử lý. * CHOCHUYENHOAN: Đơn hàng đang được chuyển hoàn lại cho khách hàng. * DACHUYENHOAN: Đơn hàng đã được chuyển hoàn lại cho khách hàng. * THATLAC: Đơn hàng bị thất lạc. * HUY: Đơn hàng đã bị hủy. * TICHTHU: Đơn hàng đã bị tịch thu bởi cơ quan chức năng do vi phạm về loại hàng hóa... {% endhint %} ### TRACKING API KEY {% hint style="info" %} Để lấy apikey, thực hiện các bước như sau: * Đăng nhập website: [https://247express.vn](https://247express.vn/) * Vào chức năng "THÔNG TIN KHÁCH HÀNG" {% endhint %} ### THÔNG TIN MÃ LỖI {% hint style="danger" %} MISSING\_APIKEY: Chưa truyền APIKey\ MISSING\_ORDERCODE: Chưa truyền số vận đơn \ ORDERCODE\_MIN\_LENGTH: Số vận đơn nhỏ hơn 5 ký tự\ ORDERCODE\_MAX\_LENGTH: Số vận đơn tối đa là 20 ký tự \ ORDERCODE\_NOT\_FOUND: Số vận đơn không tìm thấy ORDERCODE\_DOES\_NOT\_BELONG\_TO\_YOUR\_ACCOUNT: số vận đơn thuộc tài khoản khác APIKEY\_NOT\_FOUND: Apikey không tìm thấy \ APIKEY\_LIMIT: Tra cứu vượt quá 200.000 lần/ngày \ EXCEPTION: Lỗi không xác định, vui lòng liên hệ 247\ ORDERCODE\_FORMAT\_EXCEPTION*:* Số vận đơn chứa ký tự đặc biệt (ngoại trừ\_-)\ ORDERCODE\_QUERY\_EXPIRED: Đơn hàng đã quá hạn tra cứu thông tin {% endhint %} ### LUỒNG TRẠNG THÁI ![](https://content.gitbook.com/content/Cvj03JMHuyGaXE4Z6Kkr/blobs/0WfQtDzdzQQFeiunZkPR/imgpsh_fullsize_anim.jpg) ## Tracking `GET` `https://tracking.247express.vn/api/Order/v1/Tracking?ordercode=12345&apikey=1111-1111-1111-1111-111111111` #### Query Parameters | Name | Type | Description | | --------- | ------ | -------------------------------- | | apiKey | string | Liên hệ với 247 để được cung cấp | | ordercode | string | Mã vận đơn | {% tabs %} {% tab title="200 " %} ``` { "errorMessage": null, "errorCode": null, "orderCode": "CNN2200057", "externalCode": null, "acceptDate": "2022-10-10T00:00:00+07:00", "status": "25", "statusName": "DANGDIPHAT", "trackingName": "Đang đi phát", "delayCode": null, "delayNote": null, "deliveryNotes": null, "deliveryDate": null, "poDeliveryID": null, "mailMan": null, "receiverName": null, "serviceTypeID": "DE", "mailerTypeID": "TL", "extraServiceName": null, "length": 0, "width": 0, "height": 0, "realWeight": 0.3, "calWeight": 0, "weight": 0.3, "quantity": 1, "price": 32000.0000, "priceFR": 0.0000, "farRegionFeeAmount": 6400.0000, "fuelFeeAmount": 9216.0000, "vatAmount": 3809.0000, "totalServiceCost": 51425.0000, "edtFrom": null, "edtTo": null, "postOfficeAcceptID": null, "codAmount": 0.000, "priceInfo": [ { "serviceName": "Chuyển phát nhanh", "serviceID": "DE", "cost": 32000.0000 }, { "serviceName": "Phí ngoại thành", "serviceID": "VSVX", "cost": 6400.0000 }, { "serviceName": "Phí xăng dầu", "serviceID": "Fuel", "cost": 9216.0000 }, { "serviceName": "Phí VAT", "serviceID": "VAT", "cost": 3809.0000 } ], "statuses": [ { "time": "2022-10-10T15:36:56.92+07:00", "status": "23", "statusName": "DALAYHANG", "trackingName": "Đã lấy hàng", "provinceName": "HỒ CHÍ MINH", "postOfficeName": "Phòng Công nghệ" }, { "time": "2022-10-10T15:37:10.323+07:00", "status": "24", "statusName": "DANGVANCHUYEN", "trackingName": "Đang vận chuyển", "provinceName": "HỒ CHÍ MINH", "postOfficeName": "Phòng Công nghệ" }, { "time": "2022-10-10T15:38:50.407+07:00", "status": "25", "statusName": "DANGDIPHAT", "trackingName": "Đang đi phát", "provinceName": "HỒ CHÍ MINH", "postOfficeName": "Phòng Công nghệ" } ], "trackings": [ { "statusID": "0", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:36:56.92+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Nhập hệ thống", "notes": null }, { "statusID": "2", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:36:56.92+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đóng gói", "notes": null }, { "statusID": "3", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:37:10.323+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đang chuyển tiếp", "notes": null }, { "statusID": "4", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:38:50.4+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đến bưu cục", "notes": "" }, { "statusID": "10", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:38:50.407+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Giao bưu tá phát", "notes": "" }, { "statusID": "5", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:38:50.41+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đi phát", "notes": "" } ], "estimateRoutes": null, "confirmImage": null } ``` {% endtab %} {% endtabs %} ### **Mô tả kết quả trả về** | Properties | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | errorMessage | Thông báo khi có lỗi | | errorCode | Mã lỗi | | orderCode | Mã đơn hàng | | status | Mã trạng thái đơn hàng | | statusName | Tên trạng thái đơn hàng | | delayCode | Mã lý do phát chưa thành công | | delayNote | Diễn giải khi phát chưa thành công | | deliveryNotes | Ghi chú giao hàng | | deliveryDate | Ngày phát | | receiverName | Tên người nhận | | mailerTypeID | Loại hình đơn hàng: HH - Hàng hóa; TL - Tài liệu | | length | Chiều dài | | width | Chiều rộng | | height | Chiều cao | | realWeight | Trọng lượng thực tế | | calWeight | Trọng lượng quy đổi dựa theo kích thước để tính giá | | weight | Trọng lượng tính cước | | quantity | Số lượng kiện | | price | Cước dịch vụ chính | | priceFR | Cước chuyển hoàn - chuyển tiếp | | farRegionFeeAmount | Phí ngoại thành | | fuelFeeAmount | Phí nhiên liệu | | vatAmount | VAT | | totalServiceCost | Tổng tiền phí các dịch vụ | | priceInfo |

Thông tin dịch vụ sử dụng:
\[
{
"serviceName": Tên dịch vụ,
"serviceID": Mã dịch vụ,
"cost": Giá tiền
},
...
]

| | statuses |

Lịch sử cập nhật trạng thái:
\[
{
"time": Thời gian cập nhật,
"status": Mã trạng thái,
"statusName": Tên trạng thái,
"trackingName": Tên tracking/trạng thái
},
...
]

| | trackings |

Lịch sử đơn hàng:
\[
{
"statusID": Mã trạng thái,
"statusName": Tên trạng thái,
"postOfficeID": Mã bưu cục,
"postOfficeName": Tên bưu cục,
"provinceID": Mã tỉnh thành của bưu cục,
"provinceName": Tên tỉnh thành của bưu cục,
"dateChange": Ngày cập nhật,
"notes": Ghi chú
},
...
]

| | estimateRoutes | Thời gian phát dự kiến | | confirmImage | Thông tin hình ảnh xác nhận | | acceptDate | Ngày 247 lấy thư/hàng | ### Bảng lý do phát chưa thành công
Delay CodeDelayNote
01Địa chỉ sai
02Địa chỉ đóng cửa
03Địa chỉ trên phong bì và phiếu gửi khác nhau
04Không tìm thấy địa chỉ
05Lạc tuyến
06Người nhận chuyển địa chỉ
07Người nhận báo không biết về thông tin này
08Người nhận không muốn nhận nữa
09Người nhận báo bận nên không nhận được
10Người nhận yêu cầu nhận vào thời gian khác
11Điện thoại người nhận khóa máy/thuê bao
12Người nhận không nghe điện thoại
13Người nhận vắng nhà/không có mặt ở cơ quan
14Không tồn tại người nhận tại địa chỉ phát
15Chờ người nhận đến văn phòng nhận
16Người nhận yêu cầu kiểm tra nội dung hàng
20Người nhận hẹn phát lại quá thời gian quy định
21Người nhận nghỉ thứ 7
22Người nhận nghỉ lễ
24Mưa lớn/Ngập nước/Bão lũ/Thiên tai
26Người gửi yêu cầu không phát và chuyển hoàn
30Hư hỏng nội dung bên trong bưu gửi
31Mất một phần bưu gửi
33Mất bưu gửi
35Số điện thoại người nhận bị sai số/nhầm số
40Lý do khác
41CMND/Thẻ căn cước bị mất/hỏng
43Người nhận yêu cầu giao cho người khác
46Sai thông tin đơn hàng
52Người gửi thay đổi địa chỉ phát
53Người gửi yêu cầu tiêu hủy
### Mẫu ví dụ ``` /api/Order/v1/Tracking?ordercode=12345&apikey=1111-1111-1111-1111-111111111 ``` # Cập nhật trạng thái Mẫu ví dụ API tích hợp phía khách hàng sử dụng API. Đối tác sử dụng dịch của 247, cung cấp API tương ứng bên dưới để 247 thực hiện trả lại trạng thái đơn hàng. {% hint style="info" %} * Sử dụng RESTful APIs * Content-Type: application/json * Hỗ trợ một trong các cơ chế xác thực sau: * Apikey * Basic Authentication {% endhint %} ## Cập nhật trạng thái đơn hàng `POST` `/IntergrationAPI` #### Headers | Name | Type | Description | | ------------ | ------ | ----------- | | Content-Type | string | ContentType | #### Request Body | Name | Type | Description | | -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- | | Time | datetime | Thời điểm phát sinh sự kiện | | TransactionId | string | Mã giao dịch | | DeliveryDate | datetime(null) | Ngày phát | | ReceiverName | string | Tên người nhận | | Mailman | string | Nhân viên phát thư | | DeliveryNotes | string | Ghi chú phát | | DelayNotes | string | Lý do chưa phát thành công | | RequestFeedbackCount | integer | Số lần yêu cầu phản hồi | | Description | string | Mô tả trạng thái | | Status | string | Mã trạng thái [*(xem chi tiết)* ](#danh-sach-trang-thai) | | StatusName | string | Tên trạng thái | | OrderCode | string | Mã vận đơn | | ApiKey | string | API key xác thực giữa 2 bên | | DelayCode | string | Mã lý do chưa phát thành công [*(xem chi tiết)*](/tracking/tracking-don-hang#bang-ly-do-phat-chua-thanh-cong) | | ExternalCode | string | Mã vận đơn khách hàng | | ReferenceCode | string | Mã tham chiếu khách hàng | {% tabs %} {% tab title="200 Cake successfully retrieved." %} ``` // Success { "IsError": false, "ErrorMessage": "" } // Error { "IsError": true, "ErrorMessage": "Mô tả lỗi" } ``` {% endtab %} {% endtabs %} ### Mẫu ví dụ ```json5 { "ApiKey": "EBD2E298-20AC-483F-80EC-B51CF8D79A2A", "OrderCode": "HD000003", "ExternalCode": "HD000003", "ReferenceCode": "HD000003" "Status": "25", "StatusName": "DANGDIPHAT", "Description": "Change order status: DANGVANCHUYEN ==> DANGDIPHAT", "RequestFeedbackCount": 0, "DelayCode": null, "DelayNotes": null, "DeliveryNotes": null, "Mailman": null, "DeliveryDate": null, "ReceiverName": "THANH", "TransactionId": "e07147ce-ebdb-47c6-ac96-959222494dbe", "Time": "2019-08-07T11:24:12.4946223+07:00" } ``` ### Danh sách trạng thái {% hint style="info" %} * 16: CHOXULY - chờ xử lý * 18: HUY - Hủy * 19: THATLAC - Thất lạc * 21: DATIEPNHAN - đã tiếp nhận * 23: DALAYHANG - đã lấy hàng * 24: DANGVANCHUYEN - Đang vận chuyển * 25: DANGDIPHAT - đang đi phát * 27: CHOCHUYENHOAN - chờ chuyển hoàn * 28: DACHUYENHOAN - đã chuyển hoàn * 30: PHATTHANHCONG - phát thành công * 32: TICHTHU - tịch thu {% endhint %} # Lịch sử cập nhật trạng thái Lịch sử các phiên 247 gửi trạng thái vận đơn sang khách hàng `POST` `api/Customer/GetStatusLogs` #### Headers | Name | Type | Description | | ------------------------------------------ | ------ | ---------------------------- | | ClientID\* | Number | ClientID lấy ở api đăng nhập | | Token\* | String | Token lấy ở api đăng nhập | #### Request Body | Name | Type | Description | | ------------------------------------------ | -------- | ------------------------------------------------------------------- | | FromDate\* | DateTime | Từ ngày | | ToDate\* | DateTime | Đến ngày | | OrderCodes | String | Mã đơn hàng 247 (Có thể truyền nhiều vận đơn cách nhau bởi dấu ",") | {% tabs %} {% tab title="200: OK " %} {% tabs %} {% tab title="Thành công" %} {% code fullWidth="true" %} ```json { "Data": { "Orders": [ { "OrderCode": "HD000003", "Histories": [ { "OrderCode": "HD000003", "ExternalCode": "HD000003", "ReferenceCode": "HD000003", "Status": "21", "StatusName": "DATIEPNHAN", "Description": null, "RequestFeedbackCount": 0, "DelayCode": null, "DelayNotes": null, "DeliveryNotes": null, "Mailman": null, "TransactionId": "8b2213ed-g2de-457b-a0e1-9a26c4d23a3f", "DeliveryDate": null, "ReceiverName": null, "Time": "2023-01-03T10:11:19.6240597+07:00", "IsCallError": false, "ErrorMessage": null, "IsPartnerResponseError": false, "PartnerResponseErrorMsg": null }, { "OrderCode": "HD000003", "ExternalCode": "HD000003", "ReferenceCode": "HD000003", "Status": "23", "StatusName": "DALAYHANG", "Description": null, "RequestFeedbackCount": 0, "DelayCode": null, "DelayNotes": null, "DeliveryNotes": null, "Mailman": null, "TransactionId": "eda18522-2ffc-48ce-beb8-abe32aa60a54", "DeliveryDate": null, "ReceiverName": null, "Time": "2023-01-04T10:11:19.6240597+07:00", "IsCallError": false, "ErrorMessage": null, "IsPartnerResponseError": false, "PartnerResponseErrorMsg": null } ] } ] }, "IsError": false, "ErrorMessage": "" } ``` {% endcode %} {% endtab %} {% tab title="Lỗi" %} ```json { "Data": null, "IsError": true, "ErrorMessage": "" // Mô tả lỗi } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### Mô tả kết quả trả về | Trường | Mô tả | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | Data | Dữ liệu chính | | Orders | Danh danh sách đơn hàng | | Histories | Danh sách những lần thay đổi trạng thái đơn hàng | | OrderCode | Mã vận đơn | | ExternalCode | Mã vận đơn khách hàng | | ReferenceCode | Mã tham chiếu khách hàng | | Status | Mã trạng thái [*(xem chi tiết)*](/webhooks/webhooks#danh-sach-trang-thai) | | StatusName | Tên trạng thái | | Description | Mô tả trạng thái | | RequestFeedbackCount | Số lần yêu cầu phản hồi | | DelayCode | Mã lý do chưa phát thành công [*(xem chi tiết)*](/tracking/tracking-don-hang#bang-ly-do-phat-chua-thanh-cong) | | DelayNotes | Lý do chưa phát thành công | | Mailman | Nhân viên phát thư | | TransactionId | Mã giao dịch | | DeliveryDate | Ngày phát | | DeliveryNotes | Ghi chú phát | | ReceiverName | Tên người nhận | | Time | Thời điểm phát sinh sự kiện | | IsCallError | Lỗi gửi trạng thái? | | ErrorMessage | Mô tả lỗi gửi trạng thái | | IsPartnerResponseError | Lỗi hệ thống khách hàng trả về? | | PartnerResponseErrorMsg | Mô tả lỗi hệ thống khách hàng trả về | # Getting Started Integrate API 247 ## How to integrate API 247? ### Steps * **Step 1:** Login to get ClientID and Token according to [the login API](/english-1.0.6/sso/sso-login). Username and Password will be provided as a customer of 247. * **Step 2:** Get [the ClientHubID list](/english-1.0.6/customer/list-of-clienthubs), which is a list of customer shipping address identifiers (ID). When creating an order for delivery, you must enter the correct identifier (ClientHubID) corresponding to the shipping address of that order. * **Step 3:** Get [a list of main services](/english-1.0.6/customer/main-services) that have been registered by the customer. * **Step 4:** Get [a list of value-added services](/english-1.0.6/customer/vat-services) that customers can use. * **Step 5:** To use [the order creation API](/english-1.0.6/customer/create-an-order), you must have the following information: * ClientID and Token in **Step 1**. * ClientHubId in **Step 2**. * Key services/value-added services in **Steps 3** and **4** (if used). ### API INFORMATION {% hint style="success" %} Staging: [https://customerapi-stg.247tech.vn](https://customerapi-stg.247tech.vn/)\ Production: {% endhint %} ### RATE LIMIT {% hint style="warning" %} Login API: 5 requests/minute/IP address All other APIs: 360 requests/minute/IP address {% endhint %} ### NOTES {% hint style="info" %} Marked required fields must be entered.\ All APIs require a Header with Token and ClientID. {% endhint %} # Change Log ## 1.0.7 - 2026-07-17 Add api [Check shipping address](/english-1.0.6/customer/check-shipping-address) ## 1.0.6 - 2024-07-24 Add API Feedback Add COPAmt parameter to the [create order api](/english-1.0.6/customer/create-an-order) and [update order api](/english-1.0.6/customer/update-order). ## 1.0.5 - 2024-02-27 Add Packages parameter to the [create order api](/english-1.0.6/customer/create-an-order) and [update order api](/english-1.0.6/customer/update-order). ## 1.0.4 - 2023-07-12 ### Changed Add API get [Status update log](/english-1.0.6/webhooks/status-update-log). ## 1.0.3 - 2020-10-16 247Express implements API support on nodejs platform compatible with today's popular frameworks such as ReactJS, Angular, VueJS... ## 1.0.2 - 2020-03-26 ### Changed Add return shipping parameters to the order creation API:\ Details of the changes please refer [here](/english-1.0.6/customer/create-an-order). #### Example ``` "ReturnInfo": { "FRPhone":"0909123456", "FRProvinceName": "Hồ Chí Minh", "FRDistrictName": "Quận Tân Bình", "FRWardName": "Phường 12", "FRDetailAddress" : "18A Cộng Hòa", "FRFullAddress": "18A Cộng Hòa, Phường 12, Quận Tân Bình, Hồ Chí Minh" } ``` #### ## 1.0.1 - 2020-01-09 ### Fixed * Quantity property name in order object. ### Changed * Change the UI. ## 1.0.0 - 2019-11-20 ### Added * Released version 1.0.0 # Support ### How to register? Please contact sales support for a demo account. ### When I have problems with the login API, where can I contact? If you are having trouble logging in using the API, please contact online technical support through the channels provided below. {% hint style="info" %} SKYPE: hotro.247post\ ZALO : 19006980\ EMAIL: {% endhint %} # Header Request Description of the header configuration for the API request ## API `POST` `https://api.247post.vn/api/API` All Customer API will use below header template for authentication. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ---------------------------------- | | Content-Type\* | string | application/json | | ClientID\* | string | ClientID, get from ClientLogin API | | token\* | string | Token, get from ClientLoginAPI | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} # Shipment Pick-up and Delivery Workflow
# Main services API get list of main services 247Express has provided. ## GetServiceTypes `POST` `/Api/Customer/GetServiceTypes` {% tabs %} {% tab title="200 " %} ``` { "ServiceTypes": [ { "ServiceTypeID": "DE", "ServiceTypeName": "Chuyển phát nhanh", "CalculateVolumetric": 6000 }, { "ServiceTypeID": "TF", "ServiceTypeName": "Dịch vụ Chuyển phát đường bộ", "CalculateVolumetric": 4000 }, { "ServiceTypeID": "TH", "ServiceTypeName": "Chuyển phát 55h", "CalculateVolumetric": 4000 }, { "ServiceTypeID": "IE", "ServiceTypeName": "Chuyển phát nhanh quốc tế", "CalculateVolumetric": 5000 }, { "ServiceTypeID": "IM", "ServiceTypeName": "Chuyển phát tiết kiệm quốc tế", "CalculateVolumetric": 5000 } ], "ErrorMessage": null, "IsError": false, "ErrorCode": null, "StatusCode": 0, "IsPassError": false } ``` {% endtab %} {% endtabs %} ### Example ``` {} ``` ### Response description | Properties | Description | | ------------------- | ------------------------------------------------------------------------------ | | ServiceTypeID | ServiceTypeID | | ServiceTypeName | ServiceTypeName | | CalculateVolumetric | Calculate the converted weight = Length x Width x Height / CalculateVolumetric | # Value-added services API get list of Value-added services is provided by 247Express ## Services `POST` `/api/Customer/Services` {% tabs %} {% tab title="200 " %} ``` { "Services": [ { "ServiceID": "HDL", "ServiceName": "Hàng đông lạnh" }, { "ServiceID": "BP", "ServiceName": "Báo phát" }, { "ServiceID": "HQK", "ServiceName": "DV hàng quá khổ" } ], "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Example ``` {} ``` # List of ClientHubs API get list of pick up points (Client hub) ## CustomerGetClientHubs `POST` `/Api/Customer/CustomerGetClientHubs` #### Request Body | Name | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | GetFullAddress | boolean |

true: take all including approved and unapproved Clienthubs.
false: take only approved Client Hub

| {% tabs %} {% tab title="200 " %} ``` { "Errors": [], "ErrorMessage": "", "Hubs": [ { "ClientHubID": 1158, "Address": "nguyễn huệ", "ContactName": "SAIGONBPO", "ContactPhone": "0963225098", "ManagerName": null, "ManagerPhone": null, "IsMain": true, "DistrictName": "Quận Một", "ProvinceName": "HỒ CHÍ MINH", "WardName": "Phường Bến Nghé", "StatusName": "Đã duyệt", "Phone": "0963225098", "IsEnable": false } ] } ``` {% endtab %} {% endtabs %} ### Example ``` { "GetFullAddress": true } ``` # Create an order ## Recipient Address For addresses with a **3-level structure** (Province/City, District, Ward/Commune — based on Vietnam’s administrative divisions **before July 1, 2025**), provide the following fields: * **ReceiverProvinceName**: Recipient’s province/city name. * **ReceiverDistrictName**: Recipient’s district name. * **ReceiverWardName**: Recipient’s ward/commune name. For addresses with a **2-level structure** (Province/City, Ward/Commune — based on Vietnam’s administrative divisions **from July 1, 2025**), provide the following fields: * **ReceiverProvinceName**: Recipient’s province/city name. * **ReceiverDistrictName**: Leave null. * **ReceiverWardName**: Recipient’s ward/commune name. ## CustomerApiCreateOrder `POST:``/Api/Customer/CustomerAPICreateOrder` **Headers** | Name | Value | | -------- | -------------- | | ClientID | From login api | | Token | From login api | **Body**
NameTypeDescription
ClientHubID*integerClientHubID (Required when not passed CusWareHouseID)
CusWareHouseIDstringShopID/WareHouseID (Required when not passed ClientHubID)
ContactNamestringContact name
ContactPhonestringContact phone
SenderAddressstringSender full address
DirectSenderNamestringDirect sender name
ReceiverPhonestringRecipient's phone.
ReceiverNamestringRecipient's name.
ReceiverAddress*stringRecipient's full address (2-level format: house number, Street name, Ward name, Province name / 3-level format: house number, Street name, Ward name, District name, Province name).
ReceiverProvinceName*stringRecipient's Province name. (2-level format and 3-level format)
ReceiverDistrictName*stringRecipient's District name. This field must be omitted or set to null when using the new 2-level address format (Commune/Ward + Province/City), following Vietnam’s administrative changes effective from July 1st, 2025.
ReceiverWardNamestringRecipient's Ward name.
ReceiveCompanyNamestringrecipient company name
RealWeightnumberReal weight(kg).
LengthnumberLength (cm).
WidthnumberWidth (cm).
HeightnumberHeight (cm).
QuantityintegerQuantity package.
NotestringNote.
ServiceTypeIDstringService code.
MailerTypestringCode type of freight: HH - Goods. TL - Document.
CODAmountnumberThe amount of COD will be collected from the recipient.
ExternalCodestringCustomer order code (max length: 20).
ReferenceCodestringCustomer reference code
SpecialInstructionIdnumberSpecial note code for COD orders only: 1 - Show the goods. 2 - Do not show the goods.
InformFeenumberDeclared value. Cases to note when declaring: 1 - Price calculation volume >= 2.5kg need to choose type = HH (goods). 2 - Type = HH (goods), required to enter the declared value (InformFee). 3 - If you choose DVBH (insurance service), you must enter the declared value(InformFee)
ExtraServicesarrayList of VAT Services
Packagesarray
{
    "PackageID": "", //PackageID,
    "Length": 100, // Length (cm) (Required when entering in Height, Width),
    "Width": 50, // Width (cm)(Required when entering in Height, Length),
    "Height": 80, // Height (cm) (Required when entering in Width, Length),
    "RealWeight": 25 //Real weight (kg)
}

(*)The number of Packages must be equal to Quantity property. In case Quantity = 1 thenPackages = []

COPAmtnumberCOP amount (Cash on pickup)
RequestedDeliveryTimedatetimeRequested delivery time (only applicable to delivery service units that support scheduled delivery)
RequestedDeliveryTypestringDelivery appointment type:
"DUNGGIO": On-time
"TRUOCGIO": Before the specified time
(only applicable to delivery service units that support scheduled delivery)
**Response** {% tabs %} {% tab title="200" %} ```json { "Errors": [], "ErrorCode": "0", "OrderInfo": { "OrderCode": "HD000003", "ReferenceCode": "HD000003", "ExternalCode": "HD000003", "TotalServiceCost": 44176, "ExtraServices": [ { "ServiceName": "Chuyển phát nhanh", "ServiceID": "DE", "Cost": 16800 }, { "ServiceName": "Hàng đông lạnh", "ServiceID": "HDL", "Cost": 15000 }, { "ServiceName": "Báo phát", "ServiceID": "BP", "Cost": 5000 }, { "ServiceName": "Phí xăng dầu", "ServiceID": "Fuel", "Cost": 3360 }, { "ServiceName": "Phí VAT", "ServiceID": "VAT", "Cost": 4016 } ], "DeliveryType": "1" }, "ErrorMessage": "" } ``` {% endtab %} {% tab title="401" %} ```json { "IsError": true, "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này." } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ---------------- | ------------ | ------------------------------------------------------- | | Errors | array object | Array of Errors | | ErrorCode | string | Error code | | ErrorMessage | string | Error message | | **OrderInfo** | object | Order Info | | OrderCode | string | Order ID | | ReferenceCode | string | Customer reference code | | ExternalCode | string | Customer order code | | TotalServiceCost | number | Total Service Cost | | **ExtraService** | array object | Value-added services list | | ServiceName | string | Value-added service name | | ServiceID | string | Value-added service id | | Cost | number | Value-added service cost | | DeliveryTimeType | string |

Delivery by:
"1" - 247 Exprest
"2" - Other

| ### Example ```json { "OrderInfo":{ "ClientHubID":11583, "CusWareHouseID":"30984", "ContactName": "Trần Văn B", "ContactPhone": "0332318317", "ReceiverPhone":"0345555777", "ReceiverName":"Trương Chí Nhân", "ReceiverAddress":"326 Võ Văn Kiệt, phường Cầu Ông Lãnh, Hồ Chí Minh, Việt Nam", "ReceiverProvinceName":"Hồ Chí Minh", "ReceiverDistrictName": null, "ReceiverWardName":"Phường Cầu Ông Lãnh", "RealWeight":1, "Length":0, "Width":0, "Height":0, "Quantity":1, "Note":"Tài liệu", "ServiceTypeID":"DE", "MailerType":"TL", "CODAmount":0, "ExternalCode":"HD000003", "ReferenceCode": "HD000003", "SpecialInstructionId":1, "ExtraServices":[ { "ServiceID":"PTN", "Type":2 }, { "ServiceID":"BP", "Type":2 } ] } } ``` ### Error Code {% hint style="danger" %} * 1: Ward error * 2: District error * 3: Province error * 4: Duplicate ordercode * 5: Server error * 6: Was an exception * 9: SpecialInstruction is required * 10: ServiceType is required * 11: SenderAddred is invalid * 12: Account is invalid * 15: OrderCode is required * 16: OrderCode is invalid * 17: ReceiverAddress is invalid * 18: MailerType is invalid * 19: Quantity is invalid * 20: Packages is invalid * 21: Sender info is incomplete * 25: COP amount is invalid {% endhint %} # Update Order API Update Order ## Recipient Address For addresses with a **3-level structure** (Province/City, District, Ward/Commune — based on Vietnam’s administrative divisions **before July 1, 2025**), provide the following fields: * **ReceiverProvinceName**: Recipient’s province/city name. * **ReceiverDistrictName**: Recipient’s district name. * **ReceiverWardName**: Recipient’s ward/commune name. For addresses with a **2-level structure** (Province/City, Ward/Commune — based on Vietnam’s administrative divisions **from July 1, 2025**), provide the following fields: * **ReceiverProvinceName**: Recipient’s province/city name. * **ReceiverDistrictName**: Leave null. * **ReceiverWardName**: Recipient’s ward/commune name. ## CustomerAPIUpdateOrder `POST` `/api/Customer/CustomerAPIUpdateOrder` #### Request Body
NameTypeDescription
OrderCode*stringFrom response of Create an order api
ClientHubIDintergerClientHubID (Required when not passed CusWareHouseID)
CusWareHouseIDstringShopID/WareHouseID (Required when not passed ClientHubID)
ContactNamestringContact name
ContactPhonestringContact phone
SenderAddressstringSender full address
NotestringNote
ExtraServicesarrayList of VAT Services
InformFeestringDeclared value. Cases to note when declaring:
1 - Price calculation volume >= 2.5kg need to choose type = HH (goods).
2 - Type = HH (goods), required to enter the declared value (InformFee).
3 - In the form to select DVBH (insurance service), required to enter the declared value (InformFee).
SpecialInstructionIdstringSpecial note code for COD orders only:
1 - Show the goods.
0 - Do not show the goods.
MailerTypestringCode type of freight:
HH - Goods
TL - Document
ExternalCodestringCustomer order code (max length: 20).
ReferenceCodestringCustomer reference code
CODAmountnumberThe amount of COD will be collected from the recipient
ServiceTypeIDstringServiceTypeID
HeightnumberHeight (cm)
WidthnumberWidth (cm)
LengthnumberLength(cm)
QuantityintegerQuantity package
RealWeightnumberReal Weight (kg)
ReceiverWardNamestringRecipient's Ward name
ReceiverDistrictName*stringRecipient's District name
ReceiverProvinceName*stringRecipient's Province name
ReceiverAddressstringRecipient's full address
ReceiverNamestringRecipient's name
ReceiverPhonestringRecipient's phone
ReceiveCompanyNamestringrecipient company name
Packagesarray
{
    "PackageID": "", //PackageID,
    "Length": 100, // Length (cm) (Required when entering in Height, Width),
    "Width": 50, // Width (cm)(Required when entering in Height, Length),
    "Height": 80, // Height (cm) (Required when entering in Width, Length),
    "RealWeight": 25 //Real weight (kg)
}

(*)The number of Packages must be equal to Quantity property. In case Quantity = 1 thenPackages = []

COPAmtnumberCOP amount (Cash on pickup)
RequestedDeliveryTimedatetimeRequested delivery time (only applicable to delivery service units that support scheduled delivery)
RequestedDeliveryTypestringDelivery appointment type:
"DUNGGIO": On-time
"TRUOCGIO": Before the specified time
(only applicable to delivery service units that support scheduled delivery)
{% tabs %} {% tab title="200 " %} ``` { "Errors": [], "ErrorCode": "0", "OrderInfo": { "OrderCode": "HD000003", "ReferenceCode": "HD000004", "ExternalCode": "HD000003", "TotalServiceCost": 44176, "ExtraServices": [ { "ServiceName": "Chuyển phát nhanh", "ServiceID": "DE", "Cost": 16800 }, { "ServiceName": "Hàng đông lạnh", "ServiceID": "HDL", "Cost": 15000 }, { "ServiceName": "Báo phát", "ServiceID": "BP", "Cost": 5000 }, { "ServiceName": "Phí xăng dầu", "ServiceID": "Fuel", "Cost": 3360 }, { "ServiceName": "Phí VAT", "ServiceID": "VAT", "Cost": 4016 } ], "DeliveryType": "1" }, "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Example ```json { "OrderInfo":{ "OrderCode": "HD000003", "ClientHubID":11583, "CusWareHouseID":"30984", "ContactName": "Trần Văn B", "ContactPhone": "0332318317", "ReceiverPhone":"0345555777", "ReceiverName":"Nguyễn Thành Đạt", "ReceiverAddress":"12 Tân Trào, phường Tân Phú, Quận 7, Hồ Chí Minh, Việt Nam", "ReceiverProvinceName":"Hồ Chí Minh", "ReceiverDistrictName":"Quận 7", "ReceiverWardName":"Phường Tân Phú", "RealWeight":1, "Length":0, "Width":0, "Height":0, "Quantity":1, "Note":"Tài liệu", "ServiceTypeID":"DE", "MailerType":"TL", "CODAmount":0, "ExternalCode":"HD000003", "SpecialInstructionId":1, "ReferenceCode": "HD000004", "ExtraServices":[ { "ServiceID":"PTN", "Type":2 }, { "ServiceID":"BP", "Type":2 } ] } } ``` ### Errors Code {% hint style="danger" %} * 1: Ward error * 2: District error * 3: Province error * 4: Duplicate ordercode * 5: Server error * 6: Was an exception * 8: Update Order error * 9: SpecialInstruction is required * 10: ServiceType is required * 12: Account is invalid * 13: Order is not found * 15: OrderCode is required * 16: OrderCode is invalid * 17: ReceiverAddress is invalid * 18: MailerType is invalid * 19: Quantity is invalid * 20: Packages is invalid * 21: Sender info incomplete * 25: COPAmt is invalid {% endhint %} # Check shipping address API for checking shipping address ## CheckAddressInfo `POST` `/api/Customer/CheckAddressInfo` **Headers** | Name | Value | | -------- | -------------- | | ClientID | From login api | | Token | From login api | **Body** | Name | Type | Description | | ------- | ------ | ---------------- | | Address | string | Shipping address | **Response** {% tabs %} {% tab title="200" %} ```json { "DeliveryArea": "IN", "IsError": false, "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% tab title="401" %} ```json { "IsError": true, "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này." } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DeliveryArea | string |

  • IN: Delivery address within the service area (Order can be created)
  • OUT: Delivery address outside the service area (Order can be created)
  • UNKNOWN: Unrecognized delivery address (Not ready for order creation)
| | IsError | bool | IsError | | ErrorMessage | string | Error message | ### Example ```json { "Address": "326 Võ Văn Kiệt, Phường Cầu Ông Lãnh, HCM" } ``` # Cancel order Cancel an order when a new order is created or in received status. ## CancelOrder `POST` `/Api/Customer/CancelOrder` #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | OrderCode\* | string | Order code | {% tabs %} {% tab title="200 " %} ``` { "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Example ``` { "OrderCode":"WKH091808-00002" } ``` ### Errors Code {% hint style="danger" %} 6: Exception. 12: Customer account is invalid. 13: Order not found. 14: Order status is invalid. 15: OrderCode is null or empty. 16: Order is invalid. {% endhint %} # Get delivered pictures The API get delivered pictures. ## GetOrderImages `POST` `/Api/Customer/GetOrderImages` #### Request Body | Name | Type | Description | | --------- | ------ | ----------- | | OrderCode | string | Order code | {% tabs %} {% tab title="200 " %} ``` { "Items": [ { "No": 1, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/39raazlyjhotdi/123456789-1-image-1892fa10-61db-4446-8679-fcbede8ff542.jpg?dl=1" }, { "No": 2, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/8nntd5rgidma4n/123456789-1-image-a3ba444b-e6d4-48c3-a4b0-d419d2e96979.jpg?dl=1" }, { "No": 3, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/qyfr0kkhqajsbw/123456789-1-image-25dfed28-6885-48d1-b2eb-638e389146a4.jpg?dl=1" }, { "No": 4, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/elzsazr502ijkq/123456789-1-image-93fc383a-90eb-4c41-ac62-50ea58ad3e74.jpg?dl=1" }, { "No": 5, "OrderCode": "123456789", "ImageURL": "https://www.dropbox.com/s/j63171se6m6sxs/123456789-1-image-e770a911-f81b-41c7-be53-af90976b7146.jpg?dl=1" } ], "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Example ``` { "OrderCode": "123456789" } ``` # Pricing The API charges a service fee of 247. The price is for reference only. ## GetPriceForCustomerAPI `POST` `/Api/Customer/GetPriceForCustomerAPI` #### Request Body | Name | Type | Description | | ---------------- | ------ | --------------------------------------------------------------- | | ServiceTypeID | string | Service code | | ClientHubID | number | ClientHubID (not required when pickup address is flexible) | | RealWeight | number | Real weight (after packing) (kg) | | Height | number | Height (0 if size is unknow) (cm) | | Width | number | Width (0 if size is unknow) (cm) | | Length | number | Length (0 if size is unknow) (cm) | | FromProvinceName | string | From province name (required if the pickup address is flexible) | | ToWardName | string | To ward name | | ToDistrictName | string | To district name | | ToProvinceName | string | To province name | {% tabs %} {% tab title="200 " %} ``` { "ExtraServices": [ { "ServiceName": "Chuyển phát nhanh", "ServiceID": "DE", "Cost": 1184800.0 }, { "ServiceName": "Phí xăng dầu", "ServiceID": "Fuel", "Cost": 236960.0 }, { "ServiceName": "Phí VAT", "ServiceID": "VAT", "Cost": 142176.0 } ], "TotalServiceCost": 1563936.0, "IsError": false, "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Example ``` { "ToProvinceName": "Hồ Chí Minh", "ToDistrictName": "Quận 1", "ToWardName": "Phường Bến Nghé", "Length": 60, "Width": 60, "Height": 60, "RealWeight": 60, "ClientHubID": "5590", "ServiceTypeID": "DE" } ``` # Create client hub Create client hub for customer. ## Address For addresses with a **3-level structure** (Province/City, District, Ward/Commune — based on Vietnam’s administrative divisions **before July 1, 2025**), provide the following fields: * **ProvinceName**: Recipient’s province/city name. * **DistrictName**: Recipient’s district name. * **WardName**: Recipient’s ward/commune name. For addresses with a **2-level structure** (Province/City, Ward/Commune — based on Vietnam’s administrative divisions **from July 1, 2025**), provide the following fields: * **ProvinceName**: Recipient’s province/city name. * **DistrictName**: leave null. * **WardName**: Recipient’s ward/commune name. ## CustomerInsertClientHub `POST` `/Api/Customer/CustomerInsertClientHub` #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- | | Address\* | string | Customer's Addresss following Apartment number/Street name, Ward name, District name, Province name. | | ContactName\* | string | Contact name | | ContactPhone\* | string | Contact phone | | ProvinceName\* | string | Province name | | DistrictName\* | string | District name | | WardName | string | Ward name | | CusWarehouseID | string | ID of Shop/WareHouse | | CusWarehouseName | String | Name of Shop/WareHouse | {% tabs %} {% tab title="200 " %} ``` { "HubInfo": { "Address": "HH1, Yên Hòa, Cầu Giấy, Hà Nội", "WardID": "CYGYHO", "ClientHubID": "248", "ContactName": "Nguyễn Thành Trung", "ContactPhone": "0986226622", "DistrictID": "CGY", "IsMain": "true", "ProvinceID": "HNI", "CustomerID": "15", "Status": "Init", "StatusName": "Chờ duyệt", "CusWarehouseName: "Chi nhánh HN1" }, "Errors": [], "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} ### Example ``` { "HubInfo": { "Address": "326 Võ Văn Kiệt, Phường Cầu Ông Lãnh, Hồ Chí Minh", "ContactName": "Nguyễn Văn A", "ContactPhone": "0909123456", "ProvinceName": "Thành phố Hồ Chí Minh", "WardName": "Phường cầu ông lãnh", "CusWarehouseID": "30984", "CusWarehouseName": "Chi nhánh số 3" } } ``` # Update client hub Update contact name, contact phone of client hub. ## CustomerUpdateClientHub `POST` `/api/Customer/CustomerUpdateClientHub` #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | ------------ | | ClientHubID\* | int | ClientHubID | | ContactName\* | string | ContactName | | ContactPhone\* | string | ContactPhone | {% tabs %} {% tab title="200: OK " %} ```javascript { "IsError": false, "Errors": [], "ErrorMessage": "", "DepositChangeAmount": 0.0 } ``` {% endtab %} {% endtabs %} ### Example ``` { "HubInfo": { "ClientHubID": 1285, "ContactName": "Tran Van B", "ContactPhone": "0909123123" } } ``` # Feedback ## CustomerConfirmDelivery `POST` `/api/Customer/CustomerConfirmDelivery` **Headers** | Name | Value | | -------- | ---------------------------------------------- | | ClientID | From [SSO-Login](/english-1.0.6/sso/sso-login) | | Token | From [SSO-Login](/english-1.0.6/sso/sso-login) | **Body** | OrderCode\* | string | OrderCode | | ------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | ConfirmID\* | string | ConfirmID [*(detail)*](#thong-tin-ma-xac-nhan-confirmid) | | Notes | string | Notes | | **DeliveryInfo** | object | Delivery Info | | ReceiverName | string | Recipient's name | | ReceiverAddress | string | Recipient's full address (house number, Street name, Ward name, District name, Province name). | | ReceiverPhone | string | Recipient's phone | | DeliveryTime | DateTime | ReDelivery Time | **Response** {% tabs %} {% tab title="200" %} ```json { "IsError": false, "Errors": [], "ErrorMessage": "", "ErrorCode": "" } ``` {% endtab %} {% tab title="200" %} ```json { "IsError": true, "Errors": [ { "ErrorMessage": "Số điện thoại không hợp lệ (09871111231)", "PropertyName": "ReceiverPhone" } ], "ErrorMessage": "Số điện thoại không hợp lệ (09871111231)", "ErrorCode": "24" } ``` {% endtab %} {% tab title="401" %} ```json { "IsError": true, "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này." } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------------- | ------------ | ------------------------------------------ | | IsError | bool | IsError? | | ErrorMessage | string | Error mesage | | ErrorCode | string | Error code [*(detail)*](#thong-tin-ma-loi) | | **Errors** | array object | Array of Errors | | Errors.PropertyName | string | Property name | | Errors.ErrorMessage | string | Error mesage of property | ### ConfirmID {% hint style="info" %} * 1: Re-Delivery * 2: Return to sender address * 3: Return to other address * 4: Forward to order address * 5: Destroy {% endhint %} ### Errors Code {% hint style="danger" %} * 1: Ward error * 2: District Error * 3: Province Error * 6: Was an exception * 13: OrderCode not found * 14: OrderCode's status is invalid * 15: OrderCode is not allow null * 17: ReceiverAddress is invalid * 22: ConfirmID is in valid * 23: DeliveryInfo is not allow null * 24: Delivery info is invalid {% endhint %} ### Example ```json { "OrderCode" : "HD00001", "ConfirmID" : 3, "DeliveryInfo" : { "ReceiverName" : "Thành", "ReceiverAddress" : "326 Võ Văn Kiệt, Cô Giang, Quận 1", "ReceiverPhone" : "09871111231" }, "Notes": "Chuyển hoàn về kho" } ``` # SSO - Login Instructions for using the login API ## SSO - Login `POST` `/api/Client/ClientLogin` NOTE: Please use the account provided by 247 #### Headers | Name | Type | Description | | ------------ | ------ | ------------ | | Content-Type | string | Content Type | #### Request Body | Name | Type | Description | | -------- | ------ | ----------- | | UserName | string | UserName | | Password | string | Password | {% tabs %} {% tab title="200 Logged in successfully." %} ``` Mẫu ví dụ khi đăng nhập thành công: { "ClientID": 2876, "ClientName": "Lê Thanh Tùng", "Token": "e93e4ad62b8b35d5361bb12f2de77330e834ac0a1e6a6fa39f4c920d0646e198", "Errors": [], "ErrorMessage": "" } Mẫu ví dụ khi đăng nhập không thành công: { "ClientID": 0, "ClientName": null, "Token": null, "Errors": [ { "ErrorMessage": "Tên tài khoản hoặc mật khẩu không đúng!", "PropertyName": null } ], "ErrorMessage": " | Tên tài khoản hoặc mật khẩu không đúng! | Tên tài khoản hoặc mật khẩu không đúng! | Tên tài khoản hoặc mật khẩu không đúng!" } ``` {% endtab %} {% endtabs %} ### Example ``` { "UserName": "TXN-KH18-0059", "Password": "456123@" } ``` # Order Tracking Tracking requests are limited to 200,000 per day. Tracking data is available for up to six (6) months from the shipment acceptance date. A source IP address is required to enable tracking access. {% hint style="info" %} API Staging: [https://tracking-stg.247tech.vn](https://tracking-stg.247tech.vn/)\ API Production: {% endhint %} {% hint style="info" %} Statuses: * ACCEPTED: The order was created using API or Customer website 247Express. * PICKED\_UP:The order has been picked up by the delivery staff of 247Express. * IN\_TRANSIT: The order is being shipped by 247. * DELIVERING: Orders are being delivered. * DELIVERED: The order has been successfully delivered. * PENDING\_FOR\_PROCEED: The order has not been successfully delivered, pending. * PENDING\_FOR\_RETURN: The order is being returned to the customer. * RETURNED: The order has been returned to the customer. * LOST: The order has been lost. * CANCEL: The order has been cancelled. * CONFISCATED: The order was confiscated by the authorities for violating the category of goods. {% endhint %} ### TRACKING API KEY {% hint style="info" %} To get the apikey, following: * Login to the website: [https://247express.vn](https://247express.vn/) * Go to the function "CUSTOMER INFORMATION". {% endhint %} ### Error codes {% hint style="danger" %} MISSING\_APIKEY: Missing Apikey.\ MISSING\_ORDERCODE: Missing Ordercode.\ ORDERCODE\_MIN\_LENGTH: OrderCode less than 5 characters.\ ORDERCODE\_MAX\_LENGTH: The maximum number of OrderCode is 20 characters.\ ORDERCODE\_NOT\_FOUND: OrderCode is not found.\ ORDERCODE\_DOES\_NOT\_BELONG\_TO\_YOUR\_ACCOUNT: Ordercode does not belong to your account.\ APIKEY\_NOT\_FOUND: Apikey is not found.\ APIKEY\_LIMIT: Look up more than 200,000 times/day.\ EXCEPTION: Unknown error, please contact 247.\ ORDERCODE\_FORMAT\_EXCEPTION*:* The ordercode contain special characters (except \_-).\ ORDERCODE\_QUERY\_EXPIRED: The order has exceeded the tracking lookup period. {% endhint %} ### Workflow ![](https://content.gitbook.com/content/jXAnwuWJ2j7Luqyl3eBN/blobs/LT10wYAzW9SJg2r23u48/imgpsh_fullsize_anim.jpg) ## Tracking `GET` `https://tracking.247express.vn /api/Order/v1/Tracking?ordercode=12345&apikey=1111-1111-1111-1111-111111111` #### Query Parameters | Name | Type | Description | | --------- | ------ | ----------- | | apiKey | string | Api key | | ordercode | string | Order code | {% tabs %} {% tab title="200 " %} ``` { "errorMessage": null, "errorCode": null, "orderCode": "CNN2200057", "externalCode": null, "acceptDate": "2022-10-10T00:00:00+07:00", "status": "25", "statusName": "DANGDIPHAT", "trackingName": "Đang đi phát", "delayCode": null, "delayNote": null, "deliveryNotes": null, "deliveryDate": null, "poDeliveryID": null, "mailMan": null, "receiverName": null, "serviceTypeID": "DE", "mailerTypeID": "TL", "extraServiceName": null, "length": 0, "width": 0, "height": 0, "realWeight": 0.3, "calWeight": 0, "weight": 0.3, "quantity": 1, "price": 32000.0000, "priceFR": 0.0000, "farRegionFeeAmount": 6400.0000, "fuelFeeAmount": 9216.0000, "vatAmount": 3809.0000, "totalServiceCost": 51425.0000, "edtFrom": null, "edtTo": null, "postOfficeAcceptID": null, "codAmount": 0.000, "priceInfo": [ { "serviceName": "Chuyển phát nhanh", "serviceID": "DE", "cost": 32000.0000 }, { "serviceName": "Phí ngoại thành", "serviceID": "VSVX", "cost": 6400.0000 }, { "serviceName": "Phí xăng dầu", "serviceID": "Fuel", "cost": 9216.0000 }, { "serviceName": "Phí VAT", "serviceID": "VAT", "cost": 3809.0000 } ], "statuses": [ { "time": "2022-10-10T15:36:56.92+07:00", "status": "23", "statusName": "DALAYHANG", "trackingName": "Đã lấy hàng", "provinceName": "HỒ CHÍ MINH", "postOfficeName": "Phòng Công nghệ" }, { "time": "2022-10-10T15:37:10.323+07:00", "status": "24", "statusName": "DANGVANCHUYEN", "trackingName": "Đang vận chuyển", "provinceName": "HỒ CHÍ MINH", "postOfficeName": "Phòng Công nghệ" }, { "time": "2022-10-10T15:38:50.407+07:00", "status": "25", "statusName": "DANGDIPHAT", "trackingName": "Đang đi phát", "provinceName": "HỒ CHÍ MINH", "postOfficeName": "Phòng Công nghệ" } ], "trackings": [ { "statusID": "0", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:36:56.92+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Nhập hệ thống", "notes": null }, { "statusID": "2", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:36:56.92+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đóng gói", "notes": null }, { "statusID": "3", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:37:10.323+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đang chuyển tiếp", "notes": null }, { "statusID": "4", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:38:50.4+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đến bưu cục", "notes": "" }, { "statusID": "10", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:38:50.407+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Giao bưu tá phát", "notes": "" }, { "statusID": "5", "postOfficeID": "CNN", "provinceID": "HCM", "provinceName": "HỒ CHÍ MINH", "dateChange": "2022-10-10T15:38:50.41+07:00", "postOfficeName": "Phòng Công nghệ", "statusName": "Đi phát", "notes": "" } ], "estimateRoutes": null, "confirmImage": null } ``` {% endtab %} {% endtabs %} ### Response description | Properties | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | errorMessage | Message when there is an error | | errorCode | Message code | | orderCode | Order code | | status | Order status ID | | statusName | Order status name | | delayCode | Delay code | | delayNote | Note the information when the delivery has not succeeded yet | | deliveryNotes | Delivery notes | | deliveryDate | Delivery date | | receiverName | Receiver name | | mailerTypeID | Type of Order: HH-Goods, TL-Document | | length | Size of Package - Length | | width | Size of Package - Width | | height | Size of Package - Height | | realWeight | Real Weight of Package | | calWeight | Convert weight to charge | | weight | Weight used to calculate freight | | quantity | Number of packages | | price | Main service price (ServiceType) | | priceFR | Forward & Return fee | | farRegionFeeAmount | Suburban Fee | | fuelFeeAmount | Fuel Fee | | vatAmount | V.A.T tax amount | | totalServiceCost | Total service cost | | priceInfo |

Service information used:
\[
{
"serviceName": Service name,
"serviceID": Service ID,
"cost": Service cost
},
...
]

| | statuses |

Status update history:
\[
{
"time": Time update status,
"status": Status ID,
"statusName": Status name,
"trackingName": Tracking name/status
},
...
]

| | trackings |

Track order history:
\[
{
"statusID": Tracking status ID,
"statusName": Tracking status name,
"postOfficeID": Post Office ID,
"postOfficeName": Post Office name,
"provinceID": Province ID of Post Office,
"provinceName": Province name of Post Office,
"dateChange": Update date,
"notes": Notes
},
...
]

| | estimateRoutes | Estimate Delivery Time | | confirmImage | Delivered pictures | | acceptDate | Date 247 Picked up | ### List of reasons for delay
Delay CodeDelayNote
1Wrong address.
2The recipient is not at the address, the recipient's house is closed.
3Addresses on envelopes and delivery slips are different. Mean when the dispatcher mistakenly pasted the delivery information slip on the package.
4Address not found.
5Wrong route delivered in logistics.
6The recipient changes another address.
7The recipient does not know this information. Mean recipient does not receive notification of delivery information.
8The recipient doesn't want to receive
9The recipient has no free time to receive.
10The recipient is requested to delivery at another time.
11Locked recipient's phone/subscriber, unable to contact the recipient.
12The recipient does not answer the phone, unable to contact the recipient.
13The recipient is not at home/at work.
14No recipient at delivery address.
15The recipient is notified to go to the post office to pick up the goods.
16The receiver requested to inspect the goods, but the package is of a type that is not allowed to check the goods.
19The recipient has no money.
21The recipient do not work on Saturdays.
22Recipients do not work holidays.
24Bad weather: Heavy rain/Flood/Storm/Flood/Natural disaster.
26The sender requested no delivery and return.
30The contents of the parcel were damaged during delivery.
31Part of the parcel is missing during delivery.
33Lost parcel during delivery.
35Incorrect recipient's phone number or incorrect phone number.
40Another reason.
41The order requires the recipient to present ID card to receive, but the ID card is not valid(ID card/ID card lost/damaged).
43When the sender requests to hand-deliver to the recipient, but when contacting again, the recipient requests to deliver to someone else.
46Wrong order information.
52Customer changes delivery address
53The customer requests to cancel the order
### Example ``` /api/Order/v1/Tracking?ordercode=12345&apikey=1111-1111-1111-1111-111111111 ``` # Update status Integration for customer using APIs. Partner using 247's service, provide the corresponding API below for 247 to return order status. {% hint style="info" %} * Use RESTful APIs * Content-Type: application/json * Supports one of the following authentication mechanisms: * Apikey * Basic Authentication {% endhint %} ## Update Order Status `POST` `/IntergrationAPI` #### Headers | Name | Type | Description | | ------------ | ------ | ------------ | | Content-Type | string | Content type | #### Request Body | Name | Type | Description | | -------------------- | -------------- | ----------------------------------------------------------------------------------------- | | Time | datetime | Event occurrence time | | TransactionId | string | Transaction ID | | DeliveryDate | datetime(null) | Delivery date | | ReceiverName | string | Recipient's name | | Mailman | string | Mail man | | DeliveryNotes | string | Delivery notes | | DelayNotes | string | Reason for failed delivery | | RequestFeedbackCount | integer | Number of request for feedback | | Description | string | Description status | | StatusName | string | Status name | | Status | string | Status ID [*(detail)*](#list-of-statuses) | | OrderCode | string | Order Code | | ApiKey | string | API key for authentication between 2 parties | | DelayCode | string | Delay Code [*(detail)*](/english-1.0.6/tracking/order-tracking#list-of-reasons-for-delay) | | ExternalCode | string | External Code (Order code entered by customer) | | ReferenceCode | string | Customer reference code | {% tabs %} {% tab title="200 " %} ```json // Success { "IsError": false, "ErrorMessage": "" } // Error { "IsError": true, "ErrorMessage": "Mô tả lỗi" } ``` {% endtab %} {% endtabs %} ### Example ```json { "ApiKey": "EBD2E298-20AC-483F-80EC-B51CF8D79A2A", "OrderCode": "HD000003", "ExternalCode": "HD000003", "ReferenceCode":"HD000003" "Status": "25", "StatusName": "DANGDIPHAT", "Description": "Change order status: DANGVANCHUYEN ==> DANGDIPHAT", "RequestFeedbackCount": 0, "DelayCode": null, "DelayNotes": null, "DeliveryNotes": null, "Mailman": null, "DeliveryDate": null, "ReceiverName": "THANH", "TransactionId": "e07147ce-ebdb-47c6-ac96-959222494dbe", "Time": "2019-08-07T11:24:12.4946223+07:00" } ``` ### List of Statuses {% hint style="info" %} * 16: CHOXULY - PENDING\_FOR\_PROCEED * 18: HUY - CANCEL * 19: THATLAC - LOST * 21: DATIEPNHAN - ACCEPTED * 23: DALAYHANG - PICKED\_UP * 24: DANGVANCHUYEN - IN\_TRANSIT * 25: DANGDIPHAT - DELIVERING * 27: CHOCHUYENHOAN - PENDING\_FOR\_RETURN * 28: DACHUYENHOAN - RETURNED * 30: PHATTHANHCONG - DELIVERED * 32: TICHTHU - CONFISCATED {% endhint %} # Status update log Transaction log returns order status to customer `POST` `api/Customer/GetStatusLogs` #### Headers | Name | Type | Description | | ------------------------------------------ | ------ | ------------------ | | ClientID\* | Number | Get at SSO - Login | | Token\* | String | Get at SSO - Login | #### Request Body | Name | Type | Description | | ------------------------------------------ | -------- | --------------------------------------------- | | FromDate\* | DateTime | From date | | ToDate\* | DateTime | To date | | OrderCodes | String | Order code (multiple orders separated by ",") | {% tabs %} {% tab title="200: OK " %} {% tabs %} {% tab title="Success" %} ```json { "Data": { "Orders": [ { "OrderCode": "HD000003", "Histories": [ { "OrderCode": "HD000003", "ExternalCode": "HD000003", "ReferenceCode": "HD000003", "Status": "21", "StatusName": "DATIEPNHAN", "Description": null, "RequestFeedbackCount": 0, "DelayCode": null, "DelayNotes": null, "DeliveryNotes": null, "Mailman": null, "TransactionId": "8b2213ed-g2de-457b-a0e1-9a26c4d23a3f", "DeliveryDate": null, "ReceiverName": null, "Time": "2023-01-03T10:11:19.6240597+07:00", "IsCallError": false, "ErrorMessage": null, "IsPartnerResponseError": false, "PartnerResponseErrorMsg": null }, { "OrderCode": "MDH24700000001", "ExternalCode": null, "Status": "23", "StatusName": "DALAYHANG", "Description": null, "RequestFeedbackCount": 0, "DelayCode": null, "DelayNotes": null, "DeliveryNotes": null, "Mailman": null, "TransactionId": "eda18522-2ffc-48ce-beb8-abe32aa60a54", "DeliveryDate": null, "ReceiverName": null, "Time": "2023-01-04T10:11:19.6240597+07:00", "IsCallError": false, "ErrorMessage": null, "IsPartnerResponseError": false, "PartnerResponseErrorMsg": null } ] } ] }, "IsError": false, "ErrorMessage": "" } ``` {% endtab %} {% tab title="Error" %} ```json { "Data": null, "IsError": true, "ErrorMessage": "" } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### Response description | Trường | Mô tả | | ----------------------- | ----------------------------------------------------------------------------------------- | | Data | Data | | Orders | List of orders | | Histories | Transaction log of update status orders | | OrderCode | Order code | | ExternalCode | External code (Order code entered by customer) | | ReferenceCode | Customer reference code | | Status | Status ID [*(detail)*](/english-1.0.6/webhooks/update-status#list-of-statuses) | | StatusName | Status name | | Description | Description status | | RequestFeedbackCount | External code | | DelayCode | Delay code [*(detail)*](/english-1.0.6/tracking/order-tracking#list-of-reasons-for-delay) | | DelayNotes | Reason for failed delivery | | Mailman | Mail man | | TransactionId | Transaction ID | | DeliveryDate | Delivery date | | DeliveryNotes | Delivery notes | | ReceiverName | Recipient's name | | Time | Event occurrence time | | IsCallError | Is call API failed? | | ErrorMessage | Description for API Call Failed | | IsPartnerResponseError | Is the response error? | | PartnerResponseErrorMsg | Description for response error |