Trang chủ / Nhà phát triển

Xây dựng chỉ trong một buổi chiều

Xác thực, lấy dữ liệu chấm công, đăng ký vân tay và mở cửa — với các ví dụ sao chép dán dùng ngay bằng ngôn ngữ bạn đang dùng.

Bắt đầu nhanh

Ba bước đến lệnh gọi đầu tiên

Nhận khóa API

Tạo tài khoản trên cổng nhà phát triển và ghép nối thiết bị của bạn bằng số sê-ri. Bạn sẽ nhận được một AuthToken.

Xác thực mọi yêu cầu

Truyền AuthToken trong mỗi lệnh gọi. Nó giới hạn quyền truy cập trong phạm vi tài khoản và thiết bị cụ thể của bạn.

Gọi một endpoint

Bắt đầu với GetAttendanceByDate để xác nhận dữ liệu đang chảy về, sau đó chuyển sang đăng ký và kiểm soát ra vào.

Base URL

https://api.camsbiometrics.com/v3/

# Fetch attendance for a date range
curl https://api.camsbiometrics.com/v3/attendance/getbyscandate \
  -d "AuthToken=$API_KEY" \
  -d "StartDate=2026-06-01" \
  -d "EndDate=2026-06-21"
$ch = curl_init("https://api.camsbiometrics.com/v3/attendance/getbyscandate");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => [
    "AuthToken"  => $apiKey,
    "StartDate"  => "2026-06-01",
    "EndDate"    => "2026-06-21",
  ],
]);
$data = json_decode(curl_exec($ch), true);
import requests

r = requests.post(
    "https://api.camsbiometrics.com/v3/attendance/getbyscandate",
    data={
        "AuthToken": api_key,
        "StartDate": "2026-06-01",
        "EndDate": "2026-06-21",
    },
)
logs = r.json()["Attendance"]
const res = await fetch(
  "https://api.camsbiometrics.com/v3/attendance/getbyscandate",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      AuthToken: apiKey,
      StartDate: "2026-06-01",
      EndDate: "2026-06-21",
    }),
  }
);
const { Attendance } = await res.json();

Mẫu tương tự áp dụng cho mọi thao tác — chỉ cần đổi đường dẫn và tham số.

Công thức thường dùng

Sao chép, dán, triển khai

POST

Đăng ký người dùng

curl .../v3/user/add \
 -d "AuthToken=$K" \
 -d "DeviceSN=ZK6A2300583" \
 -d "EmployeeCode=1042" \
 -d "Name=Priya"
POST

Mở cửa

curl .../v3/access/opendoor \
 -d "AuthToken=$K" \
 -d "DeviceSN=ZK6A2300583" \
 -d "DoorNo=1"
CALLBACK

Đăng ký webhook

curl .../v3/callback/register \
 -d "AuthToken=$K" \
 -d "Url=https://app/hook" \
 -d "Events=attendance.new"
🔒

Giữ khóa ở phía máy chủ

Không bao giờ nhúng AuthToken vào mã phía client. Hãy chuyển tiếp lệnh gọi qua backend của bạn.

🔄

Làm cho webhook có tính idempotent

Gateway sẽ thử lại cho đến khi bạn trả về 200. Hãy loại trùng theo id sự kiện để việc thử lại luôn an toàn.

⏳

Xử lý các lệnh trong hàng đợi

Nếu thiết bị ngoại tuyến, bạn sẽ nhận được 409; lệnh được xếp vào hàng đợi. Hãy poll GetCommandStatus.

Kiểm thử cục bộ

Kiểm thử callback URL từ máy của bạn

Máy phát triển của bạn nằm sau tường lửa nên gateway không thể truy cập trực tiếp localhost. Hãy mở nó ra ngoài bằng một tunnel, trỏ Callback URL của bạn đến địa chỉ công khai và kích hoạt một lượt chấm công thử.

  • Luôn dùng callback URL HTTPS
  • Giữ tunnel chạy trong suốt phiên kiểm thử
  • URL ngrok miễn phí sẽ đổi khi khởi động lại — hãy cập nhật callback khi điều đó xảy ra
  • Làm cho trình xử lý của bạn có tính idempotent — gateway thử lại cho đến khi nhận được 200
# 1. install & authenticate ngrok
ngrok config add-authtoken $TOKEN
# 2. expose your local app (e.g. port 3000)
ngrok http 3000
# Forwarding https://abc123.ngrok-free.app -> localhost:3000
# 3. set that HTTPS URL as your Callback URL
# Cams ngrok helper kit (Windows)
# download:
developer.camsbiometrics.com/setup/ngrok-helper-kit.rar
# then:
edit app.properties   # add your ngrok authtoken
run  check_ngrok.bat

Kết nối thiết bị

Trỏ thiết bị đầu cuối đến gateway

Hầu hết các thiết bị chấm công đầu cuối (ZKTeco, eSSL và tương thích) dùng giao thức ICLOCK / push. Hãy cài các trường máy chủ đám mây trên thiết bị và nó sẽ truyền dữ liệu chấm công đến tài khoản của bạn — không cần PC hay phần mềm cục bộ.

⚙
Trên thiết bị: Menu → COMM → Cloud Server / ADMS, nhập máy chủ bên dưới, rồi xác nhận biểu tượng kết nối máy chủ xuất hiện trên màn hình chính.

Cài đặt máy chủ trên thiết bị

IP máy chủ
152.53.172.248
Cổng
8123 (phát triển / kiểm thử) · 80 (production)
Enable Domain Name
OFF
Proxy Server
OFF
Giao thức
ICLOCK / Push

Hãy khớp IP / subnet / gateway / DNS của thiết bị với mạng LAN của bạn (hoặc dùng DHCP) trước khi cài đặt máy chủ đám mây.

Đã có số sê-ri thiết bị trong tay?

Ghép nối nó trên cổng nhà phát triển và thực hiện lệnh gọi trực tiếp chỉ trong vài phút.