Diseñando una API de Asistencia Biométrica

Principios de diseño

Al diseñar la API de PunchConnect, estudiamos las APIs que más admiramos: Stripe por su consistencia, Twilio por sus webhooks y GitHub por la experiencia del desarrollador. Surgieron tres principios:

1. Ser predecible — nombres consistentes, formatos de respuesta y códigos de error en cada endpoint

2. Ser en tiempo real — webhooks para eventos, no polling. Los desarrolladores deben reaccionar a los eventos, no verificarlos.

3. Ser resiliente — cada operación debe ser segura para reintentar. Claves de idempotencia, deduplicación y entrega al menos una vez.

Garantías de entrega de webhooks

PunchConnect garantiza la entrega al menos una vez para todos los eventos de webhook. Así es como funciona:

Cuando ocurre un evento de fichaje, se escribe en una cola durable. Un worker de entrega lo recoge y envía el HTTP POST a tu URL de callback. Si tu servidor responde con 2xx, el evento se marca como entregado.

Si tu servidor está caído o responde con 5xx, el evento se reintenta con backoff exponencial: 1 min, 5 min, 30 min, 2 horas, 12 horas, 72 horas. Después de agotar todos los reintentos, el evento se marca como fallido y se te notifica por correo electrónico.

Estrategia de rate limiting

Usamos un rate limiter de ventana deslizante con valores predeterminados generosos: 1.000 llamadas API por dispositivo por día para endpoints REST, e ilimitado para webhooks entrantes (dispositivo → PunchConnect).

Los límites de tasa se comunican mediante headers estándar: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Cuando alcanzas el límite, recibes una respuesta 429 con un header Retry-After.

Idempotencia

Todos los endpoints mutantes (POST, PUT, DELETE) aceptan un header Idempotency-Key. Si envías la misma solicitud con la misma clave dentro de 24 horas, obtienes la respuesta en caché en lugar de crear un duplicado.

Esto es crítico para los comandos de dispositivos. Si envías un comando "sincronizar empleados" y tu red se cae antes de recibir la respuesta, puedes reintentar con seguridad sin activar accidentalmente una sincronización doble.

Lecciones aprendidas

La mayor lección: los datos biométricos del mundo real son desordenados. Los dispositivos envían fichajes duplicados, timestamps desordenados y ocasionalmente datos basura. Nuestra API normaliza y deduplica antes de que tu webhook lo reciba, para que obtengas datos limpios y confiables.