Cómo crear un receptor de callbacks biométricos en Python, Node.js y PHP
Un receptor de callbacks es la pequeña pieza de código que convierte cada escaneo de huella, rostro o tarjeta en un registro en tu propio sistema. Cams Biometrics Gateway envía cada escaneo verificado a tu servidor como una solicitud JSON, y tu servidor responde para confirmar que lo recibió. No tienes que escribir ese receptor desde cero. Cams ofrece prompts generadores de código con IA para Python, Node.js y PHP: pégalo en un asistente de IA como Claude o ChatGPT y obtendrás un archivo completo y funcional con un receptor de callbacks, un cliente REST y una interfaz de prueba. Este tutorial explica qué debe hacer un receptor, cómo generarlo para tu lenguaje, cómo configurarlo y cómo probarlo antes de ponerlo en producción.
01 · Las seis funciones
Qué debe hacer un receptor de callbacks
Sin importar el lenguaje que uses, todo receptor de callbacks biométricos realiza las mismas seis funciones. Estas son también las cosas que debes revisar en cualquier código que generes.
| Función | Qué significa | Por qué importa |
|---|---|---|
| 1. Aceptar la solicitud | Recibir un POST HTTP/HTTPS con un cuerpo JSON sin procesar | Así es como el Gateway entrega cada evento |
| 2. Verificar el token | Comprobar el AuthToken con el token de callback esperado | Evita que otros envíen asistencias falsas a tu URL |
| 3. Enrutar por tipo de evento | Revisar qué clave está dentro de RealTime y procesarla en consecuencia | No todos los callbacks son fichajes; algunos informan fotos o cambios de usuario |
| 4. Omitir duplicados | Usar OperationID para ignorar eventos que ya has guardado | Un envío repetido nunca genera un registro doble |
| 5. Almacenar y registrar | Guardar los campos que necesitas y registrar cada callback | Crea el registro que usarán tu HRMS, nómina o panel |
| 6. Responder con done | Devolver {“status”:”done”} con HTTP 200 | Indica al Gateway que el evento llegó correctamente |
02 · Conoce tus datos
La carga útil que recibirás
El callback más común es un registro de fichaje, que se envía cada vez que alguien escanea. Guarda este ejemplo como sample.json, porque lo usarás más adelante para probar tu receptor.
|
Callback API, solicitud PunchLog enviada a tu receptor {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
Después de procesar cualquier callback, tu receptor debe responder con HTTP 200 y exactamente este cuerpo:
|
Callback API, respuesta que debe devolver tu receptor { "status": "done" } (HTTP 200)
|
Tipos de evento de callback
Cada callback llega dentro de un objeto RealTime. Tu receptor decide qué hacer comprobando cuál de estas claves está presente:
| Clave dentro de RealTime | Qué informa |
|---|---|
| PunchLog | Un escaneo de asistencia: quién, entrada o salida, cuándo y cómo |
| UserUpdated | Los datos de un usuario se actualizaron en el dispositivo |
Dos detalles que confunden a los desarrolladores
| Detalle | Qué vigilar |
|---|---|
| La clave de respuesta va en minúsculas | Devuelve status en minúsculas con el valor done. No copies el campo Status con mayúscula de las respuestas de la RESTful API |
| El formato de LogTime | LogTime tiene un aspecto como 2020-09-17 07:48:22 GMT +0530. Es la hora real del escaneo con el desfase horario del dispositivo. Analízala con ese desfase y utilízala como hora de asistencia |
03 · Deja que la IA escriba el código
Genera tu receptor con los prompts generadores de código con IA
Cams publica un archivo de prompt listo para usar para cada lenguaje de servidor compatible. Cada prompt contiene un resumen de la especificación de Cams Web API 3.0 e instrucciones claras sobre lo que hay que construir. Lo pegas en un asistente de IA, y el asistente genera una implementación completa de un solo archivo para tu stack.
|
Descarga el archivo de prompt Elige tu lenguaje en la siguiente sección y descarga su archivo de prompt .txt. |
|
|
Pégalo en un asistente de IA Abre Claude, ChatGPT, Copilot o cualquier herramienta de programación con IA, y pega todo el contenido del prompt. |
|
|
Obtén un archivo completo y funcional La IA genera un solo archivo. Define tus valores de configuración, impleméntalo y ejecútalo. |
| Cada archivo generado incluye | Qué hace |
|---|---|
| Receptor de callbacks | Lee el cuerpo POST sin procesar, valida el AuthToken, enruta por tipo de evento, registra cada callback, guarda los registros de fichaje, almacena las fotos de asistencia y responde con done |
| Cliente REST | Una función genérica de solicitud más funciones envoltorio para las 27 operaciones RESTful, como AddUser, DeleteUser, ResendAllUser y UpdateAccessTime |
| Interfaz de prueba HTML | Una página del navegador con los campos de configuración, un desplegable de operaciones, un editor JSON precargado con plantillas de solicitud, un visor de respuestas y una lista de callbacks recientes |
|
Primero, la documentación en línea Cada prompt indica a la IA que lea la documentación completa de Cams Web API y la trate como fuente oficial para operaciones, esquemas JSON, nombres de campos y códigos de respuesta. Si algo del resumen del prompt entra en conflicto con la documentación en línea, prevalece la documentación. |
04 · Elige tu lenguaje
Prompts para Python, Node.js y PHP
Cada prompt está ajustado para generar código idiomático con dependencias mínimas para su lenguaje.
|
|
|
También hay prompts disponibles para C# (.NET 8) con Minimal API, Java con el HttpServer integrado y sin dependencias, Go con net/http y solo la biblioteca estándar, y Ruby con Sinatra y SQLite. Puedes encontrarlos todos en la sección de prompts generadores de código con IA de la documentación de Cams Web API. Obtener prompts.
05 · Tres valores que definir
Configurar el archivo generado
El archivo generado tiene un bloque de configuración al principio. En la versión de PHP tiene este aspecto, y los demás lenguajes usan los mismos tres valores:
|
Bloque de configuración, versión de PHP $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Ajuste | Qué introducir |
|---|---|
| base_url | La URL del endpoint RESTful de tu cuenta de Cams API Monitor |
| stgid | Tu ID de Service Tag. |
| auth_token | Tu AuthToken, incluido en tus solicitudes RESTful salientes y comprobado frente al AuthToken de las solicitudes de callback entrantes. |
|
Mantén los tokens fuera del código compartido Para una prueba rápida, escribir los valores en el bloque de configuración es aceptable. Antes de producción, traslada los tokens a variables de entorno o a un gestor de secretos, para que nunca acaben en el control de versiones ni en un archivo compartido. |
Una vez configurado e implementado en una dirección HTTPS pública, establece esa dirección como la URL de Callback en Cams Gateway. A partir de ese momento, cada escaneo verificado llegará a tu receptor en tiempo real.
06 · Prueba antes de conectar dispositivos
Probar tu receptor
No necesitas un dispositivo biométrico para probar el receptor de callbacks. Envíale tú mismo la carga de ejemplo con cURL, usando un token de callback que coincida, y comprueba la respuesta.
|
Terminal, envía un callback de prueba # Guarda la carga de ejemplo como sample.json y envíala a tu receptor:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Respuesta esperada (HTTP 200):
# {"status":"done"}
|
| Prueba | Qué enviar | Resultado esperado |
|---|---|---|
| Evento válido | sample.json, con el AuthToken igual a tu auth_token | HTTP 200 con done, y el fichaje se guarda |
| Evento duplicado | La misma solicitud una segunda vez | HTTP 200 con done, y no se guarda ningún segundo registro |
| Token incorrecto | sample.json con un AuthToken diferente | Rechazado, y no se guarda nada |
| Evento de entrada | sample.json con Type cambiado a CheckIn | Guardado como entrada |
| Operación RESTful | Usa la interfaz de prueba HTML integrada para enviar una operación | Una respuesta con Status y StatusCode |
La interfaz de prueba HTML generada facilita probar el lado RESTful: abre el archivo en un navegador, elige una operación en el desplegable, ajusta el JSON precargado y envíalo. El visor de callbacks recientes de la misma página confirma que tus callbacks de prueba fueron recibidos.
07 · Lista de verificación para producción
Revisa antes de salir a producción
El código generado con IA es un punto de partida rápido y fiable, pero, como cualquier código, debe revisarse antes de manejar datos reales de empleados.
| Elemento | Listo cuando |
|---|---|
| Código revisado | Un desarrollador ha leído el archivo generado y entiende qué hace cada sección |
| Solo HTTPS | El receptor solo es accesible por HTTPS con un certificado válido |
| Tokens protegidos | Los AuthToken se guardan en variables de entorno o en un gestor de secretos |
| Duplicados gestionados | OperationID se guarda y se comprueba para ignorar los envíos repetidos |
| Almacenamiento adecuado | El almacenamiento en archivo JSON sirve para instalaciones pequeñas; las implementaciones más grandes pueden migrar a una base de datos de producción |
| Interfaz de prueba protegida | La página de prueba HTML tiene contraseña o está desactivada en servidores públicos |
| Fotos tratadas con cuidado | Las fotos de asistencia guardadas en disco tienen control de acceso y se conservan solo el tiempo necesario |
| Monitorización activa | Los errores y los volúmenes de callbacks inusuales se registran y generan alertas en tu propia monitorización |
|
Mantén las reglas de negocio en otro lugar La función del receptor es aceptar, verificar, enrutar, almacenar y confirmar. Decidir quién llega tarde, calcular las horas extra o enviar avisos corresponde a los sistemas que leen los eventos almacenados, como tu HRMS, ERP o herramientas de automatización. Un receptor centrado en una sola tarea es más fácil de proteger y mantener. |
Preguntas frecuentes
|
¿Tengo que escribir yo algún código? Normalmente no. Los prompts generadores de código con IA producen un archivo completo y funcional. Defines tres valores de configuración, lo implementas y lo pruebas. Aun así, un desarrollador debe revisar el código antes de producción. |
|
¿Qué asistentes de IA funcionan con los prompts? Cualquier asistente de programación con IA capaz, incluidos Claude, ChatGPT y Copilot. Pega todo el contenido del prompt de una vez para que el asistente tenga la especificación completa. |
|
¿Dónde encuentro la URL del endpoint RESTful y el ID de Service Tag? Ambos proceden de tu cuenta de Cams API Monitor. Las solicitudes RESTful se envían a la URL del endpoint con ?stgid= seguido de tu ID de Service Tag. |
|
¿Por qué responder con done a un evento duplicado? Porque el evento sí llegó correctamente, aunque ya lo hubieras guardado. Responder con done indica al Gateway que no necesita volver a enviarlo. |
|
¿Puedo usar un lenguaje que no aparece en la lista? Sí. El receptor de callbacks solo necesita aceptar un POST HTTPS y devolver JSON. Los prompts son un atajo, y la misma API funciona con cualquier lenguaje que pueda hacer eso. |
Conclusión: del prompt a la asistencia en tiempo real en una tarde
Un receptor de callbacks biométricos es pequeño, pero es la pieza que convierte cada escaneo verificado en datos en vivo para tu HRMS, nómina, paneles y automatizaciones. Con los prompts generadores de código con IA de Cams, ya no necesitas construirlo desde cero. Descarga el prompt para Python, Node.js o PHP, pégalo en tu asistente de IA, define tres valores y prueba. Después, revisa, protege y deja que los datos de asistencia en tiempo real empiecen a fluir.
Cams Biometrics Gateway entrega los eventos que necesita tu receptor. Su Callback API envía cada escaneo verificado en tiempo real, en un formato JSON uniforme, desde dispositivos de más de 15 marcas, y su RESTful API ofrece 27 operaciones que tu cliente generado puede invocar. Toda la comunicación se realiza mediante HTTP/HTTPS con validación de auth token y cifrado AES-256 opcional. Explora la plataforma en CamsBiometrics.com y consulta la documentación completa de Web API, incluidos todos los prompts generadores de código con IA: Obtener prompts.