FAQ, SDK và chi phí
Các câu hỏi thường gặp từ đơn vị tích hợp, cùng cách SDK và giá API hoạt động.
Thông tin bổ sung
Câu hỏi thường gặp
Các câu hỏi thường gặp về việc tích hợp với Cams Biometrics Web API 3.0.
Chung
Hỏi: Cams Biometric Gateway và Biometric API của nó là gì?
Cams Biometric Gateway là nền tảng đám mây phổ quát cung cấp Biometric API, cho phép mọi ứng dụng web giao tiếp với các thiết bị chấm công và kiểm soát ra vào sinh trắc học theo thời gian thực. Nền tảng hỗ trợ 38 thao tác thuộc Callback API (chiều vào) và RESTful API (chiều ra) — không cần SDK thiết bị hay IP tĩnh.
Cams Biometric Gateway là nền tảng đám mây phổ quát cung cấp Biometric API, cho phép mọi ứng dụng web giao tiếp với các thiết bị chấm công và kiểm soát ra vào sinh trắc học theo thời gian thực. Nền tảng hỗ trợ 38 thao tác thuộc Callback API (chiều vào) và RESTful API (chiều ra) — không cần SDK thiết bị hay IP tĩnh.
Hỏi: Tôi có cần SDK để tích hợp không?
Không. Cams không cung cấp và cũng không yêu cầu SDK. Mọi giao tiếp đều dùng yêu cầu HTTP/HTTPS POST tiêu chuẩn với payload JSON. Bất kỳ ngôn ngữ nào có thể gọi HTTP đều dùng được.
Không. Cams không cung cấp và cũng không yêu cầu SDK. Mọi giao tiếp đều dùng yêu cầu HTTP/HTTPS POST tiêu chuẩn với payload JSON. Bất kỳ ngôn ngữ nào có thể gọi HTTP đều dùng được.
Hỏi: Hỗ trợ những ngôn ngữ lập trình nào?
Bất kỳ ngôn ngữ nào có thể gửi/nhận HTTP POST với JSON — PHP, Python, Java, C#, Node.js, Go, Ruby và nhiều ngôn ngữ khác. Chúng tôi cung cấp prompt tạo mã bằng AI cho 7 ngôn ngữ.
Bất kỳ ngôn ngữ nào có thể gửi/nhận HTTP POST với JSON — PHP, Python, Java, C#, Node.js, Go, Ruby và nhiều ngôn ngữ khác. Chúng tôi cung cấp prompt tạo mã bằng AI cho 7 ngôn ngữ.
Hỏi: Cams Protocol Engine là gì?
Đó là middleware đám mây nằm giữa các thiết bị sinh trắc học và máy chủ của bạn. Nó xử lý chuyển đổi giao thức, chuẩn hóa dữ liệu, bộ nhớ đệm ngoại tuyến, và cung cấp JSON API nhất quán bất kể thương hiệu hay model thiết bị bên dưới.
Đó là middleware đám mây nằm giữa các thiết bị sinh trắc học và máy chủ của bạn. Nó xử lý chuyển đổi giao thức, chuẩn hóa dữ liệu, bộ nhớ đệm ngoại tuyến, và cung cấp JSON API nhất quán bất kể thương hiệu hay model thiết bị bên dưới.
Hỏi: API Monitor là gì?
API Monitor là cổng quản trị nơi bạn cấu hình Callback URL, quản lý AuthToken, đặt Security Key, xem trạng thái thiết bị và truy cập URL endpoint RESTful cùng các Service Tag ID của mình.
API Monitor là cổng quản trị nơi bạn cấu hình Callback URL, quản lý AuthToken, đặt Security Key, xem trạng thái thiết bị và truy cập URL endpoint RESTful cùng các Service Tag ID của mình.
Tương thích thiết bị
Hỏi: Hỗ trợ những thiết bị sinh trắc học nào?
Tất cả thiết bị Cams Biometrics (liệt kê tại camsbiometrics.com/product) đều hỗ trợ API đầy đủ với Native Push. Các thiết bị đã được xác minh tại developer.camsbiometrics.com cũng được hỗ trợ Native Push đầy đủ.
Tất cả thiết bị Cams Biometrics (liệt kê tại camsbiometrics.com/product) đều hỗ trợ API đầy đủ với Native Push. Các thiết bị đã được xác minh tại developer.camsbiometrics.com cũng được hỗ trợ Native Push đầy đủ.
Hỏi: Thiết bị không phải của Cams (ZkTeco, eSSL, BioMax, v.v.) có dùng được API này không?
Có, với Protocol Update. Thiết bị không phải của Cams và chưa được xác minh hoạt động qua Hybrid Push. Một số tính năng có thể bị hạn chế tùy theo chế độ kết nối và khả năng phần cứng.
Có, với Protocol Update. Thiết bị không phải của Cams và chưa được xác minh hoạt động qua Hybrid Push. Một số tính năng có thể bị hạn chế tùy theo chế độ kết nối và khả năng phần cứng.
Hỏi: Native Push và Hybrid Push khác nhau thế nào?
Native Push: Hỗ trợ API đầy đủ, không giới hạn — cả 38 thao tác đều hoạt động. Dành cho thiết bị Cams và thiết bị đã xác minh.
Hybrid Push: Dành cho thiết bị không phải của Cams/chưa được xác minh. Tính năng khả dụng phụ thuộc vào chế độ giao tiếp (SDK, DB Pull hoặc File Processing). Xem Chế độ kết nối.
Native Push: Hỗ trợ API đầy đủ, không giới hạn — cả 38 thao tác đều hoạt động. Dành cho thiết bị Cams và thiết bị đã xác minh.
Hybrid Push: Dành cho thiết bị không phải của Cams/chưa được xác minh. Tính năng khả dụng phụ thuộc vào chế độ giao tiếp (SDK, DB Pull hoặc File Processing). Xem Chế độ kết nối.
Hỏi: Hỗ trợ những phương thức sinh trắc học nào?
Vân tay, nhận diện khuôn mặt, tĩnh mạch lòng bàn tay, thẻ RFID/thẻ cảm ứng, PIN/mật khẩu dạng số, quét mống mắt và đo thân nhiệt (tùy thiết bị).
Vân tay, nhận diện khuôn mặt, tĩnh mạch lòng bàn tay, thẻ RFID/thẻ cảm ứng, PIN/mật khẩu dạng số, quét mống mắt và đo thân nhiệt (tùy thiết bị).
Hỏi: Một số tính năng API không hoạt động với thiết bị của tôi. Tại sao?
Điều này phụ thuộc vào (a) chế độ kết nối — chế độ DB Pull và File Processing chỉ hỗ trợ đẩy dữ liệu chấm công, không hỗ trợ RESTful API, và (b) giới hạn phần cứng — một số model thiết bị có thể không hỗ trợ các tính năng cụ thể ở cấp firmware. Hãy kiểm thử với phần cứng của bạn và liên hệ bộ phận hỗ trợ Cams để được trợ giúp.
Điều này phụ thuộc vào (a) chế độ kết nối — chế độ DB Pull và File Processing chỉ hỗ trợ đẩy dữ liệu chấm công, không hỗ trợ RESTful API, và (b) giới hạn phần cứng — một số model thiết bị có thể không hỗ trợ các tính năng cụ thể ở cấp firmware. Hãy kiểm thử với phần cứng của bạn và liên hệ bộ phận hỗ trợ Cams để được trợ giúp.
Callback API (Thiết bị → Máy chủ)
Hỏi: Callback API là gì?
Callback API chuyển các sự kiện thời gian thực từ thiết bị sinh trắc học đến máy chủ của bạn. Khi có lượt chấm công hoặc người dùng được sửa đổi trên thiết bị, Cams Protocol Engine lập tức POST một payload JSON đến Callback URL bạn đã cấu hình.
Callback API chuyển các sự kiện thời gian thực từ thiết bị sinh trắc học đến máy chủ của bạn. Khi có lượt chấm công hoặc người dùng được sửa đổi trên thiết bị, Cams Protocol Engine lập tức POST một payload JSON đến Callback URL bạn đã cấu hình.
Hỏi: Máy chủ của tôi phải phản hồi như thế nào?
Luôn trả về
Luôn trả về
{"status":"done"} với HTTP status 200 — ngay cả khi xử lý nội bộ của bạn thất bại. Không bao giờ chặn Cams Protocol Engine. Hãy đưa các tác vụ xử lý nặng vào hàng đợi để thực thi bất đồng bộ.Hỏi: Điều gì xảy ra nếu máy chủ của tôi ngoại tuyến khi có lượt chấm công?
Biometric Gateway lưu đệm mọi sự kiện và tự động chuyển đi khi máy chủ của bạn trực tuyến trở lại. Không mất dữ liệu.
Biometric Gateway lưu đệm mọi sự kiện và tự động chuyển đi khi máy chủ của bạn trực tuyến trở lại. Không mất dữ liệu.
Hỏi: Làm sao xử lý các lượt chấm công trùng lặp?
Hãy triển khai logic phát hiện trùng lặp trên máy chủ của bạn bằng tổ hợp
Hãy triển khai logic phát hiện trùng lặp trên máy chủ của bạn bằng tổ hợp
UserID + LogTime. Cùng một lượt chấm công có thể được gửi lại khi khôi phục sau ngoại tuyến hoặc khi mạng thử lại.Hỏi: Hỗ trợ những loại chấm công nào?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. Trường InputType cho biết phương thức sinh trắc học đã dùng: Fingerprint, Face, Palm, Card hoặc Password.Hỏi: Template người dùng hoạt động thế nào trong Callback?
Khi người dùng được cập nhật trên thiết bị (thao tác #3–#9), các template có thể đến từng cái một hoặc theo nhóm qua nhiều callback. Mỗi callback chỉ mang các template đã thay đổi — không phải toàn bộ. Máy chủ của bạn phải merge/upsert theo
Khi người dùng được cập nhật trên thiết bị (thao tác #3–#9), các template có thể đến từng cái một hoặc theo nhóm qua nhiều callback. Mỗi callback chỉ mang các template đã thay đổi — không phải toàn bộ. Máy chủ của bạn phải merge/upsert theo
Type + Index làm khóa duy nhất. Không bao giờ ghi đè toàn bộ template trong một callback.Hỏi: Tôi có thể nhận ảnh chấm công không?
Có. Thao tác #10 RealTimeAttendancePhoto gửi ảnh chụp JPEG mã hóa Base64 được chụp tại thời điểm chấm công. Thao tác này tách biệt với callback log chấm công (#11) và khả dụng trên thiết bị có hỗ trợ camera.
Có. Thao tác #10 RealTimeAttendancePhoto gửi ảnh chụp JPEG mã hóa Base64 được chụp tại thời điểm chấm công. Thao tác này tách biệt với callback log chấm công (#11) và khả dụng trên thiết bị có hỗ trợ camera.
Hỏi: Callback có bao gồm nhiệt độ và phát hiện khẩu trang không?
Có, nếu thiết bị hỗ trợ. Đối tượng
Có, nếu thiết bị hỗ trợ. Đối tượng
PunchLog bao gồm Temperature (số đo thân nhiệt) và FaceMask (boolean — cho biết có phát hiện khẩu trang hay không).RESTful API (Máy chủ → Thiết bị)
Hỏi: RESTful API là gì?
RESTful API cho phép máy chủ của bạn gửi lệnh đến các thiết bị sinh trắc học — thêm/xóa người dùng, tải log, đăng ký sinh trắc học và kiểm soát truy cập. Bạn POST JSON đến URL endpoint có trong tài khoản API Monitor của mình.
RESTful API cho phép máy chủ của bạn gửi lệnh đến các thiết bị sinh trắc học — thêm/xóa người dùng, tải log, đăng ký sinh trắc học và kiểm soát truy cập. Bạn POST JSON đến URL endpoint có trong tài khoản API Monitor của mình.
Hỏi: Tôi tìm URL endpoint RESTful ở đâu?
Đăng nhập vào tài khoản API Monitor của bạn. URL endpoint RESTful và các Service Tag ID (
Đăng nhập vào tài khoản API Monitor của bạn. URL endpoint RESTful và các Service Tag ID (
stgid) được liệt kê ở đó.Hỏi: Độ trễ của các lệnh RESTful là bao nhiêu?
Khoảng 15 giây. Biometric Gateway đưa lệnh của bạn vào hàng đợi và chuyển đến thiết bị khi thiết bị kết nối lần tiếp theo (gần như liên tục đối với thiết bị trực tuyến).
Khoảng 15 giây. Biometric Gateway đưa lệnh của bạn vào hàng đợi và chuyển đến thiết bị khi thiết bị kết nối lần tiếp theo (gần như liên tục đối với thiết bị trực tuyến).
Hỏi: Khoảng ngày tối đa của LoadLog là bao nhiêu?
Khuyến nghị tối đa 30 ngày mỗi yêu cầu. Với khoảng dài hơn, hãy gửi nhiều yêu cầu với các khoảng thời gian liên tiếp.
Khuyến nghị tối đa 30 ngày mỗi yêu cầu. Với khoảng dài hơn, hãy gửi nhiều yêu cầu với các khoảng thời gian liên tiếp.
Hỏi: Tôi có thể thêm người dùng với nhiều template sinh trắc học cùng lúc không?
Có. Mảng Template chấp nhận nhiều phần tử. Ví dụ, thao tác #27 thêm người dùng với Card + Fingerprint + Password + Face + Palm + UserPhoto trong cùng một yêu cầu.
Có. Mảng Template chấp nhận nhiều phần tử. Ví dụ, thao tác #27 thêm người dùng với Card + Fingerprint + Password + Face + Palm + UserPhoto trong cùng một yêu cầu.
Hỏi: Điều gì xảy ra nếu thiết bị ngoại tuyến khi tôi gửi lệnh RESTful?
Biometric Gateway đưa lệnh vào hàng đợi và tự động chuyển đi khi thiết bị kết nối lại. Bạn sẽ nhận mã trạng thái
Biometric Gateway đưa lệnh vào hàng đợi và tự động chuyển đi khi thiết bị kết nối lại. Bạn sẽ nhận mã trạng thái
5 (Device Offline) nếu thiết bị không phản hồi trong khoảng thời gian chờ.Hỏi: Làm sao kiểm tra kết quả của lệnh?
Phản hồi RESTful có trường
Phản hồi RESTful có trường
StatusCode. Mã 0 nghĩa là thành công. Xem Mã trạng thái phản hồi để biết danh sách đầy đủ các mã lỗi và ý nghĩa của chúng.Hỏi: Tôi có thể kích hoạt đăng ký vân tay từ xa không?
Có. Thao tác #35 EnrollFingerPrint kích hoạt phiên đăng ký trên thiết bị. Tuy nhiên, người dùng phải có mặt tại thiết bị để quét ngón tay.
Có. Thao tác #35 EnrollFingerPrint kích hoạt phiên đăng ký trên thiết bị. Tuy nhiên, người dùng phải có mặt tại thiết bị để quét ngón tay.
Bảo mật & Mạng
Hỏi: Tôi có thể dùng HTTPS cho callback không?
Có. HTTPS với chứng chỉ SSL hợp lệ trên cổng 443 được hỗ trợ đầy đủ và khuyến nghị cho môi trường production.
Có. HTTPS với chứng chỉ SSL hợp lệ trên cổng 443 được hỗ trợ đầy đủ và khuyến nghị cho môi trường production.
Hỏi: Mã hóa có bắt buộc không?
Không. Mã hóa AES-256 là tùy chọn. Để bật, hãy cấu hình Security Key trong API Monitor. Khi bật, toàn bộ payload JSON được mã hóa/giải mã bằng AES/ECB/PKCS5PADDING với mã hóa Base64.
Không. Mã hóa AES-256 là tùy chọn. Để bật, hãy cấu hình Security Key trong API Monitor. Khi bật, toàn bộ payload JSON được mã hóa/giải mã bằng AES/ECB/PKCS5PADDING với mã hóa Base64.
Hỏi: Làm sao xác thực một callback thực sự đến từ Cams?
Mỗi callback đều có trường
Mỗi callback đều có trường
AuthToken. Hãy so sánh với token được cấu hình trong API Monitor của bạn. Từ chối mọi yêu cầu có token không khớp.Hỏi: Tôi nên mở những cổng nào?
Cổng
Cổng
80 (HTTP) hoặc 443 (HTTPS) cho production. Cổng 8123 chỉ khả dụng để kiểm thử. Xem Các cổng được hỗ trợ.Hỏi: Làm sao kiểm thử cục bộ mà không cần triển khai lên máy chủ?
Dùng IP công khai với chuyển tiếp cổng, hoặc công cụ tunnel như ngrok. Xem Kiểm thử cục bộ để có hướng dẫn từng bước.
Dùng IP công khai với chuyển tiếp cổng, hoặc công cụ tunnel như ngrok. Xem Kiểm thử cục bộ để có hướng dẫn từng bước.
Dữ liệu & Lưu ý thiết kế
Hỏi: API dùng định dạng dữ liệu nào?
Mọi yêu cầu và phản hồi đều là JSON thô với mã hóa UTF-8. Dùng header
Mọi yêu cầu và phản hồi đều là JSON thô với mã hóa UTF-8. Dùng header
Content-Type: application/json. Không dùng form encoding.Hỏi: Định dạng dấu thời gian là gì?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (ví dụ: 2020-09-17 07:48:22 GMT +0530). Trường Time theo UTC; các dấu thời gian theo giờ cục bộ của thiết bị (như LogTime, OperationTime) có thể dùng độ lệch múi giờ khác.Hỏi: Tôi nên xử lý các lượt chấm công ngoại tuyến và dữ liệu bổ sung muộn như thế nào?
Hãy thiết kế ứng dụng để chấp nhận các lượt chấm công đến không theo thứ tự thời gian. Khi thiết bị ngoại tuyến, nó sẽ đẩy các lượt chấm công đã lưu đệm sau khi kết nối lại. Bạn có thể cần cập nhật hồi tố trạng thái chuyên cần (ví dụ: chuyển người dùng đang hiển thị "vắng mặt" thành "có mặt").
Hãy thiết kế ứng dụng để chấp nhận các lượt chấm công đến không theo thứ tự thời gian. Khi thiết bị ngoại tuyến, nó sẽ đẩy các lượt chấm công đã lưu đệm sau khi kết nối lại. Bạn có thể cần cập nhật hồi tố trạng thái chuyên cần (ví dụ: chuyển người dùng đang hiển thị "vắng mặt" thành "có mặt").
Hỏi: Làm sao xác định IN/OUT khi người dùng có nhiều thiết bị?
Sắp xếp mọi lượt chấm công của người dùng theo
Sắp xếp mọi lượt chấm công của người dùng theo
LogTime trên tất cả thiết bị, rồi áp dụng logic nghiệp vụ của bạn. Không chỉ dựa vào trường Type (CheckIn/CheckOut) từ một thiết bị duy nhất nếu người dùng chấm công trên các máy khác nhau.Hỏi: OperationID là gì và tôi nên dùng nó như thế nào?
Là một chuỗi định danh duy nhất cho mỗi thao tác. Với callback chiều vào, nó do Biometric Gateway tạo ra. Với yêu cầu RESTful chiều ra, bạn nên tạo một mã duy nhất cho mỗi yêu cầu (dựa trên UUID hoặc dấu thời gian). Phản hồi sẽ trả lại mã này để bạn đối chiếu từng cặp yêu cầu/phản hồi.
Là một chuỗi định danh duy nhất cho mỗi thao tác. Với callback chiều vào, nó do Biometric Gateway tạo ra. Với yêu cầu RESTful chiều ra, bạn nên tạo một mã duy nhất cho mỗi yêu cầu (dựa trên UUID hoặc dấu thời gian). Phản hồi sẽ trả lại mã này để bạn đối chiếu từng cặp yêu cầu/phản hồi.
Hỏi: Template sinh trắc học được lưu trữ và truyền tải như thế nào?
Dữ liệu sinh trắc học (vân tay, khuôn mặt, lòng bàn tay, ảnh người dùng) được mã hóa Base64 trong trường
Dữ liệu sinh trắc học (vân tay, khuôn mặt, lòng bàn tay, ảnh người dùng) được mã hóa Base64 trong trường
Data của đối tượng Template. Template vân tay và khuôn mặt còn có Size (độ dài byte) và Index (số vị trí). Số thẻ và PIN là chuỗi thuần.Giá & Cấp phép
Hỏi: API được cấp phép như thế nào?
Theo từng thiết bị sinh trắc học. Năm đầu cần API Activation + Yearly License. Các năm sau chỉ cần gia hạn yearly license. Xem Chi phí API để biết giá.
Theo từng thiết bị sinh trắc học. Năm đầu cần API Activation + Yearly License. Các năm sau chỉ cần gia hạn yearly license. Xem Chi phí API để biết giá.
Hỏi: Điều gì xảy ra nếu giấy phép API của tôi hết hạn?
Giao tiếp API của thiết bị đó sẽ dừng cho đến khi giấy phép được gia hạn. Dữ liệu hiện có của bạn không bị ảnh hưởng, nhưng sẽ không xử lý callback hoặc lệnh RESTful mới.
Giao tiếp API của thiết bị đó sẽ dừng cho đến khi giấy phép được gia hạn. Dữ liệu hiện có của bạn không bị ảnh hưởng, nhưng sẽ không xử lý callback hoặc lệnh RESTful mới.
Hỏi: Có phương án on-premise không?
Có. Protocol Engine Lite có thể cài trên máy chủ của riêng bạn (Windows/Linux) cho môi trường chỉ có mạng LAN hoặc tự lưu trữ. Liên hệ sales@camsbiometrics.com để biết chi tiết.
Có. Protocol Engine Lite có thể cài trên máy chủ của riêng bạn (Windows/Linux) cho môi trường chỉ có mạng LAN hoặc tự lưu trữ. Liên hệ sales@camsbiometrics.com để biết chi tiết.
Thông tin bổ sung
SDK chấm công sinh trắc học
Cams không cung cấp SDK truyền thống. Mọi thao tác dùng Callback và RESTful API HTTP tiêu chuẩn — không cần cài đặt thư viện.
Không cần SDK. Giao tiếp được xử lý hoàn toàn thông qua Cams Protocol Engine bằng Callback URL và các endpoint HTTP RESTful.
Điều này giúp việc tích hợp với mọi nền tảng web trở nên đơn giản:
OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooỨng dụng web tùy chỉnh
Thông tin bổ sung
Chi phí API
API được tính phí theo từng thiết bị sinh trắc học. Năm đầu = kích hoạt + giấy phép; các năm sau = chỉ gia hạn giấy phép.
| Dịch vụ | USD | Ghi chú |
|---|---|---|
| Native Push — Thiết bị Cams & thiết bị đã xác minh | ||
| API Activation | $120 | Một lần cho mỗi thiết bị. |
| Giấy phép API hằng năm | $60 – $120 | Cần gia hạn hằng năm. |
| Protocol Update (không phải Cams) | $120 – $280 | Một lần. Kích hoạt giao thức Cams trên thiết bị không phải của Cams. |
| Hybrid Push — ZKTeco, eSSL & mọi thương hiệu bên thứ ba | ||
| API Activation | $150 | Một lần cho mỗi thiết bị. |
| Giấy phép API hằng năm | $90 – $150 | Cần gia hạn hằng năm. |
| Hybrid Connector (chưa xác minh) | $150 – $300 | Một lần. Bắt buộc đối với thiết bị chưa xác minh dùng Hybrid Push. |
| Phần cứng & Khác | ||
| Phần cứng | $220 – $720 | Tùy theo model. |
Protocol Engine Lite (on-premise) — Dành cho môi trường chỉ có mạng LAN hoặc tự lưu trữ. Chi phí: $500–$10,000. Liên hệ bộ phận kinh doanh để biết chi tiết.