El problema.
El titular dirige una consultora especializada en suelo industrial (naves, locales, oficinas, edificios, terrenos). Su equipo son siete comerciales con recorridos muy distintos: dos socios de referencia, un perfil senior consolidado y cuatro comerciales construyendo cartera. Entre ellos trabajan operaciones de tres tipos — venta, alquiler, asesoramiento — sobre cinco clases de inmueble.
La complejidad no estaba en el volumen sino en el modelo de compensación. Conviven tres esquemas en paralelo:
- Grupo 1 (cuatro comerciales en construcción de cartera): tramos progresivos por operación según acumulado YTD.
- Grupo 2 (un senior consolidado): porcentaje fijo.
- Grupo 3 (los dos socios): porcentaje sobre la media de facturación de ambos.
Y cada operación se reparte internamente entre seis roles que suman 100 % sobre la base imponible: Captador, Cartel, Visitas, Negociación, Firma y Cobro. En una misma operación puede participar una persona en dos roles, o dos personas partiéndose uno 50/50. Encima, una comisión sólo se devenga cuando la factura en Holded pasa a estado COBRADA — no hay pagos parciales, y si una factura se anula hay que ajustar hacia delante.
El titular llevaba todo esto en un Excel maestro con siete pestañas y fórmulas cruzadas. El cierre era trimestral porque recalcular a mano cada mes era inviable. Los comerciales llamaban para preguntar cuánto llevaban, el titular abría el Excel, contestaba de memoria o por estimación, y al cerrar el trimestre se encontraba con diferencias que había que justificar.
Tenía un Excel con siete pestañas, tres fórmulas distintas y nunca sabía al minuto lo que tocaba a cada uno. Los comerciales preguntaban, yo iba a ver, se colaban errores y al cerrar el trimestre tocaba justificar diferencias. Necesitaba que la operación se metiera una sola vez, que el reparto se calculara solo y que lo suyo lo viera cada uno en tiempo real.
Qué construimos.
WebApp de entrada con acceso segmentado por rol
Una webapp desplegada en Vercel con branding corporativo del cliente — paleta navy + dorado, Roboto Condensed + Open Sans, esquinas rectas — a la que entran tanto el titular como los siete comerciales, cada uno con su credencial. La visibilidad está segmentada:
- Titular (rol admin): ve la plataforma completa. Lista de todas las operaciones con filtros (estado, tipo de operación, tipo de inmueble, búsqueda libre), formulario completo para dar de alta operaciones, acceso al BI agregado, gestión de clientes Holded y capacidad de marcar como cobrada una factura (acción que actualiza Data Table + marca pagada en Holded en un solo movimiento).
- Comerciales (rol agente): entran al mismo dominio con su usuario y sólo ven sus propias operaciones. Pueden dar de alta una operación nueva desde el mismo formulario de cuatro secciones colapsables (datos de factura, datos de operación, reparto de roles, resumen por agente) con auto-cálculos de IVA, total, €/m² y reparto automático sobre la base imponible. No ven operaciones ajenas, no acceden a clientes no suyos, no pueden marcar como cobrada, no ven el BI agregado de la casa ni el ranking cruzado.
Esto eliminó el cuello de botella que tenía el titular tecleando operaciones que le iban llegando por email, WhatsApp y de viva voz. La operación la mete ahora quien la cierra, con el reparto de roles ya acordado, y cuando llega a la cola del titular está lista para contabilizar. El dropdown de clientes se pobla en tiempo real desde Holded, con un botón para crear cliente nuevo sin salir del flujo (permiso reservado al titular; los comerciales sólo seleccionan de la lista existente).
Motor de comisiones con tres grupos y seis roles
Toda la lógica vive en el workflow principal de n8n — 33 nodos, webhook en /nueva-operacion — que valida la operación, genera un op_id, calcula IVA y totales, persiste la cabecera en la Data Table de operaciones y el desglose de roles en la Data Table de roles, y dispara la creación de factura en Holded. El nodo de comisiones aplica la regla correcta según el grupo del comercial: escalado progresivo con tier YTD para el Grupo 1, fijo para el senior, media compartida para los socios. El reparto de roles siempre se calcula sobre la base imponible, no sobre el fee. El workflow devuelve el número de factura de Holded al frontend, que lo pinta en la lista de operaciones al instante.
Integración bidireccional con Holded
Holded es la fuente única de verdad. Cinco endpoints están cableados a webhooks de n8n: listar clientes, crear cliente, crear factura, marcar pagada y verificar estado. La creación de factura sale desde la propia webapp al guardar la operación — no hay doble tecleo. Y como las comisiones sólo se devengan cuando la factura está cobrada, un segundo workflow recorre cada 4 horas las operaciones con estado PENDIENTE en la Data Table, consulta Holded y, si la factura aparece pagada, actualiza el estado a COBRADA y dispara el recálculo del BI.
BI Dashboard con vistas por rol
Un segundo frontend (Tailwind + Alpine.js + Chart.js) con login multi-usuario y dos vistas mutuamente excluyentes:
- Vista admin del titular: cinco scorecards de resumen ejecutivo, tendencia de facturación, ranking de agentes, donuts por tipo de inmueble y operación, tabla comparativa de rendimiento, heatmap de comisiones, análisis de €/m², aging de cobros y top clientes. Export CSV para contabilidad.
- Vista individual por comercial: cuatro scorecards propios, barra de progreso del tramo actual sobre el acumulado YTD (clave para el Grupo 1, que necesita saber en qué banda está cobrando cada operación), facturación mensual propia y tabla filtrada a las operaciones en las que participan. Nunca ven operaciones ajenas ni el ranking cruzado — sólo su propio dashboard.
La Data Table se consulta vía webhook /bi/dashboard-summary que calcula comisiones y devuelve el JSON ya agregado y filtrado según el rol — el dashboard no hace lógica de negocio ni filtrado sensible en cliente, sólo renderiza lo que el backend autoriza.
Cierre mensual y exportación
La tabla de operaciones del BI admin admite export CSV para contabilidad, y el workflow de cierre se dispara mensualmente agrupando por comercial, grupo y rol. Lo que antes era un ritual trimestral de tardes con el Excel ahora es un clic.
Cómo lo implementamos.
Seguimos nuestras 5 fases estándar — ver proceso completo — comprimidas en 4 semanas por el alcance acotado y el hecho de que el titular tenía el modelo de comisiones ya cristalizado en el Excel: no había que descubrir reglas, había que traducirlas y habilitar la entrada distribuida por rol.
- Semana 1 · Descubrimiento + UI/UX spec: reunión inicial con el titular. Inventariamos comerciales y grupos, mapeamos los 3 esquemas de compensación, los 6 roles por operación y los 5 tipos de inmueble, y definimos la matriz de permisos admin / agente. Documento de especificación UI/UX con las 6 pantallas, auto-cálculos y reglas de validación antes de tocar código.
- Semana 2 · Desarrollo core: webapp de entrada en HTML + Tailwind + Alpine.js con el formulario de 4 secciones colapsables, login con sesión 7 días y auto-cálculos. Workflow principal n8n (33 nodos) con los 6 webhooks de producción. Data Tables de operaciones y roles con su schema completo. Segmentación de permisos admin / agente cableada en los webhooks (el rol llega firmado en la request y filtra lo que devuelve n8n).
- Semana 3 · Integración Holded + BI: cinco endpoints de Holded cableados — contactos, creación de factura, marcar pagada, verificar estado. Workflow secundario de sync de cobros cada 4 horas. BI Dashboard con vista admin (5 scorecards, ranking, heatmap, aging) y vistas individuales por comercial con progreso de tramo, aisladas a sus propias operaciones.
- Semana 4 · Deploy y onboarding: deploy a Vercel con
vercel.json(proxy rewrites/webhook/*→ n8n, headers no-cache, CSP ajustado). Onboarding de los 7 comerciales con su credencial individual. Carga inicial de clientes en Holded. Activación de webhooks en producción.
Problemas resueltos en ruta — los dejamos documentados porque se van a repetir en futuros proyectos sobre la misma pila: webhooks n8n que no registran hasta reiniciar el servicio en Easypanel; Data Tables vacías que no emiten items y matan los nodos downstream (se envuelven en try/catch); CORS desde Vercel resuelto con proxy rewrites en vercel.json; CSP sandbox de Vercel que bloqueaba el fetch (se sobreescribe CSP vacío en headers); desfase snake_case ↔ camelCase entre n8n y la webapp que se mapea en loadOperations; clientes duplicados al pintar el dropdown ([...new Set()] + :key="idx"); overflow:hidden del plugin x-collapse que cortaba el dropdown de clientes, reemplazado por x-show puro en la sección crítica.
Stack utilizado.
n8n (6 workflows · 33 nodos en el principal)Data Tables n8nHolded API (contactos + documents/invoice + pay)VercelHTML + Tailwind CSSAlpine.jsChart.jsProxy rewrites VercellocalStorage · sesión 7 días · segmentación admin/agente