Trừ điểm thủ công

Tạo giao dịch trừ điểm tích lũy cho khách hàng bằng thao tác thủ công.

Endpoint

POST /v1/loyaltypointredeems

Quyền: customerpoint.manage

Workflow & Logic

Validate khách hàng và số điểm: Kiểm tra khách hàng tồn tại, thuộc đúng công ty, số điểm trừ > 0.
Kiểm tra số dư: So sánh points_redeemed với tổng điểm khả dụng (points_remaining còn hạn).
Trừ theo FIFO: Lấy các lô tích điểm chưa hết hạn, ưu tiên lô sắp hết hạn trước.
Ghi giao dịch: Tạo LoyaltyPointRedeem và các bản ghi LoyaltyPointRedeemDetail.
Cập nhật lô tích: Giảm points_remaining trên từng lô LoyaltyPointEarn bị ảnh hưởng.
Cập nhật thống kê khách hàng.

Body Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`creator_id`	int	Có	ID người tạo
`customer_id`	int	Có	ID khách hàng bị trừ điểm
`points_redeemed`	int	Có	Số điểm cần trừ (> 0)
`points_value`	int		Giá trị quy đổi ra tiền (VND). Mặc định: `0`
`source_id`	int		ID nguồn phát sinh. Dùng để chống trùng khi tạo lại
`external_id`	string		Mã tham chiếu ngoài hệ thống
`note`	string		Ghi chú

Lưu ý:

Giao dịch tạo thủ công sẽ có type = TYPE_DEFAULT, mode = MODE_MANUAL.

company_id được lấy từ phiên đăng nhập hiện tại.

Nếu truyền source_id > 0, hệ thống kiểm tra trùng giao dịch thủ công cùng customer_id + source_id.

Request Payload

{
  "creator_id": 1,
  "customer_id": 8801,
  "points_redeemed": 100,
  "points_value": 100000,
  "source_id": 0,
  "external_id": "MANUAL-2026-001",
  "note": "Trừ điểm đổi quà tại quầy"
}

Response Schema

HTTP 200 - JSON Object

Trả về object kết quả xử lý FIFO. Xem mục Response khi tạo mới (POST) trong LoyaltyPointRedeem Object Schema.

{
  "customer_available_points": 450,
  "redeem_points": 100,
  "redeem_id": 902,
  "redeem_details": [
    {
      "earn_id": 1201,
      "used": 80
    },
    {
      "earn_id": 1205,
      "used": 20
    }
  ],
  "updated_batches": [
    {
      "id": 1201,
      "point_remaining": 0
    },
    {
      "id": 1205,
      "point_remaining": 130
    }
  ],
  "ledger": []
}

Error Codes

HTTP	Code	Mô tả
422	`error_creator_id_required`	Thiếu ID người tạo
422	`error_customer_id_required`	Thiếu ID khách hàng
422	`error_customer_notfound`	Không tìm thấy khách hàng
422	`error_customer_company_mismatch`	Khách hàng không thuộc công ty hiện tại
422	`error_points_redeemed_required`	Số điểm trừ phải lớn hơn 0
422	`error_points_redeemed_must_be_positive`	Số điểm trừ không hợp lệ
422	`error_redeem_points_exceeds_available_points`	Số điểm trừ vượt quá điểm khả dụng
422	`error_points_value_invalid`	Giá trị quy đổi không hợp lệ (< 0)
422	`error_source_id_invalid`	ID nguồn không hợp lệ
422	`error_redeem_already_processed`	Giao dịch với `source_id` này đã được xử lý
422	`error_user_id_notfound`	ID người tạo không hợp lệ