Chấm công bằng khuôn mặt — camera TingPush làm máy chấm công

Camera TingPush nhận diện khuôn mặt nhân viên ngay trên chip của camera và ghi lại giờ đến / giờ về, giống máy chấm công khuôn mặt. Mỗi lần chấm công thành công, camera gửi một bản ghi đi giống hệt cách gửi biển số:

Lưu trên TingPush (thuê lưu trữ, mặc định): xem ai đã đến, bảng công theo tháng, xuất Excel (CSV) trên web webrtc.tingpush.com, app TingPush Camera, phần mềm Windows; phần mềm nhân sự / tính lương lấy về qua API.
API riêng: camera gửi thẳng bản ghi về máy chủ của bạn, cùng URL đang nhận biển số.

Nhận diện chạy trên camera nên mất mạng camera vẫn chấm công; bản ghi nằm trong hàng đợi trên camera và tự gửi bù khi có mạng lại.

1. Chuẩn bị

Cần	Ghi chú
Gói dịch vụ có Chấm công	Gói mặc định đã có. Thời gian lưu bản ghi chấm công theo gói (mặc định 400 ngày).
Phần mềm camera có chấm công	Bản 10/2026 trở đi. Trang Chấm công → Ca làm việc & camera báo "Phần mềm camera chưa có chấm công" nếu camera cần cập nhật.
Model khuôn mặt trên camera	Có sẵn trong phần mềm camera (phát hiện mặt YuNet, nhận diện SFace — chạy trên NPU).
Bạn là chủ camera	Chỉ chủ camera mới bật chấm công và nạp ảnh nhân viên vào camera.

Lắp camera

Đặt ở cửa ra vào / lối đi, nơi mọi người đi chậm lại hoặc dừng (cửa, cổng từ, quầy lễ tân).
Cao 1,6 – 2,2 m, chúc xuống nhẹ (≤ 15°) để thấy chính diện khuôn mặt. Camera đặt quá cao chỉ thấy đỉnh đầu.
Người đứng cách camera 1 – 3 m; mặt phải đủ lớn trên hình (mặc định ≥ 60 điểm ảnh chiều ngang trên khung phân tích).
Tránh ngược sáng (cửa kính, nắng phía sau người) — mặt tối sẽ không nhận được. Buổi tối cần đèn chiếu vào mặt.
Có thể dùng chung camera đọc biển số nếu góc nhìn thấy rõ mặt người, nhưng camera riêng cho cửa người đi bộ cho kết quả tốt nhất.

2. Đăng ký nhân viên (ảnh khuôn mặt)

Nhân viên là người trong thư viện khuôn mặt có thêm mã nhân viên và phòng ban. Thêm ở một trong các nơi:

Web: menu Nhân viên (webrtc.tingpush.com/employees).
App TingPush Camera: Tài khoản → Nhân viên & khuôn mặt (chụp ảnh ngay bằng điện thoại được).
Phần mềm Windows: mục Nhân viên.
Phần mềm nhân sự của bạn: POST /api/v1/employees (mục 7).

Mỗi người cần:

Trường	Bắt buộc	Ghi chú
Ảnh chân dung	✔	JPEG, tối đa 4 MB. Nhìn thẳng, đủ sáng, mặt chiếm phần lớn ảnh (như ảnh thẻ), không đeo khẩu trang / kính râm.
Họ tên	✔	Tối đa 60 ký tự.
Mã nhân viên		Tối đa 24 ký tự, không trùng trong tài khoản. Gửi kèm mỗi bản ghi chấm công (`employee_code`) để khớp với phần mềm tính lương.
Phòng ban		Lọc bảng công theo phòng ban.
Camera		Camera nhận diện người này. Máy chấm công: bấm Nạp tất cả để nạp cả danh sách vào một camera.

Sau khi lưu, máy chủ gửi ảnh xuống từng camera đã chọn; camera tự tính đặc trưng khuôn mặt từ ảnh (ảnh không cần gửi lại mỗi lần chấm). Trạng thái từng camera:

xanh / đã nhận — camera đã học khuôn mặt.
chờ — camera đang mất kết nối; máy chủ tự nạp khi camera online lại.
lỗi — thường là "không thấy khuôn mặt trong ảnh" hoặc ảnh quá mờ → Sửa → chọn ảnh khác.

Mỗi camera nhớ tối đa 3000 người. Đổi tên / mã / phòng ban không cần nạp lại ảnh; đổi ảnh thì máy chủ nạp lại tự động. Xóa nhân viên: camera thôi nhận diện người đó, lịch sử chấm công vẫn giữ.

3. Bật chấm công trên camera

Web: Chấm công → tab Cài đặt (app: Chấm công → Ca làm việc & camera; Windows: Chấm công → Ca làm việc & camera). Với từng camera:

Cài đặt	Mặc định	Ý nghĩa
Bật chấm công	tắt	Camera bắt đầu nhận diện và ghi chấm công.
Mỗi người chấm lại sau	60 giây	Đứng lâu trước camera chỉ ghi 1 lần; sau thời gian này đi qua lại mới ghi lần nữa. Đặt 15–30 phút nếu nhân viên hay đi qua lại cửa.
Độ giống tối thiểu	42 %	Điểm giống (cosine × 100) để coi là đúng người. Cao hơn = khó nhận nhầm nhưng có thể phải đứng lâu hơn; thấp hơn = dễ nhận nhưng tăng nguy cơ nhầm người giống nhau. Khoảng hợp lý 38–55.
Ảnh gửi kèm	ảnh mặt	Không ảnh / ảnh mặt (cắt quanh khuôn mặt, ~10–30 KB) / mặt + toàn cảnh. Ảnh giúp kiểm tra khi có khiếu nại.

Cài đặt nằm trong file /userdata/lpr/ai.conf của camera (lập trình viên / người lắp đặt):

attendance.enable=1
attendance.cooldown_s=60     ; chấm lại sau (giây)
attendance.confirm=2         ; số khung hình liên tiếp phải nhận ra cùng người (trong 3 giây)
attendance.min_face=60       ; chiều ngang mặt tối thiểu (điểm ảnh) — mặt nhỏ hơn bị bỏ qua
attendance.image=1           ; 0 không ảnh, 1 ảnh mặt, 2 ảnh mặt + toàn cảnh
attendance.schedule=         ; giờ hoạt động (trống = cả ngày), cú pháp như các tính năng AI khác
attendance.days=127          ; ngày trong tuần (bit 0 = CN)
face.threshold=42            ; độ giống tối thiểu (dùng chung với nhận diện khuôn mặt)

Camera ghi nhận thế nào

Phát hiện khuôn mặt trong khung hình (tối đa 3 mặt mỗi lần, ưu tiên mặt lớn nhất).
Bỏ qua mặt nghiêng quá, quá nhỏ hoặc mờ (cổng chất lượng) — tránh nhận nhầm.
So với thư viện; đúng một người ≥ độ giống tối thiểu trong 2 khung hình (mặc định) liên tiếp → chấm công.
Ghi bản ghi vào hàng đợi trên camera (lưu cả khi mất điện), gửi đi, rồi chặn người đó trong thời gian chấm lại.

Nhân viên chỉ cần nhìn thẳng vào camera 1–2 giây. Trang cấu hình web của camera (tab Trạng thái) có thẻ Chấm công gần đây để người lắp đặt thử tại chỗ.

Giới hạn: camera không chống giả mạo bằng ảnh / màn hình điện thoại (chưa có kiểm tra người thật). Nên đặt camera ở nơi có người qua lại / có camera giám sát, và xem ảnh kèm theo khi nghi ngờ. Khẩu trang, kính râm, mũ sụp làm giảm khả năng nhận diện.

4. Lưu trên TingPush — xem, bảng công, xuất file

Trang Chấm công (web, app, Windows):

Hôm nay: ai đã đến, giờ vào / ra, ai đi muộn, ai chưa chấm — cập nhật ngay khi camera gửi.
Bảng công: theo tháng / khoảng ngày, lọc phòng ban; mỗi người: số công, giờ làm, số lần muộn / sớm, số ngày vắng; bấm vào một người xem từng ngày.
Lịch sử: từng lần chấm kèm ảnh mặt, camera, độ giống; lọc theo người.
Chấm bổ sung: thêm tay khi nhân viên quên chấm / camera mất điện — bắt buộc ghi lý do, bản ghi đánh dấu "bổ sung tay" kèm tên người thêm.
Xuất CSV (mở được bằng Excel, mã UTF-8 có BOM): bảng công (mỗi người mỗi ngày một dòng + dòng tổng) hoặc danh sách lần chấm.

Cách tính công

Đặt ở Chấm công → Cài đặt → Ca làm việc (một ca chung cho tài khoản):

Cài đặt	Mặc định
Giờ vào ca / hết ca	08:00 / 17:00	Ca qua đêm được (VD 22:00 → 06:00).
Cho phép đến muộn / về sớm	5 / 5 phút	Trong ngần ấy phút vẫn tính đúng giờ.
Nghỉ giữa ca	60 phút	Trừ khỏi giờ làm khi làm quá 5 giờ.
Ngày làm việc	T2 – T6	Ngày khác: chấm vẫn ghi nhưng không tính muộn / sớm / vắng.
Giờ chuyển ngày công	04:00	Chấm trước giờ này tính cho hôm trước (ca đêm về lúc 02:00 vẫn thuộc ngày hôm trước).

Trong một ngày công:

Lần chấm đầu = giờ vào, lần chấm cuối = giờ ra (các lần giữa bỏ qua).
Có cả vào và ra → 1 công; chỉ một lần chấm → ½ công, trạng thái Thiếu chấm ra (hôm nay: Đang làm).
Muộn = giờ vào − giờ vào ca (nếu vượt mức cho phép); sớm = giờ hết ca − giờ ra.
Ngày làm việc không có lần chấm nào → Vắng.

Cần ca phức tạp hơn (nhiều ca, xoay ca, tăng ca)? Lấy danh sách lần chấm qua API (mục 7) rồi tính trong phần mềm nhân sự của bạn.

5. Gửi về API riêng

Khi camera đặt Nơi nhận dữ liệu = API riêng (app → Cài đặt camera → Gửi dữ liệu biển số), bản ghi chấm công gửi tới cùng URL, cùng header xác thực, cùng hàng đợi với biển số — phân biệt bằng "type": "attendance". Toàn bộ quy tắc trả lời camera (2xx / 4xx / 5xx), bỏ bản trùng theo event_id, dung lượng… giống hệt Hướng dẫn viết API nhận kết quả đọc biển số từ camera TingPush.

{
  "event_id": "LPR-9MHK902C8J5Z-1792114200-000043",
  "type": "attendance",
  "device_id": "CUA-VAN-PHONG",
  "camera_id": "LPR-9MHK902C8J5Z",
  "time": "2026-10-16T07:58:12+07:00",
  "timestamp": 1792114692,
  "person_id": "22152868dc7d49d4",
  "employee_code": "NV001",
  "name": "Nguyễn Văn A",
  "similarity": 0.713,
  "box": [1610, 520, 1790, 745],
  "frame_width": 3840,
  "frame_height": 2160,
  "face_image_type": "jpeg",
  "face_image": "/9j/4AAQSkZJRgABAQ..."
}

Trường	Kiểu	Luôn có	Ý nghĩa
`event_id`	string	✔	Mã duy nhất của lần chấm — khóa UNIQUE để bỏ bản trùng (camera gửi lại cùng mã khi mất trả lời).
`type`	string	✔	Luôn `"attendance"`. API chỉ nhận biển số thì trả 200 và bỏ qua bản ghi có `type` khác `plate` (trả 4xx camera cũng bỏ, nhưng log sẽ báo lỗi).
`camera_id`, `device_id`	string	✔	Như bản ghi biển số.
`time`, `timestamp`	string, int	✔	Thời điểm chấm (ISO 8601 có múi giờ; giây UNIX — nên dùng).
`person_id`	string	✔	Mã nhân viên do TingPush cấp (không đổi khi sửa tên / mã NV).
`employee_code`	string	✔	Mã nhân viên bạn đặt; chuỗi rỗng nếu chưa đặt. Dùng để khớp với phần mềm nhân sự.
`name`	string	✔	Họ tên lúc chấm.
`similarity`	number	✔	Độ giống 0–1 (≥ ngưỡng cài đặt).
`box`	int[4]	✔	Vị trí khuôn mặt `[x1, y1, x2, y2]` trên khung `frame_width` × `frame_height`.
`face_image`	string	khi bật	Ảnh mặt JPEG base64 (cắt quanh khuôn mặt), `face_image_type` = `"jpeg"`.
`image`	string	khi bật	Ảnh toàn cảnh JPEG base64, `image_type` = `"jpeg"`.

Lưu ý:

Danh sách nhân viên và ảnh vẫn quản lý trên TingPush (camera tải ảnh từ máy chủ TingPush) — chỉ bản ghi chấm công đi về API của bạn. Đồng bộ nhân viên từ phần mềm nhân sự: dùng API /api/v1/employees (mục 7).
Camera không gửi lần chấm "vào" / "ra" riêng — mỗi bản ghi là một lần nhìn thấy; bạn tự quy ước (VD lần đầu = vào, lần cuối = ra như TingPush).

6. Mở cửa khi chấm công thành công

Thiết bị ngoại vi (khóa cửa từ, cổng xoay, còi, đèn) có sự kiện kích hoạt Chấm công thành công (attend_ok): Cài đặt camera → Thiết bị ngoại vi → Luật tự động: Khi = Chấm công thành công, Thì = mở khóa cửa (xung). Luật chạy trên camera, mất mạng vẫn mở. Xem Thiết bị ngoại vi — mở barie, cửa cuốn, còi, đèn từ camera TingPush.

7. API công khai (khóa API)

Cùng khóa API và cách gọi với Hướng dẫn API công khai TingPush — lấy dữ liệu biển số đã lưu (X-Api-Key: tp_…). Thêm / sửa / xóa nhân viên cần khóa có quyền "Điều khiển thiết bị & sửa danh sách xe".

`GET /api/v1/attendance` — các lần chấm công

Tham số
`since_id`	Lấy bản ghi có `id` > giá trị này, cũ trước — dùng để đồng bộ dần (lưu `next_since_id` cho lần sau).
`before_id`	Trang tiếp khi duyệt mới → cũ.
`from`, `to`	Khoảng thời gian (ISO 8601).
`camera`, `person`	Lọc theo camera / `person_id`.
`limit`	1–1000, mặc định 100.

{
  "data": [
    {
      "id": 1842, "camera_id": "LPR-9MHK902C8J5Z", "camera_name": "Cửa văn phòng", "person_id": "22152868dc7d49d4",
      "employee_code": "NV001", "name": "Nguyễn Văn A", "department": "Kế toán",
      "time": "2026-10-16T07:58:12+07:00", "timestamp": 1792114692, "received_at": "2026-10-16T07:58:13+07:00",
      "similarity": 0.713, "source": "camera", "note": null,
      "face_image_url": "https://apiwebrtc.tingpush.com/api/v1/attendance/1842/image/face", "image_url": null
    }
  ],
  "next_since_id": 1842,
  "has_more": false
}

source = camera hoặc manual (chấm bổ sung tay, note là lý do). Ảnh: face_image_url (ảnh mặt), image_url (toàn cảnh, khi camera gửi và gói cho lưu) = GET /api/v1/attendance/{id}/image/face|scene, tải bằng cùng header khóa API; null = không có ảnh.

`GET /api/v1/attendance/timesheet?from=2026-10-01&to=2026-10-31&department=…` — bảng công

Tối đa 62 ngày. Trả shift (ca làm việc) và data[]: mỗi người person_id, employee_code, name, department, total (credit, late_count, late_min, early_count, early_min, work_min, absent) và days[] (date, first, last, count, late_min, early_min, work_min, credit, status).

Nhân viên


`GET /api/v1/employees`	Danh sách: `id`, `code`, `name`, `department`, `note`, `photo_url`, `cameras[]` (`id`, `state` = ok / pending / error, `message`).
`GET /api/v1/employees/{id}/photo`	Ảnh chân dung đã đăng ký (JPEG).
`POST /api/v1/employees`	Thêm: `{"name":"…","code":"NV002","department":"Kho","note":null,"photo":"<JPEG base64>","cameras":["LPR-…"]}`.
`PUT /api/v1/employees/{id}`	Sửa — chỉ gửi trường cần đổi; có `photo` = đổi ảnh; có `cameras` = đặt lại danh sách camera.
`DELETE /api/v1/employees/{id}`	Xóa (lịch sử chấm công vẫn giữ).

Thêm nhân viên chờ camera nạp ảnh (vài giây mỗi camera) — kiểm tra cameras[].state trong kết quả; error kèm message (VD không thấy khuôn mặt) thì gửi lại ảnh khác.

8. Dữ liệu cá nhân

Ảnh khuôn mặt và đặc trưng khuôn mặt là dữ liệu sinh trắc học — dữ liệu cá nhân nhạy cảm theo quy định bảo vệ dữ liệu cá nhân của Việt Nam (Nghị định 13/2023/NĐ-CP và Luật Bảo vệ dữ liệu cá nhân). Doanh nghiệp dùng chấm công khuôn mặt cần:

Thông báo và lấy đồng ý của nhân viên trước khi đăng ký ảnh (VD điều khoản trong hợp đồng / phiếu đồng ý), có phương án chấm công khác cho người không đồng ý.
Chỉ dùng cho mục đích chấm công / ra vào đã thông báo; xóa nhân viên khi nghỉ việc (camera xóa đặc trưng ngay).
Đặt thời hạn lưu phù hợp (gói dịch vụ tự xóa bản ghi và ảnh quá hạn) và giới hạn người được xem.

TingPush lưu ảnh trên máy chủ để camera tải về; đặc trưng khuôn mặt chỉ nằm trên camera. Xóa tài khoản sẽ xóa toàn bộ nhân viên, ảnh và lịch sử chấm công.

9. Lỗi thường gặp

Hiện tượng	Cách xử lý
Camera báo lỗi khi nạp ảnh	Ảnh không thấy mặt / mặt quá nhỏ / quá tối → chụp lại ảnh thẻ rõ mặt.
Đứng trước camera không chấm	Kiểm tra: đã bật chấm công? người đã đã nhận trên camera đó? mặt đủ lớn, không ngược sáng, nhìn thẳng? Model khuôn mặt chưa sẵn sàng → khởi động lại / cập nhật phần mềm camera.
Nhận nhầm người	Tăng Độ giống tối thiểu (VD 48–55), thay ảnh đăng ký rõ hơn cho cả hai người.
Phải đứng lâu mới chấm	Giảm Độ giống tối thiểu một chút (≥ 38), cải thiện ánh sáng, chỉnh camera thấp hơn.
Bảng công thiếu giờ ra	Nhân viên chỉ chấm một lần — dùng Chấm bổ sung, hoặc tăng chấm lại sau để tránh ghi nhiều lần khi đi qua lại.
Ca đêm bị tách 2 ngày	Đặt Giờ chuyển ngày công sau giờ về của ca đêm (VD về 06:00 → đặt 08:00 nếu ca ngày vào sau 08:00).