سؤالات متداول، SDK و هزینه

پرسش‌های رایج یکپارچه‌سازان، به‌همراه نحوه عملکرد SDK و قیمت‌گذاری API.

سؤالات متداول

پرسش‌های رایج درباره یکپارچه‌سازی با Cams Biometrics Web API 3.0.

عمومی

س: Cams Biometric Gateway و Biometric API آن چیست؟
Cams Biometric Gateway یک پلتفرم ابری جامع است که یک Biometric API ارائه می‌دهد تا هر برنامه وب بتواند به‌صورت بلادرنگ با دستگاه‌های حضور و غیاب و کنترل تردد بیومتریک ارتباط برقرار کند. از 38 عملیات در APIهای Callback (ورودی) و RESTful (خروجی) پشتیبانی می‌کند — بدون نیاز به SDK دستگاه یا IP ثابت.
س: آیا برای یکپارچه‌سازی به SDK نیاز دارم؟
خیر. Cams هیچ SDKی ارائه نمی‌دهد و نیازی به آن نیست. تمام ارتباطات از درخواست‌های استاندارد HTTP/HTTPS POST با payload از نوع JSON استفاده می‌کند. هر زبانی که بتواند فراخوانی HTTP انجام دهد کار می‌کند.
س: چه زبان‌های برنامه‌نویسی پشتیبانی می‌شوند؟
هر زبانی که بتواند HTTP POST با JSON ارسال/دریافت کند — PHP، Python، Java، C#، Node.js، Go، Ruby و بیشتر. ما پرامپت‌های تولیدکننده کد با هوش مصنوعی را برای 7 زبان ارائه می‌دهیم.
س: Cams Protocol Engine چیست؟
میان‌افزار ابری‌ای است که بین دستگاه‌های بیومتریک و سرور شما قرار می‌گیرد. ترجمه پروتکل، نرمال‌سازی داده و کش آفلاین را انجام می‌دهد و صرف‌نظر از برند یا مدل دستگاه، یک JSON API یکپارچه ارائه می‌کند.
س: API Monitor چیست؟
API Monitor پورتال مدیریت شماست که در آن Callback URLها را پیکربندی می‌کنید، AuthTokenها را مدیریت می‌کنید، Security Keyها را تنظیم می‌کنید، وضعیت دستگاه را می‌بینید و به URL مربوط به endpoint در RESTful و Service Tag IDها دسترسی دارید.

سازگاری دستگاه‌ها

س: چه دستگاه‌های بیومتریکی پشتیبانی می‌شوند؟
همه دستگاه‌های Cams Biometrics (فهرست‌شده در camsbiometrics.com/product) با Native Push از API کامل پشتیبانی می‌کنند. دستگاه‌های تأییدشده در developer.camsbiometrics.com نیز پشتیبانی کامل Native Push دارند.
س: آیا دستگاه‌های غیر Cams (ZkTeco، eSSL، BioMax و غیره) می‌توانند از این API استفاده کنند؟
بله، با Protocol Update. دستگاه‌های غیر Cams و تأییدنشده از طریق Hybrid Push کار می‌کنند. بسته به حالت اتصال و قابلیت‌های سخت‌افزار ممکن است برخی قابلیت‌ها محدود باشد.
س: تفاوت Native Push و Hybrid Push چیست؟
Native Push: پشتیبانی کامل از API بدون محدودیت — هر 38 عملیات کار می‌کنند. برای دستگاه‌های Cams و دستگاه‌های تأییدشده در دسترس است.
Hybrid Push: برای دستگاه‌های غیر Cams/تأییدنشده. در دسترس بودن قابلیت‌ها به حالت ارتباط (SDK، DB Pull یا پردازش فایل) بستگی دارد. به حالت‌های اتصال مراجعه کنید.
س: چه روش‌های بیومتریکی پشتیبانی می‌شوند؟
اثر انگشت، تشخیص چهره، رگ کف دست، کارت RFID/مجاورتی، PIN/رمز عددی، اسکن عنبیه و اندازه‌گیری دمای بدن (بسته به دستگاه).
س: برخی قابلیت‌های API با دستگاه من کار نمی‌کنند. چرا؟
این به (a) حالت اتصال بستگی دارد — حالت‌های DB Pull و پردازش فایل فقط از push حضور پشتیبانی می‌کنند، نه APIهای RESTful، و (b) محدودیت‌های سخت‌افزاری — ممکن است برخی مدل‌های دستگاه برخی قابلیت‌ها را در سطح firmware پشتیبانی نکنند. با سخت‌افزار خود تست کنید و برای کمک با پشتیبانی Cams تماس بگیرید.

Callback API (دستگاه → سرور)

س: Callback API چیست؟
Callback API رویدادهای بلادرنگ دستگاه‌های بیومتریک را به سرور شما می‌رساند. هنگامی که ثبت تردد رخ می‌دهد یا کاربری روی دستگاه تغییر می‌کند، Cams Protocol Engine بلافاصله یک payload از نوع JSON را با POST به Callback URL پیکربندی‌شده شما می‌فرستد.
س: سرور من باید چه پاسخی بدهد؟
همیشه {"status":"done"} را با وضعیت HTTP 200 برگردانید — حتی اگر پردازش داخلی شما شکست بخورد. هرگز Cams Protocol Engine را مسدود نکنید. پردازش‌های سنگین را برای اجرای ناهمگام در صف قرار دهید.
س: اگر هنگام ثبت تردد سرور من آفلاین باشد چه می‌شود؟
Biometric Gateway همه رویدادها را کش می‌کند و به‌محض بازگشت سرور شما به حالت آنلاین، آن‌ها را به‌طور خودکار تحویل می‌دهد. هیچ داده‌ای از دست نمی‌رود.
س: ثبت‌های تردد تکراری را چگونه مدیریت کنم؟
منطق شناسایی تکرار را روی سرور خود با ترکیب UserID + LogTime پیاده‌سازی کنید. ممکن است همان ثبت تردد هنگام بازیابی پس از آفلاین بودن یا تلاش مجدد شبکه دوباره ارسال شود.
س: چه انواع ثبت تردد پشتیبانی می‌شوند؟
CheckIn، CheckOut، BreakOut، BreakIn، OverTimeIn، OverTimeOut، MealIn، MealOut. فیلد InputType روش بیومتریک استفاده‌شده را نشان می‌دهد: Fingerprint، Face، Palm، Card یا Password.
Q: How do user templates work in Callbacks?
When a user is updated on the device (operations #3–#9), templates may arrive one at a time or in groups across multiple callbacks. Each callback only carries templates that changed — not the full set. Your server must merge/upsert by Type + Index as the unique key. Never overwrite all templates on a single callback.
س: آیا می‌توانم عکس‌های حضور را دریافت کنم؟
بله. عملیات #10 RealTimeAttendancePhoto یک تصویر JPEG رمزگذاری‌شده با Base64 را که در لحظه ثبت تردد گرفته شده تحویل می‌دهد. این جدا از callback لاگ ثبت تردد (#11) است و روی دستگاه‌های دارای دوربین در دسترس است.
س: آیا Callback شامل دما و تشخیص ماسک است؟
بله، در صورتی که دستگاه از آن پشتیبانی کند. شیء PunchLog شامل Temperature (مقدار دمای بدن) و FaceMask (مقدار منطقی — آیا ماسک صورت تشخیص داده شده است) است.

RESTful API (سرور → دستگاه)

س: RESTful API چیست؟
RESTful API به سرور شما امکان می‌دهد به دستگاه‌های بیومتریک فرمان بفرستد — افزودن/حذف کاربر، بارگذاری لاگ‌ها، ثبت‌نام بیومتریک و کنترل دسترسی. شما JSON را با POST به URL مربوط به endpoint که در حساب API Monitor شما آمده می‌فرستید.
س: URL مربوط به endpoint در RESTful را کجا پیدا کنم؟
وارد حساب API Monitor خود شوید. URL مربوط به endpoint در RESTful و Service Tag IDها (stgid) در آنجا فهرست شده‌اند.
س: تأخیر فرمان‌های RESTful چقدر است؟
تقریباً 15 ثانیه. Biometric Gateway فرمان شما را در صف قرار می‌دهد و در اتصال بعدی دستگاه (که برای دستگاه‌های آنلاین تقریباً پیوسته است) به آن تحویل می‌دهد.
س: حداکثر بازه تاریخ برای LoadLog چقدر است؟
حداکثر توصیه‌شده 30 روز در هر درخواست است. برای بازه‌های بزرگ‌تر، چند درخواست با بازه‌های زمانی متوالی ارسال کنید.
س: آیا می‌توانم یک کاربر را با چند الگوی بیومتریک هم‌زمان اضافه کنم؟
بله. آرایه Template چند مورد را می‌پذیرد. برای مثال، عملیات #27 یک کاربر را با Card + Fingerprint + Password + Face + Palm + UserPhoto همه در یک درخواست اضافه می‌کند.
س: اگر هنگام ارسال فرمان RESTful دستگاه آفلاین باشد چه می‌شود؟
Biometric Gateway فرمان را در صف قرار می‌دهد و هنگام اتصال مجدد دستگاه به‌طور خودکار تحویل می‌دهد. اگر دستگاه ظرف مهلت تعیین‌شده پاسخ ندهد، کد وضعیت 5 (دستگاه آفلاین) دریافت می‌کنید.
س: نتیجه فرمان را چگونه بررسی کنم؟
پاسخ‌های RESTful شامل فیلد StatusCode هستند. کد 0 یعنی موفق. برای فهرست کامل کدهای خطا و معانی آن‌ها به کدهای وضعیت پاسخ مراجعه کنید.
س: آیا می‌توانم ثبت‌نام اثر انگشت را از راه دور فعال کنم؟
بله. عملیات #35 EnrollFingerPrint یک جلسه ثبت‌نام روی خود دستگاه را فعال می‌کند. اما کاربر باید برای اسکن انگشت خود به‌صورت فیزیکی کنار دستگاه حاضر باشد.

امنیت و شبکه

س: آیا می‌توانم برای callbackها از HTTPS استفاده کنم؟
بله. HTTPS با گواهی SSL معتبر روی پورت 443 کاملاً پشتیبانی می‌شود و برای محیط تولید توصیه می‌شود.
س: آیا رمزنگاری اجباری است؟
خیر. رمزنگاری AES-256 اختیاری است. برای فعال‌سازی، یک Security Key را در API Monitor پیکربندی کنید. پس از فعال‌سازی، همه payloadهای JSON با AES/ECB/PKCS5PADDING و کدگذاری Base64 رمزگذاری/رمزگشایی می‌شوند.
س: چگونه تأیید کنم که یک callback واقعاً از Cams است؟
هر callback شامل فیلد AuthToken است. آن را با توکن پیکربندی‌شده در API Monitor مقایسه کنید. هر درخواستی را که توکن نامطابق دارد رد کنید.
س: کدام پورت‌ها را باید باز کنم؟
پورت 80 (HTTP) یا 443 (HTTPS) برای محیط تولید. پورت 8123 فقط برای تست در دسترس است. به پورت‌های پشتیبانی‌شده مراجعه کنید.
س: چگونه بدون استقرار روی سرور به‌صورت محلی تست کنم؟
از IP عمومی با port forwarding یا ابزار تونل مانند ngrok استفاده کنید. برای راهنمای گام‌به‌گام به تست محلی مراجعه کنید.

ملاحظات داده و طراحی

س: API از چه قالب داده‌ای استفاده می‌کند؟
همه درخواست‌ها و پاسخ‌ها JSON خام با کدگذاری UTF-8 هستند. از هدر Content-Type: application/json استفاده کنید. بدون form encoding.
س: از چه قالب زمانی استفاده می‌شود؟
YYYY-MM-DD HH:mm:ss GMT +OFFSET (مثلاً 2020-09-17 07:48:22 GMT +0530). فیلد Time به وقت UTC است؛ زمان‌های محلی دستگاه (مانند LogTime و OperationTime) ممکن است از آفست منطقه زمانی متفاوتی استفاده کنند.
س: ثبت‌های تردد آفلاین و داده‌های با تأخیر را چگونه مدیریت کنم؟
برنامه خود را طوری طراحی کنید که ثبت‌های تردد را با ترتیب زمانی نامنظم بپذیرد. هنگامی که دستگاه آفلاین بوده، پس از اتصال مجدد ثبت‌های کش‌شده را push می‌کند. ممکن است لازم باشد وضعیت حضور را با تأخیر (به‌صورت retroactive) به‌روزرسانی کنید (مثلاً کاربری را که «غایب» نمایش داده می‌شد به «حاضر» تغییر دهید).
س: وقتی کاربر چند دستگاه دارد، ورود/خروج را چگونه تشخیص دهم؟
همه ثبت‌های تردد یک کاربر را در تمام دستگاه‌ها بر اساس LogTime مرتب کنید، سپس منطق کسب‌وکار خود را اعمال کنید. اگر کاربر روی دستگاه‌های مختلف تردد ثبت می‌کند، فقط به فیلد Type (CheckIn/CheckOut) از یک دستگاه تکیه نکنید.
س: OperationID چیست و چگونه از آن استفاده کنم؟
یک شناسه رشته‌ای یکتا برای هر عملیات. برای callbackهای ورودی، توسط Biometric Gateway تولید می‌شود. برای درخواست‌های RESTful خروجی، شما باید برای هر درخواست یک شناسه یکتا (UUID یا مبتنی بر زمان) تولید کنید. پاسخ آن را برمی‌گرداند تا بتوانید جفت درخواست/پاسخ را تطبیق دهید.
س: الگوهای بیومتریک چگونه ذخیره و منتقل می‌شوند؟
داده‌های بیومتریک (اثر انگشت، چهره، کف دست، عکس کاربر) در فیلد Data شیء Template با Base64 کدگذاری می‌شوند. الگوهای اثر انگشت و چهره شامل Size (طول به بایت) و Index (شماره جایگاه) نیز هستند. شماره کارت‌ها و PINها رشته ساده‌اند.

قیمت‌گذاری و مجوز

س: مجوز API چگونه است؟
به ازای هر دستگاه بیومتریک. سال اول نیازمند فعال‌سازی API + مجوز سالانه است. سال‌های بعد فقط تمدید مجوز سالانه لازم است. برای قیمت‌ها به هزینه API مراجعه کنید.
س: اگر مجوز API من منقضی شود چه می‌شود؟
ارتباط API برای آن دستگاه تا تمدید مجوز متوقف می‌شود. داده‌های موجود شما تأثیری نمی‌پذیرد، اما هیچ callback یا فرمان RESTful جدیدی پردازش نخواهد شد.
س: آیا گزینه درون‌سازمانی (on-premise) وجود دارد؟
بله. Protocol Engine Lite را می‌توان روی سرور خودتان (Windows/Linux) برای شبکه‌های فقط LAN یا محیط‌های خودمیزبان نصب کرد. برای جزئیات با sales@camsbiometrics.com تماس بگیرید.

SDK حضور و غیاب بیومتریک

Cams هیچ SDK سنتی ارائه نمی‌دهد. همه عملیات از APIهای استاندارد HTTP Callback و RESTful استفاده می‌کنند — نیازی به نصب کتابخانه نیست.

نیازی به SDK نیست. ارتباط به‌طور کامل از طریق Cams Protocol Engine و با Callback URLها و endpointهای HTTP از نوع RESTful انجام می‌شود.

این کار یکپارچه‌سازی با هر پلتفرم وب را ساده می‌کند:

OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooبرنامه‌های وب سفارشی

هزینه API

مجوزهای API به ازای هر دستگاه بیومتریک صورت‌حساب می‌شوند. سال اول = فعال‌سازی + مجوز؛ سال‌های بعد = فقط تمدید مجوز.

سرویسUSDتوضیحات
Native Push — دستگاه‌های Cams و تأییدشده
فعال‌سازی API$120یک‌بار به ازای هر دستگاه.
مجوز سالانه API$60 – $120تمدید سالانه لازم است.
Protocol Update (غیر Cams)$120 – $280یک‌بار. پروتکل Cams را روی دستگاه‌های غیر Cams فعال می‌کند.
Hybrid Push — ZKTeco، eSSL و همه برندهای شخص ثالث
فعال‌سازی API$150یک‌بار به ازای هر دستگاه.
مجوز سالانه API$90 – $150تمدید سالانه لازم است.
Hybrid Connector (تأییدنشده)$150 – $300یک‌بار. برای دستگاه‌های تأییدنشده‌ای که از Hybrid Push استفاده می‌کنند لازم است.
سخت‌افزار و سایر موارد
سخت‌افزار$220 – $720بسته به مدل متفاوت است.
Protocol Engine Lite (درون‌سازمانی) — برای شبکه‌های فقط LAN یا محیط‌های خودمیزبان. هزینه: $500–$10,000. برای جزئیات با فروش تماس بگیرید.