เอกสารอ้างอิง API: สถาปัตยกรรม ฟิลด์ และรหัสสถานะ
องค์ประกอบพื้นฐานที่ทุกการทำงานใช้ร่วมกัน: ลำดับการส่งคำขอ ฟิลด์ JSON ทั่วไป ประเภทเทมเพลต รหัสสถานะ พอร์ต และการเข้ารหัส payload
คำตอบด่วน
API สองรูปแบบการทำงานคืออะไร
Callback API ส่งเหตุการณ์จากอุปกรณ์ (ผ่าน Cams Biometric Gateway) ไปยังเซิร์ฟเวอร์ของคุณแบบเรียลไทม์ ส่วน RESTful API ช่วยให้เซิร์ฟเวอร์ของคุณส่งคำสั่งไปยังอุปกรณ์ได้ และการตอบกลับจะมาถึงภายในประมาณ 15 วินาที หากเซิร์ฟเวอร์ของคุณออฟไลน์ engine จะแคช callback ไว้ ส่วนคำสั่ง REST จะถูกเข้าคิวไว้จนกว่าอุปกรณ์จะเชื่อมต่อใหม่
RESTful API ส่งคืนรหัสสถานะอะไรบ้าง
StatusCode แบบตัวเลข: 0 สำเร็จ, 1 ข้อมูลคำขอไม่ถูกต้อง, 2 Service Tag ID ไม่ถูกต้อง, 3 คำขอไม่ถูกต้อง, 4 การเข้ารหัสไม่ถูกต้อง, 5 อุปกรณ์ออฟไลน์, 6 การทำงานหมดเวลา, 7 auth token ไม่ถูกต้อง, 8 มีผู้ใช้อยู่แล้ว, 9 ไม่พบผู้ใช้, 10 ข้อผิดพลาดของเทมเพลต, 11 หน่วยความจำอุปกรณ์เต็ม, 13 คีย์ความปลอดภัยไม่ถูกต้อง, 15 ไม่รองรับฟีเจอร์, 999 ข้อผิดพลาดที่ไม่ทราบสาเหตุ การตอบกลับของ callback จะใช้ {"status":"done"} เสมอ
รหัสสถานะ 5 (อุปกรณ์ออฟไลน์) หมายความว่าอย่างไร
ขณะนี้อุปกรณ์เป้าหมายไม่ได้เชื่อมต่อกับ Biometric Gateway ดูรหัสสถานะ 5
ฉันจะยืนยันตัวตนของคำขอได้อย่างไร
ทุกคำขอจะมี AuthToken ซึ่งเป็นโทเค็น 32 ตัวอักษรที่ระบุอุปกรณ์หนึ่งเครื่องและตั้งค่าไว้ในพอร์ทัล API Monitor ให้ตรวจสอบโทเค็นนี้ในทุก callback ที่เข้ามา การเรียก REST จะส่งอุปกรณ์เป็นพารามิเตอร์ query stgid (Service Tag ID) ด้วย ดูฟิลด์ทั่วไป
เซิร์ฟเวอร์ของฉันต้องใช้พอร์ตใดบ้าง
พอร์ต 80 (HTTP) หรือ 443 (HTTPS) สำหรับการใช้งานจริง แนะนำให้ใช้ HTTPS ที่มีใบรับรองที่ถูกต้อง พอร์ต 8123 (HTTP) ใช้สำหรับการทดสอบเท่านั้น ดูพอร์ตที่รองรับ
payload ถูกเข้ารหัสอย่างไร
การเข้ารหัสเป็นทางเลือก เมื่อเปิดใช้งาน payload จะใช้ AES-256 โหมด ECB พร้อม PKCS5 padding (AES/ECB/PKCS5PADDING) โดยใช้ Security Key ที่ตั้งค่าไว้ใน API Monitor เป็นคีย์ และเข้ารหัส Base64 สำหรับการส่งผ่าน HTTP ให้ถอดรหัส callback ที่เข้ามาและเข้ารหัส body ของ REST ที่ส่งออกด้วยคีย์เดียวกัน ดูการเข้ารหัส
ฉันจะจัดการเทมเพลตที่มาถึงผ่านหลาย callback ได้อย่างไร
ให้รวมเข้าด้วยกัน แต่ละ callback จะมีเฉพาะเทมเพลตที่ถูกเพิ่มหรือเปลี่ยนแปลงเท่านั้น คีย์เฉพาะของเทมเพลตคือ Type + Index ดังนั้นให้ upsert ตามคู่นี้ และอย่าแทนที่ชุดเทมเพลตทั้งหมดของผู้ใช้ ดูประเภทเทมเพลต
มีเทมเพลตประเภทใดบ้าง
Card, Password, Fingerprint, Face, Palm และ UserPhoto เทมเพลต Fingerprint, Face และ Palm เข้ารหัสแบบ Base64 และดัชนีลายนิ้วมือมีค่า 0–9
สถาปัตยกรรม API
| คุณสมบัติ | Callback API | RESTful API |
|---|---|---|
| ผู้เริ่มต้น | อุปกรณ์ / Biometric Gateway | เซิร์ฟเวอร์ของคุณ |
| ทิศทาง | อุปกรณ์ → เซิร์ฟเวอร์ของคุณ | เซิร์ฟเวอร์ของคุณ → อุปกรณ์ |
| ความหน่วง | เรียลไทม์ (มิลลิวินาที) | ~15 วินาที |
| ตัวกระตุ้น | เหตุการณ์ไบโอเมตริกซ์บนอุปกรณ์ | HTTP POST จากโค้ดของคุณ |
| บทบาทของคุณ | รับและตอบรับ | ส่งคำสั่งและโพลล์/รอการตอบกลับ |
| Body ของการตอบกลับ | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| พฤติกรรมเมื่อออฟไลน์ | engine แคชไว้ และส่งเมื่อเซิร์ฟเวอร์กลับมาออนไลน์ | engine จัดคิวไว้ และส่งเมื่ออุปกรณ์เชื่อมต่อกลับมา |
ฟิลด์ทั่วไป
ทุกคำขอ — ทั้ง Callback และ RESTful — ใช้ฟิลด์ระดับบนสุดต่อไปนี้ร่วมกัน
"j95xfejt3vr1") การตอบกลับ RESTful จะส่ง OperationID เดียวกันกลับมา เพื่อให้คุณจับคู่คำขอกับการตอบกลับได้YYYY-MM-DD HH:mm:ss GMT +0000 เวลาตามเขตเวลาของอุปกรณ์ใน payload อาจใช้ค่า offset ของเขตเวลาที่ต่างออกไปPOST https://<your-endpoint>?stgid=YOUR_TAG_IDประเภทเทมเพลต
ข้อมูลไบโอเมตริกซ์และข้อมูลยืนยันตัวตนอยู่ในอาร์เรย์ Template แต่ละรายการมีฟิลด์ Type:
เมื่อข้อมูลผู้ใช้ถูกส่งมาจากอุปกรณ์ (การทำงาน 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 (สตริงหมายเลขบัตร) |
Password | PIN ตัวเลข | Data (สตริง PIN) |
Fingerprint | เทมเพลตลายนิ้วมือ — ข้อมูลไบนารีเข้ารหัส Base64 | Index (ลำดับนิ้ว 0–9), Size, Data |
Face | เทมเพลตใบหน้า — JPEG หรือข้อมูลไบนารีเข้ารหัส Base64 | Index, Size, Data |
Palm | เทมเพลตเส้นเลือดฝ่ามือ — ข้อมูลไบนารีเข้ารหัส Base64 | Index, Data |
UserPhoto | รูปโปรไฟล์ผู้ใช้ — JPEG เข้ารหัส Base64 | Data |
รหัสสถานะการตอบกลับ
การตอบกลับของ RESTful API มี StatusCode ที่เป็นตัวเลข ส่วนการตอบกลับของ Callback API ใช้รูปแบบง่าย ๆ {"status":"done"} เสมอ ไม่ว่าผลลัพธ์จะเป็นอย่างไร
| รหัส | สถานะ | คำอธิบาย |
|---|---|---|
0 | สำเร็จ | การทำงานเสร็จสมบูรณ์ |
1 | ข้อมูลคำขอไม่ถูกต้อง | JSON body มีรูปแบบผิดหรือมีค่าที่ไม่ถูกต้อง |
2 | Service Tag ID ไม่ถูกต้อง | query parameter stgid ไม่ตรงกับอุปกรณ์ใดที่ลงทะเบียนไว้ |
3 | คำขอไม่ถูกต้อง | โครงสร้างคำขอไม่ตรงกับรูปแบบของการทำงานที่คาดไว้ |
4 | การเข้ารหัสไม่ถูกต้อง | ไม่สามารถถอดรหัส payload ที่เข้ารหัส (AES-256) ได้ โปรดตรวจสอบคีย์เข้ารหัสของคุณ |
5 | อุปกรณ์ออฟไลน์ | อุปกรณ์เป้าหมายไม่ได้เชื่อมต่อกับ Biometric Gateway ในขณะนี้ |
6 | การทำงานหมดเวลา | อุปกรณ์ไม่ตอบรับคำสั่งภายในเวลาที่กำหนด |
7 | Auth Token ไม่ถูกต้อง | AuthToken ในคำขอไม่ตรงกับ token ที่กำหนดไว้ของอุปกรณ์ |
8 | มีผู้ใช้อยู่แล้ว | มีการสั่ง Add สำหรับ UserID ที่มีอยู่แล้วบนอุปกรณ์ |
9 | ไม่พบผู้ใช้ | ไม่มี UserID ที่ระบุอยู่บนอุปกรณ์ |
10 | เทมเพลตผิดพลาด | ข้อมูลเทมเพลตไบโอเมตริกซ์เสียหายหรืออยู่ในรูปแบบที่ไม่รองรับ |
11 | หน่วยความจำอุปกรณ์เต็ม | อุปกรณ์เต็มความจุสูงสุดของผู้ใช้หรือเทมเพลตแล้ว |
13 | Security Key ไม่ถูกต้อง | Security Key ที่กำหนดใน API Monitor ไม่ตรงกัน |
15 | ไม่รองรับฟีเจอร์นี้ | อุปกรณ์รุ่นนี้หรือโหมดการสื่อสารนี้ไม่รองรับการทำงานที่ร้องขอ |
999 | ข้อผิดพลาดที่ไม่ทราบสาเหตุ | เกิดข้อผิดพลาดที่ไม่คาดคิด โปรดติดต่อฝ่ายสนับสนุนของ Cams พร้อมแจ้ง OperationID |
พอร์ตที่รองรับ
เพื่อรับข้อมูลการลงเวลาแบบเรียลไทม์ เซิร์ฟเวอร์ของคุณต้องเปิด endpoint HTTP(S) ที่ Cams Protocol Engine เข้าถึงได้
| พอร์ต | โปรโตคอล | การใช้งาน |
|---|---|---|
80 | HTTP | สำหรับใช้งานจริง (Production) ผูก callback URL ของคุณเข้ากับพอร์ต 80 กำหนดค่าใน API Monitor และถูกเรียกโดยอัตโนมัติเมื่อมีการลงเวลา |
443 | HTTPS | สำหรับใช้งานจริง (ปลอดภัย) HTTPS พร้อมใบรับรอง SSL ที่ถูกต้อง แนะนำสำหรับการใช้งานจริง |
8123 | HTTP | สำหรับทดสอบเท่านั้น พอร์ตที่ไม่ใช่มาตรฐาน เปิดให้ใช้ชั่วคราวระหว่างการพัฒนา |
ข้อมูลตัวอย่าง
ตัวอย่าง payload คำขอและการตอบกลับของทั้ง 38 การทำงานอยู่ในแต่ละหัวข้อของการทำงานข้างต้น สำหรับมุมมองรวม:
การเข้ารหัส
สามารถเปิดใช้การเข้ารหัส AES-256 แบบไม่บังคับสำหรับข้อมูลทั้งหมดที่แลกเปลี่ยนระหว่าง Cams Protocol Engine กับเซิร์ฟเวอร์ของคุณ
AES/ECB/PKCS5PADDING)ตัวอย่าง 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");