# 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 (remoto o en persona) | 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 | --- ## 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? ¿Es una PC de escritorio, un servidor, una laptop? - ¿Esa computadora está encendida todos los días durante el horario laboral? ¿O a veces se apaga? - ¿Cuántas personas usan QuickBooks actualmente? ¿Desde una sola computadora o desde varias? - ¿Tienen contraseña para entrar a QuickBooks? ¿Quién la sabe? - ¿Tienen el archivo .QBW guardado localmente o en red compartida? - ¿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 — Operaciones / Caracas:** - ¿El archivo Tareas_Caracas.xlsx está en Google Drive o en el computador de alguien? - ¿Cuántas personas en Caracas reportan por ese archivo? - ¿Cada cuánto lo revisan? ¿Quién lo actualiza? - ¿Tienen Slack activo? ¿O usan WhatsApp para comunicaciones internas? **Preguntas que debes hacer — Certificados de Reventa:** - ¿Sabes cuántos clientes tienen certificado de reventa activo en Florida? - ¿Están todos en QuickBooks o algunos están guardados solo en email o papel? - ¿Alguien en el equipo sabe hoy cuáles están próximos a vencer? **Al final de esta reunión debes salir con:** - [ ] Claridad sobre dónde está físicamente QB y si la PC está siempre encendida - [ ] 5-10 POs reales en PDF para pruebas (pídelas antes de terminar la reunión) - [ ] Comprensión del flujo actual de principio a fin - [ ] Confirmación de si tienen Slack o si hay que crearlo - [ ] 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? **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 --- ### 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 — Gmail API y Slack **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 --- ### DÍA 4 — QB Bridge en la PC de Factronics Este paso se hace **en persona o en sesión remota con la PC donde está QuickBooks**. **Lo que necesitas tener instalado antes:** - Python 3.11 para Windows (descargar de python.org) - QuickBooks Desktop abierto con la empresa de Factronics cargada **Pasos:** 1. Crear carpeta `C:\QB_Bridge\` 2. Crear archivo `C:\QB_Bridge\requirements.txt`: ``` fastapi uvicorn pywin32 pyyaml python-dotenv ``` 3. Abrir Command Prompt como Administrador y ejecutar: ```bash cd C:\QB_Bridge pip install -r requirements.txt ``` 4. Descargar el archivo `bridge.py` (que prepararemos) a `C:\QB_Bridge\bridge.py` 5. Crear archivo `C:\QB_Bridge\.env`: ``` QB_BRIDGE_TOKEN=pon-aqui-una-clave-larga-y-aleatoria-de-40-caracteres QB_COMPANY_FILE=C:\Users\[usuario]\Documents\QuickBooks\[empresa].QBW ``` 6. Instalar Cloudflare Tunnel: - Descargar `cloudflared.exe` de cloudflare.com/products/tunnel - Poner en `C:\QB_Bridge\cloudflared.exe` - Abrir Command Prompt como Admin: ```bash C:\QB_Bridge\cloudflared.exe tunnel login # Se abre browser, iniciar sesión con cuenta Cloudflare C:\QB_Bridge\cloudflared.exe tunnel create factronics-qb-bridge # Anota el ID del tunnel que te da ``` 7. Probar que el bridge responde: ```bash # Terminal 1: iniciar bridge cd C:\QB_Bridge python bridge.py # Terminal 2: probar curl http://localhost:8765/health # Debes ver: {"status": "ok", "quickbooks": "connected"} ``` **Verificación final del DÍA 4:** Desde tu laptop (fuera de la red de Factronics), ejecutar: ```bash curl https://qb-bridge.factronics-internal.com/health # Debe responder igual que antes ``` Si responde → el tunnel funciona → QuickBooks es accesible desde internet de forma segura. --- ### 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` → (todavía no existe, lo desplegamos en Fase 3) - [ ] `https://qb-bridge.factronics-internal.com/health` → responde desde internet ✓ - [ ] 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 **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 --- ### 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, QB_BRIDGE_URL, etc.) - Deploy 2. **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 3. **Programar la validación contra QB** - Con el nombre del cliente extraído, buscar en QB Cache (o llamar al Bridge) - Con cada item de la PO, buscar precio en QB - Si precio de PO vs precio QB difiere más del 2%: flag como discrepancia 4. **Programar la creación del Draft en QB** - Llamar al QB Bridge: POST /sales-orders/draft - Bridge crea la Sales Order en QB en estado Draft - Devolver el ID de la Sales Order creada 5. **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 — RAG y clasificación **Paso 1: Indexar la base de conocimiento** Recopilar y subir al RAG Service estos documentos (los tienes en el proyecto de Claude): - PDFs de Linx (9800, 9000, Iris, SureClean) → ya los tienes - Case Studies Portfolio → ya lo tienes - Pedir a Jovan: lista de precios actual exportada de QB (File → Export → Items) - Pedir a Jovan: 5-10 emails que él mismo respondió en los últimos 3 meses (como ejemplos de estilo) **Paso 2: Clasificador de emails** - Programar el triage: recibe email, devuelve tipo (A/B/C/D/X) + prioridad - Probar con 20 emails reales del inbox de Jovan (exportar desde Gmail) - Meta: que clasifique correctamente al menos 85% de los emails **Paso 3: Generador de borradores** - Programar el draft generator con el prompt de Jovan - Conectar al RAG para que busque contexto técnico cuando lo necesita - Probar con los mismos 20 emails --- ### 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 + Tax Agent **Operations Agent:** - Reunión rápida (15 min) con Jovan para ver Tareas_Caracas.xlsx en vivo - Migrar la estructura del Excel a Google Sheets con las columnas estándar del blueprint - Programar el agente de resumen diario - Crear WF-003 en n8n (Schedule 8AM) - Probar: ¿el resumen del lunes en la mañana tiene la información correcta? **Tax Certificate Agent:** - Pedir a contabilidad: lista de todos los clientes con certificado de reventa en QB - Verificar cuáles están próximos a vencer - Programar el agente de monitoreo - Crear WF-004 en n8n (Schedule 1° de cada mes) **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 - Alertas activas - 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 4 | 30 min | | 4 | Revisión Inbox Agent | Jovan | Final Semana 6 | 20 min | | 5 | Demo final y entrega | Jovan + equipo | Final Semana 8 | 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, Panel) | Tú | | Cloudflare | Dominio + DNS records + Tunnel para QB Bridge | Tú | | Google Cloud | Proyecto "Hermes Factronics" + Gmail API + OAuth credentials | Jovan (con tu guía) | | Slack | Bot "Hermes Ops" + canal #ops-hermes | Tú (con acceso de Jovan) | | QB Bridge (PC Factronics) | Python + bridge.py + Cloudflare tunnel como servicio Windows | Tú en persona o remoto | | n8n | 5 workflows (WF-001 al WF-005) + credenciales Gmail y Slack | Tú | | PostgreSQL | Tablas: audit_log, pending_review, agent_status, caches | Tú | | Anthropic | Cuenta API de pago + API key | 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: - **QB Bridge no responde desde internet** → el Cloudflare Tunnel no está corriendo. Verificar que el servicio de Windows está activo en la PC de Factronics. - **QB Bridge responde pero dice "QuickBooks not found"** → QuickBooks Desktop está cerrado en esa PC o el archivo .QBW no está abierto. - **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. --- *Coordenadas — Guía operativa Proyecto Hermes × Factronics — Junio 2026*