Cập nhật đơn đặt hàng mua

Cập nhật thông tin, trạng thái và chi tiết sản phẩm của đơn đặt hàng mua (PO)

Endpoint

PUT /v1/purchaseorders/:id

Quyền: Cần ít nhất một trong các quyền: purchaseorder.edit, purchaseorder.statuscomplete, purchaseorder.statuscancel

Headers

Tên	Bắt buộc	Mô tả
`Authorization`	Có	`<JWT>` của người dùng có quyền `purchaseorder.edit`, `purchaseorder.statuscomplete` hoặc `purchaseorder.statuscancel`

Path Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`id`	int	Có	ID đơn đặt hàng mua cần cập nhật

Trường	Kiểu	Bắt buộc	Mô tả
`company_id`	int	Có	ID công ty
`creator_id`	int	Có	ID người thao tác
`status`	int	Có	Trạng thái mới. Chỉ được chuyển TỚI trạng thái cao hơn
`cancel_reason`	int	Điều kiện	Lý do hủy (bắt buộc khi status = 13). Xem Cancel Reason
`tag`	string	Không	Nhãn/Tag
`note`	string	Không	Ghi chú
`price_sell`	int	Không	Tổng giá bán tham chiếu
`price_shipping`	int	Không	Phí vận chuyển
`price_discount`	int	Không	Chiết khấu
`price_final`	int	Không	Tổng tiền cuối cùng
`details`	array	Không	Danh sách chi tiết sản phẩm (khi cần thay đổi detail)

Khi PO chưa hoàn thành/hủy (status < 11), các trường tag, note, price_sell, price_shipping, price_discount, price_final luôn được ghi đè bằng giá trị trong payload. Trường bị bỏ trống sẽ thành rỗng / 0, vì vậy cần gửi lại đầy đủ các giá trị hiện tại kể cả khi chỉ đổi trạng thái.

Chi tiết sản phẩm (details[])

Khi PO chưa hoàn thành/hủy (status < 11), có thể thay đổi chi tiết sản phẩm. Hệ thống tự động phát hiện:

Thêm mới: Detail item có id = 0 hoặc không có id → thêm mới
Cập nhật: Detail item có id > 0 và đã tồn tại → so sánh & cập nhật nếu có thay đổi
Xóa: Detail hiện tại không có trong danh sách request → tự động xóa

Trường	Kiểu	Bắt buộc	Mô tả
`id`	int	Không	ID chi tiết (0 hoặc bỏ trống = thêm mới, > 0 = cập nhật)
`product_variant_id`	int	Có (khi thêm mới)	ID biến thể sản phẩm
`item_name`	string	Không	Tên sản phẩm hiển thị
`uom_id`	int	Không	ID đơn vị tính
`uom_name`	string	Không	Tên đơn vị tính
`uom_factor`	int	Có	Hệ số quy đổi UOM
`uom_quantity`	int	Có	Số lượng theo UOM
`uom_unit_price`	int	Có	Đơn giá theo UOM
`weight_sale_mode`	int	Không	Chế độ bán cân
`weight_preset_id`	string	Không	ID preset cân
`weight_preset_name`	string	Không	Tên preset cân
`weight_preset_factor`	int	Không	Hệ số preset cân
`pricing_type`	int	Không	Loại định giá
`catch_counting`	int	Không	Catch-weight counting

Ví dụ: Cập nhật trạng thái sang Đã duyệt

{
    "company_id": 1,
    "creator_id": 10,
    "status": 5,
    "tag": "approved",
    "note": "Đã xác nhận với NCC"
}

Ví dụ: Hủy PO

{
    "company_id": 1,
    "creator_id": 10,
    "status": 13,
    "cancel_reason": 9
}

Ví dụ: Thay đổi chi tiết sản phẩm

{
    "company_id": 1,
    "creator_id": 10,
    "status": 1,
    "price_sell": 600000,
    "price_final": 630000,
    "details": [
        {
            "id": 100,
            "uom_factor": 1,
            "uom_quantity": 10,
            "uom_unit_price": 120000,
            "weight_sale_mode": 0,
            "weight_preset_id": "",
            "weight_preset_name": "",
            "weight_preset_factor": 0,
            "pricing_type": 0,
            "catch_counting": 0
        },
        {
            "id": 0,
            "product_variant_id": 999,
            "item_name": "Sản phẩm mới",
            "uom_id": 0,
            "uom_name": "Cái",
            "uom_factor": 1,
            "uom_quantity": 3,
            "uom_unit_price": 80000,
            "weight_sale_mode": 0,
            "weight_preset_id": "",
            "weight_preset_name": "",
            "weight_preset_factor": 0,
            "pricing_type": 0,
            "catch_counting": 0
        }
    ]
}

Lưu ý: Trong ví dụ trên, nếu PO hiện tại có 3 detail (id: 100, 101, 102) nhưng request chỉ gửi detail id 100 và 1 item mới → detail id 101 và 102 sẽ bị xóa tự động.

Response Schema

HTTP 200 - OK

Trả về Purchase Order Object sau khi cập nhật.

Quy tắc phân quyền

Hành động	Quyền cần thiết
Sửa nội dung PO (tag, note, detail, giá)	`purchaseorder.edit`
Chuyển trạng thái sang Hoàn thành (11)	`purchaseorder.statuscomplete`
Chuyển trạng thái sang Đã hủy (13)	`purchaseorder.statuscancel`
Thay đổi chi tiết sản phẩm	`purchaseorder.edit` + PO chưa hoàn thành/hủy

Error Codes

Lỗi dữ liệu đầu vào trả về HTTP 422 kèm mảng các mã lỗi:

Mã lỗi	Mô tả
`error_not_found`	(HTTP 404) Đối tượng không tồn tại hoặc không thuộc quyền truy cập của bạn
`error_not_permission`	Không có quyền thực hiện thao tác
`error_status_backward_not_allow`	Không được quay ngược trạng thái
`error_status_complete_not_allow`	Không có quyền chuyển sang trạng thái Hoàn thành
`error_status_cancel_not_allow`	Không có quyền chuyển sang trạng thái Đã hủy
`error_cancel_reason_require`	Hủy PO bắt buộc phải có lý do
`error_cancel_reason_not_exist`	Lý do hủy không hợp lệ
`error_not_permission_edit_detail`	Không có quyền sửa chi tiết sản phẩm
`error_not_allow_change_detail_in_complete_or_cancel_order`	Không được sửa chi tiết khi PO đã Hoàn thành hoặc Đã hủy
`error_details_have_invalid_data_line`	Chi tiết sản phẩm có dữ liệu không hợp lệ
`error_company_id_required`	ID công ty không được để trống
`error_company_id_notfound`	ID công ty không tìm thấy
`error_user1_id_required`	ID người tạo không được để trống
`error_user_id_notfound`	ID người tạo không tìm thấy
`error_delete_order_detail_id{id}` / `error_edit_order_detail_id{id}` / `error_add_order_detail_sku{sku}`	(HTTP 500) Lỗi khi xóa / sửa / thêm chi tiết sản phẩm
`error_edit`	(HTTP 500) Lỗi khi lưu PO

Webhook

Sau khi cập nhật thành công, hệ thống gửi webhook event: purchaseorder.edit

Cập nhật đơn đặt hàng mua

Endpoint

Headers

Path Parameters

Request Body

Thông tin PO chính

Chi tiết sản phẩm (details[])

Ví dụ: Cập nhật trạng thái sang Đã duyệt

Ví dụ: Hủy PO

Ví dụ: Thay đổi chi tiết sản phẩm

Response Schema

HTTP 200 - OK

Quy tắc phân quyền

Error Codes

Webhook

On this page

Cập nhật đơn đặt hàng mua

EndpointCopy Anchor Link

HeadersCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Thông tin PO chínhCopy Anchor Link

Chi tiết sản phẩm (details[])Copy Anchor Link

Ví dụ: Cập nhật trạng thái sang Đã duyệtCopy Anchor Link

Ví dụ: Hủy POCopy Anchor Link

Ví dụ: Thay đổi chi tiết sản phẩmCopy Anchor Link

Response SchemaCopy Anchor Link

HTTP 200 - OKCopy Anchor Link

Quy tắc phân quyềnCopy Anchor Link

Error CodesCopy Anchor Link

WebhookCopy Anchor Link

On this page

Endpoint

Headers

Path Parameters

Request Body

Thông tin PO chính

Chi tiết sản phẩm (details[])

Ví dụ: Cập nhật trạng thái sang Đã duyệt

Ví dụ: Hủy PO

Ví dụ: Thay đổi chi tiết sản phẩm

Response Schema

HTTP 200 - OK

Quy tắc phân quyền

Error Codes

Webhook