Tham chiếu API: kiến trúc, trường dữ liệu và mã trạng thái
Các thành phần dùng chung cho mọi thao tác: luồng yêu cầu, các trường JSON chung, loại template, mã trạng thái, cổng và mã hóa payload.
Tài liệu tham chiếu API
Kiến trúc API
| Thuộc tính | Callback API | RESTful API |
|---|---|---|
| Bên khởi tạo | Thiết bị / Biometric Gateway | Máy chủ của bạn |
| Hướng | Thiết bị → Máy chủ của bạn | Máy chủ của bạn → Thiết bị |
| Độ trễ | Thời gian thực (mili giây) | ~15 giây |
| Tác nhân kích hoạt | Sự kiện sinh trắc học trên thiết bị | HTTP POST từ mã của bạn |
| Vai trò của bạn | Nhận & xác nhận | Gửi lệnh & thăm dò/chờ phản hồi |
| Body phản hồi | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| Hành vi khi ngoại tuyến | Engine lưu đệm; chuyển đi khi máy chủ trực tuyến trở lại | Engine xếp hàng đợi; chuyển đi khi thiết bị kết nối lại |
Tài liệu tham chiếu API
Các trường chung
Mọi yêu cầu — cả Callback lẫn RESTful — đều dùng chung các trường cấp cao nhất sau.
AuthTokenString. Token gồm 32 ký tự dùng để nhận diện và xác thực các yêu cầu từ một thiết bị cụ thể. Được cấu hình trong cổng API Monitor. Hãy xác thực token này ở mọi callback đến.
OperationIDString. Mã định danh duy nhất cho lần thực hiện thao tác này (ví dụ:
"j95xfejt3vr1"). Phản hồi RESTful trả lại cùng OperationID để bạn đối chiếu yêu cầu với phản hồi.TimeString. Dấu thời gian UTC lúc sự kiện được xử lý, theo định dạng
YYYY-MM-DD HH:mm:ss GMT +0000. Các dấu thời gian theo giờ cục bộ của thiết bị trong payload có thể dùng độ lệch múi giờ khác.stgid (tham số truy vấn)String. Service Tag ID — xác định thiết bị đích cho các lệnh gọi RESTful API. Truyền dưới dạng tham số truy vấn URL đến endpoint có trong tài khoản API Monitor của bạn:
POST https://<your-endpoint>?stgid=YOUR_TAG_ID.Các loại template
Dữ liệu sinh trắc học và thông tin xác thực được truyền trong mảng Template. Mỗi phần tử có trường Type:
Hành vi hợp nhất template — Quan trọng đối với bộ xử lý callback
Khi dữ liệu người dùng được đẩy từ thiết bị (các thao tác Callback #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 không chứa toàn bộ bộ template của người dùng — nó chỉ mang các template được thêm hoặc thay đổi.
Máy chủ của bạn phải hợp nhất (merge) các template mới đến với các template đã lưu của người dùng đó. Khóa duy nhất của mỗi template là
• Callback 1 đến với
• Callback 2 đến với
• Callback 3 đến với
Không bao giờ thay thế toàn bộ template khi nhận callback — luôn upsert theo
Khi dữ liệu người dùng được đẩy từ thiết bị (các thao tác Callback #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 không chứa toàn bộ bộ template của người dùng — nó chỉ mang các template được thêm hoặc thay đổi.
Máy chủ của bạn phải hợp nhất (merge) các template mới đến với các template đã lưu của người dùng đó. Khóa duy nhất của mỗi template là
Type + Index. Ví dụ:• Callback 1 đến với
Fingerprint Index 0 → lưu lại• Callback 2 đến với
Face Index 0 + Card → hợp nhất, không ghi đè vân tay• Callback 3 đến với
Fingerprint Index 0 (dữ liệu mới) → cập nhật vân tay hiện có tại Index 0Không bao giờ thay thế toàn bộ template khi nhận callback — luôn upsert theo
Type + Index.
| Type | Mô tả | Các trường bổ sung chính |
|---|---|---|
Card | Số thẻ RFID / thẻ cảm ứng | Data (chuỗi số thẻ) |
Password | Mã PIN dạng số | Data (chuỗi PIN) |
Fingerprint | Template vân tay — dữ liệu nhị phân mã hóa Base64 | Index (chỉ số ngón tay 0–9), Size, Data |
Face | Template khuôn mặt — JPEG hoặc dữ liệu nhị phân mã hóa Base64 | Index, Size, Data |
Palm | Template tĩnh mạch lòng bàn tay — dữ liệu nhị phân mã hóa Base64 | Index, Data |
UserPhoto | Ảnh hồ sơ người dùng — JPEG mã hóa Base64 | Data |
Tài liệu tham chiếu API
Mã trạng thái phản hồi
Phản hồi RESTful API có kèm StatusCode dạng số. Phản hồi Callback API luôn dùng dạng đơn giản {"status":"done"} bất kể kết quả.
| Mã | Trạng thái | Mô tả |
|---|---|---|
0 | Thành công | Thao tác hoàn tất thành công. |
1 | Dữ liệu yêu cầu không hợp lệ | Body JSON sai định dạng hoặc chứa giá trị không hợp lệ. |
2 | Service Tag ID không hợp lệ | Tham số truy vấn stgid không khớp với bất kỳ thiết bị nào đã đăng ký. |
3 | Yêu cầu không hợp lệ | Cấu trúc yêu cầu không khớp với định dạng thao tác mong đợi. |
4 | Mã hóa không hợp lệ | Không thể giải mã payload đã mã hóa (AES-256). Hãy kiểm tra khóa mã hóa của bạn. |
5 | Thiết bị ngoại tuyến | Thiết bị đích hiện không kết nối với Biometric Gateway. |
6 | Hết thời gian thao tác | Thiết bị không xác nhận lệnh trong khoảng thời gian chờ cho phép. |
7 | Auth Token không hợp lệ | AuthToken trong yêu cầu không khớp với token đã cấu hình của thiết bị. |
8 | Người dùng đã tồn tại | Đã thực hiện thao tác Add cho một UserID đã tồn tại trên thiết bị. |
9 | Không tìm thấy người dùng | UserID được chỉ định không tồn tại trên thiết bị. |
10 | Lỗi template | Dữ liệu template sinh trắc học bị hỏng hoặc có định dạng không được hỗ trợ. |
11 | Bộ nhớ thiết bị đã đầy | Thiết bị đã đạt dung lượng tối đa về người dùng hoặc template. |
13 | Khóa bảo mật không hợp lệ | Khóa bảo mật được cấu hình trong API Monitor không khớp. |
15 | Tính năng không được hỗ trợ | Thao tác được yêu cầu không được model thiết bị này hoặc chế độ giao tiếp này hỗ trợ. |
999 | Lỗi không xác định | Đã xảy ra lỗi không mong muốn. Hãy liên hệ bộ phận hỗ trợ Cams kèm OperationID. |
Thông tin bổ sung
Các cổng được hỗ trợ
Để nhận thông tin chấm công theo thời gian thực, máy chủ của bạn phải cung cấp một endpoint HTTP(S) mà Cams Protocol Engine có thể truy cập.
| Cổng | Giao thức | Mục đích sử dụng |
|---|---|---|
80 | HTTP | Môi trường production. Gắn callback URL của bạn vào cổng 80. Được cấu hình trong API Monitor và được gọi tự động khi có lượt chấm công. |
443 | HTTPS | Production (bảo mật). HTTPS với chứng chỉ SSL hợp lệ. Khuyến nghị cho môi trường production. |
8123 | HTTP | Chỉ để kiểm thử. Cổng không chuẩn, tạm thời khả dụng trong quá trình phát triển. |
Khuyến nghị dùng HTTPS. Dùng HTTPS với chứng chỉ SSL hợp lệ cho môi trường production. Đảm bảo tự động gia hạn mà không cần khởi động lại máy chủ.
Thông tin bổ sung
Dữ liệu mẫu
Các payload yêu cầu và phản hồi mẫu cho cả 38 thao tác được trình bày ở trên trong từng mục thao tác. Để xem tổng hợp:
Trang nàyMỗi mục thao tác ở trên đều có JSON yêu cầu và phản hồi sẵn sàng sao chép, kèm dữ liệu mẫu.
Trang mẫu cũbiometric-web-api-sample-request-response.html — danh sách chọn cho từng thao tác.
Thông tin bổ sung
Mã hóa
Có thể bật mã hóa AES-256 tùy chọn cho toàn bộ dữ liệu trao đổi giữa Cams Protocol Engine và máy chủ của bạn.
Thuật toánAES-256 ở chế độ ECB với PKCS5 padding (
AES/ECB/PKCS5PADDING).Cấu hình khóaĐặt khóa của bạn làm Security Key trong API Monitor. Khi đã cấu hình, toàn bộ payload JSON thô đều được mã hóa.
Mã hóa ký tựCác payload được mã hóa sẽ được mã hóa Base64 để truyền HTTP an toàn.
Ví dụ Java
Mã hóa / Giải mã (Java)
// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));
// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");Quan trọng: Khi bật mã hóa, hãy giải mã payload Callback đến và mã hóa body yêu cầu RESTful đi bằng cùng một khóa.