Tham chiếu: Đơn hàng
Danh sách, chi tiết, tạo, sửa, đổi trạng thái và ghi chú của đơn hàng. Mọi đường dẫn dưới https://danix.. Đặc tả máy đọc: openapi.json.
Liệt kê đơn hàng
GET /orders
Phân trang theo con trỏ, sắp theo lần sửa tăng dần. Đồng bộ tăng dần bằng updatedSince (lật trang trong một lượt bằng nextCursor); dòng danh sách không có lines, payments và shippingAddress — lấy chi tiết bằng GET /orders/{id}.
Quyền cần có: khoá có quyền pos..
Tham số query
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
limit |
integer | không | Số dòng mỗi trang, từ 1 đến 100. Mặc định 50. |
cursor |
string | không | Con trỏ lấy từ nextCursor của trang trước, để lật trang trong CÙNG một lượt đọc (giữ nguyên các tham số khác). Không tự dựng, không lưu để nối lượt đồng bộ sau. |
updatedSince |
string (date-time) | không | Chỉ lấy bản ghi có updatedAt từ thời điểm này (ISO 8601 UTC), tính cả mốc. Đây là cách đồng bộ tăng dần: có tham số này thì danh sách chỉ trả bản ghi đã qua khoảng trễ an toàn (trần thời gian tua lại kho của shop cộng 15 giây, mặc định 2 phút 15 giây). |
includeDeleted |
"true" | "false" | không | true để lấy cả bản ghi đã xoá (có deletedAt). Mặc định false. |
status |
"new" | "waiting_stock" | "confirmed" | "packing" | "ready_to_ship" | "shipped" | "delivered" | "paid" | "returning" | "partially_returned" | "returned" | "cancelled" | "deleted" | không | Chỉ lấy đơn ở trạng thái này. |
customerId |
string (uuid) | không | Chỉ lấy đơn của khách này. |
code |
string | không | Tìm đúng mã đơn. |
Ví dụ yêu cầu
curl -X GET "https://danix.vn/api/open/v1/orders" \
-H "Authorization: Bearer dnx_live_…"
Phản hồi mẫu (200)
{
"data": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000101",
"code": "DH1024",
"status": "confirmed",
"warehouseId": "018f3b8e-1c2d-7a4b-9c3d-000000000001",
"warehouseName": "Kho chính",
"customerId": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
"salesChannelId": "018f3b8e-1c2d-7a4b-9c3d-000000000301",
"salesChannelName": "Facebook",
"receivedAtShop": false,
"billFullName": "Nguyễn Văn An",
"billPhone": "0901234567",
"billEmail": null,
"totalPrice": "450000",
"discount": "0",
"shippingFee": "30000",
"freeShipping": false,
"surcharge": "0",
"tax": "0",
"totalAmount": "480000",
"returnedAmount": "0",
"exchangeReturn": false,
"paidAmount": "0",
"occurredAt": "2026-10-02T03:15:00.000Z",
"note": null,
"tags": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000401",
"name": "Khách quen"
}
],
"createdAt": "2026-10-02T03:15:00.000Z",
"updatedAt": "2026-10-02T03:15:00.000Z",
"deletedAt": null
}
],
"nextCursor": null
}
Trường của phản hồi
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
data |
array<object> | có | Các bản ghi của trang này. |
data[]. |
string (uuid) | có | Mã định danh của đơn. |
data[]. |
string | có | Mã đơn, duy nhất trong shop. |
data[]. |
"new" | "waiting_stock" | "confirmed" | "packing" | "ready_to_ship" | "shipped" | "delivered" | "paid" | "returning" | "partially_returned" | "returned" | "cancelled" | "deleted" | có | Trạng thái đơn. |
data[]. |
string (uuid) | có | Kho xuất hàng. |
data[]. |
string hoặc null | có | Tên kho xuất hàng. |
data[]. |
string (uuid) hoặc null | có | Khách hàng gắn với đơn. |
data[]. |
string (uuid) hoặc null | có | Kênh bán. |
data[]. |
string hoặc null | có | Tên kênh bán. |
data[]. |
boolean | có | Khách nhận hàng tại shop. |
data[]. |
string hoặc null | có | Tên người mua ghi trên đơn. |
data[]. |
string hoặc null | có | Số điện thoại người mua. |
data[]. |
string hoặc null | có | Email người mua. |
data[]. |
object hoặc null | không | Địa chỉ giao hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
data[]. |
string hoặc null | có | Tên người nhận. |
data[]. |
string hoặc null | có | Số điện thoại người nhận. |
data[]. |
string hoặc null | có | Số nhà, đường. |
data[]. |
"old" | "new" hoặc null | có | Hệ địa giới của các mã bên dưới: old (tỉnh, huyện, xã) hoặc new (tỉnh, xã). null khi địa chỉ chỉ có chữ. |
data[]. |
string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; null khi không có. |
data[]. |
string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ new luôn null. |
data[]. |
string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; null khi không có. |
data[]. |
string hoặc null | có | Tỉnh hoặc thành phố. |
data[]. |
string hoặc null | có | Quận hoặc huyện. |
data[]. |
string hoặc null | có | Phường hoặc xã. |
data[]. |
string | có | Tiền hàng. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Giảm giá cả đơn. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Phí vận chuyển khách trả. Chuỗi thập phân, ví dụ "150000". |
data[]. |
boolean | có | Shop chịu phí giao hàng. |
data[]. |
string | có | Phụ thu. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Thuế. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Tổng tiền đơn. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Tiền hàng khách đã hoàn. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Đã thanh toán. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | không | Tiền cấn trừ vào đơn này từ phiếu đổi trả (khách trả hàng của một đơn khác): khách đã trả cho đơn này bằng khoản ấy, nên số còn phải thu đã trừ nó. Chỉ có ở chi tiết đơn, không có trong danh sách. Chuỗi thập phân, ví dụ "150000". |
data[]. |
boolean | không | Đơn trả để ĐỔI hàng: mọi lượt khách trả hàng của đơn đều là đổi (đổi size, đổi màu…), nên đơn không tính là hoàn — không vào tỉ lệ hoàn của số điện thoại, không gửi tin hoàn hay sự kiện hoàn sang Facebook. Chỉ có ở chi tiết đơn, không có trong danh sách. |
data[]. |
string (date-time) | có | Thời điểm phát sinh đơn. ISO 8601, múi giờ UTC. |
data[]. |
string hoặc null | có | Ghi chú nội bộ. |
data[]. |
array<object> | có | Các thẻ của đơn. |
data[]. |
string (uuid) | có | Mã thẻ. |
data[]. |
string | có | Tên thẻ. |
data[]. |
array<object> | không | Các dòng hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
data[]. |
string (uuid) | có | Mã dòng hàng. |
data[]. |
string (uuid) | có | Mã mẫu mã. |
data[]. |
string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
data[]. |
string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu pos.. |
data[]. |
string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu pos.. |
data[]. |
string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu pos.. |
data[]. |
string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
data[]. |
string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string | có | Số lượng khách đã hoàn. Chuỗi thập phân, tối đa ba chữ số lẻ. |
data[]. |
array<object> | không | Các khoản thu. Chỉ có ở chi tiết đơn, không có trong danh sách. |
data[]. |
string (uuid) | có | Mã phương thức thanh toán. |
data[]. |
string | có | Tên phương thức thanh toán. |
data[]. |
string | có | Số tiền thu theo phương thức này. Chuỗi thập phân, ví dụ "150000". |
data[]. |
string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
data[]. |
string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
data[]. |
string (date-time) hoặc null | có | Thời điểm xoá mềm; null nếu chưa xoá. ISO 8601 UTC hoặc null. |
nextCursor |
string hoặc null | có | Con trỏ của trang kế; null khi đã hết dữ liệu. |
Lỗi
| Trạng thái | Mã code |
Ý nghĩa |
|---|---|---|
| 401 | invalid-api-key |
Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | insufficient-permission |
Khoá API không có quyền thực hiện thao tác này |
| 403 | shop-suspended |
Shop đang bị đình chỉ |
| 403 | automation-not-active |
Shop chưa bật tính năng Tự động hoá |
| 429 | rate-limited |
Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | internal-error |
Lỗi hệ thống |
| 400 | validation-failed |
Dữ liệu gửi lên không hợp lệ |
| 400 | invalid-cursor |
Con trỏ phân trang không hợp lệ |
Định dạng lỗi và bảng mọi mã code: Lỗi.
Tạo đơn hàng
POST /orders
Tạo đơn mới ở trạng thái new. Gửi kèm header Idempotency-Key để thử lại an toàn: cùng khoá trong 24 giờ trả đúng đơn đã tạo, không tạo đơn thứ hai. unitPrice khác giá niêm yết của mẫu mã, hay giảm giá (của dòng hoặc cả đơn) khác 0, cần thêm quyền pos.; gửi payments cần thêm pos. — thiếu thì insufficient-permission.
Quyền cần có: khoá có quyền pos. và quyền pos..
Quyền thêm theo trường: pos., pos. — chỉ cần khi thân dùng trường tương ứng (xem mô tả ở trên).
Header
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
Idempotency-Key |
string | không | Khoá chống trùng do client đặt (khuyến nghị UUID). Gửi lại cùng khoá trong 24 giờ trả đúng kết quả lần đầu và header Idempotent-Replayed: true. |
Thân yêu cầu (JSON)
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
warehouseId |
string (uuid) | có | Kho xuất hàng. |
customerId |
string (uuid) hoặc null | không | Khách hàng có sẵn. Bỏ trống nếu bán lẻ. |
salesChannelId |
string (uuid) hoặc null | không | Kênh bán. |
receivedAtShop |
boolean | không | Khách nhận hàng tại shop. |
billFullName |
string hoặc null | không | Tên người mua. |
billPhone |
string hoặc null | không | Số điện thoại người mua. |
billEmail |
string hoặc null | không | Email người mua. |
shippingAddress |
object hoặc null | không | Địa chỉ giao hàng. |
shippingAddress. |
string hoặc null | không | Tên người nhận. |
shippingAddress. |
string hoặc null | không | Số điện thoại người nhận. |
shippingAddress. |
string hoặc null | không | Số nhà, đường. |
shippingAddress. |
string hoặc null | không | Tỉnh hoặc thành phố. |
shippingAddress. |
string hoặc null | không | Quận hoặc huyện. |
shippingAddress. |
string hoặc null | không | Phường hoặc xã. |
shippingAddress. |
"old" | "new" hoặc null | không | Hệ địa giới của các mã bên dưới: old (tỉnh, huyện, xã) hoặc new (tỉnh, xã). Bỏ trống thì suy từ mã. |
shippingAddress. |
string (uuid) hoặc null | không | Mã (UUID) tỉnh hoặc thành phố trong danh mục hành chính của DANIX. |
shippingAddress. |
string (uuid) hoặc null | không | Mã (UUID) quận hoặc huyện. Hệ new không có cấp này. |
shippingAddress. |
string (uuid) hoặc null | không | Mã (UUID) phường hoặc xã. |
lines |
array<object> | có | Các dòng hàng, 1 đến 200. |
lines[]. |
string (uuid) | có | Mã mẫu mã cần bán. |
lines[]. |
string | có | Số lượng, lớn hơn 0. Chuỗi thập phân, tối đa ba chữ số lẻ. |
lines[]. |
string | có | Đơn giá. Khác giá niêm yết của mẫu mã thì khoá cần thêm quyền pos.. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | không | Giảm giá của dòng. Mặc định "0". Khác 0 thì khoá cần thêm quyền pos.. |
discount |
string | không | Giảm giá cả đơn. Khác 0 thì khoá cần thêm quyền pos.. |
shippingFee |
string | không | Phí vận chuyển khách trả. |
freeShipping |
boolean | không | Shop chịu phí giao hàng. |
surcharge |
string | không | Phụ thu. |
tax |
string | không | Thuế. |
payments |
array<object> | không | Các khoản thu. Gửi khoản thu thì khoá cần thêm quyền pos.. |
payments[]. |
string (uuid) | có | Mã phương thức thanh toán. |
payments[]. |
string | có | Số tiền thu. Chuỗi thập phân, ví dụ "150000". |
occurredAt |
string (date-time) | không | Thời điểm phát sinh đơn. |
note |
string hoặc null | không | Ghi chú nội bộ. |
tagIds |
array<string (uuid)> | không | Các thẻ gắn vào đơn. |
Ví dụ yêu cầu
curl -X POST "https://danix.vn/api/open/v1/orders" \
-H "Authorization: Bearer dnx_live_…" \
-H "Idempotency-Key: cc8882df-37bd-41a7-9619-5f34df0a4f10" \
-H "Content-Type: application/json" \
-d '{
"warehouseId": "018f3b8e-1c2d-7a4b-9c3d-000000000001",
"billFullName": "Nguyễn Văn An",
"billPhone": "0901234567",
"lines": [
{
"variantId": "018f3b8e-1c2d-7a4b-9c3d-000000000601",
"quantity": "2",
"unitPrice": "225000"
}
]
}'
Phản hồi mẫu (201)
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000101",
"code": "DH1024",
"status": "confirmed",
"warehouseId": "018f3b8e-1c2d-7a4b-9c3d-000000000001",
"warehouseName": "Kho chính",
"customerId": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
"salesChannelId": "018f3b8e-1c2d-7a4b-9c3d-000000000301",
"salesChannelName": "Facebook",
"receivedAtShop": false,
"billFullName": "Nguyễn Văn An",
"billPhone": "0901234567",
"billEmail": null,
"shippingAddress": {
"recipientName": "Nguyễn Văn An",
"recipientPhone": "0901234567",
"addressLine": "12 Lê Lợi",
"geoSystem": "old",
"provinceUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001501",
"districtUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001502",
"wardUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001503",
"provinceName": "Đà Nẵng",
"districtName": "Hải Châu",
"wardName": "Thạch Thang"
},
"totalPrice": "450000",
"discount": "0",
"shippingFee": "30000",
"freeShipping": false,
"surcharge": "0",
"tax": "0",
"totalAmount": "480000",
"returnedAmount": "0",
"exchangeReturn": false,
"paidAmount": "0",
"occurredAt": "2026-10-02T03:15:00.000Z",
"note": null,
"tags": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000401",
"name": "Khách quen"
}
],
"lines": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000501",
"variantId": "018f3b8e-1c2d-7a4b-9c3d-000000000601",
"productId": "018f3b8e-1c2d-7a4b-9c3d-000000000701",
"variantCode": "AO-THUN-M",
"variantName": "Áo thun - M",
"productName": "Áo thun cổ tròn",
"quantity": "2",
"unitPrice": "225000",
"discount": "0",
"lineTotal": "450000",
"returnedQuantity": "0"
}
],
"payments": [],
"createdAt": "2026-10-02T03:15:00.000Z",
"updatedAt": "2026-10-02T03:15:00.000Z",
"deletedAt": null
}
Trường của phản hồi
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh của đơn. |
code |
string | có | Mã đơn, duy nhất trong shop. |
status |
"new" | "waiting_stock" | "confirmed" | "packing" | "ready_to_ship" | "shipped" | "delivered" | "paid" | "returning" | "partially_returned" | "returned" | "cancelled" | "deleted" | có | Trạng thái đơn. |
warehouseId |
string (uuid) | có | Kho xuất hàng. |
warehouseName |
string hoặc null | có | Tên kho xuất hàng. |
customerId |
string (uuid) hoặc null | có | Khách hàng gắn với đơn. |
salesChannelId |
string (uuid) hoặc null | có | Kênh bán. |
salesChannelName |
string hoặc null | có | Tên kênh bán. |
receivedAtShop |
boolean | có | Khách nhận hàng tại shop. |
billFullName |
string hoặc null | có | Tên người mua ghi trên đơn. |
billPhone |
string hoặc null | có | Số điện thoại người mua. |
billEmail |
string hoặc null | có | Email người mua. |
shippingAddress |
object hoặc null | không | Địa chỉ giao hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
shippingAddress. |
string hoặc null | có | Tên người nhận. |
shippingAddress. |
string hoặc null | có | Số điện thoại người nhận. |
shippingAddress. |
string hoặc null | có | Số nhà, đường. |
shippingAddress. |
"old" | "new" hoặc null | có | Hệ địa giới của các mã bên dưới: old (tỉnh, huyện, xã) hoặc new (tỉnh, xã). null khi địa chỉ chỉ có chữ. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; null khi không có. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ new luôn null. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; null khi không có. |
shippingAddress. |
string hoặc null | có | Tỉnh hoặc thành phố. |
shippingAddress. |
string hoặc null | có | Quận hoặc huyện. |
shippingAddress. |
string hoặc null | có | Phường hoặc xã. |
totalPrice |
string | có | Tiền hàng. Chuỗi thập phân, ví dụ "150000". |
discount |
string | có | Giảm giá cả đơn. Chuỗi thập phân, ví dụ "150000". |
shippingFee |
string | có | Phí vận chuyển khách trả. Chuỗi thập phân, ví dụ "150000". |
freeShipping |
boolean | có | Shop chịu phí giao hàng. |
surcharge |
string | có | Phụ thu. Chuỗi thập phân, ví dụ "150000". |
tax |
string | có | Thuế. Chuỗi thập phân, ví dụ "150000". |
totalAmount |
string | có | Tổng tiền đơn. Chuỗi thập phân, ví dụ "150000". |
returnedAmount |
string | có | Tiền hàng khách đã hoàn. Chuỗi thập phân, ví dụ "150000". |
paidAmount |
string | có | Đã thanh toán. Chuỗi thập phân, ví dụ "150000". |
creditApplied |
string | không | Tiền cấn trừ vào đơn này từ phiếu đổi trả (khách trả hàng của một đơn khác): khách đã trả cho đơn này bằng khoản ấy, nên số còn phải thu đã trừ nó. Chỉ có ở chi tiết đơn, không có trong danh sách. Chuỗi thập phân, ví dụ "150000". |
exchangeReturn |
boolean | không | Đơn trả để ĐỔI hàng: mọi lượt khách trả hàng của đơn đều là đổi (đổi size, đổi màu…), nên đơn không tính là hoàn — không vào tỉ lệ hoàn của số điện thoại, không gửi tin hoàn hay sự kiện hoàn sang Facebook. Chỉ có ở chi tiết đơn, không có trong danh sách. |
occurredAt |
string (date-time) | có | Thời điểm phát sinh đơn. ISO 8601, múi giờ UTC. |
note |
string hoặc null | có | Ghi chú nội bộ. |
tags |
array<object> | có | Các thẻ của đơn. |
tags[]. |
string (uuid) | có | Mã thẻ. |
tags[]. |
string | có | Tên thẻ. |
lines |
array<object> | không | Các dòng hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
lines[]. |
string (uuid) | có | Mã dòng hàng. |
lines[]. |
string (uuid) | có | Mã mẫu mã. |
lines[]. |
string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
lines[]. |
string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu pos.. |
lines[]. |
string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
lines[]. |
string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Số lượng khách đã hoàn. Chuỗi thập phân, tối đa ba chữ số lẻ. |
payments |
array<object> | không | Các khoản thu. Chỉ có ở chi tiết đơn, không có trong danh sách. |
payments[]. |
string (uuid) | có | Mã phương thức thanh toán. |
payments[]. |
string | có | Tên phương thức thanh toán. |
payments[]. |
string | có | Số tiền thu theo phương thức này. Chuỗi thập phân, ví dụ "150000". |
createdAt |
string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
updatedAt |
string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
deletedAt |
string (date-time) hoặc null | có | Thời điểm xoá mềm; null nếu chưa xoá. ISO 8601 UTC hoặc null. |
Lỗi
| Trạng thái | Mã code |
Ý nghĩa |
|---|---|---|
| 401 | invalid-api-key |
Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | insufficient-permission |
Khoá API không có quyền thực hiện thao tác này |
| 403 | shop-suspended |
Shop đang bị đình chỉ |
| 403 | automation-not-active |
Shop chưa bật tính năng Tự động hoá |
| 429 | rate-limited |
Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | internal-error |
Lỗi hệ thống |
| 402 | subscription-expired |
Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | validation-failed |
Dữ liệu gửi lên không hợp lệ |
| 413 | payload-too-large |
Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | unsupported-media-type |
Thân yêu cầu phải là JSON (Content-Type: application/json) |
| 409 | conflict |
Thao tác xung đột với trạng thái hiện tại |
| 409 | idempotency-key-in-progress |
Yêu cầu với cùng Idempotency-Key đang được xử lý |
| 422 | idempotency-key-reused |
Idempotency-Key đã dùng cho một yêu cầu có nội dung khác |
| 422 | variant-removed |
Mẫu mã đã bị gỡ khỏi sản phẩm |
| 422 | customer-blocked |
Khách hàng đang bị chặn |
| 422 | insufficient-stock |
Không đủ tồn kho cho thao tác này |
Định dạng lỗi và bảng mọi mã code: Lỗi.
Chi tiết một đơn hàng
GET /orders/{id}
Trả đơn kèm dòng hàng, khoản thu và địa chỉ giao hàng.
Quyền cần có: khoá có quyền pos..
Tham số đường dẫn
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh (UUID) của tài nguyên. |
Ví dụ yêu cầu
curl -X GET "https://danix.vn/api/open/v1/orders/{id}" \
-H "Authorization: Bearer dnx_live_…"
Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.
Phản hồi mẫu (200)
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000101",
"code": "DH1024",
"status": "confirmed",
"warehouseId": "018f3b8e-1c2d-7a4b-9c3d-000000000001",
"warehouseName": "Kho chính",
"customerId": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
"salesChannelId": "018f3b8e-1c2d-7a4b-9c3d-000000000301",
"salesChannelName": "Facebook",
"receivedAtShop": false,
"billFullName": "Nguyễn Văn An",
"billPhone": "0901234567",
"billEmail": null,
"shippingAddress": {
"recipientName": "Nguyễn Văn An",
"recipientPhone": "0901234567",
"addressLine": "12 Lê Lợi",
"geoSystem": "old",
"provinceUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001501",
"districtUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001502",
"wardUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001503",
"provinceName": "Đà Nẵng",
"districtName": "Hải Châu",
"wardName": "Thạch Thang"
},
"totalPrice": "450000",
"discount": "0",
"shippingFee": "30000",
"freeShipping": false,
"surcharge": "0",
"tax": "0",
"totalAmount": "480000",
"returnedAmount": "0",
"exchangeReturn": false,
"paidAmount": "0",
"occurredAt": "2026-10-02T03:15:00.000Z",
"note": null,
"tags": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000401",
"name": "Khách quen"
}
],
"lines": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000501",
"variantId": "018f3b8e-1c2d-7a4b-9c3d-000000000601",
"productId": "018f3b8e-1c2d-7a4b-9c3d-000000000701",
"variantCode": "AO-THUN-M",
"variantName": "Áo thun - M",
"productName": "Áo thun cổ tròn",
"quantity": "2",
"unitPrice": "225000",
"discount": "0",
"lineTotal": "450000",
"returnedQuantity": "0"
}
],
"payments": [],
"createdAt": "2026-10-02T03:15:00.000Z",
"updatedAt": "2026-10-02T03:15:00.000Z",
"deletedAt": null
}
Trường của phản hồi
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh của đơn. |
code |
string | có | Mã đơn, duy nhất trong shop. |
status |
"new" | "waiting_stock" | "confirmed" | "packing" | "ready_to_ship" | "shipped" | "delivered" | "paid" | "returning" | "partially_returned" | "returned" | "cancelled" | "deleted" | có | Trạng thái đơn. |
warehouseId |
string (uuid) | có | Kho xuất hàng. |
warehouseName |
string hoặc null | có | Tên kho xuất hàng. |
customerId |
string (uuid) hoặc null | có | Khách hàng gắn với đơn. |
salesChannelId |
string (uuid) hoặc null | có | Kênh bán. |
salesChannelName |
string hoặc null | có | Tên kênh bán. |
receivedAtShop |
boolean | có | Khách nhận hàng tại shop. |
billFullName |
string hoặc null | có | Tên người mua ghi trên đơn. |
billPhone |
string hoặc null | có | Số điện thoại người mua. |
billEmail |
string hoặc null | có | Email người mua. |
shippingAddress |
object hoặc null | không | Địa chỉ giao hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
shippingAddress. |
string hoặc null | có | Tên người nhận. |
shippingAddress. |
string hoặc null | có | Số điện thoại người nhận. |
shippingAddress. |
string hoặc null | có | Số nhà, đường. |
shippingAddress. |
"old" | "new" hoặc null | có | Hệ địa giới của các mã bên dưới: old (tỉnh, huyện, xã) hoặc new (tỉnh, xã). null khi địa chỉ chỉ có chữ. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; null khi không có. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ new luôn null. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; null khi không có. |
shippingAddress. |
string hoặc null | có | Tỉnh hoặc thành phố. |
shippingAddress. |
string hoặc null | có | Quận hoặc huyện. |
shippingAddress. |
string hoặc null | có | Phường hoặc xã. |
totalPrice |
string | có | Tiền hàng. Chuỗi thập phân, ví dụ "150000". |
discount |
string | có | Giảm giá cả đơn. Chuỗi thập phân, ví dụ "150000". |
shippingFee |
string | có | Phí vận chuyển khách trả. Chuỗi thập phân, ví dụ "150000". |
freeShipping |
boolean | có | Shop chịu phí giao hàng. |
surcharge |
string | có | Phụ thu. Chuỗi thập phân, ví dụ "150000". |
tax |
string | có | Thuế. Chuỗi thập phân, ví dụ "150000". |
totalAmount |
string | có | Tổng tiền đơn. Chuỗi thập phân, ví dụ "150000". |
returnedAmount |
string | có | Tiền hàng khách đã hoàn. Chuỗi thập phân, ví dụ "150000". |
paidAmount |
string | có | Đã thanh toán. Chuỗi thập phân, ví dụ "150000". |
creditApplied |
string | không | Tiền cấn trừ vào đơn này từ phiếu đổi trả (khách trả hàng của một đơn khác): khách đã trả cho đơn này bằng khoản ấy, nên số còn phải thu đã trừ nó. Chỉ có ở chi tiết đơn, không có trong danh sách. Chuỗi thập phân, ví dụ "150000". |
exchangeReturn |
boolean | không | Đơn trả để ĐỔI hàng: mọi lượt khách trả hàng của đơn đều là đổi (đổi size, đổi màu…), nên đơn không tính là hoàn — không vào tỉ lệ hoàn của số điện thoại, không gửi tin hoàn hay sự kiện hoàn sang Facebook. Chỉ có ở chi tiết đơn, không có trong danh sách. |
occurredAt |
string (date-time) | có | Thời điểm phát sinh đơn. ISO 8601, múi giờ UTC. |
note |
string hoặc null | có | Ghi chú nội bộ. |
tags |
array<object> | có | Các thẻ của đơn. |
tags[]. |
string (uuid) | có | Mã thẻ. |
tags[]. |
string | có | Tên thẻ. |
lines |
array<object> | không | Các dòng hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
lines[]. |
string (uuid) | có | Mã dòng hàng. |
lines[]. |
string (uuid) | có | Mã mẫu mã. |
lines[]. |
string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
lines[]. |
string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu pos.. |
lines[]. |
string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
lines[]. |
string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Số lượng khách đã hoàn. Chuỗi thập phân, tối đa ba chữ số lẻ. |
payments |
array<object> | không | Các khoản thu. Chỉ có ở chi tiết đơn, không có trong danh sách. |
payments[]. |
string (uuid) | có | Mã phương thức thanh toán. |
payments[]. |
string | có | Tên phương thức thanh toán. |
payments[]. |
string | có | Số tiền thu theo phương thức này. Chuỗi thập phân, ví dụ "150000". |
createdAt |
string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
updatedAt |
string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
deletedAt |
string (date-time) hoặc null | có | Thời điểm xoá mềm; null nếu chưa xoá. ISO 8601 UTC hoặc null. |
Lỗi
| Trạng thái | Mã code |
Ý nghĩa |
|---|---|---|
| 401 | invalid-api-key |
Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | insufficient-permission |
Khoá API không có quyền thực hiện thao tác này |
| 403 | shop-suspended |
Shop đang bị đình chỉ |
| 403 | automation-not-active |
Shop chưa bật tính năng Tự động hoá |
| 429 | rate-limited |
Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | internal-error |
Lỗi hệ thống |
| 404 | not-found |
Không tìm thấy tài nguyên |
| 400 | validation-failed |
Dữ liệu gửi lên không hợp lệ |
Định dạng lỗi và bảng mọi mã code: Lỗi.
Sửa đơn hàng
PATCH /orders/{id}
Chỉ gửi trường cần đổi. Dòng hàng và kho không sửa được qua đường này. Đổi discount cần thêm quyền pos..
Quyền cần có: khoá có quyền pos. và quyền pos..
Quyền thêm theo trường: pos. — chỉ cần khi thân dùng trường tương ứng (xem mô tả ở trên).
Tham số đường dẫn
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh (UUID) của tài nguyên. |
Thân yêu cầu (JSON)
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
customerId |
string (uuid) hoặc null | không | Đổi khách hàng gắn với đơn. |
salesChannelId |
string (uuid) hoặc null | không | Đổi kênh bán. |
billFullName |
string hoặc null | không | Tên người mua. |
billPhone |
string hoặc null | không | Số điện thoại người mua. |
billEmail |
string hoặc null | không | Email người mua. |
shippingAddress |
object hoặc null | không | Địa chỉ giao hàng. |
shippingAddress. |
string hoặc null | không | Tên người nhận. |
shippingAddress. |
string hoặc null | không | Số điện thoại người nhận. |
shippingAddress. |
string hoặc null | không | Số nhà, đường. |
shippingAddress. |
string hoặc null | không | Tỉnh hoặc thành phố. |
shippingAddress. |
string hoặc null | không | Quận hoặc huyện. |
shippingAddress. |
string hoặc null | không | Phường hoặc xã. |
shippingAddress. |
"old" | "new" hoặc null | không | Hệ địa giới của các mã bên dưới: old (tỉnh, huyện, xã) hoặc new (tỉnh, xã). Bỏ trống thì suy từ mã. |
shippingAddress. |
string (uuid) hoặc null | không | Mã (UUID) tỉnh hoặc thành phố trong danh mục hành chính của DANIX. |
shippingAddress. |
string (uuid) hoặc null | không | Mã (UUID) quận hoặc huyện. Hệ new không có cấp này. |
shippingAddress. |
string (uuid) hoặc null | không | Mã (UUID) phường hoặc xã. |
discount |
string | không | Giảm giá cả đơn. Đổi giảm giá thì khoá cần thêm quyền pos.. |
shippingFee |
string | không | Phí vận chuyển khách trả. |
surcharge |
string | không | Phụ thu. |
tax |
string | không | Thuế. |
note |
string hoặc null | không | Ghi chú nội bộ. |
tagIds |
array<string (uuid)> | không | Thay toàn bộ thẻ của đơn. |
Ví dụ yêu cầu
curl -X PATCH "https://danix.vn/api/open/v1/orders/{id}" \
-H "Authorization: Bearer dnx_live_…" \
-H "Content-Type: application/json" \
-d '{
"note": "Khách dặn gọi trước khi giao"
}'
Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.
Phản hồi mẫu (200)
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000101",
"code": "DH1024",
"status": "confirmed",
"warehouseId": "018f3b8e-1c2d-7a4b-9c3d-000000000001",
"warehouseName": "Kho chính",
"customerId": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
"salesChannelId": "018f3b8e-1c2d-7a4b-9c3d-000000000301",
"salesChannelName": "Facebook",
"receivedAtShop": false,
"billFullName": "Nguyễn Văn An",
"billPhone": "0901234567",
"billEmail": null,
"shippingAddress": {
"recipientName": "Nguyễn Văn An",
"recipientPhone": "0901234567",
"addressLine": "12 Lê Lợi",
"geoSystem": "old",
"provinceUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001501",
"districtUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001502",
"wardUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001503",
"provinceName": "Đà Nẵng",
"districtName": "Hải Châu",
"wardName": "Thạch Thang"
},
"totalPrice": "450000",
"discount": "0",
"shippingFee": "30000",
"freeShipping": false,
"surcharge": "0",
"tax": "0",
"totalAmount": "480000",
"returnedAmount": "0",
"exchangeReturn": false,
"paidAmount": "0",
"occurredAt": "2026-10-02T03:15:00.000Z",
"note": null,
"tags": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000401",
"name": "Khách quen"
}
],
"lines": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000501",
"variantId": "018f3b8e-1c2d-7a4b-9c3d-000000000601",
"productId": "018f3b8e-1c2d-7a4b-9c3d-000000000701",
"variantCode": "AO-THUN-M",
"variantName": "Áo thun - M",
"productName": "Áo thun cổ tròn",
"quantity": "2",
"unitPrice": "225000",
"discount": "0",
"lineTotal": "450000",
"returnedQuantity": "0"
}
],
"payments": [],
"createdAt": "2026-10-02T03:15:00.000Z",
"updatedAt": "2026-10-02T03:15:00.000Z",
"deletedAt": null
}
Trường của phản hồi
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh của đơn. |
code |
string | có | Mã đơn, duy nhất trong shop. |
status |
"new" | "waiting_stock" | "confirmed" | "packing" | "ready_to_ship" | "shipped" | "delivered" | "paid" | "returning" | "partially_returned" | "returned" | "cancelled" | "deleted" | có | Trạng thái đơn. |
warehouseId |
string (uuid) | có | Kho xuất hàng. |
warehouseName |
string hoặc null | có | Tên kho xuất hàng. |
customerId |
string (uuid) hoặc null | có | Khách hàng gắn với đơn. |
salesChannelId |
string (uuid) hoặc null | có | Kênh bán. |
salesChannelName |
string hoặc null | có | Tên kênh bán. |
receivedAtShop |
boolean | có | Khách nhận hàng tại shop. |
billFullName |
string hoặc null | có | Tên người mua ghi trên đơn. |
billPhone |
string hoặc null | có | Số điện thoại người mua. |
billEmail |
string hoặc null | có | Email người mua. |
shippingAddress |
object hoặc null | không | Địa chỉ giao hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
shippingAddress. |
string hoặc null | có | Tên người nhận. |
shippingAddress. |
string hoặc null | có | Số điện thoại người nhận. |
shippingAddress. |
string hoặc null | có | Số nhà, đường. |
shippingAddress. |
"old" | "new" hoặc null | có | Hệ địa giới của các mã bên dưới: old (tỉnh, huyện, xã) hoặc new (tỉnh, xã). null khi địa chỉ chỉ có chữ. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; null khi không có. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ new luôn null. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; null khi không có. |
shippingAddress. |
string hoặc null | có | Tỉnh hoặc thành phố. |
shippingAddress. |
string hoặc null | có | Quận hoặc huyện. |
shippingAddress. |
string hoặc null | có | Phường hoặc xã. |
totalPrice |
string | có | Tiền hàng. Chuỗi thập phân, ví dụ "150000". |
discount |
string | có | Giảm giá cả đơn. Chuỗi thập phân, ví dụ "150000". |
shippingFee |
string | có | Phí vận chuyển khách trả. Chuỗi thập phân, ví dụ "150000". |
freeShipping |
boolean | có | Shop chịu phí giao hàng. |
surcharge |
string | có | Phụ thu. Chuỗi thập phân, ví dụ "150000". |
tax |
string | có | Thuế. Chuỗi thập phân, ví dụ "150000". |
totalAmount |
string | có | Tổng tiền đơn. Chuỗi thập phân, ví dụ "150000". |
returnedAmount |
string | có | Tiền hàng khách đã hoàn. Chuỗi thập phân, ví dụ "150000". |
paidAmount |
string | có | Đã thanh toán. Chuỗi thập phân, ví dụ "150000". |
creditApplied |
string | không | Tiền cấn trừ vào đơn này từ phiếu đổi trả (khách trả hàng của một đơn khác): khách đã trả cho đơn này bằng khoản ấy, nên số còn phải thu đã trừ nó. Chỉ có ở chi tiết đơn, không có trong danh sách. Chuỗi thập phân, ví dụ "150000". |
exchangeReturn |
boolean | không | Đơn trả để ĐỔI hàng: mọi lượt khách trả hàng của đơn đều là đổi (đổi size, đổi màu…), nên đơn không tính là hoàn — không vào tỉ lệ hoàn của số điện thoại, không gửi tin hoàn hay sự kiện hoàn sang Facebook. Chỉ có ở chi tiết đơn, không có trong danh sách. |
occurredAt |
string (date-time) | có | Thời điểm phát sinh đơn. ISO 8601, múi giờ UTC. |
note |
string hoặc null | có | Ghi chú nội bộ. |
tags |
array<object> | có | Các thẻ của đơn. |
tags[]. |
string (uuid) | có | Mã thẻ. |
tags[]. |
string | có | Tên thẻ. |
lines |
array<object> | không | Các dòng hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
lines[]. |
string (uuid) | có | Mã dòng hàng. |
lines[]. |
string (uuid) | có | Mã mẫu mã. |
lines[]. |
string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
lines[]. |
string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu pos.. |
lines[]. |
string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
lines[]. |
string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Số lượng khách đã hoàn. Chuỗi thập phân, tối đa ba chữ số lẻ. |
payments |
array<object> | không | Các khoản thu. Chỉ có ở chi tiết đơn, không có trong danh sách. |
payments[]. |
string (uuid) | có | Mã phương thức thanh toán. |
payments[]. |
string | có | Tên phương thức thanh toán. |
payments[]. |
string | có | Số tiền thu theo phương thức này. Chuỗi thập phân, ví dụ "150000". |
createdAt |
string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
updatedAt |
string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
deletedAt |
string (date-time) hoặc null | có | Thời điểm xoá mềm; null nếu chưa xoá. ISO 8601 UTC hoặc null. |
Lỗi
| Trạng thái | Mã code |
Ý nghĩa |
|---|---|---|
| 401 | invalid-api-key |
Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | insufficient-permission |
Khoá API không có quyền thực hiện thao tác này |
| 403 | shop-suspended |
Shop đang bị đình chỉ |
| 403 | automation-not-active |
Shop chưa bật tính năng Tự động hoá |
| 429 | rate-limited |
Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | internal-error |
Lỗi hệ thống |
| 402 | subscription-expired |
Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | validation-failed |
Dữ liệu gửi lên không hợp lệ |
| 413 | payload-too-large |
Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | unsupported-media-type |
Thân yêu cầu phải là JSON (Content-Type: application/json) |
| 404 | not-found |
Không tìm thấy tài nguyên |
| 409 | conflict |
Thao tác xung đột với trạng thái hiện tại |
| 422 | customer-blocked |
Khách hàng đang bị chặn |
| 409 | order-has-live-shipment |
Đơn đang có vận đơn chưa kết thúc nên không thao tác được |
Định dạng lỗi và bảng mọi mã code: Lỗi.
Đổi trạng thái đơn
POST /orders/{id}/status
Chuyển đơn sang trạng thái mới theo luồng của shop. Chuyển trạng thái có thể xuất hoặc nhập kho; từ chối bằng order-status-not-allowed hoặc insufficient-stock. Huỷ một đơn đã gửi hàng (shipped, delivered, paid, returning, partially_returned, returned sang cancelled; hàng khách đang giữ được nhập lại kho) cần thêm quyền pos. — thiếu thì insufficient-permission. Đơn đã rời new thì không đưa về new được nữa (order-status-not-allowed).
Quyền cần có: khoá có quyền pos. và quyền pos..
Quyền thêm theo trường: pos. — chỉ cần khi thân dùng trường tương ứng (xem mô tả ở trên).
Tham số đường dẫn
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh (UUID) của tài nguyên. |
Thân yêu cầu (JSON)
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
status |
"new" | "waiting_stock" | "confirmed" | "packing" | "ready_to_ship" | "shipped" | "delivered" | "paid" | "returning" | "returned" | "cancelled" | có | Trạng thái mới của đơn. new không bao giờ là một đích đi được: đơn đang ở new → conflict; đơn đã rời new → order-status-not-allowed. |
Ví dụ yêu cầu
curl -X POST "https://danix.vn/api/open/v1/orders/{id}/status" \
-H "Authorization: Bearer dnx_live_…" \
-H "Content-Type: application/json" \
-d '{
"status": "confirmed"
}'
Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.
Phản hồi mẫu (200)
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000101",
"code": "DH1024",
"status": "confirmed",
"warehouseId": "018f3b8e-1c2d-7a4b-9c3d-000000000001",
"warehouseName": "Kho chính",
"customerId": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
"salesChannelId": "018f3b8e-1c2d-7a4b-9c3d-000000000301",
"salesChannelName": "Facebook",
"receivedAtShop": false,
"billFullName": "Nguyễn Văn An",
"billPhone": "0901234567",
"billEmail": null,
"shippingAddress": {
"recipientName": "Nguyễn Văn An",
"recipientPhone": "0901234567",
"addressLine": "12 Lê Lợi",
"geoSystem": "old",
"provinceUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001501",
"districtUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001502",
"wardUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001503",
"provinceName": "Đà Nẵng",
"districtName": "Hải Châu",
"wardName": "Thạch Thang"
},
"totalPrice": "450000",
"discount": "0",
"shippingFee": "30000",
"freeShipping": false,
"surcharge": "0",
"tax": "0",
"totalAmount": "480000",
"returnedAmount": "0",
"exchangeReturn": false,
"paidAmount": "0",
"occurredAt": "2026-10-02T03:15:00.000Z",
"note": null,
"tags": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000401",
"name": "Khách quen"
}
],
"lines": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000501",
"variantId": "018f3b8e-1c2d-7a4b-9c3d-000000000601",
"productId": "018f3b8e-1c2d-7a4b-9c3d-000000000701",
"variantCode": "AO-THUN-M",
"variantName": "Áo thun - M",
"productName": "Áo thun cổ tròn",
"quantity": "2",
"unitPrice": "225000",
"discount": "0",
"lineTotal": "450000",
"returnedQuantity": "0"
}
],
"payments": [],
"createdAt": "2026-10-02T03:15:00.000Z",
"updatedAt": "2026-10-02T03:15:00.000Z",
"deletedAt": null
}
Trường của phản hồi
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh của đơn. |
code |
string | có | Mã đơn, duy nhất trong shop. |
status |
"new" | "waiting_stock" | "confirmed" | "packing" | "ready_to_ship" | "shipped" | "delivered" | "paid" | "returning" | "partially_returned" | "returned" | "cancelled" | "deleted" | có | Trạng thái đơn. |
warehouseId |
string (uuid) | có | Kho xuất hàng. |
warehouseName |
string hoặc null | có | Tên kho xuất hàng. |
customerId |
string (uuid) hoặc null | có | Khách hàng gắn với đơn. |
salesChannelId |
string (uuid) hoặc null | có | Kênh bán. |
salesChannelName |
string hoặc null | có | Tên kênh bán. |
receivedAtShop |
boolean | có | Khách nhận hàng tại shop. |
billFullName |
string hoặc null | có | Tên người mua ghi trên đơn. |
billPhone |
string hoặc null | có | Số điện thoại người mua. |
billEmail |
string hoặc null | có | Email người mua. |
shippingAddress |
object hoặc null | không | Địa chỉ giao hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
shippingAddress. |
string hoặc null | có | Tên người nhận. |
shippingAddress. |
string hoặc null | có | Số điện thoại người nhận. |
shippingAddress. |
string hoặc null | có | Số nhà, đường. |
shippingAddress. |
"old" | "new" hoặc null | có | Hệ địa giới của các mã bên dưới: old (tỉnh, huyện, xã) hoặc new (tỉnh, xã). null khi địa chỉ chỉ có chữ. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; null khi không có. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ new luôn null. |
shippingAddress. |
string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; null khi không có. |
shippingAddress. |
string hoặc null | có | Tỉnh hoặc thành phố. |
shippingAddress. |
string hoặc null | có | Quận hoặc huyện. |
shippingAddress. |
string hoặc null | có | Phường hoặc xã. |
totalPrice |
string | có | Tiền hàng. Chuỗi thập phân, ví dụ "150000". |
discount |
string | có | Giảm giá cả đơn. Chuỗi thập phân, ví dụ "150000". |
shippingFee |
string | có | Phí vận chuyển khách trả. Chuỗi thập phân, ví dụ "150000". |
freeShipping |
boolean | có | Shop chịu phí giao hàng. |
surcharge |
string | có | Phụ thu. Chuỗi thập phân, ví dụ "150000". |
tax |
string | có | Thuế. Chuỗi thập phân, ví dụ "150000". |
totalAmount |
string | có | Tổng tiền đơn. Chuỗi thập phân, ví dụ "150000". |
returnedAmount |
string | có | Tiền hàng khách đã hoàn. Chuỗi thập phân, ví dụ "150000". |
paidAmount |
string | có | Đã thanh toán. Chuỗi thập phân, ví dụ "150000". |
creditApplied |
string | không | Tiền cấn trừ vào đơn này từ phiếu đổi trả (khách trả hàng của một đơn khác): khách đã trả cho đơn này bằng khoản ấy, nên số còn phải thu đã trừ nó. Chỉ có ở chi tiết đơn, không có trong danh sách. Chuỗi thập phân, ví dụ "150000". |
exchangeReturn |
boolean | không | Đơn trả để ĐỔI hàng: mọi lượt khách trả hàng của đơn đều là đổi (đổi size, đổi màu…), nên đơn không tính là hoàn — không vào tỉ lệ hoàn của số điện thoại, không gửi tin hoàn hay sự kiện hoàn sang Facebook. Chỉ có ở chi tiết đơn, không có trong danh sách. |
occurredAt |
string (date-time) | có | Thời điểm phát sinh đơn. ISO 8601, múi giờ UTC. |
note |
string hoặc null | có | Ghi chú nội bộ. |
tags |
array<object> | có | Các thẻ của đơn. |
tags[]. |
string (uuid) | có | Mã thẻ. |
tags[]. |
string | có | Tên thẻ. |
lines |
array<object> | không | Các dòng hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
lines[]. |
string (uuid) | có | Mã dòng hàng. |
lines[]. |
string (uuid) | có | Mã mẫu mã. |
lines[]. |
string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
lines[]. |
string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu pos.. |
lines[]. |
string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu pos.. |
lines[]. |
string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
lines[]. |
string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
lines[]. |
string | có | Số lượng khách đã hoàn. Chuỗi thập phân, tối đa ba chữ số lẻ. |
payments |
array<object> | không | Các khoản thu. Chỉ có ở chi tiết đơn, không có trong danh sách. |
payments[]. |
string (uuid) | có | Mã phương thức thanh toán. |
payments[]. |
string | có | Tên phương thức thanh toán. |
payments[]. |
string | có | Số tiền thu theo phương thức này. Chuỗi thập phân, ví dụ "150000". |
createdAt |
string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
updatedAt |
string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
deletedAt |
string (date-time) hoặc null | có | Thời điểm xoá mềm; null nếu chưa xoá. ISO 8601 UTC hoặc null. |
Lỗi
| Trạng thái | Mã code |
Ý nghĩa |
|---|---|---|
| 401 | invalid-api-key |
Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | insufficient-permission |
Khoá API không có quyền thực hiện thao tác này |
| 403 | shop-suspended |
Shop đang bị đình chỉ |
| 403 | automation-not-active |
Shop chưa bật tính năng Tự động hoá |
| 429 | rate-limited |
Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | internal-error |
Lỗi hệ thống |
| 402 | subscription-expired |
Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | validation-failed |
Dữ liệu gửi lên không hợp lệ |
| 413 | payload-too-large |
Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | unsupported-media-type |
Thân yêu cầu phải là JSON (Content-Type: application/json) |
| 404 | not-found |
Không tìm thấy tài nguyên |
| 409 | conflict |
Thao tác xung đột với trạng thái hiện tại |
| 422 | order-status-not-allowed |
Không chuyển được đơn sang trạng thái này từ trạng thái hiện tại |
| 422 | insufficient-stock |
Không đủ tồn kho cho thao tác này |
| 422 | variant-removed |
Mẫu mã đã bị gỡ khỏi sản phẩm |
| 409 | order-has-live-shipment |
Đơn đang có vận đơn chưa kết thúc nên không thao tác được |
Định dạng lỗi và bảng mọi mã code: Lỗi.
Ghi chú của đơn
GET /orders/{id}/notes
Danh sách ghi chú, mới nhất trước.
Quyền cần có: khoá có quyền pos..
Tham số đường dẫn
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh (UUID) của tài nguyên. |
Ví dụ yêu cầu
curl -X GET "https://danix.vn/api/open/v1/orders/{id}/notes" \
-H "Authorization: Bearer dnx_live_…"
Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.
Phản hồi mẫu (200)
{
"data": [
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000777",
"message": "Đã gọi khách xác nhận",
"createdByName": "Đồng bộ kế toán",
"createdByIsIntegration": true,
"createdAt": "2026-10-02T03:15:00.000Z",
"updatedAt": "2026-10-02T03:15:00.000Z"
}
]
}
Trường của phản hồi
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
data |
array<object> | có | Các ghi chú, mới nhất trước. |
data[]. |
string (uuid) | có | Mã ghi chú. |
data[]. |
string | có | Nội dung ghi chú. |
data[]. |
string hoặc null | có | Tên người hay ứng dụng đã ghi. |
data[]. |
boolean | có | true khi ghi chú do một ứng dụng kết nối tạo. |
data[]. |
string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
data[]. |
string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
Lỗi
| Trạng thái | Mã code |
Ý nghĩa |
|---|---|---|
| 401 | invalid-api-key |
Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | insufficient-permission |
Khoá API không có quyền thực hiện thao tác này |
| 403 | shop-suspended |
Shop đang bị đình chỉ |
| 403 | automation-not-active |
Shop chưa bật tính năng Tự động hoá |
| 429 | rate-limited |
Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | internal-error |
Lỗi hệ thống |
| 404 | not-found |
Không tìm thấy tài nguyên |
Định dạng lỗi và bảng mọi mã code: Lỗi.
Thêm ghi chú vào đơn
POST /orders/{id}/notes
Ghi chú đứng tên ứng dụng kết nối.
Quyền cần có: khoá có quyền pos..
Tham số đường dẫn
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã định danh (UUID) của tài nguyên. |
Thân yêu cầu (JSON)
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
message |
string | có | Nội dung ghi chú. |
Ví dụ yêu cầu
curl -X POST "https://danix.vn/api/open/v1/orders/{id}/notes" \
-H "Authorization: Bearer dnx_live_…" \
-H "Content-Type: application/json" \
-d '{
"message": "Đã gọi khách xác nhận"
}'
Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.
Phản hồi mẫu (201)
{
"id": "018f3b8e-1c2d-7a4b-9c3d-000000000777",
"message": "Đã gọi khách xác nhận",
"createdByName": "Đồng bộ kế toán",
"createdByIsIntegration": true,
"createdAt": "2026-10-02T03:15:00.000Z",
"updatedAt": "2026-10-02T03:15:00.000Z"
}
Trường của phản hồi
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id |
string (uuid) | có | Mã ghi chú. |
message |
string | có | Nội dung ghi chú. |
createdByName |
string hoặc null | có | Tên người hay ứng dụng đã ghi. |
createdByIsIntegration |
boolean | có | true khi ghi chú do một ứng dụng kết nối tạo. |
createdAt |
string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
updatedAt |
string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
Lỗi
| Trạng thái | Mã code |
Ý nghĩa |
|---|---|---|
| 401 | invalid-api-key |
Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | insufficient-permission |
Khoá API không có quyền thực hiện thao tác này |
| 403 | shop-suspended |
Shop đang bị đình chỉ |
| 403 | automation-not-active |
Shop chưa bật tính năng Tự động hoá |
| 429 | rate-limited |
Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | internal-error |
Lỗi hệ thống |
| 402 | subscription-expired |
Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | validation-failed |
Dữ liệu gửi lên không hợp lệ |
| 413 | payload-too-large |
Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | unsupported-media-type |
Thân yêu cầu phải là JSON (Content-Type: application/json) |
| 404 | not-found |
Không tìm thấy tài nguyên |
Định dạng lỗi và bảng mọi mã code: Lỗi.