El error que se paga con un fork
Es la evolución típica: el primer cliente tiene el modelo A y tu SaaS lo soporta bien. El segundo tiene el modelo B — y de repente tu backend tiene if modelo == "B" esparcido por todas partes. Al tercer modelo, el feature que era "integrar marcadores" se convirtió en "mantener tres adaptadores", y cada release es una culebra de riesgo.
La causa de fondo: el software se acopló al modelo cuando debió acoplarse al contrato. Los terminales son hardware heterogéneo — modelos, firmwares, periféricos — pero tu lógica de negocio solo necesita un contrato: "pasó algo, con esta persona, con este método, a esta hora, en este terminal". Diseñar para ese contrato es lo que hace el software agnóstico del modelo.
Principio 1: el serial es la llave, no el modelo
Todo lo que consume de un terminal — reportes, eventos, usuarios, credenciales — debe direccionarse por su número de serie, nunca por su modelo. El serial es estable, único y no cambia cuando el firmware se actualiza.
En API Connect, el serial direcciona todos los endpoints: /report/{serial}, gestión de usuarios, credenciales, grupos. Tu SaaS ni necesita saber (ni beneficia de saber) si el terminal es un equipo de escritorio o uno de rostro.
Principio 2: el terminal es una caja negra
Tu SaaS no debe modelar el interior del dispositivo (plantillas, firmware, memoria) sino su superficie de contrato: qué eventos emite y qué gestión acepta. Cuando la capa de hardware la mantiene una API como API Connect, esa superficie queda definida y estable — aunque debajo cambien modelos y firmwares.
Prueba de acoplamiento: si mañana tu cliente cambia un terminal por otro modelo distinto, ¿tu SaaS necesita release? Si la respuesta es sí, hay acoplamiento al modelo. Con la abstracción correcta, la respuesta es: se registra el serial nuevo y listo.
Principio 3: tu modelo de datos no es el del terminal
El terminal tiene "personas con PIN"; tu SaaS tiene empleados, residentes o socios con su ciclo de vida. Mantén esa frontera: tu tabla de personas mapea a la del terminal vía PIN/tarjeta, y el ciclo de vida (alta, cambio, baja) lo orquesta tu software vía API — no una importación manual en el menú del equipo.
Los flujos de credenciales por serial (alta con PIN y tarjeta, asignación a grupos de acceso, baja) te permiten orquestar sin tocar el hardware y sin duplicar su modelo interno.
Principio 4: normaliza los eventos
Un mismo acceso puede llegar por huella, tarjeta, PIN o rostro. Tu lógica de negocio — asistencia, notificaciones, conteos — debe consumir un registro normalizado:
- Persona (PIN/tarjeta) y método de verificación.
- Fecha/hora exactas del evento.
- Terminal de origen (serial) y dirección (entrada/salida, puerta).
- Resultado: otorgado, denegado, con su causa.
Con ese contrato, no importa qué modelo generó el evento: la nómina calcula horas, la portería notifica y la auditoría registra — todos con el mismo flujo de código.
Qué capas debe abstraer una buena API de hardware
| Capa | Si la abstrae la API | Si la maneja tu SaaS |
|---|---|---|
| Protocolo del dispositivo | REST/JSON uniforme | Adaptador por modelo/firmware |
| Conectividad (red del cliente) | Modo push: el equipo sale a la nube | IP fija, puertos, VPN por sede |
| Variedad de modelos | Serial como llave única | Ramas if modelo |
| Eventos en tiempo real | Webhook/stream normalizado | Polling e ingeniería de colas propia |
| Plantillas biométricas | Gestiona el equipo/plataforma | Riesgo y compliance en tu DB |
Cómo probar el diseño multi-modelo
La verificación práctica: mezcla modelos en pruebas. Con API Connect registras terminales de distintos modelos en la misma cuenta (y simulas la variedad desde el sandbox/trial), y verificas que tu SaaS — reportes, notificaciones, conciliación — funcione sin cambiar una línea. Si algún flujo se rompe, ahí hay un acoplamiento escondido; mejor detectarlo en pruebas que en la sede del cliente.
Preguntas frecuentes
¿Mi SaaS debe saber el modelo del terminal?
No: tu software trabaja con serial y eventos. Soportar un modelo nuevo es registrar el equipo, no escribir código.
¿Cómo normalizo métodos de verificación distintos?
Con un registro por evento: persona, método, fecha/hora, terminal y resultado. Tu lógica consume ese contrato, no el modelo que lo generó.
¿Y si el cliente mezcla modelos viejos y nuevos?
La plataforma gestiona la variedad: todos los terminales se consumen por la misma API. Tu flota puede mezclar generaciones sin que tu código lo note.
Prueba tu arquitectura con equipos reales y virtuales
Registra terminales de distintos modelos y valida que tu SaaS no cambia. 14 días gratis, sin tarjeta.