Referencia de la API: arquitectura, campos y códigos de estado
Los componentes comunes a todas las operaciones: flujo de solicitudes, campos JSON comunes, tipos de plantilla, códigos de estado, puertos y cifrado del payload.
Respuestas rápidas
¿Cuáles son los dos flujos de la API?
La API de callback envía eventos del dispositivo (a través de Cams Biometric Gateway) a su servidor en tiempo real. La API RESTful permite a su servidor enviar comandos a un dispositivo, y la respuesta llega en unos 15 segundos. Si su servidor está fuera de línea, el motor almacena los callbacks en caché; los comandos REST se ponen en cola hasta que el dispositivo se reconecte.
¿Qué códigos de estado devuelve la API RESTful?
Un StatusCode numérico: 0 correcto, 1 datos de solicitud no válidos, 2 Service Tag ID no válido, 3 solicitud no válida, 4 cifrado no válido, 5 dispositivo sin conexión, 6 tiempo de espera agotado, 7 token de autenticación no válido, 8 el usuario ya existe, 9 usuario no encontrado, 10 error de plantilla, 11 memoria del dispositivo llena, 13 clave de seguridad no válida, 15 función no admitida, 999 error desconocido. Las respuestas de callback siempre usan {"status":"done"}.
¿Qué significa el código de estado 5 (dispositivo sin conexión)?
El dispositivo de destino no está conectado actualmente a Biometric Gateway. Consulte el código de estado 5.
¿Cómo autentico las solicitudes?
Cada solicitud incluye un AuthToken, un token de 32 caracteres que identifica un dispositivo y se define en el portal API Monitor. Valídelo en cada callback entrante. Las llamadas REST también indican el dispositivo mediante el parámetro de consulta stgid (Service Tag ID). Consulte Campos comunes.
¿Qué puertos necesita mi servidor?
Puerto 80 (HTTP) o 443 (HTTPS) en producción; se recomienda HTTPS con un certificado válido. El puerto 8123 (HTTP) es solo para pruebas. Consulte Puertos admitidos.
¿Cómo se cifra el payload?
El cifrado es opcional. Cuando está activado, los payloads usan AES-256 en modo ECB con relleno PKCS5 (AES/ECB/PKCS5PADDING), con la clave de seguridad definida en API Monitor, y se codifican en Base64 para el transporte HTTP. Descifre los callbacks entrantes y cifre los cuerpos REST salientes con la misma clave. Consulte Cifrado.
¿Cómo gestiono las plantillas que llegan en varios callbacks?
Combínelas. Cada callback incluye solo las plantillas añadidas o modificadas. La clave única de una plantilla es Type + Index, así que haga upsert por ese par y nunca reemplace el conjunto completo de plantillas de un usuario. Consulte Tipos de plantilla.
¿Qué tipos de plantilla existen?
Card, Password, Fingerprint, Face, Palm y UserPhoto. Las plantillas de Fingerprint, Face y Palm están codificadas en Base64, y el índice de huella va de 0–9.
Arquitectura de la API
| Propiedad | API de callback | API RESTful |
|---|---|---|
| Iniciador | Dispositivo / Biometric Gateway | Su servidor |
| Dirección | Dispositivo → Su servidor | Su servidor → Dispositivo |
| Latencia | Tiempo real (milisegundos) | ~15 segundos |
| Disparador | Evento biométrico en el dispositivo | HTTP POST desde su código |
| Su rol | Recibir y confirmar | Enviar el comando y consultar/esperar la respuesta |
| Cuerpo de la respuesta | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| Comportamiento sin conexión | Almacenado en caché por el motor; se entrega cuando el servidor vuelve a estar en línea | Puesto en cola por el motor; se entrega cuando el dispositivo se reconecta |
Campos comunes
Todas las solicitudes, tanto de callback como RESTful, comparten estos campos de nivel superior.
"j95xfejt3vr1"). Las respuestas RESTful devuelven el mismo OperationID para que pueda asociar solicitudes y respuestas.YYYY-MM-DD HH:mm:ss GMT +0000. Las marcas de tiempo locales del dispositivo dentro del payload pueden usar un desfase horario distinto.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.Tipos de plantilla
Los datos biométricos y de credenciales se transportan en un arreglo Template. Cada elemento tiene un campo Type:
Cuando los datos de usuario se envían desde el dispositivo (operaciones de callback n.º 3–9), las plantillas pueden llegar una a una o en grupos, a lo largo de varios callbacks. Cada callback no contiene el conjunto completo de plantillas del usuario: solo incluye las plantillas añadidas o modificadas.
Su servidor debe combinar (merge) las plantillas entrantes con las plantillas ya almacenadas de ese usuario. La clave única de cada plantilla es
Type + Index. Por ejemplo:• El callback 1 llega con
Fingerprint Index 0 → almacénelo• El callback 2 llega con
Face Index 0 + Card → combine, no sobrescriba la huella• El callback 3 llega con
Fingerprint Index 0 (datos nuevos) → actualice la huella existente en Index 0Nunca reemplace todas las plantillas en un callback: haga siempre un upsert por
Type + Index.
| Tipo | Descripción | Campos adicionales clave |
|---|---|---|
Card | Número de tarjeta RFID / de proximidad | Data (cadena con el número de tarjeta) |
Password | PIN numérico | Data (cadena del PIN) |
Fingerprint | Plantilla de huella dactilar — binario codificado en Base64 | Index (índice del dedo 0–9), Size, Data |
Face | Plantilla facial — JPEG o binario codificado en Base64 | Index, Size, Data |
Palm | Plantilla de venas de la palma — binario codificado en Base64 | Index, Data |
UserPhoto | Foto de perfil del usuario — JPEG codificado en Base64 | Data |
Códigos de estado de la respuesta
Las respuestas de la API RESTful incluyen un StatusCode numérico. Las respuestas de la API de callback siempre usan la forma simple {"status":"done"}, sea cual sea el resultado.
| Código | Estado | Descripción |
|---|---|---|
0 | Éxito | La operación se completó correctamente. |
1 | Datos de solicitud no válidos | El cuerpo JSON está mal formado o contiene valores no válidos. |
2 | Service Tag ID no válido | El parámetro de consulta stgid no coincide con ningún dispositivo registrado. |
3 | Solicitud no válida | La estructura de la solicitud no coincide con el formato esperado de la operación. |
4 | Cifrado no válido | No se pudo descifrar el payload cifrado (AES-256). Compruebe su clave de cifrado. |
5 | Dispositivo sin conexión | El dispositivo de destino no está conectado actualmente al Biometric Gateway. |
6 | Tiempo de espera de la operación agotado | El dispositivo no confirmó el comando dentro del tiempo de espera. |
7 | AuthToken no válido | El AuthToken de la solicitud no coincide con el token configurado del dispositivo. |
8 | El usuario ya existe | Se intentó una operación Add para un UserID que ya existe en el dispositivo. |
9 | Usuario no encontrado | El UserID especificado no existe en el dispositivo. |
10 | Error de plantilla | Los datos de la plantilla biométrica están dañados o tienen un formato no admitido. |
11 | Memoria del dispositivo llena | El dispositivo ha alcanzado su capacidad máxima de usuarios o plantillas. |
13 | Clave de seguridad no válida | La clave de seguridad configurada en API Monitor no coincide. |
15 | Función no compatible | El modelo de este dispositivo o el modo de comunicación no admite la operación solicitada. |
999 | Error desconocido | Se produjo un error inesperado. Póngase en contacto con el soporte de Cams indicando el OperationID. |
Puertos admitidos
Para recibir información de asistencia en tiempo real, su servidor debe exponer un endpoint HTTP(S) al que pueda acceder el Cams Protocol Engine.
| Puerto | Protocolo | Uso |
|---|---|---|
80 | HTTP | Producción. Asocie su URL de callback al puerto 80. Se configura en API Monitor y se invoca automáticamente en cada marcación. |
443 | HTTPS | Producción (seguro). HTTPS con un certificado SSL válido. Recomendado para producción. |
8123 | HTTP | Solo para pruebas. Puerto no estándar disponible temporalmente durante el desarrollo. |
Datos de ejemplo
Los payloads de ejemplo de solicitud y respuesta de las 38 operaciones están documentados arriba, en la sección de cada operación. Para una vista consolidada:
Cifrado
Se puede habilitar el cifrado AES-256 opcional para todos los datos intercambiados entre el Cams Protocol Engine y su servidor.
AES/ECB/PKCS5PADDING).Ejemplo en 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");