Tutorial

De Herramienta Interna a Producto API: La Historia de PunchConnect

Cómo transformamos una integración biométrica interna construida para 24,000 empleados en un producto API REST cloud — y qué aprendimos en el camino.

PunchConnect Team·Mar 28, 2026·5 min read

Introduction

PunchConnect no estaba destinado a ser un producto. Nació de la frustración — y 4 meses de producción intensiva.

Estábamos construyendo AgriWise, una plataforma de gestión de personal para empresas agrícolas en Marruecos. 24,000+ empleados en decenas de sitios. Cada sitio tenía relojes checadores biométricos ZKTeco. Y necesitábamos obtener los datos de asistencia en tiempo real en nuestra aplicación cloud.

Nada en el mercado funcionaba. Así que lo construimos nosotros mismos.

El Problema Que Lo Inició Todo

De Un Cliente a una Plataforma

Después de 6 meses en producción con AgriWise, seguíamos escuchando la misma pregunta: "¿Cómo conectan los dispositivos ZKTeco al cloud?"

No construimos un demo. Abrimos nuestro sistema de producción. El mismo motor que maneja los 24,000+ empleados de AgriWise alimenta cada llamada API de PunchConnect.

Las Decisiones de Ingeniería Clave

1. Multi-Inquilino con Aislamiento por Dispositivo

python

@app.route("/v1/devices", methods=["GET"])
@require_api_key
def listar_dispositivos():
    tenant_id = request.auth.tenant_id
    dispositivos = db.query(
        "SELECT * FROM devices WHERE tenant_id = %s", [tenant_id]
    )
    return jsonify({"devices": dispositivos})

2. Diseño de API: Lecciones de Stripe

- Formato de respuesta consistente en cada endpoint
- Códigos de error claros con identificadores específicos
- Claves de idempotencia en cada operación mutativa

3. Sistema de Entrega Webhook con Reintentos

python

RETRASOS_RETRY = [10, 60, 300, 1800, 7200]  # segundos

def entregar_webhook(url: str, payload: dict, secreto: str):
    body = json.dumps(payload)
    firma = hmac.new(
        secreto.encode(), body.encode(), hashlib.sha256
    ).hexdigest()
    
    for intento, retraso in enumerate(RETRASOS_RETRY):
        try:
            resp = requests.post(url, data=body, headers={
                "Content-Type": "application/json",
                "X-PunchConnect-Signature": firma,
            }, timeout=10)
            if resp.status_code < 300:
                return True
        except requests.RequestException:
            pass
        time.sleep(retraso)
    return False

4. La Documentación Como Producto

Para una herramienta interna, la documentación es una wiki que nadie lee. Para un producto API, la documentación ES el producto.

En México, esta solución cumple con la NOM-035-STPS. En Colombia, facilita el cumplimiento del Art. 161 del CST para control de jornada laboral.

Lo Que Aprendimos

| Métrica | Interno (AgriWise) | Producto (PunchConnect) |
|---------|-------------------|----------------------|
| Dispositivos | 80+ | En crecimiento |
| Empleados | 24,000+ | Variable por cliente |
| Disponibilidad | 99.7% | 99.7% (mismo motor) |
| Latencia webhook | 340ms prom. | 340ms prom. |
| Registros perdidos | Cero | Cero |
| Tiempo a primera integración | 4 meses | Menos de 5 minutos |

FAQ

¿PunchConnect sigue siendo usado internamente por AgriWise?

Sí. AgriWise funciona exactamente sobre el mismo motor. Las pruebas en producción nunca paran.

¿Cuánto toma integrar PunchConnect?

La mayoría de desarrolladores reciben su primer webhook en 5 minutos.

¿Qué dispositivos soporta PunchConnect?

Dispositivos biométricos ZKTeco — la marca más desplegada globalmente. SpeedFace, ProFace, UA860, K40, MB460 y la mayoría de modelos con conectividad de red.

¿En qué se diferencia de bibliotecas open-source como pyzk?

Las bibliotecas como pyzk se conectan por LAN — un dispositivo a la vez. PunchConnect es un servicio cloud: los dispositivos se conectan de salida, funcionan en cualquier red, manejan buffering offline y entregan datos vía webhooks.

¿Puedo probarlo antes de comprometerme?

Sí. Prueba gratis de 7 días con acceso completo a la API, sin tarjeta de crédito.

---

Prueba PunchConnect gratis por 7 días — de cero al primer webhook en menos de 5 minutos.