Support Hub/API & Integrations/Xây dựng bộ nhận callback sinh trắc học bằng Python,…
Translated from the English article and reviewed by a person. Read the English original
Developer

Xây dựng bộ nhận callback sinh trắc học bằng Python, Node.js và PHP

Xây dựng bộ nhận callback sinh trắc học bằng Python, Node.js và PHP

Bộ nhận callback là đoạn mã nhỏ biến mỗi lần quét vân tay, khuôn mặt hoặc thẻ thành một bản ghi trong hệ thống riêng của bạn. Cams Biometrics Gateway gửi từng lần quét đã được xác minh đến máy chủ của bạn dưới dạng một yêu cầu JSON, và máy chủ của bạn trả lời để xác nhận đã nhận được. Bạn không cần tự viết bộ nhận này từ đầu. Cams cung cấp các Prompt tạo mã bằng AI cho Python, Node.js và PHP: dán một prompt vào trợ lý AI như Claude hoặc ChatGPT, và bạn sẽ nhận được một tệp hoàn chỉnh, có thể chạy ngay, gồm bộ nhận callback, một máy khách REST và giao diện kiểm thử. Hướng dẫn này giải thích bộ nhận cần làm những gì, cách tạo bộ nhận cho ngôn ngữ của bạn, cách cấu hình và cách kiểm thử trước khi đưa vào sử dụng chính thức.

01 · Sáu nhiệm vụ

Bộ nhận callback cần làm gì

Dù dùng ngôn ngữ nào, mọi bộ nhận callback sinh trắc học đều thực hiện cùng sáu nhiệm vụ. Đây cũng là những điểm cần kiểm tra trong bất kỳ mã nào bạn tạo ra.

Nhiệm vụ Ý nghĩa Vì sao quan trọng
1. Tiếp nhận yêu cầu Nhận một yêu cầu HTTP/HTTPS POST với nội dung JSON thô Đây là cách Gateway gửi từng sự kiện
2. Xác minh token Kiểm tra AuthToken với callback token mong đợi của bạn Ngăn người khác gửi dữ liệu chấm công giả đến URL của bạn
3. Định tuyến theo loại sự kiện Xem khóa nào nằm trong RealTime và xử lý tương ứng Không phải callback nào cũng là lượt chấm công; có callback báo ảnh hoặc thay đổi người dùng
4. Bỏ qua bản trùng lặp Dùng OperationID để bỏ qua các sự kiện bạn đã lưu Việc gửi lặp lại không bao giờ tạo thành bản ghi bị trùng
5. Lưu trữ và ghi nhật ký Lưu các trường cần thiết và ghi nhật ký cho mọi callback Tạo bản ghi mà HRMS, bảng lương hoặc bảng điều khiển của bạn sẽ sử dụng
6. Trả lời đã xong Trả về {“status”:”done”} với HTTP 200 Báo cho Gateway biết sự kiện đã được nhận an toàn

02 · Hiểu dữ liệu của bạn

Payload bạn sẽ nhận được

Callback phổ biến nhất là nhật ký chấm công, được gửi mỗi khi có người quét. Hãy lưu mẫu này thành sample.json, vì bạn sẽ dùng nó để kiểm thử bộ nhận sau này.

Callback API, yêu cầu PunchLog gửi đến bộ nhận của bạn

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}

Sau khi xử lý bất kỳ callback nào, bộ nhận của bạn phải trả về HTTP 200 với đúng nội dung sau:

Callback API, phản hồi bộ nhận của bạn phải trả về

{ "status": "done" } (HTTP 200)

Các loại sự kiện callback

Mọi callback đều được gửi trong một đối tượng RealTime. Bộ nhận của bạn quyết định cần làm gì bằng cách kiểm tra xem khóa nào trong các khóa sau có mặt:

Khóa bên trong RealTime Nội dung báo cáo
PunchLog Một lượt quét chấm công: ai, vào ca hay ra ca, lúc nào và bằng cách nào
UserUpdated Thông tin của một người dùng đã được cập nhật trên thiết bị

Hai chi tiết dễ gây lỗi cho lập trình viên

Chi tiết Cần lưu ý
Khóa phản hồi viết thường Trả về status viết thường với giá trị done. Không sao chép trường Status viết hoa từ phản hồi RESTful API
Định dạng LogTime LogTime có dạng 2020-09-17 07:48:22 GMT +0530. Đây là thời điểm quét thực tế kèm độ lệch múi giờ của thiết bị. Hãy phân tích giá trị này cùng độ lệch và dùng làm thời gian chấm công

03 · Để AI viết mã

Tạo bộ nhận của bạn bằng Prompt tạo mã AI

Cams cung cấp sẵn một tệp prompt cho mỗi ngôn ngữ máy chủ được hỗ trợ. Mỗi prompt chứa bản tóm tắt đặc tả Cams Web API 3.0 và hướng dẫn rõ ràng về những gì cần xây dựng. Bạn dán prompt vào trợ lý AI, và trợ lý sẽ tạo ra một bản triển khai hoàn chỉnh, gồm một tệp duy nhất, phù hợp với công nghệ của bạn.

1

Tải tệp prompt

Chọn ngôn ngữ của bạn trong phần tiếp theo và tải tệp prompt .txt tương ứng.

2

Dán vào trợ lý AI

Mở Claude, ChatGPT, Copilot hoặc bất kỳ công cụ lập trình AI nào, rồi dán toàn bộ nội dung prompt.

3

Nhận một tệp hoàn chỉnh có thể chạy

AI tạo ra một tệp duy nhất. Hãy thiết lập các giá trị cấu hình, triển khai và chạy tệp.

Mỗi tệp được tạo bao gồm Chức năng
Bộ nhận callback Đọc nội dung POST thô, xác thực AuthToken, định tuyến theo loại sự kiện, ghi nhật ký mọi callback, lưu nhật ký chấm công, lưu ảnh chấm công và trả lời đã xong
Máy khách REST Một hàm gửi yêu cầu chung cùng các hàm bao bọc cho tất cả 27 thao tác RESTful, như AddUser, DeleteUser, ResendAllUser và UpdateAccessTime
Giao diện kiểm thử HTML Một trang trình duyệt có các trường cấu hình, danh sách thả xuống thao tác, trình chỉnh sửa JSON được điền sẵn mẫu yêu cầu, khung xem phản hồi và danh sách các callback gần đây

Tài liệu trực tuyến được ưu tiên trước

Mỗi prompt yêu cầu AI đọc toàn bộ tài liệu Cams Web API và coi đó là nguồn chuẩn cho các thao tác, lược đồ JSON, tên trường và mã phản hồi. Nếu có điểm nào trong bản tóm tắt prompt mâu thuẫn với tài liệu trực tuyến, tài liệu trực tuyến sẽ được ưu tiên.

04 · Chọn ngôn ngữ

Prompt cho Python, Node.js và PHP

Mỗi prompt được điều chỉnh để tạo mã đúng chuẩn ngôn ngữ, với số phụ thuộc tối thiểu.

Python

Flask, SQLite, chỉ dùng thư viện chuẩn

Lấy prompt Python

Node.js

Express, kho lưu trữ tệp JSON

Lấy prompt Node.js

PHP

PHP thuần, SQLite, không dùng Composer

Tải prompt PHP

Cũng có prompt cho C# (.NET 8) với Minimal API, Java với HttpServer tích hợp sẵn và không cần phụ thuộc, Go với net/http và chỉ thư viện chuẩn, và Ruby với Sinatra và SQLite. Bạn có thể tìm tất cả trong mục Prompt tạo mã AI của tài liệu Cams Web API. Lấy prompt.

05 · Ba giá trị cần thiết lập

Cấu hình tệp đã tạo

Tệp được tạo có một khối cấu hình ở đầu. Trong phiên bản PHP, khối này trông như sau, và các ngôn ngữ khác dùng cùng ba giá trị:

Khối cấu hình, phiên bản PHP

$CONFIG = [
    'base_url'            => 'https://YOUR_RESTFUL_ENDPOINT_URL',
    'stgid'               => 'YOUR_SERVICE_TAG_ID',
    'auth_token'          => 'YOUR_AUTH_TOKEN',
];
Thiết lập Nhập gì
base_url URL điểm cuối RESTful từ tài khoản Cams API Monitor của bạn
stgid ID Service Tag của bạn.
auth_token AuthToken của bạn, được đưa vào các yêu cầu RESTful gửi đi và được đối chiếu với AuthToken trong các yêu cầu callback đến.

Không đặt token trong mã dùng chung

Khi kiểm thử nhanh, bạn có thể nhập trực tiếp giá trị vào khối cấu hình. Trước khi đưa vào sử dụng thực tế, hãy chuyển các token sang biến môi trường hoặc trình quản lý bí mật, để chúng không bao giờ xuất hiện trong hệ thống quản lý phiên bản hay tệp dùng chung.

Sau khi cấu hình và triển khai tại địa chỉ HTTPS công khai, hãy đặt địa chỉ đó làm Callback URL trong Cams Gateway. Từ đó, mọi lượt quét đã xác minh sẽ đến bộ nhận của bạn theo thời gian thực.

06 · Kiểm thử trước khi kết nối thiết bị

Kiểm thử bộ nhận của bạn

Bạn không cần thiết bị sinh trắc học để kiểm thử bộ nhận callback. Hãy tự gửi payload mẫu bằng cURL, dùng một callback token khớp, rồi kiểm tra phản hồi.

Terminal, gửi callback kiểm thử

# Lưu payload mẫu thành sample.json, sau đó gửi đến bộ nhận của bạn:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
  -H "Content-Type: application/json" \
  -d @sample.json

# Phản hồi mong đợi (HTTP 200):
# {"status":"done"}
Kiểm thử Gửi gì Kết quả mong đợi
Sự kiện hợp lệ sample.json, với AuthToken được đặt bằng auth_token của bạn HTTP 200 với done, và lượt chấm công được lưu
Sự kiện trùng lặp Cùng yêu cầu được gửi lần thứ hai HTTP 200 với done, và không lưu thêm bản ghi thứ hai
Token sai sample.json với AuthToken khác Bị từ chối, và không lưu gì cả
Sự kiện vào ca sample.json với Type đổi thành CheckIn Được lưu là lượt vào ca
Thao tác RESTful Dùng giao diện kiểm thử HTML tích hợp sẵn để gửi một thao tác Một phản hồi có Status và StatusCode

Giao diện kiểm thử HTML được tạo sẵn giúp bạn dễ dàng thử phần RESTful: mở tệp trong trình duyệt, chọn một thao tác từ danh sách thả xuống, chỉnh sửa JSON đã điền sẵn, rồi gửi đi. Khung xem các callback gần đây trên cùng trang sẽ xác nhận rằng các callback kiểm thử của bạn đã được nhận.

07 · Danh sách kiểm tra trước khi triển khai

Kiểm tra trước khi đưa vào sử dụng

Mã do AI tạo ra là điểm khởi đầu nhanh và đáng tin cậy, nhưng giống mọi mã khác, nó cần được rà soát trước khi xử lý dữ liệu nhân viên thực tế.

Hạng mục Hoàn thành khi
Đã rà soát mã Một lập trình viên đã đọc tệp được tạo và hiểu chức năng của từng phần
Chỉ HTTPS Bộ nhận chỉ truy cập được qua HTTPS với chứng chỉ hợp lệ
Token được bảo vệ AuthToken được lưu trong biến môi trường hoặc trình quản lý bí mật
Đã xử lý trùng lặp OperationID được lưu và kiểm tra để bỏ qua các lần gửi lặp lại
Lưu trữ phù hợp Kho tệp JSON phù hợp với hệ thống nhỏ; triển khai lớn hơn có thể chuyển sang cơ sở dữ liệu sản xuất
Giao diện kiểm thử được bảo vệ Trang kiểm thử HTML được đặt mật khẩu hoặc bị vô hiệu hóa trên máy chủ công khai
Ảnh được xử lý cẩn thận Ảnh chấm công lưu trên đĩa được kiểm soát truy cập và chỉ giữ trong thời gian cần thiết
Đã có giám sát Lỗi và số lượng callback bất thường được ghi nhật ký và cảnh báo qua hệ thống giám sát của riêng bạn

Đặt quy tắc nghiệp vụ ở nơi khác

Nhiệm vụ của bộ nhận là tiếp nhận, xác minh, định tuyến, lưu trữ và xác nhận. Việc xác định ai đi muộn, tính giờ làm thêm hoặc gửi thông báo thuộc về các hệ thống đọc dữ liệu đã lưu, như HRMS, ERP hoặc công cụ tự động hóa của bạn. Một bộ nhận chỉ làm một việc sẽ dễ bảo mật và bảo trì hơn.

Câu hỏi thường gặp

Tôi có cần tự viết mã không?

Thường là không. Các Prompt tạo mã bằng AI tạo ra một tệp hoàn chỉnh có thể chạy. Bạn thiết lập ba giá trị cấu hình, triển khai và kiểm thử. Tuy nhiên, lập trình viên vẫn nên rà soát mã trước khi đưa vào sử dụng thực tế.

Những trợ lý AI nào hoạt động với các prompt này?

Bất kỳ trợ lý lập trình AI đủ năng lực nào, bao gồm Claude, ChatGPT và Copilot. Hãy dán toàn bộ nội dung prompt cùng một lúc để trợ lý có đầy đủ đặc tả.

Tôi tìm URL điểm cuối RESTful và ID Service Tag ở đâu?

Cả hai đều lấy từ tài khoản Cams API Monitor của bạn. Các yêu cầu RESTful được gửi đến URL điểm cuối kèm ?stgid= theo sau là ID Service Tag của bạn.

Vì sao phải trả lời done cho sự kiện trùng lặp?

Vì sự kiện đã đến nơi an toàn, ngay cả khi bạn đã lưu nó trước đó. Trả lời done cho Gateway biết rằng không cần gửi lại sự kiện đó.

Tôi có thể dùng ngôn ngữ không có trong danh sách không?

Có. Bộ nhận callback chỉ cần chấp nhận một HTTPS POST và trả về JSON. Các prompt là cách làm tắt, và cùng API này hoạt động với bất kỳ ngôn ngữ nào làm được điều đó.

Kết luận: Từ prompt đến chấm công thời gian thực chỉ trong một buổi chiều

Bộ nhận callback sinh trắc học có kích thước nhỏ, nhưng nó là phần biến mọi lượt quét đã xác minh thành dữ liệu trực tiếp cho HRMS, bảng lương, bảng điều khiển và các tự động hóa của bạn. Với Prompt tạo mã AI của Cams, bạn không còn phải xây dựng nó từ con số không. Tải prompt cho Python, Node.js hoặc PHP, dán vào trợ lý AI, thiết lập ba giá trị và kiểm thử. Sau đó, hãy rà soát, bảo mật và để dữ liệu chấm công thời gian thực bắt đầu chảy về.

Cams Biometrics Gateway cung cấp các sự kiện mà bộ nhận của bạn cần. Callback API của Gateway gửi mọi lượt quét đã xác minh theo thời gian thực, trong một định dạng JSON nhất quán, từ thiết bị của hơn 15 thương hiệu, còn RESTful API cung cấp 27 thao tác mà máy khách được tạo của bạn có thể gọi. Mọi giao tiếp đều chạy qua HTTP/HTTPS với xác thực auth token và mã hóa AES-256 tùy chọn. Khám phá nền tảng tại CamsBiometrics.com và đọc đầy đủ tài liệu Web API, bao gồm mọi Prompt tạo mã AI: Lấy prompt.

 

Was this article helpful?