API FMCustomers/Create — dùng để thêm khách mời vào một sự kiện (Event) có sẵn trong hệ thống.

1. Tóm tắt nhanh

1. Lấy ID sự kiện của sự kiện muốn thêm khách — đây chính là key.
2. Gửi request POST dạng form-data tới /FMCustomers/Create, tối thiểu có key và FullName.
3. Muốn khách check-in bằng khuôn mặt thì gửi thêm image (ảnh chân dung) và CheckInFace=1.
4. Xem field isSuccess trong kết quả: true là tạo thành công, false thì đọc message để biết lỗi.

2. Key là gì?

key chính là ID sự kiện mà bạn muốn thêm khách vào (xem ở màn hình Event). Nó vừa dùng để xác thực, vừa để biết khách thuộc sự kiện nào.

Hệ thống sẽ kiểm tra:

• key có đúng định dạng GUID không (vd: 3fa85f64-5717-4562-b3fc-2c963f66baa6).
• Sự kiện đó có tồn tại và đang được bật (chưa bị vô hiệu hoá) không.

Nếu một trong hai điều trên không đạt → API báo lỗi và không tạo khách.

3. Các trường dữ liệu gửi lên

Trường bắt buộc

Trường tuỳ chọn (có thể bỏ trống)

Trường KHÔNG cần gửi

4. Mã khách & Số may rủi được sinh thế nào

Mã khách (Code)

Luôn do hệ thống tự sinh: một chuỗi ngẫu nhiên 20 ký tự (lấy từ GUID bỏ dấu gạch ngang), ví dụ 25ada1d56ef04200976c. Client không điền được.

Số may rủi (LuckyDraw)

5. Quy tắc chống trùng

Hệ thống chỉ kiểm tra trùng theo Số điện thoại, và chỉ trong cùng một sự kiện.

6. Ảnh và Check-in bằng khuôn mặt

Khi có gửi ảnh (image)

• Ảnh được lưu chung với hệ thống Portal.FaceMatching, đặt tên theo mã khách: /Content/{TaskId}/FaceID/{Code}.png
• Kết quả trả về sẽ có imageUrl là link đầy đủ, mở được ngay, ví dụ:
  https://facematching.aievent.vn/Content/{TaskId}/FaceID/{Code}.png

Không gửi ảnh → imageUrl là chuỗi rỗng "".

Khi bật CheckInFace=1

• Hệ thống đăng ký khuôn mặt trong ảnh lên AWS Rekognition để dùng khi check-in.
• Nếu ảnh có nhiều người, chỉ giữ khuôn mặt lớn nhất.

7. Ví dụ gọi API

Ví dụ tối thiểu

curl -X POST "https://<host-api-portal>/FMCustomers/Create" \
  -F "key=3fa85f64-5717-4562-b3fc-2c963f66baa6" \
  -F "FullName=Nguyễn Văn A"

Ví dụ đầy đủ (có ảnh + check-in khuôn mặt)

curl -X POST "https://<host-api-portal>/FMCustomers/Create" \
  -F "key=3fa85f64-5717-4562-b3fc-2c963f66baa6" \
  -F "FullName=Nguyễn Văn A" \
  -F "DearName=Anh" \
  -F "Email=nguyenvana@example.com" \
  -F "Phone=0909123456" \
  -F "Company=Công ty ABC" \
  -F "JobPosition=Trưởng phòng" \
  -F "MemberGroup=VIP" \
  -F "CheckInFace=1" \
  -F "image=@/duong/dan/anh.jpg"

Ví dụ JavaScript (fetch)

const form = new FormData();
form.append("key", "3fa85f64-5717-4562-b3fc-2c963f66baa6");
form.append("FullName", "Nguyễn Văn A");
form.append("Phone", "0909123456");
form.append("CheckInFace", "1");
form.append("image", fileInput.files[0]); // file ảnh từ <input type="file">

// Không tự set header Content-Type, trình duyệt sẽ tự thêm boundary
const res = await fetch("https://<host-api-portal>/FMCustomers/Create", {
  method: "POST",
  body: form
});
const data = await res.json();

if (data.isSuccess) {
  console.log("Tạo thành công. Mã khách:", data.result.code,
              "- Số may rủi:", data.result.luckyDraw);
} else {
  console.error("Lỗi:", data.message);
}

8. Đọc kết quả trả về

Mọi kết quả đều có 4 field: statusCode, message, isSuccess, result.

✅ Thành công

{
  "statusCode": 200,
  "message": "",
  "isSuccess": true,
  "result": {
    "id": 123,
    "taskId": "3fa85f64-5717-4562-b3fc-2c963f66baa6",
    "code": "25ada1d56ef04200976c",    // mã khách, hệ thống tự sinh
    "luckyDraw": "482",               // số may rủi (3 hoặc 4 chữ số)
    "fullName": "Nguyễn Văn A",
    "email": "nguyenvana@example.com",
    "phone": "0909123456",
    "imageUrl": "https://facematching.aievent.vn/Content/3fa85f64-.../FaceID/25ada1d56ef04200976c.png",
    ...
    "checkInFace": "1"
  }
}

❌ Thất bại

{
  "statusCode": 500,
  "message": "Key không hợp lệ hoặc sự kiện không tồn tại",
  "isSuccess": false,
  "result": null
}

9. Các lỗi thường gặp & cách xử lý