Engineering

Diseñar una API de Asistencia Biométrica Que los Desarrolladores Realmente Quieran Usar

La mayoría de las API biométricas son parches sobre SDKs de hardware. Así diseñamos la API REST de PunchConnect desde cero — con webhooks, idempotencia y entrega en tiempo real que los desarrolladores esperan de infraestructura moderna.

PunchConnect Team·Mar 28, 2026·10 min read

Introduction

Has construido un sistema de nómina. La planilla depende de los datos de asistencia. Ahora necesitas obtener los eventos de fichaje de 200 dispositivos biométricos en tu sistema — de forma confiable, en tiempo real, sin perder un solo registro. Ese es el problema de diseño de API del que nadie habla hasta que están depurando fichajes perdidos a las 2 de la mañana.

La mayoría de las "API" biométricas son SDKs de fabricante disfrazados de REST. Exponen registros crudos del dispositivo, requieren bucles de polling y fallan cuando un reloj checador se desconecta 30 segundos. No fueron diseñadas para aplicaciones cloud-native.

Cuando construimos la API de PunchConnect, partimos del otro extremo: ¿qué esperaría un desarrollador que construye una integración ERP? La respuesta se parecía mucho a Stripe, Twilio y GitHub — no a un manual de hardware.

Tres Principios de Diseño Tomados de los Mejores

Estudiamos las API que los desarrolladores realmente disfrutan usar. Tres patrones aparecían una y otra vez:

1. Ser predecible. Cada endpoint sigue la misma convención de nombres. Cada respuesta tiene la misma forma. Cada error retorna un objeto estructurado con un code legible por máquina y un message legible por humanos. Sin sorpresas.

2. Ser tiempo real. Webhooks para eventos, no polling. Cuando un empleado ficha en la puerta, tu aplicación lo sabe en segundos — no cuando tu job cron se ejecuta.

3. Ser resiliente. Cada operación mutante acepta una llave de idempotencia. Cada entrega webhook se reintenta con backoff exponencial. Cada dato puede ser reproducido sin duplicados.

El Pipeline de Entrega de Webhooks

La parte más difícil de una API de asistencia biométrica no son los endpoints REST — es garantizar la entrega de eventos de fichaje cuando el mundo real es inestable. Los dispositivos se desconectan. Las redes caen. Los servidores se reinician durante despliegues.

PunchConnect garantiza entrega al-menos-una-vez para cada evento webhook:

1. El empleado ficha en el dispositivo biométrico (huella, rostro, tarjeta)
2. El evento se persiste en una cola durable — seguro incluso si el sistema se reinicia
3. El worker de entrega envía un HTTP POST a tu URL de callback registrada
4. Tu servidor responde con 2xx → evento marcado como entregado
5. Si la entrega falla (5xx, timeout, error de red) → reintentos con backoff exponencial por 72 horas
6. Después de agotar reintentos → evento marcado como fallido, notificación email enviada

Payload del Webhook

Cada webhook entrega un objeto JSON limpio y normalizado:

json

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "attendance.punch",
  "timestamp": "2026-03-28T08:01:23Z",
  "device": {
    "id": "dev_9x8y7z",
    "serial_number": "BKRK233600045",
    "name": "Entrada Principal",
    "site": "Oficina Central"
  },
  "employee": {
    "id": "emp_4k5l6m",
    "badge_number": "1042",
    "name": "Sarah Chen"
  },
  "punch": {
    "direction": "in",
    "method": "fingerprint",
    "confidence": 0.97,
    "local_time": "2026-03-28T09:01:23+01:00"
  },
  "metadata": {
    "deduplicated": false,
    "delivery_attempt": 1
  }
}

Recibir Webhooks en Tu Aplicación

Python (Flask)

python

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_tu_secreto_de_firma"

def verify_signature(payload, signature):
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

@app.route("/webhooks/attendance", methods=["POST"])
def handle_attendance():
    signature = request.headers.get("X-PunchConnect-Signature")
    if not verify_signature(request.data, signature):
        return jsonify({"error": "Firma inválida"}), 401

    event = request.json
    if event["event_type"] == "attendance.punch":
        employee = event["employee"]["badge_number"]
        direction = event["punch"]["direction"]
        timestamp = event["timestamp"]
        print(f"Empleado {employee} fichó {direction} a las {timestamp}")

    return jsonify({"received": True}), 200

Node.js (Express)

javascript

const express = require('express');
const crypto = require('crypto');
const app = express();

const WEBHOOK_SECRET = 'whsec_tu_secreto_de_firma';

app.post('/webhooks/attendance', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-punchconnect-signature'];
  const expected = `sha256=${crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')}`;

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Firma inválida' });
  }

  const event = JSON.parse(req.body);
  if (event.event_type === 'attendance.punch') {
    const { badge_number } = event.employee;
    const { direction } = event.punch;
    console.log(`Empleado ${badge_number} fichó ${direction} a las ${event.timestamp}`);
  }

  res.json({ received: true });
});

app.listen(3000, () => console.log('Listener webhook activo en :3000'));

cURL — Registrar Tu Webhook

bash

curl -X POST https://api.punchconnect.com/v1/webhooks \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-app.com/webhooks/attendance",
    "events": ["attendance.punch", "device.status"],
    "secret": "whsec_tu_secreto_de_firma"
  }'

Idempotencia: Cada Comando Es Seguro de Reintentar

Las fallas de red pasan. Tu solicitud expira. ¿El dispositivo recibió el comando o no? Sin idempotencia, estás adivinando.

PunchConnect acepta un header Idempotency-Key en cada endpoint mutante:

Esto es crítico para comandos de dispositivo — sincronización de listas de empleados, actualización de reglas de acceso. Sin idempotencia, un simple reintento podría registrar empleados dos veces.

bash

curl -X POST https://api.punchconnect.com/v1/devices/dev_9x8y7z/commands \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Idempotency-Key: sync-empleados-2026-03-28-001" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "sync_employees",
    "payload": {
      "employees": [
        {"badge_number": "1042", "name": "Sarah Chen"},
        {"badge_number": "1043", "name": "James Okoro"}
      ]
    }
  }'

Rate Limiting Transparente

Los límites por defecto son generosos: 1,000 llamadas REST por dispositivo por día. Los webhooks entrantes (dispositivo → PunchConnect) son ilimitados.

Cumplimiento normativo para LATAM: En México, PunchConnect facilita el cumplimiento de la NOM-035 para registro de jornadas laborales. En Colombia, cumple con los requisitos de registro de asistencia de la legislación laboral. Los datos transitan cifrados por HTTPS y los webhooks soportan verificación HMAC-SHA256.

Normalización de Datos

Los datos de dispositivos biométricos son desordenados: fichajes duplicados, timestamps desfasados, registros corruptos. PunchConnect normaliza todo:

- Detección de duplicados — Mismo empleado, mismo dispositivo en ventana configurable (default: 60 seg) → filtrado
- Normalización de timestamps — Reconciliación reloj dispositivo/servidor, entrega en UTC
- Inferencia de dirección — Reglas configurables (primer fichaje = entrada, último = salida, o alternancia)
- Filtrado de datos inválidos — Registros malformados, timestamps cero, números de badge no registrados → capturados y registrados en log

Lo Que 24,000+ Empleados Nos Enseñaron

Ejecutar PunchConnect en 50+ sitios para los 24,000+ empleados de AgriWise nos enseñó cosas que ninguna teoría de diseño de API podía:

La deriva de reloj es real. Dispositivos en zonas horarias y redes inestables se desfasan. La normalización UTC no es opcional.

El buffering offline es obligatorio. Sitios agrícolas rurales pierden internet por horas. Los relojes checadores almacenan fichajes localmente. Cuando vuelve la conectividad, todo se procesa en orden.

Las operaciones batch importan. Sincronizar 5,000 empleados en 50 dispositivos requiere endpoints batch con seguimiento de progreso y manejo de fallas parciales.

Preguntas Frecuentes

¿Qué tan rápida es la entrega de webhooks?
Generalmente menos de 2 segundos desde el fichaje hasta la recepción en tu webhook. El cuello de botella suele ser el intervalo de push del dispositivo, no el procesamiento de PunchConnect.

¿Qué pasa si mi endpoint está caído por horas?
Los eventos se acumulan y se reintentan con backoff exponencial por 72 horas. Cuando tu servidor vuelve, recibes todos los eventos perdidos en orden.

¿Puedo reproducir eventos webhook históricos?
Sí. La API de gestión de webhooks te permite reproducir eventos para un rango de tiempo dado.

¿Necesito manejar entregas webhook duplicadas?
Con entrega al-menos-una-vez, es posible recibir el mismo evento dos veces. Usa el campo event_id para deduplicación — es único por evento y estable entre reintentos.

¿Cómo pruebo webhooks durante desarrollo?
Registra una URL de webhook apuntando a ngrok o webhook.site. PunchConnect entregará eventos reales de tus dispositivos de prueba a tu máquina local.

---

¿Construyendo una integración biométrica? PunchConnect te da la API que diseñarías tú mismo — si tuvieras seis meses y 24,000 empleados para probar. Inicia una prueba gratuita de 7 días y recibe tu primer webhook en menos de 5 minutos. Sin tarjeta de crédito. Sin IP fija. Solo datos limpios, entregados de forma confiable.