مرجع API: معماری، فیلدها و کدهای وضعیت
اجزای مشترک همه عملیات: جریان درخواست، فیلدهای JSON مشترک، انواع الگو، کدهای وضعیت، پورتها و رمزنگاری payload.
پاسخهای سریع
دو جریان API کداماند؟
API نوع Callback رویدادها را از دستگاه (از طریق Cams Biometric Gateway) بهصورت لحظهای به سرور شما ارسال میکند. API نوع RESTful به سرور شما امکان میدهد دستورها را به دستگاه بفرستد و پاسخ در حدود 15 ثانیه میرسد. اگر سرور شما آفلاین باشد، موتور callbackها را ذخیره میکند؛ دستورهای REST تا اتصال مجدد دستگاه در صف میمانند.
API نوع RESTful چه کدهای وضعیتی برمیگرداند؟
یک مقدار عددی StatusCode: 0 موفق، 1 داده درخواست نامعتبر، 2 Service Tag ID نامعتبر، 3 درخواست نامعتبر، 4 رمزنگاری نامعتبر، 5 دستگاه آفلاین، 6 اتمام مهلت عملیات، 7 توکن احراز هویت نامعتبر، 8 کاربر از قبل وجود دارد، 9 کاربر یافت نشد، 10 خطای الگو، 11 حافظه دستگاه پر است، 13 کلید امنیتی نامعتبر، 15 قابلیت پشتیبانی نمیشود، 999 خطای ناشناخته. پاسخهای callback همیشه از {"status":"done"} استفاده میکنند.
کد وضعیت 5 (دستگاه آفلاین) به چه معناست؟
دستگاه هدف در حال حاضر به Biometric Gateway متصل نیست. به کد وضعیت 5 مراجعه کنید.
چگونه درخواستها را احراز هویت کنم؟
هر درخواست یک AuthToken دارد؛ توکنی 32 نویسهای که یک دستگاه را مشخص میکند و در پورتال API Monitor تنظیم میشود. آن را در هر callback ورودی اعتبارسنجی کنید. فراخوانیهای REST نیز دستگاه را با پارامتر کوئری stgid (Service Tag ID) ارسال میکنند. به فیلدهای مشترک مراجعه کنید.
سرور من به کدام پورتها نیاز دارد؟
پورت 80 (HTTP) یا 443 (HTTPS) برای محیط عملیاتی؛ استفاده از HTTPS با گواهی معتبر توصیه میشود. پورت 8123 (HTTP) فقط برای آزمایش است. به پورتهای پشتیبانیشده مراجعه کنید.
دادههای ارسالی چگونه رمزنگاری میشوند؟
رمزنگاری اختیاری است. در صورت فعال بودن، دادهها با AES-256 در حالت ECB و با padding از نوع PKCS5 (AES/ECB/PKCS5PADDING) و با کلید امنیتی تنظیمشده در API Monitor رمزنگاری میشوند و برای انتقال HTTP به Base64 کدگذاری میشوند. callbackهای ورودی را رمزگشایی و بدنه درخواستهای REST خروجی را با همان کلید رمزنگاری کنید. به رمزنگاری مراجعه کنید.
الگوهایی را که در چند callback میرسند چگونه مدیریت کنم؟
آنها را ادغام کنید. هر callback فقط الگوهای افزودهشده یا تغییریافته را دارد. کلید یکتای هر الگو Type + Index است؛ پس بر اساس این جفت upsert کنید و هرگز کل مجموعه الگوهای کاربر را جایگزین نکنید. به انواع الگو مراجعه کنید.
چه انواع الگویی وجود دارد؟
Card، Password، Fingerprint، Face، Palm و UserPhoto. الگوهای Fingerprint، Face و Palm با Base64 کدگذاری میشوند و اندیس اثر انگشت از 0–9 است.
معماری API
| ویژگی | API نوع Callback | API نوع RESTful |
|---|---|---|
| آغازگر | دستگاه / Biometric Gateway | سرور شما |
| جهت | از دستگاه به سرور شما | از سرور شما به دستگاه |
| تأخیر | بلادرنگ (میلیثانیه) | ~15 ثانیه |
| محرک | رویداد بیومتریک روی دستگاه | HTTP POST از کد شما |
| نقش شما | دریافت و تأیید | ارسال فرمان و polling/انتظار برای پاسخ |
| بدنه پاسخ | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| رفتار در حالت آفلاین | توسط موتور کش میشود؛ پس از بازگشت سرور به حالت آنلاین تحویل داده میشود | توسط موتور در صف قرار میگیرد؛ پس از اتصال مجدد دستگاه تحویل داده میشود |
فیلدهای مشترک
همه درخواستها — هم Callback و هم RESTful — این فیلدهای سطح بالا را مشترکاً دارند.
"j95xfejt3vr1"). پاسخهای RESTful همان OperationID را بازمیگردانند تا بتوانید درخواستها را با پاسخها تطبیق دهید.YYYY-MM-DD HH:mm:ss GMT +0000. زمانهای محلی دستگاه درون payload ممکن است از آفست منطقه زمانی متفاوتی استفاده کنند.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.انواع الگو
دادههای بیومتریک و اعتبارنامه در آرایه Template منتقل میشوند. هر مورد یک فیلد Type دارد:
هنگامی که داده کاربر از دستگاه push میشود (عملیات Callback شماره 3–9)، الگوها ممکن است یکییکی یا گروهی در چند callback برسند. هر callback شامل مجموعه کامل الگوهای کاربر نیست — فقط الگوهایی را حمل میکند که افزوده یا تغییر کردهاند.
سرور شما باید الگوهای ورودی را با الگوهای ذخیرهشده آن کاربر ادغام کند. کلید یکتای هر الگو
Type + Index است. برای مثال:• callback اول با
Fingerprint Index 0 میرسد → ذخیره کنید• callback دوم با
Face Index 0 + Card میرسد → ادغام کنید، اثر انگشت را بازنویسی نکنید• callback سوم با
Fingerprint Index 0 (داده جدید) میرسد → اثر انگشت موجود در Index 0 را بهروزرسانی کنیدهرگز در یک callback همه الگوها را جایگزین نکنید — همیشه بر اساس
Type + Index عمل upsert انجام دهید.
| نوع | توضیح | فیلدهای اضافی کلیدی |
|---|---|---|
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 شامل یک StatusCode عددی هستند. پاسخهای Callback صرفنظر از نتیجه، همیشه از قالب ساده {"status":"done"} استفاده میکنند.
| کد | وضعیت | توضیح |
|---|---|---|
0 | موفق | عملیات با موفقیت انجام شد. |
1 | داده درخواست نامعتبر | بدنه JSON ناقص است یا مقادیر نامعتبر دارد. |
2 | Service Tag ID نامعتبر | query parameter با نام stgid با هیچ دستگاه ثبتشدهای مطابقت ندارد. |
3 | درخواست نامعتبر | ساختار درخواست با قالب مورد انتظار عملیات مطابقت ندارد. |
4 | رمزنگاری نامعتبر | رمزگشایی payload (AES-256) انجام نشد. کلید رمزنگاری خود را بررسی کنید. |
5 | دستگاه آفلاین | دستگاه هدف در حال حاضر به Biometric Gateway متصل نیست. |
6 | پایان مهلت عملیات | دستگاه ظرف مهلت تعیینشده فرمان را تأیید نکرد. |
7 | توکن احراز هویت نامعتبر | AuthToken موجود در درخواست با توکن پیکربندیشده دستگاه مطابقت ندارد. |
8 | کاربر از قبل وجود دارد | عملیات افزودن برای UserIDی انجام شد که از قبل روی دستگاه وجود دارد. |
9 | کاربر یافت نشد | UserID مشخصشده روی دستگاه وجود ندارد. |
10 | خطای الگو | داده الگوی بیومتریک خراب است یا قالب آن پشتیبانی نمیشود. |
11 | حافظه دستگاه پر است | دستگاه به حداکثر ظرفیت کاربر یا الگوی خود رسیده است. |
13 | کلید امنیتی نامعتبر | کلید امنیتی پیکربندیشده در API Monitor مطابقت ندارد. |
15 | قابلیت پشتیبانی نمیشود | عملیات درخواستی توسط این مدل دستگاه یا حالت ارتباط پشتیبانی نمیشود. |
999 | خطای ناشناخته | خطای غیرمنتظرهای رخ داد. با ذکر OperationID با پشتیبانی Cams تماس بگیرید. |
پورتهای پشتیبانیشده
برای دریافت بلادرنگ اطلاعات حضور، سرور شما باید یک endpoint از نوع HTTP(S) در دسترس Cams Protocol Engine ارائه دهد.
| پورت | پروتکل | کاربرد |
|---|---|---|
80 | HTTP | محیط تولید. 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");