# Factronics × Hermes — Guía de Ejecución Paso a Paso
**Para:** Pablo y equipo Coordenadas
**Propósito:** Saber exactamente qué hacer, en qué orden, con quién y qué necesitas tener listo
**Nivel:** For dummies — sin asumir nada
---
## ANTES DE EMPEZAR — Checklist de inputs que debes tener
Antes de hacer cualquier cosa técnica, necesitas estos insumos. Sin ellos, nada avanza.
| Input | Quién lo tiene | Status |
|---|---|---|---|
| Acceso a QuickBooks Desktop de Factronics (servidor Windows dedicado) | Jovan / contabilidad | Pendiente |
| 5-10 POs reales históricas en PDF (NSP, Bauducco, otros) | Jovan / contabilidad | Pendiente |
| Credenciales Google Workspace de accounting@ y jovan.gutic@ | Jovan | Pendiente |
| Acceso a Slack de Factronics (o crear workspace nuevo) | Jovan | Pendiente |
| Dominio para el panel de operaciones (o comprar uno nuevo) | Tú | Pendiente |
| Cuenta de Hostinger con VPS | Tú | Pendiente |
| Cuenta de Cloudflare (puede ser la tuya de la agencia) | Tú | Pendiente |
| API Key de Anthropic (Claude) — cuenta de pago | Tú | Pendiente |
| API Key de OpenAI (Assistants API) — cuenta de pago | Tú | Pendiente |
| IDs de los Custom GPTs de Factronics (OpenAI) | Jovan | Pendiente |
| API Key de la plataforma de tareas (Airtable/ClickUp/Trello) | Jovan | Pendiente |
| QB Web Connector (QBWC) — descargar de Intuit Developer | Tú | Pendiente |
| Acceso a HubSpot API (token privado) | Jovan | Pendiente |
---
## FASE 1 — DISCOVERY
**Duración:** 1 semana
**Objetivo:** Entender exactamente cómo funciona el negocio antes de escribir una sola línea de código
---
### REUNIÓN 1 — Kick-off con Jovan
**Quién:** Tú + Jovan
**Duración:** 45-60 minutos
**Formato:** Video call o presencial (mejor presencial si puedes ir a Medley)
**Cuándo hacerla:** Lo antes posible, esta semana si es posible
**Qué decirle al inicio:**
> "Jovan, antes de empezar a construir cualquier cosa, necesito entender exactamente cómo funciona tu operación hoy. Voy a hacerte preguntas básicas — algunas van a parecer obvias, pero necesito los detalles para que el sistema funcione bien desde el primer día."
**Preguntas que debes hacer — QuickBooks:**
- ¿En qué computadora está instalado QuickBooks Desktop? ¿Ya tienes el servidor Windows dedicado listo?
- ¿Esa computadora está encendida todos los días durante el horario laboral (L-V 7 AM - 7 PM)?
- ¿Cuántas personas usan QuickBooks actualmente? ¿Desde una sola computadora o desde varias?
- ¿Tienen contraseña para entrar a QuickBooks? ¿Quién la sabe?
- ¿El servidor Windows tiene acceso a internet? (el QBWC necesita conectarse al SOAP endpoint)
- ¿La misma QuickBooks maneja Factronics USA y FACCA Caracas, o son archivos separados?
**Preguntas que debes hacer — Emails y POs:**
- Cuando llega una PO de NSP o Bauducco, ¿llega siempre al mismo email (accounting@)?
- ¿Siempre llegan en PDF? ¿O a veces son Excel, Word, imagen escaneada?
- ¿Los PDFs vienen del sistema de ellos (SAP, Oracle) o son documentos manuales?
- ¿Cuántas POs recibes en una semana típica? ¿Y en semana pico?
- ¿Cuando hay un error de precio, quién lo detecta hoy? ¿Cómo se comunica?
- ¿A qué email llegan las POs de cada cliente? (¿todos a accounting@ o algunos a jovan@?)
**Preguntas que debes hacer — Inbox de Jovan:**
- ¿Cuántos emails recibes en promedio por día en jovan@?
- ¿Cuáles son los clientes que más te escriben y que más tiempo te toman?
- ¿Cuando Nestlé o NSP te manda algo técnico, cuánto tiempo te toma responder?
- ¿Tienes alguna plantilla o respuesta que uses repetidamente? ¿Puedes compartirla?
- ¿En qué idioma responde a cada cliente? (quiero mapearlo)
**Preguntas que debes hacer — Custom GPTs (OpenAI):**
- ¿Qué Custom GPTs tienes creados en ChatGPT? ¿Qué contenido tiene cada uno?
- ¿Puedes compartirme los IDs de los asistentes o acceso para revisarlos?
- ¿Qué información técnica NO está cubierta en los GPTs actuales?
**Preguntas que debes hacer — Plataforma de Tareas (Agente 3):**
- ¿Usan actualmente Airtable, ClickUp, Trello o alguna otra plataforma para gestionar tareas?
- ¿O prefieren que recomendemos una? (Airtable es la más flexible para este caso)
- ¿El equipo de Caracas ya usa esta plataforma o sería nueva para ellos?
**Preguntas que debes hacer — Onboarding de Clientes (Agente 4):**
- ¿Cómo es el proceso hoy cuando un prospecto se convierte en cliente?
- ¿Quién envía los formularios de registro? ¿Hay un formulario estándar?
- ¿Quién verifica la información del cliente antes de crearlo en QB?
- ¿Manejan certificados de reventa de Florida? ¿Cómo los verifican hoy?
**Preguntas que debes hacer — HubSpot:**
- ¿Qué campos personalizados tienen en el CRM?
- ¿Tienen pipelines definidos para ventas y servicio?
- ¿Quieres que el agente pueda mover deals de etapa automáticamente basado en análisis de los emails?
**Al final de esta reunión debes salir con:**
- [ ] Claridad sobre el servidor Windows dedicado para QB y su disponibilidad
- [ ] 5-10 POs reales en PDF para pruebas (pídelas antes de terminar la reunión)
- [ ] IDs de los Custom GPTs de Factronics (o plan para mapearlos)
- [ ] Confirmación de la plataforma de tareas (Airtable/ClickUp/Trello) + API key
- [ ] Comprensión del flujo de onboarding de clientes actual
- [ ] Acceso a HubSpot API o confirmación de crear token
- [ ] Fecha para la Reunión 2 (con el equipo de contabilidad)
---
### REUNIÓN 2 — Con el equipo de contabilidad
**Quién:** Tú + la persona que procesa las POs en QB hoy (no Jovan)
**Duración:** 30-45 minutos
**Formato:** Presencial en Medley si puedes — necesitas ver la pantalla de QB en vivo
**Qué decirle al inicio:**
> "Quiero que me muestres exactamente cómo procesas una PO, paso a paso, como si yo no supiera nada. Desde que te llega el email hasta que queda en QuickBooks."
**Lo que debes observar y anotar:**
- Cómo abre el PDF de la PO
- Cómo busca al cliente en QB
- Dónde escribe el número de PO en QB
- Cómo agrega los items (¿los busca por código, por nombre?)
- Cómo pone el precio (¿lo copia de la PO o lo busca en QB?)
- Qué hace cuando un item no existe en QB
- Qué hace cuando el precio no coincide
- Cuánto tiempo le toma una PO típica vs una complicada
**Preguntas adicionales:**
- ¿Cuál es la PO más complicada que has procesado? ¿Por qué fue difícil?
- ¿Cuándo hay errores, de qué tipo suelen ser?
- ¿Hay clientes cuyas POs siempre traen problemas?
- ¿Qué campos de QB son obligatorios para crear una Sales Order?
- **¿QB Web Connector está instalado?** (pregunta para verificar compatibilidad)
- **¿La empresa de Factronics está en modo "Single-user" o "Multi-user"?** (QBWC requiere multi-user mode desactivado o configurado correctamente)
**Al final de esta reunión debes salir con:**
- [ ] Haber visto el proceso completo en pantalla
- [ ] Foto o captura de cómo se ve una Sales Order en QB (campos reales)
- [ ] Lista de los 5 clientes más frecuentes y cómo se llaman exactamente en QB
- [ ] Entender qué pasa cuando algo sale mal
- [ ] Verificar que QB responde correctamente a QBWC (haremos prueba en Semana 3)
---
### TAREA SOLO (después de las reuniones)
**Duración:** 2-3 horas
**Qué hacer:**
1. **Mapear el flujo actual en papel** (o en Notion/Miro):
- Email llega → quién lo ve → qué hace → cuánto tarda → qué crea en QB
- Hacer esto para cada uno de los 4 procesos del RFP
2. **Analizar las POs que te dio Jovan:**
- ¿Vienen todas en el mismo formato?
- ¿Tienen tablas limpias o están en formato raro?
- ¿Los códigos de producto en la PO coinciden con los códigos en QB?
- Clasificar: "fáciles de extraer" vs "complicadas"
3. **Documentar el mapeo de clientes:**
- Como se llama el cliente en sus POs vs como está en QB
- Ejemplo: "National Steak Processors" en la PO = "NSP" en QB
---
## FASE 2 — SETUP DE INFRAESTRUCTURA
**Duración:** 1 semana
**Objetivo:** Tener todas las plataformas instaladas y conectadas entre sí (sin agentes todavía)
---
### DÍA 1 — VPS y Coolify
**Paso 1: Comprar el VPS en Hostinger**
- Ir a hostinger.com → VPS → Plan KVM 2 (8GB RAM)
- Seleccionar OS: Ubuntu 22.04 LTS
- Seleccionar datacenter: USA East (para cercanía con Factronics en Florida)
- Anotar: IP pública del VPS, usuario root, contraseña
**Paso 2: Instalar Coolify**
- Conectarte al VPS por SSH: `ssh root@[IP-DEL-VPS]`
- Ejecutar este único comando:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```
- Esperar ~5 minutos
- Abrir en browser: `http://[IP-DEL-VPS]:8000`
- Crear cuenta admin (guardar usuario y contraseña)
**Paso 3: Conectar dominio en Cloudflare**
- En Cloudflare: agregar el dominio que vas a usar (ej. `factronic-ops.com`)
- Crear registros DNS tipo A apuntando a la IP del VPS:
- `n8n.factronic-ops.com` → IP del VPS
- `api.factronic-ops.com` → IP del VPS
- `ops.factronic-ops.com` → IP del VPS
- En Coolify: ir a Settings → Domains → agregar los dominios
- Activar SSL automático (Let's Encrypt, está incluido en Coolify)
---
### DÍA 2 — Bases de datos y n8n
**Paso 4: Crear PostgreSQL en Coolify**
- En Coolify: New Resource → Database → PostgreSQL 15
- Nombre: `hermes-db`
- Anotar: host interno, puerto (5432), usuario, contraseña
- Coolify te da la connection string — guardarla
**Paso 5: Crear Redis en Coolify**
- En Coolify: New Resource → Database → Redis
- Nombre: `hermes-redis`
- Anotar connection string
**Paso 6: Desplegar n8n en Coolify**
- En Coolify: New Resource → Docker Image → `n8nio/n8n`
- Dominio: `n8n.factronic-ops.com`
- Variables de entorno a agregar:
```
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=[contraseña fuerte]
WEBHOOK_URL=https://n8n.factronic-ops.com
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=[contraseña]
EXECUTIONS_DATA_SAVE_ON_ERROR=all
EXECUTIONS_DATA_SAVE_ON_SUCCESS=all
```
- Deploy
- Verificar que abre en `https://n8n.factronic-ops.com`
---
### DÍA 3 — Integraciones: Gmail API, Slack, HubSpot, OpenAI
**Paso 7: Configurar Gmail API — Google Cloud Console**
Esto lo hace Jovan (o tú con acceso a su cuenta de Google Workspace):
1. Ir a: `console.cloud.google.com`
2. Crear proyecto nuevo: "Hermes Factronics"
3. Ir a: APIs & Services → Enable APIs → buscar "Gmail API" → Enable
4. Ir a: APIs & Services → Credentials
5. Create Credentials → OAuth 2.0 Client ID
6. Application type: Web application
7. Authorized redirect URIs: agregar `https://n8n.factronic-ops.com/rest/oauth2-credential/callback`
8. Descargar el JSON con client_id y client_secret
9. **Repetir este proceso para accounting@ y jovan.gutic@** (necesitas autorizar ambas cuentas)
*Nota: Google va a pedir verificar la app. Para uso interno, en modo "Testing" con las cuentas de Factronics es suficiente para empezar.*
**Paso 8: Configurar Slack Bot**
1. Ir a: `api.slack.com/apps`
2. Create New App → From scratch
3. Nombre: "Hermes Ops"
4. Workspace: el de Factronics (o crear uno nuevo)
5. En "OAuth & Permissions" → Bot Token Scopes → agregar:
- `chat:write` (para escribir mensajes)
- `channels:read` (para ver canales)
6. Install to Workspace → autorizar
7. Copiar el "Bot Token" (empieza con `xoxb-`)
8. Crear canal en Slack: `#ops-hermes`
9. Agregar el bot al canal: en Slack, en el canal → Add apps → Hermes Ops
**Paso 9: Configurar HubSpot API (opcional pero recomendado desde ahora)**
1. Ir a: `app.hubspot.com` → Settings → Integrations → Private Apps
2. Create private app → nombre: "Hermes AI Agent"
3. Scopes necesarios:
- `crm.objects.contacts.read` y `write`
- `crm.objects.deals.read` y `write`
- `crm.objects.companies.read` y `write`
- `tickets.read` y `write` (para soporte post-venta)
4. Create → copiar token (empieza con `pat-...`)
5. Guardar como `HUBSPOT_API_KEY` en Coolify
**Paso 10: Configurar OpenAI API (Assistants)**
1. Ir a: `platform.openai.com/api-keys`
2. Create new secret key → copiar (empieza con `sk-proj-...`)
3. Ir a: `platform.openai.com/assistants`
4. Pedir a Jovan que comparta los Custom GPTs de Factronics
5. Crear un Assistant en OpenAI por cada Custom GPT de Factronics:
- Configurar: nombre, instrucciones, modelo (gpt-4o-mini recomendado), files de conocimiento
- Anotar el `asst_xxxx` ID de cada uno
6. Guardar `OPENAI_API_KEY` en Coolify
7. Crear variable `ASSISTANT_IDS` en Coolify con el mapping:
```json
{
"technical_linx": "asst_...",
"technical_anritsu": "asst_...",
"commercial": "asst_...",
"packaging": "asst_..."
}
```
---
### DÍA 4 — QB Web Connector en el Servidor Windows de Factronics
Este paso se hace **en persona en Medley, FL** (o sesión remota con el servidor Windows dedicado).
**Lo que necesitas tener listo antes:**
- QuickBooks Desktop 2024 Premier Manufacturing Edition instalado y abierto
- El archivo .QBW de Factronics cargado
- Hermes API ya desplegada en Coolify (dominio: `api.factronic-ops.com`) con endpoint SOAP `/qbwc`
- Credenciales SOAP configuradas: `QBWC_SOAP_USERNAME` y `QBWC_SOAP_PASSWORD`
**Pasos:**
1. **Descargar QB Web Connector desde Intuit Developer:**
- Ir a: `https://developer.intuit.com/app/developer/qbdesktop/download-qbwc`
- Descargar `QBWebConnectorInstall.exe`
- Ejecutar instalador en el servidor Windows → siguiente → siguiente → Finish
2. **Crear archivo de configuración `.QWC`:**
- En la máquina local, crear archivo `C:\QBWC\hermes_factronics.qwc`:
```xml
Hermes Factronics Integration
factronics-hermes-001
https://api.factronic-ops.com/qbwc
Integración automática POs → Sales Orders vía IA
mailto:support@coordenadas.agency
hermes
{00000000-0000-0000-0000-000000000001}
{00000000-0000-0000-0000-000000000002}
QBFS
false
false
```
3. **Registrar la aplicación en QBWC:**
- Hacer doble clic en `hermes_factronics.qwc`
- QBWC se abre y muestra: "New application 'Hermes Factronics Integration' has been added"
- Ingresar la contraseña (la misma que `QBWC_SOAP_PASSWORD`)
- QBWC muestra la app con status "Waiting for first request"
4. **Configurar intervalo de polling:**
- En QBWC: File → Settings
- Polling Interval: 60 segundos (balance entre tiempo real y carga)
- Auto-Run: Marcar "Run application automatically every [1] minute(s)"
- Aceptar
5. **Verificar que Hermes SOAP endpoint está listo:**
- Desde el servidor Windows, abrir browser y probar:
```
https://api.factronic-ops.com/health
```
- Debe responder `{"status": "ok"}`
6. **Probar el flujo QBWC → Hermes → QB:**
- Desde tu laptop, insertar un trabajo de prueba en la cola:
```sql
INSERT INTO qbwc_jobs_queue (job_type, qbxml_request)
VALUES ('customer_query', '...test query...');
```
- QBWC detecta el trabajo en el próximo polling (máximo 60s)
- QBWC ejecuta la consulta contra QB
- QBWC devuelve el resultado al endpoint SOAP
- Revisar: `qbwc_jobs_queue.status = 'completed'`
**Verificación final del DÍA 4:**
- Desde la máquina Windows: QBWC muestra "Hermes Factronics Integration: Connected"
- Desde PostgreSQL: `SELECT * FROM qbwc_jobs_queue WHERE status = 'completed'` muestra al menos 1 registro
- No se necesita Cloudflare Tunnel ni exponer puertos locales
---
### DÍA 5 — Verificación general
Antes de pasar a construir agentes, verificar que todo comunica:
**Checklist de conectividad:**
- [ ] `https://n8n.factronic-ops.com` → abre y pide login ✓
- [ ] `https://api.factronic-ops.com/health` → responde `{"status": "ok"}` ✓
- [ ] `https://ops.factronic-ops.com` → (todavía no existe, lo desplegamos en Fase 5)
- [ ] n8n puede conectarse a Gmail (crear credencial de prueba en n8n → Credentials → Gmail)
- [ ] Slack bot responde en `#ops-hermes` (enviar mensaje de prueba desde n8n → Slack node → test)
- [ ] PostgreSQL: conectarse con DBeaver o TablePlus y correr los CREATE TABLE del blueprint
- [ ] QBWC: `hermes_factronics.qwc` registrado y status "Connected" en el servidor Windows
- [ ] OpenAI Assistants API: probar consulta manual a un Assistant y recibir respuesta
- [ ] HubSpot API: probar `GET /crm/v3/objects/contacts` desde Postman y recibir lista
**Si todo está verde → listo para Fase 3**
---
## FASE 3 — POC CONTABLE (El Agente 1)
**Duración:** 2 semanas
**Objetivo:** Que una PO real de NSP llegue por email y aparezca como Draft en QB en menos de 3 minutos (más el tiempo de polling del QBWC: máximo 60s adicionales)
---
### SEMANA 3 — Build del Agente Contable
**Lo que tú (o tu dev) hace:**
1. **Desplegar Hermes API en Coolify**
- Crear el repositorio de Hermes en GitHub (privado)
- En Coolify: New Resource → GitHub Repository → conectar repo
- Dominio: `api.factronic-ops.com`
- Variables de entorno: todas las del blueprint (ANTHROPIC_API_KEY, OPENAI_API_KEY, QBWC_SOAP_USERNAME, etc.)
- Deploy
2. **Programar el endpoint SOAP /qbwc**
- Implementar el handler SOAP que QBWC va a consultar
- Lógica: recibir autenticación → revisar qbwc_jobs_queue → devolver QBXML pendiente
- Si no hay trabajos: devolver respuesta vacía (QBWC espera)
3. **Programar el extractor de POs**
- El agente recibe el PDF en base64
- Lo manda a Claude API con el prompt de extracción
- Claude devuelve JSON estructurado con todos los campos
- Validar cada campo extraído
4. **Programar la validación contra QB Cache**
- Con el nombre del cliente extraído, buscar en qb_customers_cache
- Con cada item de la PO, buscar precio en qb_items_cache
- Si precio de PO vs precio QB difiere más del 2%: flag como discrepancia
5. **Programar la creación del Draft en QB (vía QBWC)**
- En lugar de llamar un REST API, insertar QBXML en qbwc_jobs_queue
- QBWC recoge el trabajo en el próximo ciclo de polling
- El QBXML para crear Sales Order Draft es estándar de Intuit
- Monitorear: `qbwc_jobs_queue.status` hasta que sea 'completed' o 'failed'
6. **Crear el workflow WF-001 en n8n**
- Gmail Trigger → filtro → HTTP Request a Hermes → Slack notification
- (el blueprint tiene el detalle de cada nodo)
---
### SEMANA 4 — Pruebas con datos reales
**Prueba 1 — Solo extracción (sin QB):**
- Tomar cada una de las 10 POs que te dio Jovan
- Pasarlas al agente manualmente (via Postman o similar)
- Verificar que los campos extraídos coinciden con lo que dice el PDF
- Documentar tasa de éxito: cuántos campos correctos de 10
**Prueba 2 — Extracción + validación QB:**
- Mismas POs, pero ahora cruzando contra QB real
- Verificar que el cliente se encuentra en QB
- Verificar que los precios coinciden (o que el agente detecta correctamente la discrepancia)
**Prueba 3 — Flujo completo:**
- Enviar un email a accounting@ con una PO adjunta (una real del pasado)
- Ver si n8n lo detecta en <5 minutos
- Ver si Hermes la procesa correctamente
- Ver si el Draft aparece en QB
- Ver si llega el mensaje de Slack
---
### REUNIÓN 3 — Demo del POC con Jovan
**Quién:** Tú + Jovan + persona de contabilidad
**Duración:** 30 minutos
**Cuándo:** Al final de la Semana 4
**Guión de la demo:**
1. Mostrar el inbox de accounting@ (vacío o con POs sin procesar)
2. Enviar un email con una PO real en PDF (pueden usar una PO vieja de NSP)
3. Todos ven la pantalla — esperar máximo 3 minutos
4. Mostrar: el Draft en QuickBooks con todos los campos llenos
5. Mostrar: el mensaje en Slack con el resumen
6. Mostrar: el audit log en el panel con el detalle de qué hizo el agente
**Preguntas para Jovan después de la demo:**
- ¿Los datos que extrajo QB están correctos?
- ¿El formato del Draft en QB está bien para que contabilidad pueda aprobarlo fácilmente?
- ¿Hay algún campo que faltó o que debería verse diferente?
- ¿El mensaje de Slack tiene la información que necesitas?
**Al salir de esta reunión:**
- [ ] Aprobación de Jovan para continuar con los agentes 2, 3 y 4
- [ ] Lista de ajustes menores a hacer en el agente contable
- [ ] Confirmación del precio del retainer mensual
---
## FASE 4 — INBOX COPILOT (Agente 2)
**Duración:** 2 semanas
---
### SEMANA 5 — OpenAI Assistants, clasificación y HubSpot
**Paso 1: Conectar los Custom GPTs de Factronics como Asistentes de OpenAI**
No necesitas construir RAG. Factronics ya tiene sus GPTs entrenados.
- Mapear cada Custom GPT a un Assistant en OpenAI API
- Configurar: nombre, instrucciones, modelo (gpt-4o-mini), archivos de conocimiento
- Probar consulta manual a cada Assistant:
```python
from openai import OpenAI
client = OpenAI()
thread = client.beta.threads.create()
client.beta.threads.messages.create(thread_id=thread.id, role="user", content="¿Qué es el Linx SureClean?")
run = client.beta.threads.runs.create_and_poll(thread_id=thread.id, assistant_id="asst_...")
# Verificar que responde con información correcta
```
- Documentar qué Assistant usar para cada tipo de consulta técnica
**Paso 2: Clasificador de emails con triage + HubSpot**
- Programar el triage: recibe email, devuelve tipo (A/B/C/D/X) + prioridad + análisis de sentimiento
- El triage ahora incluye campos HubSpot: sentiment_score, buying_intent, suggested_deal_stage
- Probar con 20 emails reales del inbox de Jovan (exportar desde Gmail)
- Meta: que clasifique correctamente al menos 85% de los emails
- Meta de sentimiento: que el análisis de intención sea preciso en 80% de los casos
**Paso 3: Generador de borradores con contexto de Asistentes**
- Programar el draft generator con el prompt de Jovan
- Conectar a OpenAI Assistants API para buscar contexto técnico cuando lo necesita
- NO construir RAG — solo llamar al Assistant correspondiente según el tipo de consulta
- Probar con los mismos 20 emails
**Paso 4: Integración HubSpot — acciones autónomas**
- Programar el cliente HubSpot con estas acciones:
- Crear contacto nuevo cuando un email tipo D (lead nuevo) es detectado
- Poblar campos personalizados: fuente, sentiment_score, onboarding_status
- Actualizar etapa del deal en pipeline basado en sentimiento e intención
- Solo mover de etapa si confidence > 0.85
- Probar con datos de prueba (no tocar deals reales todavía)
---
### SEMANA 6 — Integración y pruebas
**Crear WF-002 en n8n:**
- Gmail Trigger (jovan@) → Hermes triage → Hermes draft → Gmail Create Draft → Label → Slack si prioridad alta
**Prueba en vivo:**
- Activar el workflow para los emails de una sola mañana
- Jovan revisa cada borrador y da feedback:
- ✅ Correcto tal como está
- ✍️ Correcto pero cambiaría esto: [comentario]
- ❌ Equivocado — lo que debería decir es: [corrección]
- Con ese feedback ajustar el prompt
---
### REUNIÓN 4 — Revisión del Inbox Agent con Jovan
**Quién:** Tú + Jovan
**Duración:** 20 minutos
**Propósito:** Ver en vivo cómo el agente manejó los emails de esa semana
**Preguntas:**
- ¿Cuántos borradores aprovechaste sin modificar?
- ¿Cuáles tuviste que reescribir mucho?
- ¿Hay algún tipo de email que el agente no está manejando bien?
- ¿El tono de los borradores suena como tú?
---
## FASE 5 — AGENTES 3 y 4 + SISTEMA COMPLETO
**Duración:** 2 semanas
---
### SEMANA 7 — Operations + Onboarding Agent
**Operations Agent (Agente 3):**
- Reunión rápida (15 min) con Jovan para ver la plataforma de tareas en vivo
- Confirmar: ¿usamos Airtable, ClickUp o Trello?
- Configurar API client en Hermes para la plataforma elegida
- NO migrar datos — la plataforma ya existe, solo la conectamos
- Programar el agente de resumen diario que consulta tareas vía API
- Crear WF-003 en n8n (Schedule 8AM Mon-Fri)
- Probar: ¿el resumen del lunes en la mañana tiene la información correcta?
**Onboarding Agent (Agente 4 — antes llamado Tax Agent):**
- Configurar webhook en HubSpot para detectar deals en etapa "Closed Won"
- Programar el flujo de envío de formularios de registro
- Programar el extractor de datos de formularios recibidos (PDF)
- Programar la verificación web básica (EIN, resale certificate, etc.)
- Programar la cola de onboarding_queue
- Crear WF-004 en n8n (HubSpot Webhook → Hermes → Gmail → QBWC)
**Kill Switch:**
- Crear WF-005
- Agregar botón en el Control Panel
- Probar: activar kill switch → verificar que n8n desactiva todos los workflows → reactivar
---
### SEMANA 8 — Control Panel y documentación
**Control Panel:**
- Desplegar la interfaz web en Coolify (dominio: `ops.factronic-ops.com`)
- Vistas a tener listas:
- Dashboard principal (resumen del día)
- Lista de borradores QB pendientes de aprobar
- Lista de borradores de email pendientes
- Cola de onboarding de clientes (status: forms_sent → received → verified → qb_created)
- Alertas activas (discrepancias de precio, onboarding pendiente de revisión)
- Log de acciones (audit)
- Config / Kill Switch
**Documentación para Factronics:**
- Crear un Google Doc con "Cómo usar el sistema Hermes" (1-2 páginas, con capturas)
- Incluir: qué hace cada agente, qué necesita revisar el equipo cada día, cómo activar el Kill Switch
---
### REUNIÓN 5 — Demo final y entrega
**Quién:** Tú + Jovan + equipo contabilidad
**Duración:** 45 minutos
**Propósito:** Entrega formal del sistema, capacitación, inicio del retainer
**Agenda:**
1. Demo completa del sistema (10 min) — mostrar los 4 agentes funcionando
2. Walkthrough del Control Panel (10 min) — que Jovan lo navegue solo
3. Explicar el Kill Switch y cuándo usarlo (5 min)
4. Preguntas y ajustes finales (10 min)
5. Confirmar el esquema de soporte mensual (10 min)
---
## RESUMEN DE REUNIONES
| # | Reunión | Con quién | Cuándo | Duración |
|---|---|---|---|---|
| 1 | Kick-off discovery | Jovan | Semana 1 | 60 min |
| 2 | Observación QB en vivo | Contabilidad Factronics | Semana 1 | 45 min |
| 3 | Demo POC Contable | Jovan + Contabilidad | Final Semana 5 | 30 min |
| 4 | Revisión Inbox Agent + HubSpot | Jovan | Final Semana 7 | 20 min |
| 5 | Demo final y entrega | Jovan + equipo | Final Semana 10 | 45 min |
---
## RESUMEN DE LO QUE DEBES CREAR / CONFIGURAR
| Plataforma | Qué crear/configurar | Quién lo hace |
|---|---|---|
| Hostinger | VPS KVM 2 Ubuntu 22.04 | Tú |
| Coolify | Instalar, crear servicios (n8n, PostgreSQL, Redis, Hermes API, Control Panel) | Tú |
| Cloudflare | Dominio + DNS records (sin Tunnel — QBWC usa comunicación saliente) | Tú |
| Google Cloud | Proyecto "Hermes Factronics" + Gmail API + OAuth credentials (accounting@ + jovan@) | Jovan (con tu guía) |
| Slack | Bot "Hermes Ops" + canal #ops-hermes | Tú (con acceso de Jovan) |
| HubSpot | Private App token + webhooks para deal stage changes | Jovan (con tu guía) |
| OpenAI | API key + Asistentes (mapear Custom GPTs de Factronics como Assistants de OpenAI) | Tú |
| QB Web Connector (servidor Windows Factronics) | Instalar QBWC + archivo .QWC + registrar app Hermes | Tú en persona en Medley, FL |
| n8n | 5 workflows (WF-001 al WF-005) + credenciales Gmail, Slack, HubSpot | Tú |
| PostgreSQL | Tablas: audit_log, pending_review, agent_status, qbwc_jobs_queue, onboarding_queue, caches | Tú |
| Anthropic | Cuenta API de pago + API key (Claude para orquestación Hermes) | Tú |
| OpenAI | Cuenta API de pago + API key (Assistants para contexto técnico) | Tú |
| GitHub | Repo privado para Hermes API | Tú |
---
## SEÑALES DE QUE ALGO NO ESTÁ BIEN
Si alguna de estas cosas pasa, parar y resolver antes de continuar:
- **QBWC muestra "Waiting for first request" permanentemente** → el endpoint SOAP /qbwc no responde correctamente. Verificar:
- Que Hermes API está corriendo y accesible desde internet
- Que la URL en el .QWC es correcta (https, no http)
- Que las credenciales SOAP coinciden entre el .QWC y Coolify
- **QBWC ejecuta trabajos pero todos fallan** → revisar qbwc_jobs_queue.error_message. Posibles causas: QBXML mal formado, el archivo .QBW no es el correcto, QB está en modo multi-user.
- **QBWC no detecta trabajos nuevos** → el polling puede estar en un intervalo muy largo. Verificar configuración (recomendado: 60 segundos). O el SOAP endpoint devuelve vacío incorrectamente.
- **El extractor de POs falla en más del 20% de los casos** → los PDFs son imágenes escaneadas, no texto. Necesitas agregar OCR antes de pasar el PDF a Claude.
- **n8n no detecta emails nuevos** → el token de Gmail expiró o los permisos OAuth no incluyen "gmail.readonly". Regenerar credenciales.
- **Los precios no coinciden con QB aunque deberían** → el nombre del item en la PO no coincide con el código en QB. Hay que mejorar el mapeo de items.
- **OpenAI Assistants devuelve respuestas incorrectas** → el Custom GPT no tiene la información actualizada. Pedir a Jovan que revise el contenido del GPT en ChatGPT.
- **HubSpot no recibe actualizaciones del agente** → verificar que el token de Private App tiene los scopes correctos (crm.objects.deals.write, crm.objects.contacts.write). Verificar que el pipeline ID está correcto.
---
*Coordenadas — Guía operativa Proyecto Hermes × Factronics — Junio 2026*
*Versión 2.0 — Actualizado con feedback de Jovan (QBWC, Assistants API, Onboarding, HubSpot autónomo)*