Support Hub/API & Integrations/Cómo crear un receptor de callbacks biométricos en Python,…
Translated from the English article and reviewed by a person. Read the English original
Developer

Cómo crear un receptor de callbacks biométricos en Python, Node.js y PHP

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.

1

Descarga el archivo de prompt

Elige tu lenguaje en la siguiente sección y descarga su archivo de prompt .txt.

2

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.

3

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.

Python

Flask, SQLite, solo biblioteca estándar

Obtener prompt de Python

Node.js

Express, almacenamiento en archivo JSON

Obtener prompt de Node.js

PHP

PHP puro, SQLite, sin Composer

Descargar prompt de PHP

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.

 

Was this article helpful?