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.

Referencia de la API

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

Referencia de la API

Campos comunes

Todas las solicitudes, tanto de callback como RESTful, comparten estos campos de nivel superior.

AuthTokenString. Un token de 32 caracteres que identifica y autentica las solicitudes de un dispositivo concreto. Se configura en el portal API Monitor. Valídelo en cada callback entrante.

OperationIDString. Un identificador único de esta instancia de operación (p. ej. "j95xfejt3vr1"). Las respuestas RESTful devuelven el mismo OperationID para que pueda asociar solicitudes y respuestas.

TimeString. Marca de tiempo UTC del momento en que se procesó el evento, con el formato YYYY-MM-DD HH:mm:ss GMT +0000. Las marcas de tiempo locales del dispositivo dentro del payload pueden usar un desfase horario distinto.

stgid (parámetro de consulta)String. Service Tag ID: identifica el dispositivo de destino en las llamadas a la API RESTful. Páselo como parámetro de consulta de la URL al endpoint que figura en su cuenta de API Monitor: 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:

Comportamiento de combinación de plantillas — Importante para los controladores de callback
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 0
Nunca 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`

Referencia de la API

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.

Información adicional

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.

Se recomienda HTTPS. Use HTTPS con un certificado SSL válido en producción. Asegúrese de que la renovación sea automática y no requiera reiniciar el servidor.

Información adicional

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:

Esta páginaCada sección de operación anterior incluye JSON de solicitud y respuesta listo para copiar, con datos de ejemplo.

Página de ejemplos heredadabiometric-web-api-sample-request-response.html — selector desplegable para cada operación.

Información adicional

Cifrado

Se puede habilitar el cifrado AES-256 opcional para todos los datos intercambiados entre el Cams Protocol Engine y su servidor.

AlgoritmoAES-256 en modo ECB con relleno PKCS5 (AES/ECB/PKCS5PADDING).

Configuración de la claveEstablezca su clave como Security Key en API Monitor. Una vez configurada, todos los payloads JSON sin procesar se cifran.

CodificaciónLos payloads cifrados se codifican en Base64 para un transporte HTTP seguro.

Ejemplo en Java

Cifrar / descifrar (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");

Importante: Cuando el cifrado está habilitado, descifre los payloads de callback entrantes y cifre los cuerpos de solicitud RESTful salientes con la misma clave.