Preguntas frecuentes, SDK y costo

Preguntas habituales de los integradores, además de cómo funcionan el SDK y los precios de la API.

Información adicional

Preguntas frecuentes

Preguntas habituales sobre la integración con la Cams Biometrics Web API 3.0.

General

P: ¿Qué es el Cams Biometric Gateway y su API biométrica?
El Cams Biometric Gateway es una plataforma universal en la nube que expone una API biométrica que permite a cualquier aplicación web comunicarse en tiempo real con dispositivos biométricos de asistencia y control de acceso. Admite 38 operaciones entre APIs de callback (entrantes) y RESTful (salientes), sin necesidad de un SDK de dispositivo ni de una IP estática.
P: ¿Necesito un SDK para integrar?
No. Cams no ofrece ni requiere un SDK. Toda la comunicación usa solicitudes HTTP/HTTPS POST estándar con payloads JSON. Sirve cualquier lenguaje capaz de hacer llamadas HTTP.
P: ¿Qué lenguajes de programación se admiten?
Cualquier lenguaje que pueda enviar/recibir HTTP POST con JSON — PHP, Python, Java, C#, Node.js, Go, Ruby y más. Ofrecemos prompts de IA para generar código en 7 lenguajes.
P: ¿Qué es el Cams Protocol Engine?
Es el middleware en la nube que se sitúa entre los dispositivos biométricos y su servidor. Se encarga de la traducción de protocolos, la normalización de datos y la caché sin conexión, y ofrece una API JSON coherente sea cual sea la marca o el modelo del dispositivo.
P: ¿Qué es API Monitor?
API Monitor es su portal de administración donde configura las URL de callback, gestiona los AuthToken, establece las Security Key, consulta el estado de los dispositivos y accede a la URL de su endpoint RESTful y a los Service Tag ID.

Compatibilidad de dispositivos

P: ¿Qué dispositivos biométricos son compatibles?
Todos los equipos de Cams Biometrics (listados en camsbiometrics.com/product) admiten la API completa con Native Push. Los dispositivos verificados en developer.camsbiometrics.com también tienen compatibilidad total con Native Push.
P: ¿Pueden usar esta API los dispositivos que no son de Cams (ZkTeco, eSSL, BioMax, etc.)?
Sí, con una Protocol Update. Los dispositivos que no son de Cams ni están verificados funcionan mediante Hybrid Push. Algunas funciones pueden estar limitadas según el modo de conexión y las capacidades del hardware.
P: ¿Cuál es la diferencia entre Native Push y Hybrid Push?
Native Push: compatibilidad total con la API y sin limitaciones: las 38 operaciones funcionan. Disponible para equipos Cams y dispositivos verificados.
Hybrid Push: para dispositivos que no son de Cams ni están verificados. La disponibilidad de funciones depende del modo de comunicación (SDK, DB Pull o procesamiento de archivos). Consulte los modos de conexión.
P: ¿Qué métodos biométricos se admiten?
Huella dactilar, reconocimiento facial, venas de la palma, tarjeta RFID/de proximidad, PIN/contraseña numérico, escaneo de iris y medición de la temperatura corporal (según el dispositivo).
P: Algunas funciones de la API no funcionan con mi dispositivo. ¿Por qué?
Depende de (a) el modo de conexión — los modos DB Pull y procesamiento de archivos solo admiten el envío de asistencia, no las APIs RESTful, y (b) las limitaciones del hardware — es posible que algunos modelos no admitan funciones concretas a nivel de firmware. Pruebe con su hardware y póngase en contacto con el soporte de Cams para recibir ayuda.

API de callback (Dispositivo → Servidor)

P: ¿Qué es la API de callback?
La API de callback entrega a su servidor los eventos en tiempo real de los dispositivos biométricos. Cuando se produce una marcación o se modifica un usuario en el dispositivo, el Cams Protocol Engine envía (POST) de inmediato un payload JSON a su URL de callback configurada.
P: ¿Qué debe responder mi servidor?
Devuelva siempre {"status":"done"} con estado HTTP 200 — incluso si falla su procesamiento interno. No bloquee nunca el Cams Protocol Engine. Ponga en cola los procesamientos pesados para ejecutarlos de forma asíncrona.
P: ¿Qué ocurre si mi servidor está sin conexión cuando se produce una marcación?
El Biometric Gateway guarda en caché todos los eventos y los entrega automáticamente cuando su servidor vuelve a estar en línea. No se pierde ningún dato.
P: ¿Cómo gestiono las marcaciones duplicadas?
Implemente en su servidor una lógica de detección de duplicados usando la combinación de UserID + LogTime. Una misma marcación puede reenviarse durante la recuperación tras una desconexión o en reintentos de red.
P: ¿Qué tipos de marcación se admiten?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. El campo InputType indica el método biométrico utilizado: Fingerprint, Face, Palm, Card o Password.
P: ¿Cómo funcionan las plantillas de usuario en los callbacks?
Cuando se actualiza un usuario en el dispositivo (operaciones n.º 3–9), las plantillas pueden llegar una a una o en grupos a lo largo de varios callbacks. Cada callback solo incluye las plantillas que cambiaron, no el conjunto completo. Su servidor debe hacer un merge/upsert usando Type + Index como clave única. No sobrescriba nunca todas las plantillas con un único callback.
P: ¿Puedo recibir fotos de asistencia?
Sí. La operación n.º 10 RealTimeAttendancePhoto entrega una captura JPEG codificada en Base64 tomada en el momento de la marcación. Es independiente del callback del registro de marcaciones (n.º 11) y está disponible en dispositivos con cámara.
P: ¿El callback incluye temperatura y detección de mascarilla?
Sí, si el dispositivo lo admite. El objeto PunchLog incluye Temperature (lectura de la temperatura corporal) y FaceMask (booleano — indica si se detectó una mascarilla).

API RESTful (Servidor → Dispositivo)

P: ¿Qué es la API RESTful?
La API RESTful permite a su servidor enviar comandos a los dispositivos biométricos — agregar/eliminar usuarios, cargar registros, registrar datos biométricos y controlar el acceso. Usted envía (POST) JSON a la URL del endpoint que figura en su cuenta de API Monitor.
P: ¿Dónde encuentro la URL de mi endpoint RESTful?
Inicie sesión en su cuenta de API Monitor. Allí figuran la URL de su endpoint RESTful y los Service Tag ID (stgid).
P: ¿Cuál es la latencia de los comandos RESTful?
Aproximadamente 15 segundos. El Biometric Gateway pone su comando en cola y lo entrega al dispositivo la próxima vez que se conecte (lo cual es casi continuo en los dispositivos en línea).
P: ¿Cuál es el rango de fechas máximo de LoadLog?
Se recomienda un máximo de 30 días por solicitud. Para rangos mayores, haga varias solicitudes con ventanas de tiempo consecutivas.
P: ¿Puedo agregar un usuario con varias plantillas biométricas a la vez?
Sí. El arreglo Template acepta varias entradas. Por ejemplo, la operación n.º 27 agrega un usuario con Card + Fingerprint + Password + Face + Palm + UserPhoto en una sola solicitud.
P: ¿Qué ocurre si el dispositivo está sin conexión cuando envío un comando RESTful?
El Biometric Gateway pone el comando en cola y lo entrega automáticamente cuando el dispositivo se reconecta. Recibirá el código de estado 5 (Dispositivo sin conexión) si el dispositivo no responde dentro del tiempo de espera.
P: ¿Cómo compruebo el resultado de un comando?
Las respuestas RESTful incluyen un campo StatusCode. El código 0 significa éxito. Consulte los códigos de estado de la respuesta para ver la lista completa de códigos de error y su significado.
P: ¿Puedo iniciar el registro de huella dactilar de forma remota?
Sí. La operación n.º 35 EnrollFingerPrint inicia una sesión de registro en el dispositivo. Sin embargo, el usuario debe estar físicamente presente frente al dispositivo para escanear su dedo.

Seguridad y redes

P: ¿Puedo usar HTTPS para los callbacks?
Sí. HTTPS con un certificado SSL válido en el puerto 443 es totalmente compatible y se recomienda para producción.
P: ¿El cifrado es obligatorio?
No. El cifrado AES-256 es opcional. Para habilitarlo, configure una Security Key en API Monitor. Una vez habilitado, todos los payloads JSON se cifran/descifran con AES/ECB/PKCS5PADDING y codificación Base64.
P: ¿Cómo valido que un callback proviene realmente de Cams?
Cada callback incluye un campo AuthToken. Compárelo con el token configurado en su API Monitor. Rechace cualquier solicitud cuyo token no coincida.
P: ¿Qué puertos debo abrir?
El puerto 80 (HTTP) o 443 (HTTPS) para producción. El puerto 8123 está disponible solo para pruebas. Consulte los puertos admitidos.
P: ¿Cómo pruebo en local sin desplegar en un servidor?
Use una IP pública con redirección de puertos o una herramienta de túnel como ngrok. Consulte las pruebas locales para ver una guía paso a paso.

Datos y consideraciones de diseño

P: ¿Qué formato de datos usa la API?
Todas las solicitudes y respuestas son JSON sin procesar con codificación UTF-8. Use la cabecera Content-Type: application/json. Sin codificación de formulario.
P: ¿Qué formato de marca de tiempo se usa?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (p. ej., 2020-09-17 07:48:22 GMT +0530). El campo Time está en UTC; las marcas de tiempo locales del dispositivo (como LogTime, OperationTime) pueden usar un desfase horario distinto.
P: ¿Cómo debo gestionar las marcaciones sin conexión y los datos retroactivos?
Diseñe su aplicación para aceptar marcaciones que lleguen fuera de orden cronológico. Cuando un dispositivo estuvo sin conexión, enviará las marcaciones almacenadas en caché una vez reconectado. Puede ser necesario actualizar retroactivamente el estado de asistencia (p. ej., cambiar a «presente» a un usuario que figuraba como «ausente»).
P: ¿Cómo determino ENTRADA/SALIDA cuando un usuario tiene varios dispositivos?
Ordene todas las marcaciones de un usuario por LogTime entre todos los dispositivos y luego aplique su lógica de negocio. No se base únicamente en el campo Type (CheckIn/CheckOut) de un solo dispositivo si el usuario marca en equipos distintos.
P: ¿Qué es el OperationID y cómo debo usarlo?
Un identificador de cadena único para cada operación. En los callbacks entrantes lo genera el Biometric Gateway. En las solicitudes RESTful salientes, usted debe generar uno único por solicitud (UUID o basado en marca de tiempo). La respuesta lo devuelve para que pueda correlacionar los pares solicitud/respuesta.
P: ¿Cómo se almacenan y transmiten las plantillas biométricas?
Los datos biométricos (huella dactilar, rostro, palma, foto de usuario) se codifican en Base64 en el campo Data del objeto Template. Las plantillas de huella dactilar y rostro también incluyen Size (longitud en bytes) e Index (número de ranura). Los números de tarjeta y los PIN son cadenas de texto plano.

Precios y licencias

P: ¿Cómo se licencia la API?
Por equipo biométrico. El primer año requiere Activación de la API + Licencia anual. Los años siguientes requieren solo la renovación de la licencia anual. Consulte el costo de la API para ver los precios.
P: ¿Qué ocurre si caduca mi licencia de la API?
La comunicación de la API de ese dispositivo se detiene hasta que se renueve la licencia. Sus datos existentes no se ven afectados, pero no se procesarán nuevos callbacks ni comandos RESTful.
P: ¿Hay una opción local (on-premise)?
Sí. El Protocol Engine Lite puede instalarse en su propio servidor (Windows/Linux) para entornos solo LAN o autoalojados. Escriba a sales@camsbiometrics.com para más detalles.
Información adicional

SDK de asistencia biométrica

Cams no ofrece un SDK tradicional. Todas las operaciones usan las APIs estándar de callback HTTP y RESTful — no hace falta instalar ninguna biblioteca.

No se necesita SDK. La comunicación se gestiona íntegramente a través del Cams Protocol Engine mediante URL de callback y endpoints HTTP RESTful.

Esto simplifica la integración con cualquier plataforma web:

OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooAplicaciones web a medida
Información adicional

Costo de la API

Las licencias de la API se facturan por equipo biométrico. Primer año = activación + licencia; años siguientes = solo renovación de la licencia.

ServicioUSDNotas
Native Push — Dispositivos Cams y verificados
Activación de la API$120Pago único por equipo.
Licencia anual de la API$60 – $120Requiere renovación anual.
Protocol Update (no Cams)$120 – $280Pago único. Habilita el protocolo de Cams en dispositivos que no son de Cams.
Hybrid Push — ZKTeco, eSSL y todas las marcas de terceros
Activación de la API$150Pago único por equipo.
Licencia anual de la API$90 – $150Requiere renovación anual.
Hybrid Connector (no verificado)$150 – $300Pago único. Obligatorio para dispositivos no verificados que usan Hybrid Push.
Hardware y otros
Hardware$220 – $720Varía según el modelo.
Protocol Engine Lite (on-premise) — Para entornos solo LAN o autoalojados. Costo: $500–$10,000. Contacte con ventas para más detalles.