Cập nhật phiếu nhập/xuất
Cập nhật thông tin của một phiếu nhập/xuất kho
Endpoint
PUT /v1/productreceipts/:id
Quyền: Cần ít nhất 1 trong các quyền:
inventory.statusapprove,inventory.statuscheck,inventory.statuscomplete(scoped theo warehouse của phiếu).
Path Parameters
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id | int | Có | ID của phiếu cần cập nhật |
Request Payload
JSON Object Payload:
{
"company_id": 1,
"creator_id": 101,
"quantity": 100,
"count_detail": 5,
"note": "Cập nhật ghi chú",
"tag": "update",
"file_id_list": [],
"type": 1,
"external_id": "",
"status": 3,
"details": [
{
"id": 567,
"product_variant_id": 201,
"uom_quantity": 20,
"item_quantity": 20,
"uom_factor": 1
},
{
"id": 0,
"product_variant_id": 202,
"uom_id": 1,
"uom_name": "Cái",
"uom_factor": 1,
"uom_quantity": 5,
"item_quantity": 5
}
]
}Các trường chính
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
company_id | int | Có | ID công ty |
creator_id | int | Có | ID người thực hiện |
status | int | Có | Trạng thái mới (1, 3, 5, 7, 9). Không được nhỏ hơn trạng thái hiện tại; không được truyền 11 (Hủy) |
details | array | Có | Danh sách dòng hàng của phiếu (xem quy tắc bên dưới) |
type | int | Loại phiếu | |
external_id | string | ID tham chiếu bên ngoài | |
note | string | Ghi chú | |
tag | string | Thẻ, phân cách bằng dấu phẩy | |
file_id_list | array | Danh sách ID file đính kèm | |
quantity | int | Tổng số lượng | |
count_detail | int | Số dòng chi tiết |
Mỗi dòng trong details dùng các trường như API tạo phiếu, kèm id của dòng chi tiết đã có (0 hoặc bỏ trống với dòng mới).
Gửi đầy đủ dữ liệu phiếu
API ghi đè các trường type, external_id, note, tag, file_id_list, quantity, count_detail, status bằng giá trị trong payload. Trường nào không gửi sẽ bị đặt về giá trị rỗng/0, vì vậy hãy gửi lại toàn bộ giá trị hiện tại của phiếu cùng với phần thay đổi. Các trường warehouse_id, direction, identifier, source, source_id, shift_id, picking_list_id không thay đổi được sau khi tạo.
Quy tắc cập nhật dòng chi tiết
- Phiếu đang ở trạng thái Nháp (
status = 1): được thêm dòng mới, dòng có sẵn không có trongdetailssẽ bị xóa.uom_quantitycập nhật số lượng ban đầu của dòng. - Phiếu ở trạng thái khác Nháp:
detailsphải chứa đúng và đủ các dòng hiện có (không thêm, không bớt), nếu không trả vềerror_detail_change_not_allow. Dòng hàng loại IMEI phải cóitem_serial_number.uom_quantitycập nhật số lượng thực tế (uom_quantity,item_quantity) của dòng, số lượng ban đầu giữ nguyên. - Phiếu đã Hoàn thành (
status = 9): số lượng các dòng không còn được cập nhật. - Trạng thái không được quay ngược (VD: từ 5 về 3). Không dùng API này để hủy phiếu — dùng API Hủy phiếu.
Workflow & Logic
- Sau khi cập nhật, tồn kho của các biến thể liên quan được cập nhật bất đồng bộ.
- Khi phiếu xuất tạo từ phiếu chuyển kho (
source = 3) chuyển sang Hoàn thành, phiếu chuyển kho liên quan được hoàn tất (tạo phiếu nhập ở kho đích). - Khi phiếu tạo từ đơn bán hàng (
source = 11) chuyển sang Hoàn thành và mọi phiếu xuất của đơn đó đều đã hoàn thành, hệ thống tự cập nhật trạng thái đơn hàng.
Response Schema
HTTP 200 - JSON Object
Xem ProductReceipt Object Schema. Trường details chứa các dòng hợp lệ đã gửi lên.
Error Codes
| HTTP | Code | Mô tả |
|---|---|---|
| 404 | (not found) | Không tìm thấy phiếu |
| 422 | error_company_id_required | ID công ty không được để trống |
| 422 | error_company_id_notfound | Công ty không hợp lệ hoặc không thuộc phạm vi truy cập |
| 422 | error_user1_id_required | ID người thực hiện (creator_id) không được để trống |
| 422 | error_user_id_notfound | Người thực hiện không hợp lệ |
| 422 | error_not_permission | Không có quyền chỉnh sửa phiếu |
| 422 | error_status_invalid | Trạng thái không hợp lệ |
| 422 | error_status_backward_not_allow | Không được phép quay lại trạng thái trước đó |
| 422 | error_status_complete_not_allow | Không có quyền hoàn thành phiếu |
| 422 | error_this_api_not_allow_cancel | API này không cho phép hủy phiếu (dùng API Hủy phiếu) |
| 422 | error_detail_required | Chi tiết phiếu là bắt buộc |
| 422 | error_detail_change_not_allow | Không được phép thêm/xóa dòng chi tiết (khi phiếu không còn ở trạng thái Nháp) |
| 422 | error_detail_item_required_imei (SKU: ...) | Dòng hàng loại IMEI thiếu item_serial_number (kèm SKU của dòng) |
| 422 | error_edit | Lỗi khi cập nhật phiếu |