# n8n-nodes-induxsoft-iae

Nodos comunitarios de n8n para interactuar con la plataforma de agentes de IA **Induxsoft IAE**.

## ¿Qué es Induxsoft IAE?

IAE (Inteligencia Artificial Empresarial) es la plataforma de Induxsoft para crear, administrar y desplegar agentes de IA con capacidades de lenguaje natural, memoria, visión, razonamiento y uso de herramientas. Los agentes pueden operar en múltiples canales: chat web, WhatsApp, Facebook Messenger, Instagram, Telegram y teléfono.

## Instalación

### En n8n Community Nodes

1. Ve a **Settings > Community Nodes**
2. Selecciona **Install**
3. Ingresa `n8n-nodes-induxsoft-iae`
4. Acepta los riesgos y haz clic en **Install**

[Descargar n8n-nodes-induxsoft-iae](n8n-nodes-induxsoft-iae.tar.gz)

### Manual

```bash
cd ~/.n8n/nodes
npm install n8n-nodes-induxsoft-iae
```

## Configuración de Credenciales

Este paquete incluye tres tipos de credenciales independientes:

### Induxsoft IAE API (Agentes)

| Campo       | Descripción                                     |
|-------------|--------------------------------------------------|
| **Agent ID** | El identificador único del agente               |
| **API Token** | El código de seguridad (Bearer token) del agente |

### Induxsoft IAE Search Engine API (Motor de Búsqueda)

| Campo                  | Descripción                                     |
|------------------------|--------------------------------------------------|
| **Search Engine ID**    | El identificador del motor de resultados (seid) |
| **Token del Motor**     | Token de autorización del motor de búsqueda     |

### Induxsoft IAE Order Book API (Libretas de Órdenes)

| Campo                    | Descripción                                     |
|--------------------------|--------------------------------------------------|
| **Token de Autorización** | Token de la libreta de órdenes (si está configurado) |

## Recursos y Operaciones disponibles

### 1. Mensaje

| Operación              | Descripción                                                   |
|------------------------|---------------------------------------------------------------|
| **Enviar Mensaje**      | Envía un mensaje al agente en nombre de un usuario. Inicia o continúa una conversación. |
| **Obtener Mensajes**    | Recupera mensajes de una conversación (últimos N, antes/después de un mensaje). |

**Opciones adicionales al enviar mensaje:**
- `chat_id` — continuar conversación existente
- `chat_topic` — tema de la conversación
- `user_sid`, `user_name`, `user_phone`, `user_email` — datos del usuario
- `channel` — canal de comunicación
- `context` — instrucciones adicionales al prompt
- `file` / `fileurl` + `filename` — enviar archivos
- `latitude` / `longitude` — enviar coordenadas
- `params` — parámetros JSON para herramientas del agente
- `format` — formato de respuesta: `text`, `html`, `json`

### 2. Conversación

| Operación                 | Descripción                                              |
|---------------------------|----------------------------------------------------------|
| **Obtener Info**           | Devuelve estado de una conversación activa (canal, último mensaje, si la IA tiene control, etc.) |
| **Listar Conversaciones**  | Lista conversaciones del agente con filtros por fecha, tema, canal. |

### 3. Handoff (Toma de control humano)

| Operación              | Descripción                                                      |
|------------------------|------------------------------------------------------------------|
| **Tomar Control**       | Desactiva al agente (`ai_control=false`) y opcionalmente envía un mensaje. |
| **Devolver Control**    | Reactiva al agente (`ai_control=true`) y opcionalmente envía un mensaje.  |
| **Enviar Mensaje Humano** | Envía un mensaje como humano sin cambiar el estado del control.        |

### 4. Whisper (Susurro)

| Operación         | Descripción                                                            |
|-------------------|------------------------------------------------------------------------|
| **Enviar Susurro** | Envía información contextual al agente para que responda mejor en el siguiente turno. |

### 5. Envío Proactivo

| Operación                | Descripción                                                        |
|--------------------------|--------------------------------------------------------------------|
| **Enviar por WhatsApp**   | Inicia conversación con plantilla aprobada de Meta (API oficial).  |
| **Enviar por WhatsApp QR** | Inicia conversación con mensaje de texto libre por WhatsApp QR.   |

---

## Nodo: IAE Search Engine (Motor de Búsqueda Semántica)

Motor de búsqueda basado en vectores con soporte para respuestas generadas por IA (RAG).

### Operaciones

| Operación                    | Descripción                                                    |
|------------------------------|----------------------------------------------------------------|
| **Buscar**                    | Búsqueda semántica con 4 tipos de resultado: `answer` (respuesta IA), `content` (texto plano), `json` (completo), `metadata` (resumen). |
| **Agregar/Actualizar Vector** | Indexar uno o varios vectores (individual o batch con JSON array). Si se omite el ID, se asigna automáticamente. |
| **Obtener Vector**            | Recuperar un vector por su ID numérico.                        |
| **Eliminar Vector**           | Eliminar un vector del índice.                                 |

**Opciones de búsqueda:**
- `resultType` — tipo de resultado: `answer`, `content`, `json`, `metadata`
- `model` — modelo de IA para respuestas: `fast`, `smart`, `precise`, `strategic`
- `limit` — cantidad de resultados (default: 10)
- `queryField` — nombre del campo de consulta en el payload
- `filters` — filtros JSON opcionales
- `extraPayload` — campos adicionales para el payload

---

## Nodo: IAE Order Book (Libretas de Órdenes)

Gestión de libretas de órdenes para pedidos, solicitudes, reservaciones, etc. Las órdenes se registran con estado "Recibida" y pueden cambiarse a "Atendida" o "Descartada".

### Operaciones

| Operación           | Descripción                                                        |
|---------------------|--------------------------------------------------------------------|
| **Crear Orden**      | Registrar una nueva orden en la libreta con datos, params y campos del protocolo de integración. |
| **Listar Órdenes**   | Listar órdenes con filtros por fecha, texto libre y límite.        |
| **Obtener Orden**    | Recuperar una orden específica por su GUID.                        |
| **Actualizar Orden** | Actualizar los datos de una orden existente (PUT).                 |
| **Descartar Orden**  | Cambiar el estado de una orden a "Descartada".                     |
| **Eliminar Orden**   | Eliminar permanentemente una orden.                                |

**Campos de creación de orden:**
- `bookId` — ID de la libreta
- `originalQuestion` — mensaje original del usuario
- `userName` — nombre del usuario
- `data` — objeto JSON con datos específicos de la orden
- `params` — parámetros clave/valor del agente
- Campos adicionales: `intention`, `preliminaryAnswer`, `reformulatedQuestion`, `agentId`, `agentName`, `sourceUrl`, `userSid`, `user`

**Nota:** Las órdenes permanecen disponibles por 30 días, después se eliminan automáticamente.

## Ejemplos de Flujos

### Ejemplo 1: Chatbot con webhook

```
[Webhook] → [Induxsoft IAE: Enviar Mensaje] → [Responder al Webhook]
```

Recibe mensajes de cualquier fuente vía webhook, los envía al agente IAE y devuelve la respuesta.

### Ejemplo 2: Escalación automática con handoff

```
[Webhook] → [Induxsoft IAE: Enviar Mensaje] → [IF: detectar keyword "humano"]
   → SÍ: [Induxsoft IAE: Tomar Control] → [Slack: Notificar agente humano]
   → NO: [Responder al Webhook]
```

### Ejemplo 3: Campañas proactivas por WhatsApp

```
[Google Sheets: Leer contactos] → [Loop] → [Induxsoft IAE: Enviar por WhatsApp]
```

Envía mensajes proactivos a una lista de contactos usando plantillas aprobadas de Meta.

### Ejemplo 4: Enriquecer contexto con susurro

```
[Webhook] → [HTTP Request: consultar CRM] → [Induxsoft IAE: Enviar Susurro]
   → [Induxsoft IAE: Enviar Mensaje] → [Responder]
```

Antes de enviar el mensaje del usuario, se inyecta contexto del CRM como susurro para que el agente responda con información personalizada.

### Ejemplo 5: Búsqueda RAG con webhook

```
[Webhook] → [IAE Search Engine: Buscar (answer)] → [Responder al Webhook]
```

Recibe una pregunta y devuelve una respuesta generada por IA basada en el contenido indexado en el motor de búsqueda semántica.

### Ejemplo 6: Indexar vectores desde Google Sheets

```
[Google Sheets: Leer filas] → [IAE Search Engine: Agregar Vector] → [Fin]
```

Toma cada fila de una hoja de cálculo (título, descripción, contenido) y la indexa como vector en el motor de búsqueda.

### Ejemplo 7: Registrar pedidos en Libreta de Órdenes

```
[Webhook] → [IAE Order Book: Crear Orden] → [Responder confirmación]
```

Recibe datos de un pedido (producto, cantidad, dirección) y los registra como una orden en la libreta.

## Estructura de respuestas

### Respuesta exitosa (envío de mensaje)

```json
{
  "success": true,
  "data": {
    "chat_id": "uuid-de-la-conversación",
    "response": "Respuesta del agente",
    "download": "url-si-aplica",
    "isbusy": false
  }
}
```

### Respuesta de error

```json
{
  "success": false,
  "message": "Descripción del error"
}
```

## Compatibilidad con OpenAI (BYOK)

IAE también expone un endpoint compatible con el protocolo de OpenAI Chat Completions, útil para integraciones con orquestadores de voz (Vapi, Retell, Bland AI):

- **Base URL:** `https://agent.induxsoft.net/svc/{agent_id}/proto/openai/v1/`
- **Endpoint:** `https://agent.induxsoft.net/svc/{agent_id}/proto/openai/v1/chat/completions`

Este endpoint no está incluido como operación del nodo porque n8n ya tiene nodos nativos para el protocolo OpenAI que pueden apuntar a esta URL.

## Documentación oficial

- [Servicio Web IAE (Agentes)](https://docs.induxsoft.net/es/iae/agentes/servicio-web.md)
- [Envío Proactivo](https://docs.induxsoft.net/es/iae/agentes/servicio-web-send.md)
- [Motor de Búsqueda (Servicios)](https://docs.induxsoft.net/es/iae/motor-busqueda/servicios.md)
- [Libretas de Órdenes](https://docs.induxsoft.net/es/iae/herramientas/libretas-de-ordenes.md)
- [Induxsoft IA](https://es.induxsoft.net/ia/)

## Licencia

MIT