# Plataforma conversacional desacoplada — documento de diseño

**Fecha:** 17/10/2026
**Estado:** diseño completo y aprobado — listo para plan de implementación
**Autoría:** Derlis D'Acosta (decisiones de producto y negocio) + Claude (decisiones de arquitectura, marcadas como tales)
**Revisión:** pasó por revisión de constructor el 17/10/2026; las correcciones de §5.5 vienen de ahí.
**Revisión 2 (17/10/2026):** el producto pasa a ser un **servicio independiente**, no un módulo de Novasis. Ver D13–D16. Esta revisión reescribió §1, §5, §6 y §8.

> **Nota de lectura.** El documento describe dos repositorios: el **servicio conversacional** (nuevo, a crear) y **Novasis** (el ERP existente). Cada pieza dice explícitamente dónde vive. Cuando dice "el servicio", es el nuevo.

---

## 1. Intención y por qué

El mercado de "inbox multicanal + constructor de bots" está completamente commoditizado: Wati, Respond.io, Gupshup, 360dialog, AiSensy, SleekFlow, y Chatwoot por abajo en open source. **No hay espacio para competir ahí y no es lo que se intenta.**

Lo que ninguno de ellos puede hacer es completar una transacción comercial paraguaya de punta a punta. Un bot que consulta stock real, arma el pedido, cotiza, emite la factura electrónica por SIFEN, manda el KuDE, genera el link de pago y registra la cobranza. Eso requiere saber qué necesita un DE, cómo funciona el timbrado, qué es el KuDE y cómo concilia una cobranza — y ese conocimiento está hoy en Novasis, un ERP multi-tenant en producción.

**El foso es ese conocimiento, no la co-ubicación del código.** Es una distinción que importa: el conocimiento vive en el conector, y vive igual si la llamada es en proceso o por HTTP. Por eso el servicio puede estar desacoplado del ERP sin perder la ventaja.

Hay un segundo dolor, independiente y también real: **configurar un número en Meta es prohibitivo** para una PyME paraguaya — Business Manager, verificación de negocio, app en developers.facebook.com, permisos, tokens. Meta lo resolvió con [Embedded Signup](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/implementation/): un popup OAuth alojado por Meta donde el cliente conecta su WABA en 5–15 minutos. Pero solo está disponible para **Tech Providers** aprobados. Chatwoot y el resto del open source exigen que el cliente traiga sus credenciales ya armadas, es decir, no resuelven el dolor.

### Por qué desacoplado

El producto es un **servicio independiente** con su propio repositorio, su propio deploy y su propia multi-tenencia. Novasis es una integración — la primera y por ahora la única.

Qué habilita esto:

- **Se le puede vender a empresas que no usan Novasis.** Es la diferencia entre un módulo y un producto.
- **Aclara una confusión del borrador anterior.** Lo que antes era "una API pública" son en realidad dos contratos en direcciones opuestas, y Novasis queda a los dos lados: es **proveedor** de la API privada de ERP (el bot le pide stock, le pide emitir un DE) y es **consumidor** de la API de mensajería (las campañas de `src/cartera/campanas/` y las gestiones de `src/cobranzas/` mandan WhatsApp a través del servicio, como cualquier tercero).
- **Aísla el radio de daño.** Un bug en el bot no puede tumbar la facturación electrónica.
- **Licencias y deploy independientes.** Chatwoot y el servicio se despliegan juntos sin arrastrar el ERP.

Qué cuesta — y una parte está escondida:

- **Novasis tiene que exponer una API de ERP que hoy no tiene.** Este es el costo oculto y es grande (pieza 5).
- **"El bot afirma solo lo que el ERP confirmó" ahora cruza la red.** Stock → pedido → factura es una transacción distribuida con fallas parciales. Un timeout después de emitir el DE deja al bot sin saber si emitió.
- Dos repos, dos deploys, versionado del contrato entre ambos.

**Contexto honesto que condiciona todo el diseño:** no hay ningún cliente que haya pedido esto. Es construcción especulativa para tener una solución que ofrecer. El riesgo dominante no es técnico, es construir piezas perfectas que nadie compra.

---

## 2. Objetivos

1. **Un servicio conversacional que se despliega y se vende sin Novasis**, con su propia multi-tenencia.
2. **Alta de un número de WhatsApp en un clic**, sin que el cliente toque nunca la consola de Meta.
3. **Un bot que ejecuta, no que deriva.** El agente invoca operaciones comerciales reales a través de un conector de ERP, y las deja registradas.
4. **Handoff a humano como capacidad de primera clase**, no como caso de error.
5. **Una capa de canales unificada** — WhatsApp, SMS, email, webhooks — con un contrato único.
6. **Una API de mensajería** que consuman terceros, Novasis incluido.
7. **Una frontera que no se pueda violar por accidente**: el servicio no importa código de Novasis ni comparte su base de datos.

## 3. No-objetivos

- **Un segundo conector de ERP en v1.** La interfaz existe; la implementación es una sola (D14).
- **Publicaciones automatizadas en Instagram y Facebook.** Es la Content Publishing API, otra superficie, otro comprador.
- **Mensajería de Instagram y Messenger como canales de atención.** Entran después por `ICanalProvider`.
- **Constructor visual de flujos para el cliente final.** Los flujos los arma el proveedor del servicio.
- **Reemplazar el inbox de agentes humanos con código propio.** Se reusa open source.
- **Llamadas de voz y voicebots.**
- **Ser BSP de Meta** (línea de crédito, reventa de mensajes con markup). Ver D1.
- **Una API de ERP pública y documentada.** La API de la pieza 5 es privada y acotada (D15).

## 4. Anti-objetivos

Qué haría de esto un fracaso aunque funcione técnicamente.

- **Que el producto se pueda describir sin mencionar la capacidad transaccional.** Si el pitch termina siendo "inbox con bots", se construyó el décimo clon de Wati.
- **Que la frontera se viole.** Un `import` desde el servicio hacia `src/` de Novasis, una credencial de la base del ERP, o una tabla compartida, y el desacople se vuelve ficción. La separación tiene que ser verificable, no una intención.
- **Que la API de ERP se vuelva pública.** Si cualquiera puede escribir el mismo conector contra Novasis, el foso se disuelve. Desacoplado no significa público.
- **Que la lógica central viva en una herramienta con licencia hostil.** Un flujo conversacional en una interfaz visual de un tercero no se versiona con el repo, no se testea, no se revisa en PR, y limita a quién se le puede vender.
- **Dos fuentes de verdad.** Ver §5.6 para el reparto. Si el mismo dato vive autoritativamente en los dos lados, divergen.
- **Que el onboarding siga requiriendo que alguien entre a Business Manager por el cliente.** Tampoco sirve automatizar el alta del número y dejar que el cliente cree sus plantillas a mano en la UI de Meta: la fricción vuelve por la ventana.
- **Que el bot prometa y no cumpla.** Un bot que dice "ya te emití la factura" sin haberla emitido es peor que no tener bot. Con la red en el medio esto se vuelve más difícil, no menos: ver §6.3.
- **Que el bot filtre datos de cuenta a quien no es el titular.** Un número de WhatsApp no es una identidad verificada.

---

## 5. Restricciones

### 5.1 Licencias — restricción de arquitectura, no detalle legal

Se verificó contra el texto de cada licencia.

| Herramienta | Licencia | Veredicto para este producto |
|---|---|---|
| **Chatwoot CE** (todo fuera de `enterprise/`) | MIT | **Usable.** MIT no tiene cláusula de uso interno ni de multi-tenancy; permite hospedar, servir a múltiples empresas, cobrar, modificar y rebrandear. Chatwoot CE ya es multi-tenant de fábrica (modelo de *accounts*). |
| **Chatwoot** `enterprise/` + planes pagos | Source-available + ToS | **No usable.** Los ToS prohíben uso para *service bureau*, sublicenciar, revender y quitar las marcas. |
| **n8n** | Sustainable Use (fair-code) | **Usable solo en modelo agencia.** Permitido: construir automatizaciones para clientes en instancia propia siempre que el cliente no las cree ni edite, y cobrar por armado, mantenimiento y consultoría. Prohibido: vender un producto cuyo valor derive sustancialmente de n8n, dar acceso a la interfaz, o self-service multi-tenant. Licencia Embed desde USD 50.000/año. |
| **Dify** | Apache 2.0 modificada | **No usable.** Prohíbe multi-tenant sin permiso escrito y prohíbe quitar el logo. Aplica aunque el servidor sea propio. |
| **Botpress** | MIT/AGPL dual + propietaria | **No usable.** La propietaria prohíbe construir una plataforma de bots competidora. El repo auto-hospedable (`v12`, AGPL) está sin mantenimiento desde abril 2025. |

Alternativas MIT/Apache si Chatwoot no cierra: **Tiledesk** (MIT, multicanal + bots), **Erxes**. **Papercups** se descarta por estar en modo mantenimiento desde 2025.

**Requisito previo a facturar:** un abogado revisa la distinción entre el grant MIT del core de Chatwoot y los ToS de sus materiales licenciados. El diseño asume que la lectura es correcta; la asunción es del negocio, no del código.

### 5.2 Meta

- Ser **Tech Provider** requiere pasar App Review para acceso avanzado a `whatsapp_business_messaging` y `whatsapp_business_management`. Es un proceso con tiempos que Meta controla y que puede rechazar. **Es la dependencia externa de mayor riesgo del proyecto.**
- Embedded Signup está en **v4** (8/10/2025). v2 y v3 dejaron de funcionar el 15/10/2026; se implementa v4 directamente.
- El cambio *Phone Number First* (changelog del 3/9/2026) exige que la selección o asignación del número ocurra **antes** de que el cliente inicie el flujo.
- La versión de Graph API está fijada en `VERSION_GRAPH = 'v21.0'` como constante exportada y deliberada. Subirla es un cambio consciente.
- **Desde el 01/10/2026 Meta cobra también las respuestas dentro de la ventana de 24 h** (anotado en `mensajeria.service.ts:117`). Cada turno del bot le factura al cliente. Consecuencias en §6.3 y D11.

### 5.3 El servicio conversacional (repo nuevo)

- **NestJS**, mismo stack que Novasis, para no partir el conocimiento del equipo (D16).
- **Multi-tenencia propia.** Un tenant del servicio es una empresa cliente del servicio. **No** asume el modelo de tenencia de Novasis: el mapeo tenant → `empresa_id` del ERP es configuración del conector, no una columna compartida.
- **Autenticación propia.** No puede reusar `AuthGuard('jwt')` ni `PermissionGuard` de Novasis, que resuelven privilegios contra `usuario_perfiles`. El servicio necesita su propio modelo de usuarios, roles y API keys.
- **Base de datos propia.** Ninguna tabla compartida con el ERP, ninguna credencial cruzada.
- **Sin infraestructura como código de referencia:** el repo de Novasis no tiene Dockerfile, compose ni CI. El servicio arranca eso de cero y conviene que lo tenga desde el primer commit, porque además hay que deployar Chatwoot.
- **Enums tipados** en TypeScript y Prisma para todo discriminador de estado o tipo, desde el inicio. El repo nuevo no arrastra la deuda del CRM (§5.5).

### 5.4 Novasis (repo existente)

Aplica a la pieza 5, que es la única que se escribe del lado del ERP.

- Prefijo `/api`, versionado URI `/api/v1`, Swagger en `/docs`.
- Guards en capas: `AuthGuard('jwt')` → `ModuleGuard`/`SubmoduloGuard` → `PermissionGuard`, más `SuscripcionGuard` global. La API privada de ERP usa autenticación por API key, no JWT, igual que `src/cartera/api-publica/`.
- Catálogo de seguridad en `src/seguridad/seeds/seguridad.seed-data.ts`, sincronizado en cada arranque por `SeguridadSeedBootstrap`. Privilegios nuevos se declaran ahí, no por migración.
- Migraciones: **directorios** en `prisma/migrations/`, nunca archivos `.sql` sueltos. Orden de aplicación **alfabético**, no por dependencia.
- Valores monetarios en el frontend van siempre por `MonedaInput.jsx`.

### 5.5 Lo que NO existe todavía

Verificado contra el código. **Cambia el tamaño del trabajo, no el diseño.**

- **No hay tool-calling en ningún lugar del repo de Novasis.** `AiProviderService` expone solo `completar()` y `completarConImagenes()`: un turno, un único mensaje de usuario, `max_tokens` fijo en 2048, sin array `messages[]`, sin `tools`/`input_schema`, sin streaming. El "agente" de `ai-dashboard` es text-to-SQL con validación AST. **El loop de agente se construye desde cero en el repo nuevo.** De Novasis se toma como referencia conceptual el enrutamiento por proveedor y el modelo de consumo (`ai_empresa_config`, `credencial_modo`, `limite_tokens_mensual`, `ai_consumo`, `ai_tarifas`, `LimiteTokensExcedidoError`), pero se **reimplementa** en el servicio: es configuración de un tenant del servicio, no de una empresa del ERP.
- **El CRM de Novasis no tiene la base de conversaciones.** Faltan `crm_conversaciones`, `crm_mensajes`, `crm_contactos` y `crm_plantillas`. No hay `ConversacionesService`, ni gateway de WebSocket, ni submódulo `CRM_BANDEJA` en el seed. Las colas `crm-automatizaciones`, `crm-mensajeria` y `crm-recurrente` **no están registradas** y el motor de reglas M100 solo existe en los documentos. **Esto deja de ser deuda de Novasis: esas tablas y colas nacen en el servicio nuevo** (ver §8 y §11).
- **`MetaCloudProvider` guarda el *media id* de Meta en `adjunto_url`** sin descargar el archivo, y **nada persiste `id_externo`**, así que hoy no hay protección contra los reintentos de Meta. Se resuelve en la migración del código al repo nuevo.
- **`src/cartera/api-publica/` es menos precedente de lo que parecía.** Tiene hasheo de claves, scopes y revocación. **No** tiene rate limiting, **no** tiene idempotencia, la verificación de scope se hace a mano en cada método sin decorador (se olvida en silencio), y `ApiKeysService.auditar()` no tiene ningún llamador — `cartera_api_audit` está siempre vacía. Hay un punto de partida de idempotencia en `src/mobile/v1/common/idempotency.interceptor.ts`, pero exige `usuario_id`.
- **El CRM existente no tiene ni un enum** — `crm_canales.tipo` y `crm_leads.estado` son `VarChar` con CHECK, contra la convención de `CLAUDE.md`. **Mi llamada:** el repo nuevo usa enums desde el inicio; migrar los `VarChar` heredados de Novasis es un PR aparte, fuera del alcance de este diseño.
- **Twilio es una sola cuenta de plataforma** (`TWILIO_*` en env), no credenciales por tenant. Ver §6.2.

### 5.6 Reparto de la verdad

La regla que evita el anti-objetivo de las dos fuentes de verdad. Cada dato tiene **un** dueño.

| Dato | Dueño | El otro lado |
|---|---|---|
| Canales, credenciales de Meta, plantillas | **Servicio** | El ERP no los conoce |
| Conversaciones, mensajes, acuses | **Servicio** | El ERP los consulta por API si los necesita |
| Identidad conversacional (teléfono, verificación OTP) | **Servicio** | — |
| Identidad comercial (cliente, RUC, saldo, historial) | **ERP** | El servicio guarda solo una referencia opaca (`cliente_ref`), nunca el saldo |
| Catálogo, stock, precios | **ERP** | El servicio consulta, con caché de TTL corto y declarado |
| Pedidos, presupuestos, documentos electrónicos, cobranzas | **ERP** | El servicio consulta y ordena, nunca es autoritativo |
| Consumo de inferencia y presupuesto de mensajes | **Servicio** | — |

**Caso borde que hay que resolver explícitamente:** un contacto que conversa y todavía no es cliente. El servicio lo tiene como identidad conversacional sin `cliente_ref`. Cuando se convierte, el ERP crea el cliente y devuelve la referencia. El servicio **no** crea clientes por su cuenta.

### 5.7 Restricciones de producto heredadas

- **Baileys no hace envíos automáticos.** `evolution_baileys` usa protocolo no oficial; un envío masivo es la vía más rápida a que Meta bloquee el número del cliente para siempre. Codificado en `permiteAutomaticos()` y `BaileysAutomaticoBloqueadoError`. **El agente IA cae bajo esta prohibición: un bot sobre Baileys no envía nada automático.**
- **Sin tarifa cargada, el estimador de costo devuelve `null`, no cero.** Un costo de 0 invita a mandar campañas creyendo que son gratis.
- Las credenciales de canal se devuelven siempre enmascaradas y nunca salen en claro por la API.

---

## 6. Las cinco piezas

Cuatro en el servicio nuevo, una en Novasis.

### 6.1 Pieza 1 — Onboarding en un clic *(servicio)*

El diferenciador. Convierte un proceso de días con asistencia humana en un popup de 10 minutos. **No depende del ERP en absoluto**, así que sale entera del desacople.

**Qué hace:** el cliente, desde el panel del servicio, elige o confirma su número, abre el popup de Meta, autoriza, y al cerrarse el canal queda creado y suscrito al webhook, listo para enviar y recibir.

**Alcance:**
- Flujo Embedded Signup v4, con selección de número **previa** al popup (*Phone Number First*).
- Intercambio del código de autorización por el token de larga duración del cliente, cifrado y guardado en el canal.
- Registro del número y suscripción de la app al WABA del cliente.
- **Migración de un número que ya está en WhatsApp Business App.** Es el caso PyME más común en Paraguay y tiene su propio sub-flujo: hay que desvincularlo de la app antes de registrarlo, y el cliente pierde el historial local. Sin este camino, el "un clic" falla justo para el perfil de cliente más probable. **Entra en alcance (D10).**
- **Gestión de plantillas desde el servicio.** Todo mensaje que el bot inicie fuera de la ventana de 24 h —link de pago, "pedido listo", envío del KuDE, dunning— necesita plantilla aprobada por Meta. Si el cliente tiene que crearlas en la UI de Meta, vuelve la fricción que esta pieza existe para eliminar. Implica **pedir también ese permiso en el App Review**. `enviarPlantilla()` hoy recibe un nombre suelto sin validar que exista ni esté aprobada.
- Estados visibles del onboarding, con mensajes accionables en cada falla: número ya registrado en otro WABA, negocio sin verificar, autorización cancelada a mitad de camino.
- Reintento idempotente: reabrir el popup no duplica canales.

**Lo que hace valiosa a esta pieza es el manejo de los caminos infelices.** El camino feliz es una llamada OAuth; lo que diferencia es que cuando el número ya está tomado, el cliente lea qué hacer en lugar de un error de Meta en inglés.

### 6.2 Pieza 2 — Capa de canales unificada *(servicio)*

**Qué hace:** un contrato único —`ICanalProvider`— para WhatsApp, SMS, email y webhooks salientes, de modo que el resto del sistema no sepa por qué canal viaja un mensaje.

**Punto de partida real:** `src/crm/canales/whatsapp/whatsapp-provider.interface.ts` ya define `enviarTexto`, `enviarPlantilla`, `enviarAdjunto`, `parsearWebhook`, `estadoSesion?`, más `EnvioResult` y `WebhookEvento` (variante `mensaje` / variante `estado`). **Ese código y el de `MetaCloudProvider`, `EvolutionProvider`, el factory y el controller de webhooks migran al repo nuevo** (D16). Es refactorización con mudanza, no construcción desde cero.

**Alcance:**
- `ICanalProvider` con los tipos de canal como enum tipado.
- Capacidades declaradas por proveedor: no todo canal soporta plantillas, adjuntos o acuses de lectura. El llamador debe poder preguntar antes de intentar, no descubrirlo en el error.
- Implementaciones: Meta Cloud (migra), Evolution (migra), SMS, email.
- Normalización de `WebhookEvento` para que un acuse de SMS y uno de WhatsApp se procesen por el mismo camino.
- Persistencia de `id_externo` con dedupe, y descarga de adjuntos desde el *media id*. Ambas cosas faltan hoy.
- La prohibición de automáticos sobre Baileys se preserva en la generalización.

**Credenciales por tenant vs de plataforma.** Dos modelos que el contrato tiene que admitir: credenciales propias del cliente (WhatsApp vía Embedded Signup, obligatoriamente) y credenciales de plataforma compartidas (SMS por Twilio, al menos al principio — hoy es una sola cuenta en env). **Mi llamada:** `ICanalProvider` declara de dónde saca las credenciales y el canal guarda un `credencial_modo`, reusando el concepto que ya existe en `ai_empresa_config` en lugar de inventar otro.

**Queda al constructor:** si el canal de email tiene transporte propio o reusa un SMTP configurado por tenant.

### 6.3 Pieza 3 — Agente con herramientas sobre el ERP *(servicio)*

**El foso.** Lo que ningún competidor puede copiar sin aprender la operativa comercial paraguaya.

**Qué hace:** un agente LLM con tool-calling, donde cada herramienta es una operación comercial real, ejecutada a través de `IERPConnector`.

**El loop se construye desde cero** (§5.5). No hay tool-calling en ninguno de los dos repos.

#### `IERPConnector` — una interfaz, una implementación

Se define la interfaz y se implementa **solo Novasis** (D14). La abstracción existe para que el segundo conector no obligue a reescribir el agente, no para soportar conectores imaginarios. Cuando aparezca un segundo ERP, la interfaz se valida contra un caso real.

| Operación | Tipo | Servicio de Novasis detrás |
|---|---|---|
| Consultar catálogo y precios | lectura | `src/ecommerce/public/ecommerce-public.service.ts`, `catalogo-cache.ts` |
| Consultar stock | lectura | `src/ecommerce/stock/ecommerce-stock-reserva.service.ts` |
| Resolver teléfono → `cliente_ref` | lectura | `clientes`, `crm_leads`, `ecommerce_clientes` |
| Consultar estado de cuenta | lectura, requiere OTP | `src/cartera/` |
| Armar y confirmar pedido | **escritura** | `src/ecommerce/pedidos/ecommerce-pedidos.service.ts`, `ecommerce-workflow.ts` |
| Cotizar | **escritura** | `src/presupuestos/presupuestos.service.ts` |
| Emitir documento electrónico y KuDE | **escritura** | `src/middleware-sifen/` |
| Generar link de pago | **escritura** | **Novasis Pay**, no Bancard (D7) |
| Registrar cobranza y gestión | **escritura** | `src/cobranzas/`, `src/crm/` |

#### Reglas no negociables

- **Toda operación de escritura lleva clave de idempotencia y tiene su consulta de estado correspondiente.** Esto no es opcional con la red en el medio: un timeout después de emitir un DE deja al bot sin saber si emitió. La regla es **consultar antes de reintentar, nunca reintentar a ciegas**. Es la diferencia entre un bot y un bot que factura dos veces.
- **Toda operación con efecto económico irreversible requiere confirmación explícita del cliente en la conversación** antes de ejecutarse. Emitir una factura electrónica no se deshace.
- **El bot afirma solo lo que el ERP confirmó.** Si SIFEN devuelve pendiente, el mensaje dice pendiente. Si la llamada falló sin respuesta, el mensaje dice que está verificando — no dice que se emitió.
- **El servicio nunca toca la base de Novasis.** Todo pasa por la pieza 5.
- **Trazabilidad a los dos lados:** el servicio audita qué herramienta ejecutó el bot y en qué conversación; el ERP audita la operación con la API key del servicio como actor más la metadata de correlación (ver pieza 5).

#### Identidad y verificación del interlocutor

Un número de WhatsApp no es una identidad verificada: puede ser un teléfono reasignado, un familiar, o un número que el cliente cambió. Herramientas como estado de cuenta y emisión de documentos atados a un RUC no pueden depender de él. **Herramientas escalonadas (D8):**

- **Sin verificar:** catálogo, precios de lista, stock, horarios, información general. Nada específico de una cuenta.
- **Verificado por OTP:** todo lo específico de la cuenta — saldo, facturas, pedidos propios, emisión de documentos, pagos.
- La verificación vence y se revalida; no es permanente por número.

**Quién hace qué, ahora que están separados.** El servicio tiene los canales, así que **el servicio envía y valida el OTP** y guarda el estado de verificación. El ERP solo responde la pregunta "¿este teléfono corresponde a algún cliente?" y devuelve un `cliente_ref` opaco. El servicio nunca guarda el saldo; lo pide cada vez. (Novasis tiene `src/codigos-verificacion/`, pero queda del lado del ERP: el servicio implementa el suyo porque es dueño del canal.)

#### Handoff a humano *(D11)*

El bot tiene que poder entregarle la conversación a una persona, y no como caso de error. Esto es lo que vuelve coherente a D2: Chatwoot existe precisamente para que el handoff tenga dónde aterrizar.

Disparadores:
- **El cliente lo pide**, explícito o detectado.
- **El bot no puede resolver** — N turnos sin avanzar, o intención fuera de sus herramientas.
- **Se agotó el presupuesto de mensajes** del tenant. El bot deja de responder automáticamente pero la conversación sigue viva con un humano.
- **Operación sensible** que el tenant decidió no delegar al bot, aunque la herramienta esté disponible.
- **Enojo o frustración detectada.** Una queja que escala con un bot en el medio se vuelve peor.

Garantías:
- **Contexto completo.** El agente humano ve toda la conversación, qué herramientas ejecutó el bot y con qué resultado. Un humano que hereda "el cliente pregunta por su pedido" sin saber que el bot ya le dijo tres cosas, repite y contradice.
- **Silencio del bot mientras hay humano asignado.** Dos voces en el mismo chat es peor que ninguna.
- **Horario de atención.** Fuera de horario no hay a quién entregar; el bot dice cuándo habrá alguien en lugar de prometer una derivación que no ocurre.
- **Devolución al bot**, opcional y explícita, cuando el humano resolvió.

**Queda al constructor:** cómo se detecta "no puede resolver" y "frustración" — heurística de turnos, señal del propio modelo, o clasificador aparte.

#### Costo por turno

Con el cambio de Meta del 01/10/2026, cada respuesta del bot le cuesta dinero al cliente. El agente **agrupa su respuesta en un mensaje** en lugar de mandar tres seguidos. Es regla de diseño, no optimización posterior.

#### Inferencia

Configuración por tenant del servicio: proveedor, modelo y modo de credencial. Se agrega OpenRouter como proveedor (`https://openrouter.ai/api/v1`, OpenAI-compatible) para poder mover el modelo por tenant sin tocar código y tener fallback ante caídas. Costo: 5,5% al cargar crédito, 8% en tier Business, sin markup por token.

#### Orquestación

Los flujos del producto son **código NestJS sobre BullMQ en el repo del servicio**. Las colas nacen acá; las que figuran en el plan CRM de Novasis no están registradas y no se van a registrar ahí (§11). No viven en n8n (D3).

### 6.4 Pieza 4 — API de mensajería para terceros *(servicio)*

**Qué hace:** permite que un sistema externo mande mensajes por cualquier canal con una API key. **Novasis es uno de esos terceros**: las campañas de `src/cartera/campanas/` y las gestiones de `src/cobranzas/` pasan a mandar WhatsApp por acá.

**Alcance:**
- Enviar mensaje por canal, con scopes por tipo de canal.
- Consultar estado de un envío por el `id_externo` del proveedor.
- Webhooks salientes para que el tercero reciba mensajes entrantes y acuses.
- Rate limiting por API key.
- Idempotencia por clave del llamador, para que un reintento de red no duplique mensajes al cliente final.

**Lo que se aprende de `src/cartera/api-publica/` sin copiarlo:** el patrón de claves hasheadas, scopes y revocación sirve. Sus cuatro defectos verificados —sin rate limiting, sin idempotencia, scopes a mano sin decorador, auditoría que nunca se escribe— son exactamente lo que no hay que repetir. **Mi llamada:** scopes por decorador, no verificación manual en cada método; un scope que se olvida tiene que romper en tests, no fallar en silencio.

### 6.5 Pieza 5 — API privada de ERP *(Novasis)*

**El costo oculto del desacople.** La única pieza que se escribe en el repo del ERP, y la que no estaba en ningún plan.

**Qué hace:** expone las operaciones de la tabla de §6.3 como endpoints autenticados, para que el conector del servicio las consuma.

**Privada y acotada (D15):** no documentada públicamente, no ofrecida como producto. Cubre **solo** lo que las herramientas del bot usan, no una API de ERP completa. Dos razones: preserva el foso —nadie más puede escribir el conector— y acota drásticamente el alcance.

**Alcance:**
- Autenticación por API key con scopes, sobre el patrón de `src/cartera/api-publica/` pero **con** rate limiting, idempotencia y auditoría que efectivamente se escriba.
- **Idempotencia obligatoria en toda operación de escritura**, con la consulta de estado correspondiente. Es la contraparte de la regla del §6.3.
- **Auditoría con correlación.** La API key identifica al servicio como actor; cada request lleva además `cliente_ref` (en nombre de quién) y una referencia de conversación. Así el audit del ERP responde "quién pidió esto y por qué" sin inventar usuarios.
- Contrato versionado, con una política explícita de qué se puede cambiar sin romper al conector.

**Esto simplifica D9.** El borrador anterior necesitaba columnas de actor para bots en `audit_logs` de Novasis, porque el bot corría dentro del ERP. Ya no: el actor es una API key, que es un concepto que el ERP ya tiene. Lo que hace falta es que la auditoría guarde la metadata de correlación — bastante menos que modificar guards y `AuditInterceptor` para aceptar actores no humanos.

**Queda al constructor:** si se arregla y generaliza `src/cartera/api-publica/` para que las dos APIs compartan la infraestructura de claves, o si la de ERP nace aparte y la de Cartera se migra después. Lo segundo saca una refactorización del camino crítico.

---

## 7. Decisiones ya tomadas

**(negocio)** las tomó Derlis. **(arquitectura)** las tomé yo y están sujetas a revisión.

- **D1 — Tech Provider, no BSP. (negocio)** El cliente pone su propio medio de pago y le paga los mensajes directo a Meta; se cobra plataforma, 0% markup. Evita línea de crédito con Meta, riesgo de cobranza y la operación de revender mensajes. Un BSP típico agrega 5–20% sobre la tarifa publicada; ese margen no compensa el costo operativo de arrancar.

- **D2 — Chatwoot CE como bandeja del agente humano, integrado como *API channel*. (arquitectura)** El Agent Bot de Chatwoot presupone que Chatwoot tiene el inbox y las credenciales de Meta; la pieza 1 exige que el token lo guarde el servicio. Entonces **Chatwoot es un API channel alimentado por el servicio**: el servicio recibe el webhook de Meta, procesa, decide si responde el bot o escala a humano, y en ese caso empuja la conversación a Chatwoot y recibe de vuelta lo que el agente escribe.
  Con el desacople esto queda **más limpio que antes**: Chatwoot se deploya junto al servicio, no junto al ERP, y el reparto de la verdad de §5.6 ya dice que las conversaciones son del servicio. Igual sigue siendo la decisión de mayor costo operativo (dos stacks, NestJS + Rails) y la más razonable de revisar: la alternativa es escribir la bandeja propia.

- **D3 — Los flujos del producto son código, no n8n. (arquitectura)** Ver §4 y §5.1. n8n se usa para implementaciones a medida de un solo cliente y para operación interna. Nunca como motor de un flujo que se repita en varios clientes.

- **D4 — El proveedor del servicio paga la inferencia y la incluye en el plan, con techo por tenant. (negocio)** Pedirle al cliente que traiga su API key reintroduce la fricción que el producto promete eliminar. OpenRouter permite mover el modelo por tenant sin tocar código y cubre caídas con fallback. **Deroga D7 del plan CRM-360**, que exigía BYOK (ver D11b).

- **D5 — Las etapas son orden de entrega, no compuertas. (negocio)** El plan cubre **las cinco piezas**, no solo la primera.
  Mi recomendación había sido tratar el gate de etapa 1 como vinculante —construir poco y planificar el resto contra evidencia de venta— por el riesgo que nombra §1. Derlis decidió lo contrario con el riesgo sobre la mesa, y esa es la decisión que vale. Queda anotado para que el constructor sepa que fue deliberado.

- **D6 — IG/FB publicaciones fuera de alcance. (negocio)**

- **D7 — El link de pago es Novasis Pay, no Bancard. (arquitectura)** `src/crm/CLAUDE.md` tiene una decisión explícita en contra de Bancard (D14 de ese documento), con `novasis_pay_customer_ref` y conciliación por webhook ya construidos. Se respeta. El bot no puede afirmar "cobrado" si escucha el webhook equivocado.

- **D8 — Herramientas escalonadas por verificación de identidad, con OTP del lado del servicio. (arquitectura)** Ver §6.3.

- **D9 — El actor es una API key, no un usuario sintético ni columnas de actor para bots. (arquitectura)** *Simplificada por el desacople.* Ver pieza 5.

- **D10 — Gestión de plantillas y migración de número entran en la pieza 1. (arquitectura)** Expande el alcance y lo que se pide en el App Review, pero sin eso el "un clic" no cumple su promesa.

- **D11 — Presupuesto mensual de mensajes configurable, con handoff a humano al agotarse. (negocio)** Techo por tenant y por mes, **configurable y ampliable** —por monto o por cantidad de mensajes— y a futuro **derivable del plan del cliente**, con la convención de que `0` o `null` significa ilimitado. Al agotarse, el bot deja de responder automáticamente y la conversación **se deriva a un humano**; no se corta la atención del cliente final. El handoff no es solo el comportamiento al tocar el techo: es capacidad de primera clase (§6.3).

- **D11b — D7 del plan CRM-360 queda derogada. (negocio)** El agente **escribe**: emite documentos electrónicos, arma pedidos y registra cobranzas, contra la regla de "solo lectura" de CRM-45. Y la inferencia la paga el proveedor del servicio (D4), contra el BYOK de D7. Razón: un agente de solo lectura es un bot de preguntas frecuentes y no se diferencia de Wati — se pierde la única ventaja estructural.

- **D12 — Una sola app de Meta; plan B es BYO-credenciales. (negocio)** Los tenants que venda un reseller se onboardean bajo la app y el portfolio único del servicio. Si Meta rechaza el Tech Provider, se cae a credenciales traídas por el cliente **y se reordenan las etapas poniendo la pieza 3 primero**, porque sin Embedded Signup el diferenciador del onboarding desaparece.
  **Consecuencia operativa:** la app única es punto único de falla comercial. Una suspensión por parte de Meta deja sin servicio a todos los tenants a la vez, resellers incluidos.

- **D13 — El producto es un servicio independiente, no un módulo de Novasis. (negocio)** Repo propio, deploy propio, multi-tenencia propia, base de datos propia. Novasis es una integración. Habilita venderlo a empresas que no usan Novasis y aísla el radio de daño. Costo: la pieza 5, y que las escrituras pasen a ser transacciones distribuidas.

- **D14 — Novasis-primero detrás de `IERPConnector`, una sola implementación. (negocio)** Se define la interfaz pero no se construyen abstracciones para conectores que no existen. El único caso conocido es Novasis; abstraer contra un solo caso se valida contra sí mismo. Cuando aparezca el segundo ERP, la interfaz ya está y se implementa contra un caso real.

- **D15 — La API de ERP es privada y acotada. (negocio)** No documentada públicamente, no ofrecida como producto, y cubre solo lo que las herramientas del bot usan. Preserva el foso y acota el alcance. Desacoplado no significa público.

- **D16 — Repo nuevo, NestJS. (negocio)** Repositorio separado para que el desacople sea real y no una carpeta que termina importando de `src/`. Mismo stack para no partir el conocimiento del equipo. El código de CRM-22 —`MetaCloudProvider`, `EvolutionProvider`, factory, controller de webhooks, interfaz de proveedor— **migra** al repo nuevo.

---

## 8. Etapas

El plan cubre las cinco piezas (D5). Este es el **orden de construcción y entrega** recomendado.

**Etapa 0 — Cimientos del servicio.** Repo nuevo, NestJS, multi-tenencia, autenticación propia, Prisma con enums, Dockerfile y CI desde el primer commit. Migración del código de CRM-22 desde Novasis. Modelado de conversaciones, mensajes y canales. Colas BullMQ registradas. Persistencia de `id_externo` con dedupe y descarga de adjuntos — las dos cosas que faltan hoy y que protegen contra los reintentos de Meta. Deploy de Chatwoot.
*Esto es lo que antes era "CRM-23 ingesta" y ahora es el arranque de un servicio.*

**Etapa 1 — Mensajería operativa.** Capa de canales (pieza 2) y API de mensajería (pieza 4). Al final de esta etapa el servicio ya manda y recibe mensajes por API y tiene bandeja humana. **Es el primer punto cobrable** y no necesita ERP ni Meta aprobado.

**Etapa 2 — Puente con el ERP.** Pieza 5 en Novasis, más `IERPConnector` con su implementación de Novasis. Al final de esta etapa Novasis manda sus campañas y gestiones por el servicio, y el servicio puede leer catálogo y stock. **Primer valor concreto para los clientes Novasis existentes.**

**Etapa 3 — El agente.** Pieza 3: loop de tool-calling, herramientas de lectura primero, después las de escritura con idempotencia y confirmación. Handoff a humano. **Acá nace el producto real.**

**Etapa 4 — Onboarding en un clic.** Pieza 1. Requiere la aprobación de Tech Provider, cuyo tiempo no se controla. **La solicitud a Meta conviene iniciarla en la etapa 0**, no acá: es una dependencia externa con cola, y tenerla aprobada antes de necesitarla saca el riesgo del camino crítico.

El constructor puede reordenar con justificación, excepto la etapa 0.

---

## 9. Lo que queda abierto al constructor

Decisiones que un buen implementador puede tomar solo, listadas para que no parezcan olvidos:

- Forma concreta de `ICanalProvider` e `IERPConnector`: cómo se declaran y consultan las capacidades.
- Cuál entidad del ERP es el contacto canónico detrás de `cliente_ref`, entre `clientes`, `crm_leads` y `ecommerce_clientes` (que ya tiene su propio JWT en `src/store-auth/`).
- Sincronización servicio → Chatwoot: qué se sincroniza, con qué frecuencia, cómo se resuelve un conflicto. La regla fijada es §5.6.
- TTL del caché de catálogo y stock en el servicio, y qué se hace cuando el ERP no responde.
- Si la pieza 5 generaliza `src/cartera/api-publica/` o nace aparte.
- Transporte de email en la capa de canales.
- Estrategia de prompts y contexto del agente: cuánto historial, cómo se le informa el catálogo, cómo se recorta.
- Cómo se detecta "el bot no puede resolver" y "frustración".
- Cómo se prueba el agente sin emitir documentos fiscales de prueba contra SIFEN productivo.
- Versionado del contrato entre los dos repos y cómo se corren los tests de contrato.
- Nombre del producto y marca.

---

## 10. Verificación previa a facturar

Ninguna de las tres es código:

1. **Revisión legal** de la distinción MIT core / ToS de Chatwoot, y del modelo agencia bajo la licencia de n8n.
2. **Aprobación de Tech Provider** por parte de Meta, o activar el plan B de D12.
3. **Al menos una venta cerrada**, como evidencia de que el problema es real para alguien que no sea nosotros. No bloquea la construcción (D5), pero sí el momento de poner precio.

---

## 11. Documentos y código que este diseño modifica

Para que no queden dos verdades en el repo de Novasis.

| Documento / código | Qué cambia |
|---|---|
| `docs/plan-crm-360.md` — **D7** | **Derogada.** El agente escribe y la inferencia la paga el servicio (D11b). |
| `docs/plan-crm-360.md` — **CRM-45** | **Sale de Novasis.** El agente IA vive en el servicio (pieza 3), con herramientas de escritura. |
| `docs/plan-crm-360.md` — **CRM-22** | **Implementado, y migra** al repo nuevo (D16). |
| `docs/plan-crm-360.md` — **CRM-23** | **Sale de Novasis.** La ingesta es la etapa 0 del servicio. Las tablas `crm_conversaciones` / `crm_mensajes` no nacen en el ERP. |
| `docs/plan-crm-360.md` — **CRM-24** | **Sale de Novasis.** Plantillas van en la pieza 1 (D10). |
| `docs/plan-crm-360.md` — **CRM-25** | **Sale de Novasis.** Email entra como `ICanalProvider` en la pieza 2. |
| `docs/plan-crm-360.md` — **CRM-26** | **Reemplazado por Chatwoot** (D2). No se construye bandeja propia. |
| `docs/plan-crm-360.md` — **CRM-31** | Se solapa con la orquestación de la pieza 3. Revisar al planificar. |
| `docs/plan-crm-360.md` — colas `crm-mensajeria`, `crm-automatizaciones` | **No se registran en Novasis.** Nacen en el servicio. |
| `src/crm/canales/**` | **Migra** al repo nuevo y se elimina de Novasis. |
| `src/cartera/campanas/`, `src/cobranzas/` | Pasan a mandar WhatsApp por la API de mensajería del servicio (pieza 4), no por un provider propio. |
| `src/crm/CLAUDE.md` — **D14** | Sin cambios. Se respeta: Novasis Pay, no Bancard (D7 de este documento). |
| `src/cartera/api-publica/` | Candidato a generalizarse para la pieza 5; queda al constructor (§9). |

Actualizar el plan CRM es parte del trabajo, no un detalle posterior. **Un plan que siga diciendo que la bandeja y el agente se construyen dentro de Novasis va a hacer que alguien construya lo que ya no va.**
