مرجع API: معماری، فیلدها و کدهای وضعیت

اجزای مشترک همه عملیات: جریان درخواست، فیلدهای JSON مشترک، انواع الگو، کدهای وضعیت، پورت‌ها و رمزنگاری payload.

مرجع API

معماری API

ویژگی	API نوع Callback	API نوع RESTful
آغازگر	دستگاه / Biometric Gateway	سرور شما
جهت	از دستگاه به سرور شما	از سرور شما به دستگاه
تأخیر	بلادرنگ (میلی‌ثانیه)	~15 ثانیه
محرک	رویداد بیومتریک روی دستگاه	HTTP POST از کد شما
نقش شما	دریافت و تأیید	ارسال فرمان و polling/انتظار برای پاسخ
بدنه پاسخ	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
رفتار در حالت آفلاین	توسط موتور کش می‌شود؛ پس از بازگشت سرور به حالت آنلاین تحویل داده می‌شود	توسط موتور در صف قرار می‌گیرد؛ پس از اتصال مجدد دستگاه تحویل داده می‌شود

مرجع API

فیلدهای مشترک

همه درخواست‌ها — هم Callback و هم RESTful — این فیلدهای سطح بالا را مشترکاً دارند.

AuthTokenرشته. یک توکن 32 نویسه‌ای که درخواست‌های یک دستگاه مشخص را شناسایی و احراز هویت می‌کند. در پورتال API Monitor پیکربندی می‌شود. آن را در هر callback ورودی اعتبارسنجی کنید.

OperationIDرشته. شناسه یکتا برای این نمونه از عملیات (مثلاً "j95xfejt3vr1"). پاسخ‌های RESTful همان OperationID را بازمی‌گردانند تا بتوانید درخواست‌ها را با پاسخ‌ها تطبیق دهید.

Timeرشته. زمان UTC پردازش رویداد، با قالب YYYY-MM-DD HH:mm:ss GMT +0000. زمان‌های محلی دستگاه درون payload ممکن است از آفست منطقه زمانی متفاوتی استفاده کنند.

stgid (query param)رشته. Service Tag ID — دستگاه هدف را در فراخوانی‌های RESTful مشخص می‌کند. آن را به‌صورت query parameter در URL مربوط به endpoint موجود در حساب API Monitor خود ارسال کنید: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

انواع الگو

داده‌های بیومتریک و اعتبارنامه در آرایه Template منتقل می‌شوند. هر مورد یک فیلد Type دارد:

رفتار ادغام الگوها — مهم برای Callback handlerها
هنگامی که داده کاربر از دستگاه 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`

مرجع API

کدهای وضعیت پاسخ

پاسخ‌های 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	فقط برای تست. پورت غیراستاندارد که به‌طور موقت در زمان توسعه در دسترس است.

HTTPS توصیه می‌شود. در محیط تولید از HTTPS با گواهی SSL معتبر استفاده کنید. از تمدید خودکار بدون راه‌اندازی مجدد سرور اطمینان حاصل کنید.

اطلاعات تکمیلی

داده‌های نمونه

payloadهای نمونه درخواست و پاسخ برای هر 38 عملیات در بخش هر عملیات در بالا مستند شده‌اند. برای نمایی یکجا:

این صفحههر بخش عملیات در بالا شامل JSON درخواست و پاسخ آماده کپی با داده‌های نمونه است.

صفحه نمونه قدیمیbiometric-web-api-sample-request-response.html — انتخابگر کشویی برای هر عملیات.

اطلاعات تکمیلی

رمزنگاری

رمزنگاری اختیاری AES-256 را می‌توان برای همه داده‌های مبادله‌شده بین Cams Protocol Engine و سرور شما فعال کرد.

الگوریتمAES-256 در حالت ECB با padding از نوع PKCS5 (AES/ECB/PKCS5PADDING).

پیکربندی کلیدکلید خود را به‌عنوان Security Key در API Monitor تنظیم کنید. پس از پیکربندی، همه payloadهای JSON خام رمزگذاری می‌شوند.

کدگذاریpayloadهای رمزگذاری‌شده برای انتقال امن روی HTTP با Base64 کدگذاری می‌شوند.

نمونه 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 ورودی را رمزگشایی و بدنه درخواست‌های RESTful خروجی را با همان کلید رمزگذاری کنید.