เอกสารอ้างอิง API: สถาปัตยกรรม ฟิลด์ และรหัสสถานะ

องค์ประกอบพื้นฐานที่ทุกการทำงานใช้ร่วมกัน: ลำดับการส่งคำขอ ฟิลด์ JSON ทั่วไป ประเภทเทมเพลต รหัสสถานะ พอร์ต และการเข้ารหัส payload

เอกสารอ้างอิง API

สถาปัตยกรรม API

คุณสมบัติCallback APIRESTful API
ผู้เริ่มต้นอุปกรณ์ / Biometric Gatewayเซิร์ฟเวอร์ของคุณ
ทิศทางอุปกรณ์ → เซิร์ฟเวอร์ของคุณเซิร์ฟเวอร์ของคุณ → อุปกรณ์
ความหน่วงเรียลไทม์ (มิลลิวินาที)~15 วินาที
ตัวกระตุ้นเหตุการณ์ไบโอเมตริกซ์บนอุปกรณ์HTTP POST จากโค้ดของคุณ
บทบาทของคุณรับและตอบรับส่งคำสั่งและโพลล์/รอการตอบกลับ
Body ของการตอบกลับ{"status":"done"}{"Status":"done","OperationID":"…","StatusCode":0}
พฤติกรรมเมื่อออฟไลน์engine แคชไว้ และส่งเมื่อเซิร์ฟเวอร์กลับมาออนไลน์engine จัดคิวไว้ และส่งเมื่ออุปกรณ์เชื่อมต่อกลับมา
เอกสารอ้างอิง API

ฟิลด์ทั่วไป

ทุกคำขอ — ทั้ง Callback และ RESTful — ใช้ฟิลด์ระดับบนสุดต่อไปนี้ร่วมกัน

AuthTokenString token ความยาว 32 ตัวอักษรที่ใช้ระบุและยืนยันตัวตนของคำขอจากอุปกรณ์เฉพาะเครื่อง กำหนดค่าในพอร์ทัล API Monitor ให้ตรวจสอบค่านี้ในทุก callback ขาเข้า
OperationIDString ตัวระบุเฉพาะของการทำงานแต่ละครั้ง (เช่น "j95xfejt3vr1") การตอบกลับ RESTful จะส่ง OperationID เดียวกันกลับมา เพื่อให้คุณจับคู่คำขอกับการตอบกลับได้
TimeString เวลา UTC ที่เหตุการณ์ถูกประมวลผล ในรูปแบบ YYYY-MM-DD HH:mm:ss GMT +0000 เวลาตามเขตเวลาของอุปกรณ์ใน payload อาจใช้ค่า offset ของเขตเวลาที่ต่างออกไป
stgid (query param)String Service Tag ID — ระบุอุปกรณ์เป้าหมายสำหรับการเรียก RESTful API ส่งเป็น URL query parameter ไปยัง endpoint ที่อยู่ในบัญชี API Monitor ของคุณ: POST https://<your-endpoint>?stgid=YOUR_TAG_ID

ประเภทเทมเพลต

ข้อมูลไบโอเมตริกซ์และข้อมูลยืนยันตัวตนอยู่ในอาร์เรย์ Template แต่ละรายการมีฟิลด์ Type:

พฤติกรรมการรวมเทมเพลต — สำคัญสำหรับตัวจัดการ Callback
เมื่อข้อมูลผู้ใช้ถูกส่งมาจากอุปกรณ์ (การทำงาน Callback #3–#9) เทมเพลตอาจมาทีละรายการหรือเป็นกลุ่ม กระจายอยู่ในหลาย callback แต่ละ callback ไม่ได้มีชุดเทมเพลตทั้งหมดของผู้ใช้ — มีเฉพาะเทมเพลตที่เพิ่มหรือเปลี่ยนแปลงเท่านั้น

เซิร์ฟเวอร์ของคุณต้องรวม (merge) เทมเพลตที่เข้ามากับเทมเพลตที่จัดเก็บไว้ของผู้ใช้รายนั้น คีย์เฉพาะของเทมเพลตแต่ละรายการคือ Type + Index ตัวอย่างเช่น:
• Callback 1 มาพร้อม Fingerprint Index 0 → จัดเก็บไว้
• Callback 2 มาพร้อม Face Index 0 + Card → รวมเข้าด้วยกัน อย่าเขียนทับลายนิ้วมือ
• Callback 3 มาพร้อม Fingerprint Index 0 (ข้อมูลใหม่) → อัปเดตลายนิ้วมือเดิมที่ Index 0
 ห้ามแทนที่เทมเพลตทั้งหมดเมื่อได้รับ callback — ให้ upsert ตาม Type + Index เสมอ
Typeคำอธิบายฟิลด์เพิ่มเติมที่สำคัญ
Cardหมายเลขบัตร RFID / บัตรใกล้ตัวData (สตริงหมายเลขบัตร)
PasswordPIN ตัวเลขData (สตริง PIN)
Fingerprintเทมเพลตลายนิ้วมือ — ข้อมูลไบนารีเข้ารหัส Base64Index (ลำดับนิ้ว 0–9), Size, Data
Faceเทมเพลตใบหน้า — JPEG หรือข้อมูลไบนารีเข้ารหัส Base64Index, Size, Data
Palmเทมเพลตเส้นเลือดฝ่ามือ — ข้อมูลไบนารีเข้ารหัส Base64Index, Data
UserPhotoรูปโปรไฟล์ผู้ใช้ — JPEG เข้ารหัส Base64Data
เอกสารอ้างอิง API

รหัสสถานะการตอบกลับ

การตอบกลับของ RESTful API มี StatusCode ที่เป็นตัวเลข ส่วนการตอบกลับของ Callback API ใช้รูปแบบง่าย ๆ {"status":"done"} เสมอ ไม่ว่าผลลัพธ์จะเป็นอย่างไร

รหัสสถานะคำอธิบาย
0สำเร็จการทำงานเสร็จสมบูรณ์
1ข้อมูลคำขอไม่ถูกต้องJSON body มีรูปแบบผิดหรือมีค่าที่ไม่ถูกต้อง
2Service Tag ID ไม่ถูกต้องquery parameter stgid ไม่ตรงกับอุปกรณ์ใดที่ลงทะเบียนไว้
3คำขอไม่ถูกต้องโครงสร้างคำขอไม่ตรงกับรูปแบบของการทำงานที่คาดไว้
4การเข้ารหัสไม่ถูกต้องไม่สามารถถอดรหัส payload ที่เข้ารหัส (AES-256) ได้ โปรดตรวจสอบคีย์เข้ารหัสของคุณ
5อุปกรณ์ออฟไลน์อุปกรณ์เป้าหมายไม่ได้เชื่อมต่อกับ Biometric Gateway ในขณะนี้
6การทำงานหมดเวลาอุปกรณ์ไม่ตอบรับคำสั่งภายในเวลาที่กำหนด
7Auth Token ไม่ถูกต้องAuthToken ในคำขอไม่ตรงกับ token ที่กำหนดไว้ของอุปกรณ์
8มีผู้ใช้อยู่แล้วมีการสั่ง Add สำหรับ UserID ที่มีอยู่แล้วบนอุปกรณ์
9ไม่พบผู้ใช้ไม่มี UserID ที่ระบุอยู่บนอุปกรณ์
10เทมเพลตผิดพลาดข้อมูลเทมเพลตไบโอเมตริกซ์เสียหายหรืออยู่ในรูปแบบที่ไม่รองรับ
11หน่วยความจำอุปกรณ์เต็มอุปกรณ์เต็มความจุสูงสุดของผู้ใช้หรือเทมเพลตแล้ว
13Security Key ไม่ถูกต้องSecurity Key ที่กำหนดใน API Monitor ไม่ตรงกัน
15ไม่รองรับฟีเจอร์นี้อุปกรณ์รุ่นนี้หรือโหมดการสื่อสารนี้ไม่รองรับการทำงานที่ร้องขอ
999ข้อผิดพลาดที่ไม่ทราบสาเหตุเกิดข้อผิดพลาดที่ไม่คาดคิด โปรดติดต่อฝ่ายสนับสนุนของ Cams พร้อมแจ้ง OperationID
ข้อมูลเพิ่มเติม

พอร์ตที่รองรับ

เพื่อรับข้อมูลการลงเวลาแบบเรียลไทม์ เซิร์ฟเวอร์ของคุณต้องเปิด endpoint HTTP(S) ที่ Cams Protocol Engine เข้าถึงได้

พอร์ตโปรโตคอลการใช้งาน
80HTTPสำหรับใช้งานจริง (Production) ผูก callback URL ของคุณเข้ากับพอร์ต 80 กำหนดค่าใน API Monitor และถูกเรียกโดยอัตโนมัติเมื่อมีการลงเวลา
443HTTPSสำหรับใช้งานจริง (ปลอดภัย) HTTPS พร้อมใบรับรอง SSL ที่ถูกต้อง แนะนำสำหรับการใช้งานจริง
8123HTTPสำหรับทดสอบเท่านั้น พอร์ตที่ไม่ใช่มาตรฐาน เปิดให้ใช้ชั่วคราวระหว่างการพัฒนา
แนะนำให้ใช้ HTTPS ใช้ HTTPS พร้อมใบรับรอง SSL ที่ถูกต้องสำหรับการใช้งานจริง และตั้งให้ต่ออายุอัตโนมัติโดยไม่ต้องรีสตาร์ทเซิร์ฟเวอร์
ข้อมูลเพิ่มเติม

ข้อมูลตัวอย่าง

ตัวอย่าง payload คำขอและการตอบกลับของทั้ง 38 การทำงานอยู่ในแต่ละหัวข้อของการทำงานข้างต้น สำหรับมุมมองรวม:

หน้านี้ทุกหัวข้อของการทำงานข้างต้นมี JSON คำขอและการตอบกลับพร้อมข้อมูลตัวอย่างที่คัดลอกไปใช้ได้ทันที
หน้าตัวอย่างเดิมbiometric-web-api-sample-request-response.html — ตัวเลือกแบบดรอปดาวน์สำหรับแต่ละการทำงาน
ข้อมูลเพิ่มเติม

การเข้ารหัส

สามารถเปิดใช้การเข้ารหัส AES-256 แบบไม่บังคับสำหรับข้อมูลทั้งหมดที่แลกเปลี่ยนระหว่าง Cams Protocol Engine กับเซิร์ฟเวอร์ของคุณ

อัลกอริทึมAES-256 ในโหมด ECB พร้อม PKCS5 padding (AES/ECB/PKCS5PADDING)
การกำหนดค่าคีย์ตั้งคีย์ของคุณเป็น Security Key ใน API Monitor เมื่อกำหนดแล้ว payload JSON ดิบทั้งหมดจะถูกเข้ารหัส
การเข้ารหัสอักขระpayload ที่เข้ารหัสแล้วจะถูกเข้ารหัสเป็น Base64 เพื่อการส่งผ่าน HTTP ที่ปลอดภัย

ตัวอย่าง Java

เข้ารหัส / ถอดรหัส (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");
สำคัญ: เมื่อเปิดใช้การเข้ารหัส ให้ถอดรหัส payload ของ Callback ขาเข้า และเข้ารหัส body ของคำขอ RESTful ขาออก โดยใช้คีย์เดียวกัน