> For the complete documentation index, see [llms.txt](https://apidocs.nhanh.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.nhanh.vn/v3/order/list.md).
# Danh sách đơn hàng
* API này dùng để lấy [danh sách đơn hàng](https://nhanh.vn/order/manage/index).
* **Chú ý:**
* Hệ thống chỉ hỗ trợ lấy đơn hàng trong 31 ngày.
* Hệ thống đang hỗ trợ lọc dữ liệu theo 3 loại ngày:
* createdAtFrom, createdAtTo: Lọc theo ngày tạo đơn hàng.
* deliveryAtFrom, deliveryAtTo: Lọc theo ngày giao hàng.
* updatedAtFrom, updatedAtTo: Lọc theo ngày cập nhật đơn hàng.
* Nếu bạn không truyền param createdAtFrom mặc định sẽ lấy 31 ngày gần nhất. Nếu bạn muốn lấy dữ liệu các ngày cũ hơn, xin vui lòng truyền createdAtFrom và createdAtTo trong khoảng 31 ngày.
* Nếu bạn lọc theo id đơn hàng hoặc id khách hàng (hoặc số điện thoại khách hàng) thì có thể bỏ qua việc bắt buộc lọc createdAtFrom, createdAtTo.
* Nếu bạn hay thường xuyên cần gọi toàn bộ đơn hàng, bạn nên lưu giá trị thời gian lần cuối cùng quét toàn bộ, sau đó dùng 2 request params là updatedAtFrom và updatedAtTo để chỉ lấy về các đơn hàng có cập nhật mới, không cần gọi lại toàn bộ đơn cũ không có thay đổi gì. updatedAtFrom và updatedAtTo cũng bị giới hạn trong vòng 31 ngày, khi bạn lọc theo updatedAtFrom và updatedAtTo sẽ không bị bắt buộc có createdAtFrom và createdAtTo nữa.
## Request
* Xem [common request params](/v3/readme.md#request-params).
* Xem [Postman sample](https://www.postman.com/nhanh-vn/pos-open-nhanh-vn/request/w7aichy/order-list).
```curl
curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/order/list?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
"filters": {},
"paginator": {
"size": 50
},
"dataOptions": {}
}'
```
### Filters
| Key | Type | Description |
| --------------- | ----- | ------------------------------------------------------------- |
| createdAtFrom | int | Thời gian tạo từ ngày (định dạng timestamp) |
| createdAtTo | int | Thời gian tạo đến này (định dạng timestamp |
| deliveryAtFrom | int | Thời gian giao hàng từ ngày (định dạng timestamp) |
| deliveryAtTo | int | Thời gian giao hàng đến ngày (định dạng timestamp) |
| updatedAtFrom | int | Thời gian cập nhật từ ngày (định dạng timestamp) |
| updatedAtTo | int | Thời gian cập nhật đến ngày (định dạng timestamp) |
| ids | array | Mảng ID đơn hàng |
| statuses | array | Mảng [trạng thái đơn hàng](/v3/modelconstant.md#order-status) |
| saleChannels | array | Mảng ID [kênh bán](/v3/modelconstant.md#order-sale-channel) |
| depotIds | array | Mảng ID kho hàng |
| type | int | [Loại đơn hàng](/v3/modelconstant.md#order-type) |
| handoverId | int | ID biên bản bàn giao |
| carrier | array | Thông tin [hãng vận chuyển](#carrier) |
| shippingAddress | array | Thông tin [người nhận hàng](#shippingAddress) |
#### carrier
* Thông tin vận chuyển
| Key | Type | Description |
| ---- | ------ | -------------------------- |
| id | int | ID hãng vận chuyển |
| code | string | Mã vận đơn hãng vận chuyển |
#### shippingAddress
* Thông tin người nhận hàng
| Key | Type | Description |
| ---------- | ------ | ------------------ |
| id | int | ID người nhận hàng |
| mobile | string | Số điện thoại |
| cityId | int | ID thành phố |
| districtId | int | ID quận/huyện |
| wardId | int | ID phường/xã |
### Paginator
* Xem cấu trúc chung [tại đây](/v3/readme.md#paginator).
### DataOptions
* Dữ liệu cần lấy thêm:
| Key | Type | Description |
| ---------- | ---- | -------------------------------------------------- |
| marketing | int | 1: Lấy thông tin utmSource, utmMedium, utmCampaign |
| comboItems | int | 1: Lấy thông tin sản phẩm con trong combo |
## Failed response
* Xem các mã lỗi chung [tại đây](/v3/readme.md#failed-response).
## Successful response
* Xem thêm các const của Order [tại đây](/v3/modelconstant.md#order).
```json
{
"code": 1,
"paginator": {
"next": "Dùng để lấy dữ liệu trang tiếp theo"
},
"data": [
{
"info": {},
"channel": {},
"shippingAddress": {},
"products": [],
"carrier": {},
"payment": {},
"gifts": []
}
]
}
```
### info
* Thông tin chung của đơn hàng
| Key | Type | Description |
| ------------------ | ------ | ----------------------------------------------- |
| id | int | ID đơn hàng |
| depotId | int | ID kho hàng |
| pickupDepotId | int | ID kho lấy hàng |
| type | int | Loại đơn hàng |
| mode | int | Loại giá bán |
| exportType | int | Đánh dấu đơn hàng đã xuất kho thủ công hay chưa |
| originalOrderId | int | ID đơn hàng gốc |
| returnFromId | int | Hoàn từ ID đơn hàng |
| idReturn | int | Trả từ ID đơn hàng |
| createdById | int | ID người tạo đơn hàng |
| createdByName | string | Người tạo đơn hàng |
| saleId | int | ID nhân viên bán hàng |
| saleName | string | Nhân viên bán hàng |
| packedById | id | ID nhân viên đóng gói |
| packedByName | string | Nhân viên đóng gói |
| customerCareId | int | ID nhân viên chăm sóc |
| customerCareName | string | Nhân viên chăm sóc |
| createdAt | int | Thời gian tạo |
| updatedAt | int | Thời gian cập nhật lần cuối cùng |
| confirmedAt | int | Thời gian xác nhận |
| packedAt | int | Thời gian đóng gói |
| description | string | Ghi chú khách hàng |
| privateDescription | string | Ghi chú của chăm sóc khách hàng |
| orderIndex | int | Số thứ tự đơn trong ngày |
| status | int | Trạng thái đơn hàng |
| reason | int | ID lý do hủy đơn hàng |
| handoverIds | array | Mảng ID biên bản bàn giao |
| trackingUrl | string | Link lịch trình đơn hàng |
| tags | array | Mảng nhãn đơn hàng (xem bảng bên dưới) |
#### tags
| Key | Type | Description |
| --------- | ------ | ----------- |
| id | string | ID nhãn |
| name | string | Tên nhãn |
| textColor | string | Màu chữ |
| bgColor | string | Màu nền |
| status | int | Trạng thái |
### channel
* Thông tin kênh bán
| Key | Type | Description |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| appOrderId | string | ID website tích hợp hoặc ID đơn hàng trên sàn (Shopee, Tiktok, Lazada...) |
| saleChannel | int | Kênh bán |
| trafficSource | string | Nguồn đơn hàng |
| pageId | string | Tạo từ pageId |
| conversationId | string | Tạo từ cuộc trò chuyện |
| fbAdsId | int | Facebook ads ID |
| fbPsid | int | Facebook PSID |
| domain | string | Tên miền |
| shopId | int | ID gian hàng |
| shopName | string | Tên gian hàng |
| affiliate | object | Thông tin tiếp thị liên kết
- code: Mã affiliate
- value: Giá trị affiliate
- bonus: Hoa hồng affiliate
- bonusRate: Phần trăm Hoa hồng affiliate
|
| marketting | object | Thông tin marketting
- utmSource: Utm Source
- utmMedium: Utm Medium
- utmCampaign: Utm Campaign
|
### shippingAddress
* Thông tin người nhận hàng
| Key | Type | Description |
| -------------- | ------ | ------------------- |
| id | int | ID khách hàng |
| code | string | Mã khách hàng |
| name | string | Tên khách hàng |
| mobile | string | Số điện thoại |
| email | string | Email |
| address | string | Địa chỉ |
| birthday | string | Ngày tháng năm sinh |
| cityId | int | ID tỉnh / thành phố |
| districtId | int | ID quận / huyện |
| wardId | int | ID phường / xã |
| companyName | string | Tên công ty |
| companyAddress | string | Địa chỉ công ty |
| taxCode | string | Mã số thuế công ty |
### products
* Mảng thông tin sản phẩm
| Key | Type | Description |
| ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| productId | int | ID sản phẩm |
| orderProductId | int | ID sản phẩm trong đơn hàng |
| typeId | int | Loại sản phẩm |
| code | string | Mã sản phẩm |
| name | string | Tên sản phẩm |
| appProductId | string | ID sản phẩm website tích hợp |
| weight | int | Khối lượng sản phẩm |
| quantity | int | Số lượng |
| price | int | Giá bán chưa VAT |
| originalPrice | int | Giá gốc |
| priceVatMode | int |
- 1: Giá bán đã bao gồm
- 2: Giá bán chưa bao gồm VAT
|
| priceAfterVAT | int | Giá bán đã bao gồm VAT |
| discount | int | Chiết khấu với số lượng 1 |
| discountAmount | int | Tổng chiết khấu sản phẩm |
| avgCost | int | Giá vốn |
| vatPercent | int | Giá trị VAT |
| description | string | Ghi chú sản phẩm |
| imeiId | int | ID IMEI bán |
| imei | string | Số IMEI bán |
| imeiIds | array | Mảng ID IMEI đã bán |
| imeiCodes | array | Mảng số IMEI đã bán
- id: ID IMEI
- code: Số IMEI
|
| priceListName | string | Tên bảng giá áp dụng |
| transactionFee | int | Phí giao dịch |
| paymentStatus | int | Trạng thái thanh toán |
| partialReturnStatus | int | Trạng thái giao hàng một phần |
| usedPoints | int | Số điểm đã tiêu |
| usedPointAmount | int | Số tiền tương ứng điểm đã tiêu |
| batch | object | Thông tin lô hàng
- id: ID lô
- name: Tên lô
- manufactureDate: Ngày sản xuất
- expiredDate: Ngày hết hạn
|
| unit | object | Thông tin đơn vị tính
- id: ID đơn vị tính
- name: Tên đơn vị tính
- quantity: Số lượng theo đơn vị tính
- price: Giá theo đơn vị tính chưa VAT
- priceAfterVAT: Giá theo đơn vị tính đã bao gồm VAT
|
| partialDelivery | object | Thông tin giao hàng một phần
- deliveredQuantity: Số lượng khách nhận
- deliveredUnitQuantity: Số lượng khách nhận theo đơn vị tính
- returnQuantity: Số lượng hoàn về
- returnUnitQuantity: Số lượng hoàn về theo đơn vị tính
- lostQuantity: Số lượng mất
- lostUnitQuantity: Số lượng mất theo đơn vị tính
|
| combos | array | Mảng sản phẩm con trong combo (xem bảng bên dưới) |
| totalAmount | int | Tổng tiền sản phẩm sau VAT, sau chiết khấu |
#### combos
* Mảng sản phẩm con trong combo
| Key | Type | Description |
| -------- | ------ | ------------ |
| id | int | ID sản phẩm |
| code | string | Mã sản phẩm |
| name | string | Tên sản phẩm |
| quantity | int | Số lượng |
### carrier
* Thông tin vận chuyển
| Key | Type | Description |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | int | ID hãng vận chuyển |
| name | string | Hãng vận chuyển |
| service | object | Dịch vụ vận chuyển
- id: ID dịch vụ vận chuyể
- code: Mã dịch vụ vận chuyển
- name: Tên dịch vụ vận chuyển
- type: Loại dịch vụ vận chuyểnn
|
| carrierCode | string | Mã vận đơn |
| fullCarrierCode | string | Mã hãng vận chuyển đầy đủ |
| carrierSortCode | string | Mã chia vận đơn |
| packageCode | string | Mã gói hàng |
| checkGoods | string | Kiểm tra hàng hóa |
| sendCarrierType | int | Hình thức kết nối vận chuyển |
| sendCarrierAt | int | Thời gian gửi vận chuyển |
| deliveryAt | int | Thời gian giao hàng thành công |
| isPartDelivery | int |
- 1: Đơn giao hàng một phần
- 0: Không giao hàng một phần
|
| isDeclaredFee | int |
- 1: Khai giá
- 0: Không khai giá
|
| declaredValue | int | Giá trị khai giá |
| declaredFee | int | Phí khai giá |
| carrierPromotionCode | string | Mã khuyến mại vận chuyển |
| weight | int | Trọng lượng đơn hang khai báo |
| shipFee | int | Phí vận chuyển |
| codFee | int | Phí thu tiền hộ |
| overWeightShipFee | int | Phí vượt cân |
| returnFee | int | Phí chuyển hoàn |
| customerShipFee | int | Phí ship báo khách |
| ecomFee | int | Tổng các loại phí trên sàn |
| carrierPaymentStatus | int | Trạng thái đối soát đơn hàng với hãng vận chuyển |
### payment
* Thông tin thanh toán
| Key | Type | Description |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| usedPoints | object | Tiêu điểm
- points: Số điểm đã tiêu
- amount: Số tiền tương ứng đã tiêu
|
| vat | object | VAT
- percent: Giá trị VAT. Ví dụ: 5%, 8%
- amount: Số tiền VAT
- taxCode: Mã số thuế
- taxDate: Ngày xuất hóa đơn
|
| discount | object | Chiết khấu đơn hàng
- percent: Giá trị chiết khấu. Ví dụ: 5%, 8%
- amount: Số tiền chiết khấu
|
| couponCode | string | Mã giảm giá |
| debtDueDate | string | Ngày hẹn thanh toán |
| deposit | object | Tiền đặt cọc
- amount: Số tiền đặt cọc
- accountId: ID tài khoản kế toán nhận tiền
- name: Tên tài khoản kế toán
|
| transfer | object | Tiền chuyển khoản
- amount: Số tiền chuyển khoản
- accountId: ID tài khoản kế toán nhận tiền
- name: Tên tài khoản kế toán
|
| credit | object | Tiền quẹt thẻ
- amount: Số tiền quẹt thẻ
- accountId: ID tài khoản kế toán nhận tiền
- code: Mã quẹt thẻ
- name: Tên tài khoản kế toán
|
| codAmount | int | Tổng thu khách hàng |
| businessPayment | int | Tổng tiền trả cho doanh nghiệp sau khi đã trừ các loại phí phải trả cho dịch vụ vận chuyển |
| businessPaymentStatus | int | Trạng thái thanh toán tiền với doanh nghiệp |
### gifts
* Mảng thông tin quà tặng
| Key | Type | Description |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| productId | int | ID sản phẩm |
| orderProductId | int | ID sản phẩm trong đơn hàng
- Giá trị lớn hơn 0 thì là quà tặng theo sản phẩm
- Giá trị bằng 0 thì là quà tặng theo đơn hàng
|
| name | string | Tên sản phẩm |
| quantity | int | Số lượng |
| price | string | Giá trị quà tặng |
## Lỗi thường gặp
* Bạn gọi API lấy danh sách đơn hàng, nhưng lại thấy nhiều đơn hàng hơn trên giao diện cho user, hoặc lấy từ API về, thấy 1 ID đơn hàng, nhưng tìm ở danh sách đơn hàng lại không thấy đơn này. Nguyên nhân:
* Trên giao diện, do luồng xử lý đơn ngoại sàn và đơn trên các sàn khác nhau, nên giao diện tách ra mấy trang danh sách đơn hàng riêng:
* : Đơn ngoại sàn
* : Đơn Shopee
* : Đơn Tiktok
* : Đơn Lazada
* : Đơn Tiki
* `/v3.0/order/list` trả về toàn bộ danh sách đơn hàng, bạn có thể filter theo kênh bán `saleChannel`.