Đơn hàng — Tạo
Tạo đơn hàng bán lẻ mới: chọn biến thể, số lượng, kho xuất, khách hàng và phương thức thanh toán.
Endpoint tạo đơn hàng ghi nhận một giao dịch bán và tự động trừ tồn kho ở kho được chỉ định. Mỗi dòng hàng tham chiếu đến một variation_id.
Endpoint
| Method | Endpoint | Mô tả |
|---|---|---|
POST | /api/v1/shops/{shop_id}/orders | Tạo đơn hàng mới |
Tham số thân yêu cầu (Body)
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
warehouse_id | string | Có | Kho xuất hàng và trừ tồn |
items | array | Có | Danh sách dòng hàng, mỗi dòng có variation_id và quantity |
items[].variation_id | string | Có | Biến thể được bán |
items[].quantity | number | Có | Số lượng |
items[].price | number | Không | Giá bán tuỳ chỉnh (mặc định lấy giá niêm yết) |
customer | object | Không | Thông tin khách (name, phone) hoặc customer_id |
discount | number | Không | Số tiền giảm giá trên tổng đơn |
payment_method | string | Không | cash, card, transfer, cod |
note | string | Không | Ghi chú đơn hàng |
Kiểm thử tại chỗ
POST
https://pos.hitechcloud.vn/api/v1/shops/{shop_id}/ordersKiểm thử tại chỗGửi thử sẽ tạo đơn thật và trừ kho trên môi trường được chọn. Nên thử trên Sandbox. Key không được lưu lại.
Tham số đường dẫn
Body
cURL tạo đơn hàng
curl -X POST "https://pos.hitechcloud.vn/api/v1/shops/shop_0a1b2c3d/orders" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"warehouse_id": "wh_main",
"items": [
{ "variation_id": "var_1001", "quantity": 2 },
{ "variation_id": "var_1002", "quantity": 1, "price": 180000 }
],
"customer": { "name": "Nguyen Van A", "phone": "0901234567" },
"discount": 20000,
"payment_method": "transfer",
"note": "Giao gio hanh chinh"
}'Phản hồi tạo đơn (201 Created)
{
"status": "success",
"data": {
"id": "order_900123",
"code": "DH900123",
"shop_id": "shop_0a1b2c3d",
"warehouse_id": "wh_main",
"status": "confirmed",
"payment_status": "unpaid",
"subtotal": 578000,
"discount": 20000,
"total": 558000,
"items": [
{ "variation_id": "var_1001", "quantity": 2, "price": 199000, "line_total": 398000 },
{ "variation_id": "var_1002", "quantity": 1, "price": 180000, "line_total": 180000 }
],
"created_at": "2026-10-31 10:12:00"
}
}Nếu tồn kho không đủ cho một biến thể, API trả về lỗi
422 OUT_OF_STOCK và không tạo đơn. Hãy kiểm tra tồn trước hoặc bắt lỗi này.Endpoint tạo đơn hàng ghi nhận một giao dịch bán và tự động trừ tồn kho ở kho được chỉ định. Mỗi dòng hàng tham chiếu đến một variation_id.
Endpoint
| Method | Endpoint | Mô tả |
|---|---|---|
POST | /api/v1/shops/{shop_id}/orders | Tạo đơn hàng mới |
Tham số thân yêu cầu (Body)
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
warehouse_id | string | Có | Kho xuất hàng và trừ tồn |
items | array | Có | Danh sách dòng hàng, mỗi dòng có variation_id và quantity |
items[].variation_id | string | Có | Biến thể được bán |
items[].quantity | number | Có | Số lượng |
items[].price | number | Không | Giá bán tuỳ chỉnh (mặc định lấy giá niêm yết) |
customer | object | Không | Thông tin khách (name, phone) hoặc customer_id |
discount | number | Không | Số tiền giảm giá trên tổng đơn |
payment_method | string | Không | cash, card, transfer, cod |
note | string | Không | Ghi chú đơn hàng |
Kiểm thử tại chỗ
POST
https://pos.hitechcloud.vn/api/v1/shops/{shop_id}/ordersKiểm thử tại chỗGửi thử sẽ tạo đơn thật và trừ kho trên môi trường được chọn. Nên thử trên Sandbox. Key không được lưu lại.
Tham số đường dẫn
Body
Nếu tồn kho không đủ cho một biến thể, API trả về lỗi
422 OUT_OF_STOCK và không tạo đơn. Hãy kiểm tra tồn trước hoặc bắt lỗi này.cURL tạo đơn hàng
curl -X POST "https://pos.hitechcloud.vn/api/v1/shops/shop_0a1b2c3d/orders" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"warehouse_id": "wh_main",
"items": [
{ "variation_id": "var_1001", "quantity": 2 },
{ "variation_id": "var_1002", "quantity": 1, "price": 180000 }
],
"customer": { "name": "Nguyen Van A", "phone": "0901234567" },
"discount": 20000,
"payment_method": "transfer",
"note": "Giao gio hanh chinh"
}'Phản hồi tạo đơn (201 Created)
{
"status": "success",
"data": {
"id": "order_900123",
"code": "DH900123",
"shop_id": "shop_0a1b2c3d",
"warehouse_id": "wh_main",
"status": "confirmed",
"payment_status": "unpaid",
"subtotal": 578000,
"discount": 20000,
"total": 558000,
"items": [
{ "variation_id": "var_1001", "quantity": 2, "price": 199000, "line_total": 398000 },
{ "variation_id": "var_1002", "quantity": 1, "price": 180000, "line_total": 180000 }
],
"created_at": "2026-10-31 10:12:00"
}
}