# 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.vn/api/open/v1`. Đặc tả máy đọc: [openapi.json](/openapi.json).

## Liệt kê đơn hàng {#listOrders}

`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.orders.read`.

**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**

```bash
curl -X GET "https://danix.vn/api/open/v1/orders" \
  -H "Authorization: Bearer dnx_live_…"
```

**Phản hồi mẫu (200)**

```json
{
  "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[].id` | string (uuid) | có | Mã định danh của đơn. |
| `data[].code` | string | có | Mã đơn, duy nhất trong shop. |
| `data[].status` | "new" \| "waiting_stock" \| "confirmed" \| "packing" \| "ready_to_ship" \| "shipped" \| "delivered" \| "paid" \| "returning" \| "partially_returned" \| "returned" \| "cancelled" \| "deleted" | có | Trạng thái đơn. |
| `data[].warehouseId` | string (uuid) | có | Kho xuất hàng. |
| `data[].warehouseName` | string hoặc null | có | Tên kho xuất hàng. |
| `data[].customerId` | string (uuid) hoặc null | có | Khách hàng gắn với đơn. |
| `data[].salesChannelId` | string (uuid) hoặc null | có | Kênh bán. |
| `data[].salesChannelName` | string hoặc null | có | Tên kênh bán. |
| `data[].receivedAtShop` | boolean | có | Khách nhận hàng tại shop. |
| `data[].billFullName` | string hoặc null | có | Tên người mua ghi trên đơn. |
| `data[].billPhone` | string hoặc null | có | Số điện thoại người mua. |
| `data[].billEmail` | string hoặc null | có | Email người mua. |
| `data[].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. |
| `data[].shippingAddress.recipientName` | string hoặc null | có | Tên người nhận. |
| `data[].shippingAddress.recipientPhone` | string hoặc null | có | Số điện thoại người nhận. |
| `data[].shippingAddress.addressLine` | string hoặc null | có | Số nhà, đường. |
| `data[].shippingAddress.geoSystem` | "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[].shippingAddress.provinceUnitId` | string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; `null` khi không có. |
| `data[].shippingAddress.districtUnitId` | string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ `new` luôn `null`. |
| `data[].shippingAddress.wardUnitId` | string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; `null` khi không có. |
| `data[].shippingAddress.provinceName` | string hoặc null | có | Tỉnh hoặc thành phố. |
| `data[].shippingAddress.districtName` | string hoặc null | có | Quận hoặc huyện. |
| `data[].shippingAddress.wardName` | string hoặc null | có | Phường hoặc xã. |
| `data[].totalPrice` | string | có | Tiền hàng. Chuỗi thập phân, ví dụ "150000". |
| `data[].discount` | string | có | Giảm giá cả đơn. Chuỗi thập phân, ví dụ "150000". |
| `data[].shippingFee` | string | có | Phí vận chuyển khách trả. Chuỗi thập phân, ví dụ "150000". |
| `data[].freeShipping` | boolean | có | Shop chịu phí giao hàng. |
| `data[].surcharge` | string | có | Phụ thu. Chuỗi thập phân, ví dụ "150000". |
| `data[].tax` | string | có | Thuế. Chuỗi thập phân, ví dụ "150000". |
| `data[].totalAmount` | string | có | Tổng tiền đơn. Chuỗi thập phân, ví dụ "150000". |
| `data[].returnedAmount` | string | có | Tiền hàng khách đã hoàn. Chuỗi thập phân, ví dụ "150000". |
| `data[].paidAmount` | string | có | Đã thanh toán. Chuỗi thập phân, ví dụ "150000". |
| `data[].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". |
| `data[].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. |
| `data[].occurredAt` | string (date-time) | có | Thời điểm phát sinh đơn. ISO 8601, múi giờ UTC. |
| `data[].note` | string hoặc null | có | Ghi chú nội bộ. |
| `data[].tags` | array<object> | có | Các thẻ của đơn. |
| `data[].tags[].id` | string (uuid) | có | Mã thẻ. |
| `data[].tags[].name` | string | có | Tên thẻ. |
| `data[].lines` | array<object> | không | Các dòng hàng. Chỉ có ở chi tiết đơn, không có trong danh sách. |
| `data[].lines[].id` | string (uuid) | có | Mã dòng hàng. |
| `data[].lines[].variantId` | string (uuid) | có | Mã mẫu mã. |
| `data[].lines[].productId` | string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
| `data[].lines[].variantCode` | string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `data[].lines[].variantName` | string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `data[].lines[].productName` | string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu `pos.products.read`. |
| `data[].lines[].quantity` | string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
| `data[].lines[].unitPrice` | string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
| `data[].lines[].discount` | string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
| `data[].lines[].lineTotal` | string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
| `data[].lines[].returnedQuantity` | string | có | Số lượng khách đã hoàn. Chuỗi thập phân, tối đa ba chữ số lẻ. |
| `data[].payments` | array<object> | không | Các khoản thu. Chỉ có ở chi tiết đơn, không có trong danh sách. |
| `data[].payments[].methodId` | string (uuid) | có | Mã phương thức thanh toán. |
| `data[].payments[].methodName` | string | có | Tên phương thức thanh toán. |
| `data[].payments[].amount` | string | có | Số tiền thu theo phương thức này. Chuỗi thập phân, ví dụ "150000". |
| `data[].createdAt` | string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
| `data[].updatedAt` | string (date-time) | có | Thời điểm sửa gần nhất. ISO 8601, múi giờ UTC. |
| `data[].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`. |
| `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`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 400 | [`validation-failed`](/developers/errors#validation-failed) | Dữ liệu gửi lên không hợp lệ |
| 400 | [`invalid-cursor`](/developers/errors#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](/developers/errors).

## Tạo đơn hàng {#createOrder}

`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.orders.price.override`; gửi `payments` cần thêm `pos.orders.payment.record` — thiếu thì `insufficient-permission`.

**Quyền cần có:** khoá có quyền `pos.orders.create` và quyền `pos.products.read`.

**Quyền thêm theo trường:** `pos.orders.payment.record`, `pos.orders.price.override` — 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.recipientName` | string hoặc null | không | Tên người nhận. |
| `shippingAddress.recipientPhone` | string hoặc null | không | Số điện thoại người nhận. |
| `shippingAddress.addressLine` | string hoặc null | không | Số nhà, đường. |
| `shippingAddress.provinceName` | string hoặc null | không | Tỉnh hoặc thành phố. |
| `shippingAddress.districtName` | string hoặc null | không | Quận hoặc huyện. |
| `shippingAddress.wardName` | string hoặc null | không | Phường hoặc xã. |
| `shippingAddress.geoSystem` | "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.provinceUnitId` | 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.districtUnitId` | 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.wardUnitId` | 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[].variantId` | string (uuid) | có | Mã mẫu mã cần bán. |
| `lines[].quantity` | string | có | Số lượng, lớn hơn 0. Chuỗi thập phân, tối đa ba chữ số lẻ. |
| `lines[].unitPrice` | 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.orders.price.override`. Chuỗi thập phân, ví dụ "150000". |
| `lines[].discount` | 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.orders.price.override`. |
| `discount` | string | không | Giảm giá cả đơn. Khác 0 thì khoá cần thêm quyền `pos.orders.price.override`. |
| `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.orders.payment.record`. |
| `payments[].methodId` | string (uuid) | có | Mã phương thức thanh toán. |
| `payments[].amount` | 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**

```bash
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)**

```json
{
  "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.recipientName` | string hoặc null | có | Tên người nhận. |
| `shippingAddress.recipientPhone` | string hoặc null | có | Số điện thoại người nhận. |
| `shippingAddress.addressLine` | string hoặc null | có | Số nhà, đường. |
| `shippingAddress.geoSystem` | "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.provinceUnitId` | string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; `null` khi không có. |
| `shippingAddress.districtUnitId` | string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ `new` luôn `null`. |
| `shippingAddress.wardUnitId` | string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; `null` khi không có. |
| `shippingAddress.provinceName` | string hoặc null | có | Tỉnh hoặc thành phố. |
| `shippingAddress.districtName` | string hoặc null | có | Quận hoặc huyện. |
| `shippingAddress.wardName` | 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[].id` | string (uuid) | có | Mã thẻ. |
| `tags[].name` | 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[].id` | string (uuid) | có | Mã dòng hàng. |
| `lines[].variantId` | string (uuid) | có | Mã mẫu mã. |
| `lines[].productId` | string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
| `lines[].variantCode` | string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].variantName` | string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].productName` | string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].quantity` | string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
| `lines[].unitPrice` | string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].discount` | string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
| `lines[].lineTotal` | string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].returnedQuantity` | 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[].methodId` | string (uuid) | có | Mã phương thức thanh toán. |
| `payments[].methodName` | string | có | Tên phương thức thanh toán. |
| `payments[].amount` | 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`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 402 | [`subscription-expired`](/developers/errors#subscription-expired) | Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | [`validation-failed`](/developers/errors#validation-failed) | Dữ liệu gửi lên không hợp lệ |
| 413 | [`payload-too-large`](/developers/errors#payload-too-large) | Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | [`unsupported-media-type`](/developers/errors#unsupported-media-type) | Thân yêu cầu phải là JSON (`Content-Type: application/json`) |
| 409 | [`conflict`](/developers/errors#conflict) | Thao tác xung đột với trạng thái hiện tại |
| 409 | [`idempotency-key-in-progress`](/developers/errors#idempotency-key-in-progress) | Yêu cầu với cùng Idempotency-Key đang được xử lý |
| 422 | [`idempotency-key-reused`](/developers/errors#idempotency-key-reused) | Idempotency-Key đã dùng cho một yêu cầu có nội dung khác |
| 422 | [`variant-removed`](/developers/errors#variant-removed) | Mẫu mã đã bị gỡ khỏi sản phẩm |
| 422 | [`customer-blocked`](/developers/errors#customer-blocked) | Khách hàng đang bị chặn |
| 422 | [`insufficient-stock`](/developers/errors#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](/developers/errors).

## Chi tiết một đơn hàng {#getOrder}

`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.orders.read`.

**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**

```bash
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)**

```json
{
  "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.recipientName` | string hoặc null | có | Tên người nhận. |
| `shippingAddress.recipientPhone` | string hoặc null | có | Số điện thoại người nhận. |
| `shippingAddress.addressLine` | string hoặc null | có | Số nhà, đường. |
| `shippingAddress.geoSystem` | "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.provinceUnitId` | string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; `null` khi không có. |
| `shippingAddress.districtUnitId` | string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ `new` luôn `null`. |
| `shippingAddress.wardUnitId` | string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; `null` khi không có. |
| `shippingAddress.provinceName` | string hoặc null | có | Tỉnh hoặc thành phố. |
| `shippingAddress.districtName` | string hoặc null | có | Quận hoặc huyện. |
| `shippingAddress.wardName` | 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[].id` | string (uuid) | có | Mã thẻ. |
| `tags[].name` | 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[].id` | string (uuid) | có | Mã dòng hàng. |
| `lines[].variantId` | string (uuid) | có | Mã mẫu mã. |
| `lines[].productId` | string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
| `lines[].variantCode` | string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].variantName` | string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].productName` | string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].quantity` | string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
| `lines[].unitPrice` | string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].discount` | string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
| `lines[].lineTotal` | string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].returnedQuantity` | 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[].methodId` | string (uuid) | có | Mã phương thức thanh toán. |
| `payments[].methodName` | string | có | Tên phương thức thanh toán. |
| `payments[].amount` | 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`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 404 | [`not-found`](/developers/errors#not-found) | Không tìm thấy tài nguyên |
| 400 | [`validation-failed`](/developers/errors#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](/developers/errors).

## Sửa đơn hàng {#updateOrder}

`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.orders.price.override`.

**Quyền cần có:** khoá có quyền `pos.orders.update` và quyền `pos.products.read`.

**Quyền thêm theo trường:** `pos.orders.price.override` — 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.recipientName` | string hoặc null | không | Tên người nhận. |
| `shippingAddress.recipientPhone` | string hoặc null | không | Số điện thoại người nhận. |
| `shippingAddress.addressLine` | string hoặc null | không | Số nhà, đường. |
| `shippingAddress.provinceName` | string hoặc null | không | Tỉnh hoặc thành phố. |
| `shippingAddress.districtName` | string hoặc null | không | Quận hoặc huyện. |
| `shippingAddress.wardName` | string hoặc null | không | Phường hoặc xã. |
| `shippingAddress.geoSystem` | "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.provinceUnitId` | 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.districtUnitId` | 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.wardUnitId` | 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.orders.price.override`. |
| `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**

```bash
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)**

```json
{
  "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.recipientName` | string hoặc null | có | Tên người nhận. |
| `shippingAddress.recipientPhone` | string hoặc null | có | Số điện thoại người nhận. |
| `shippingAddress.addressLine` | string hoặc null | có | Số nhà, đường. |
| `shippingAddress.geoSystem` | "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.provinceUnitId` | string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; `null` khi không có. |
| `shippingAddress.districtUnitId` | string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ `new` luôn `null`. |
| `shippingAddress.wardUnitId` | string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; `null` khi không có. |
| `shippingAddress.provinceName` | string hoặc null | có | Tỉnh hoặc thành phố. |
| `shippingAddress.districtName` | string hoặc null | có | Quận hoặc huyện. |
| `shippingAddress.wardName` | 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[].id` | string (uuid) | có | Mã thẻ. |
| `tags[].name` | 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[].id` | string (uuid) | có | Mã dòng hàng. |
| `lines[].variantId` | string (uuid) | có | Mã mẫu mã. |
| `lines[].productId` | string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
| `lines[].variantCode` | string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].variantName` | string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].productName` | string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].quantity` | string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
| `lines[].unitPrice` | string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].discount` | string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
| `lines[].lineTotal` | string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].returnedQuantity` | 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[].methodId` | string (uuid) | có | Mã phương thức thanh toán. |
| `payments[].methodName` | string | có | Tên phương thức thanh toán. |
| `payments[].amount` | 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`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 402 | [`subscription-expired`](/developers/errors#subscription-expired) | Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | [`validation-failed`](/developers/errors#validation-failed) | Dữ liệu gửi lên không hợp lệ |
| 413 | [`payload-too-large`](/developers/errors#payload-too-large) | Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | [`unsupported-media-type`](/developers/errors#unsupported-media-type) | Thân yêu cầu phải là JSON (`Content-Type: application/json`) |
| 404 | [`not-found`](/developers/errors#not-found) | Không tìm thấy tài nguyên |
| 409 | [`conflict`](/developers/errors#conflict) | Thao tác xung đột với trạng thái hiện tại |
| 422 | [`customer-blocked`](/developers/errors#customer-blocked) | Khách hàng đang bị chặn |
| 409 | [`order-has-live-shipment`](/developers/errors#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](/developers/errors).

## Đổi trạng thái đơn {#changeOrderStatus}

`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.orders.delete` — 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.orders.status` và quyền `pos.products.read`.

**Quyền thêm theo trường:** `pos.orders.delete` — 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**

```bash
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)**

```json
{
  "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.recipientName` | string hoặc null | có | Tên người nhận. |
| `shippingAddress.recipientPhone` | string hoặc null | có | Số điện thoại người nhận. |
| `shippingAddress.addressLine` | string hoặc null | có | Số nhà, đường. |
| `shippingAddress.geoSystem` | "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.provinceUnitId` | string (uuid) hoặc null | có | Mã (UUID) tỉnh hoặc thành phố; `null` khi không có. |
| `shippingAddress.districtUnitId` | string (uuid) hoặc null | có | Mã (UUID) quận hoặc huyện; hệ `new` luôn `null`. |
| `shippingAddress.wardUnitId` | string (uuid) hoặc null | có | Mã (UUID) phường hoặc xã; `null` khi không có. |
| `shippingAddress.provinceName` | string hoặc null | có | Tỉnh hoặc thành phố. |
| `shippingAddress.districtName` | string hoặc null | có | Quận hoặc huyện. |
| `shippingAddress.wardName` | 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[].id` | string (uuid) | có | Mã thẻ. |
| `tags[].name` | 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[].id` | string (uuid) | có | Mã dòng hàng. |
| `lines[].variantId` | string (uuid) | có | Mã mẫu mã. |
| `lines[].productId` | string (uuid) hoặc null | có | Mã sản phẩm của mẫu mã. |
| `lines[].variantCode` | string hoặc null | không | Mã mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].variantName` | string hoặc null | không | Tên mẫu mã. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].productName` | string hoặc null | không | Tên sản phẩm. Vắng khi khoá thiếu `pos.products.read`. |
| `lines[].quantity` | string | có | Số lượng. Chuỗi thập phân, tối đa ba chữ số lẻ. |
| `lines[].unitPrice` | string | có | Đơn giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].discount` | string | có | Giảm giá của dòng. Chuỗi thập phân, ví dụ "150000". |
| `lines[].lineTotal` | string | có | Thành tiền của dòng, đã trừ giảm giá. Chuỗi thập phân, ví dụ "150000". |
| `lines[].returnedQuantity` | 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[].methodId` | string (uuid) | có | Mã phương thức thanh toán. |
| `payments[].methodName` | string | có | Tên phương thức thanh toán. |
| `payments[].amount` | 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`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 402 | [`subscription-expired`](/developers/errors#subscription-expired) | Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | [`validation-failed`](/developers/errors#validation-failed) | Dữ liệu gửi lên không hợp lệ |
| 413 | [`payload-too-large`](/developers/errors#payload-too-large) | Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | [`unsupported-media-type`](/developers/errors#unsupported-media-type) | Thân yêu cầu phải là JSON (`Content-Type: application/json`) |
| 404 | [`not-found`](/developers/errors#not-found) | Không tìm thấy tài nguyên |
| 409 | [`conflict`](/developers/errors#conflict) | Thao tác xung đột với trạng thái hiện tại |
| 422 | [`order-status-not-allowed`](/developers/errors#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`](/developers/errors#insufficient-stock) | Không đủ tồn kho cho thao tác này |
| 422 | [`variant-removed`](/developers/errors#variant-removed) | Mẫu mã đã bị gỡ khỏi sản phẩm |
| 409 | [`order-has-live-shipment`](/developers/errors#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](/developers/errors).

## Ghi chú của đơn {#listOrderNotes}

`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.orders.read`.

**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**

```bash
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)**

```json
{
  "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[].id` | string (uuid) | có | Mã ghi chú. |
| `data[].message` | string | có | Nội dung ghi chú. |
| `data[].createdByName` | string hoặc null | có | Tên người hay ứng dụng đã ghi. |
| `data[].createdByIsIntegration` | boolean | có | `true` khi ghi chú do một ứng dụng kết nối tạo. |
| `data[].createdAt` | string (date-time) | có | Thời điểm tạo. ISO 8601, múi giờ UTC. |
| `data[].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`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 404 | [`not-found`](/developers/errors#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](/developers/errors).

## Thêm ghi chú vào đơn {#createOrderNote}

`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.orders.update`.

**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**

```bash
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)**

```json
{
  "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`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 402 | [`subscription-expired`](/developers/errors#subscription-expired) | Gói cước của shop đã hết hạn, chỉ còn quyền đọc |
| 400 | [`validation-failed`](/developers/errors#validation-failed) | Dữ liệu gửi lên không hợp lệ |
| 413 | [`payload-too-large`](/developers/errors#payload-too-large) | Thân yêu cầu vượt quá dung lượng cho phép |
| 415 | [`unsupported-media-type`](/developers/errors#unsupported-media-type) | Thân yêu cầu phải là JSON (`Content-Type: application/json`) |
| 404 | [`not-found`](/developers/errors#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](/developers/errors).