# Kuvento — API de Integracion

> Kuvento es un asistente de IA empresarial. Esta documentacion describe como integrar
> un ERP o sistema externo con Kuvento via webhooks para sincronizar productos, clientes,
> facturas, antiguedad de saldos, compras, proveedores, saldos de proveedores (CxP),
> inventarios (saldos almacen), maximos/minimos y documentos.

## Autenticacion

Todas las llamadas requieren el header `X-API-Key` con la clave del webhook.
La clave se obtiene desde el portal de Kuvento en Integraciones > Webhooks.

## Endpoint base

POST {KUVENTO_URL}/api/webhooks/inbound/{webhook_id}

Headers:
  X-API-Key: {api_key}
  Content-Type: application/json

El body es un array JSON de objetos, o un objeto individual.

---

## Webhook: Productos

Sincroniza el catalogo de productos. Kuvento usa estos datos para cotizar,
consultar precios, verificar existencias y responder preguntas del equipo.

Campo `id` obligatorio (es el identificador unico/SKU del producto).

```json
[
  {
    "id": "PROD-001",
    "nombre": "Laptop HP ProBook 450",
    "categoria": "Electronica",
    "linea": "Computo",
    "sublinea": "Laptops",
    "precio": 18500.00,
    "precio_mayoreo": 16900.00,
    "existencia": 45,
    "unidad": "pieza",
    "sku": "HP-PB450-G10",
    "marca": "HP",
    "descripcion": "Laptop 15.6, Intel i5, 16GB RAM, 512GB SSD",
    "activo": true
  }
]
```

Campos minimos requeridos: `id`, `nombre`, `precio`.
Campos opcionales: `categoria`, `linea`, `sublinea`, `precio_mayoreo`, `existencia`, `unidad`, `sku`, `marca`, `descripcion`, `activo`.

---

## Webhook: Clientes

Sincroniza el catalogo de clientes: datos fiscales, contacto y condiciones comerciales.
**No contiene saldos ni adeudos** — esos datos van en el webhook de Antiguedad de saldos.
Kuvento usa estos datos para comunicaciones, consultas de datos fiscales y como referencia
para vincular facturas y documentos pendientes.

```json
[
  {
    "id": "CLI-001",
    "nombre": "Distribuidora del Norte S.A.",
    "rfc": "DNO850315XX1",
    "email": "pagos@delnorte.com",
    "telefono": "+52 81 8123 4567",
    "direccion": "Av. Industria 1520, Monterrey, NL",
    "contacto": "Lic. Roberto Garza",
    "dias_credito": 30,
    "limite_credito": 100000.00,
    "estatus": "activo"
  }
]
```

Campos minimos: `id`, `nombre`.
Campos opcionales: `rfc`, `email`, `telefono`, `direccion`, `contacto`, `dias_credito`, `limite_credito`, `estatus`.

---

## Webhook: Facturas

Sincroniza el historial de ventas con productos/conceptos facturados.
Util para consultar que se le ha vendido a un cliente, detalle de partidas y montos.
El campo `conceptos` es un array de partidas con `descripcion`, `cantidad`, `precio_unitario` e `importe`.
Opcionalmente `codigo_producto` en cada concepto para cruce exacto con el catalogo de productos.

```json
[
  {
    "id": "FAC-2024-001",
    "cliente_id": "CLI-001",
    "cliente_nombre": "Distribuidora del Norte S.A.",
    "fecha_emision": "2024-11-15",
    "fecha_vencimiento": "2024-12-15",
    "subtotal": 35000.00,
    "iva": 5600.00,
    "total": 40600.00,
    "moneda": "MXN",
    "estatus": "pendiente",
    "metodo_pago": "transferencia",
    "conceptos": [
      {
        "codigo_producto": "PROD-001",
        "descripcion": "Laptop HP ProBook 450 G10",
        "cantidad": 2,
        "precio_unitario": 17500.00,
        "importe": 35000.00
      }
    ]
  }
]
```

Campos minimos: `id`, `cliente_id`.
Valores de `estatus`: pendiente, pagada, vencida, cancelada.

---

## Webhook: Compras

Sincroniza ordenes de compra (una linea por producto por orden).
Kuvento usa estos datos para analisis de proveedores, costos, eficiencia de compra y proyecciones.

```json
[
  {
    "id": "OC-2024-001-01",
    "folio": "OC-2024-001",
    "fecha": "2024-11-15",
    "proveedor_id": "PROV-001",
    "proveedor_nombre": "Aceros y Metales del Pacifico S.A.",
    "producto_id": "PROD-001",
    "producto_nombre": "Lamina de Acero Cal. 14",
    "cantidad": 500,
    "precio": 45.50,
    "monto": 22750.00,
    "precio_mn": 45.50,
    "monto_mn": 22750.00,
    "tipo_cambio": 1.0,
    "moneda": "MXN"
  },
  {
    "id": "OC-2024-002-01",
    "folio": "OC-2024-002",
    "fecha": "2024-11-20",
    "proveedor_id": "PROV-005",
    "proveedor_nombre": "US Industrial Supplies Inc.",
    "producto_id": "PROD-010",
    "producto_nombre": "Motor electrico 5HP",
    "cantidad": 10,
    "precio": 285.00,
    "monto": 2850.00,
    "precio_mn": 5472.00,
    "monto_mn": 54720.00,
    "tipo_cambio": 19.2,
    "moneda": "USD"
  }
]
```

Campos minimos: `id`, `proveedor_id`, `producto_id`, `cantidad`, `monto`.
Campos opcionales: `folio`, `proveedor_nombre`, `producto_nombre`, `fecha`, `moneda`, `precio`, `precio_mn`, `monto_mn`, `tipo_cambio`.

**Nota sobre moneda extranjera**: `precio` y `monto` van en la moneda original. `precio_mn` y `monto_mn` son el equivalente en moneda nacional (MXN). `tipo_cambio` es el factor de conversion usado. Si solo se envia `monto`, Kuvento lo interpreta como moneda nacional.

---

## Webhook: Proveedores

Sincroniza el catalogo de proveedores: datos fiscales, contacto y condiciones de credito.

```json
[
  {
    "id": "PROV-001",
    "nombre": "Aceros y Metales del Pacifico S.A. de C.V.",
    "razon_social": "Aceros y Metales del Pacifico S.A. de C.V.",
    "rfc": "AMD161110JGB",
    "email": "ventas@proveedor1.com.mx",
    "contacto": "Leticia Rodriguez Sanchez",
    "telefono": "442-1487-4951",
    "direccion": "Av. Industria 3342, Zapopan, Jalisco",
    "plazo_credito": 45,
    "limite_credito": 750000
  }
]
```

Campos minimos: `id`, `nombre`.
Campos opcionales: `razon_social`, `rfc`, `email`, `contacto`, `telefono`, `direccion`, `plazo_credito`, `limite_credito`.

---

## Webhook: Antiguedad de saldos (cartera)

Sincroniza documentos pendientes de cobro con desglose de vencimientos.
**Esta es la fuente de verdad para saldos y adeudos de clientes.**
Un cliente puede tener multiples documentos en diferentes monedas (MXN, USD, etc.).
El campo `cliente_id` vincula con el catalogo de clientes.
El campo ID debe ser `folio` (identificador unico del documento).

```json
[
  {
    "folio": "FAC-2024-001",
    "cliente_id": "CLI-001",
    "cliente_nombre": "Distribuidora del Norte S.A.",
    "fecha_emision": "2024-11-15",
    "fecha_vencimiento": "2024-12-15",
    "moneda": "MXN",
    "total": 40600.00,
    "saldo": 40600.00,
    "no_vencido": 40600.00,
    "vencido_15": 0,
    "vencido_30": 0,
    "vencido_45": 0,
    "vencido_mas_45": 0
  }
]
```

Campos minimos: `folio`, `cliente_id`, `saldo`.
Campos opcionales: `cliente_nombre`, `fecha_emision`, `fecha_vencimiento`, `moneda`, `total`, `no_vencido`, `vencido_15`, `vencido_30`, `vencido_45`, `vencido_mas_45`.

---

## Webhook: Saldos proveedores (CxP)

Sincroniza documentos pendientes de pago a proveedores.

```json
[
  {
    "folio": "OC-2024-001",
    "proveedor_id": "PROV-001",
    "proveedor_nombre": "Aceros y Metales del Pacifico S.A.",
    "saldo": 22750.00,
    "moneda": "MXN",
    "fecha_vencimiento": "2025-01-15",
    "dias_vencido": 62
  }
]
```

Campos minimos: `folio`, `proveedor_id`, `saldo`.
Opcionales: `proveedor_nombre`, `moneda`, `fecha_vencimiento`, `dias_vencido`, `no_vencido`, `vencido_15`, `vencido_30`, `vencido_45`, `vencido_mas_45`.

---

## Webhook: Saldos almacen (Inventario)

Sincroniza existencias y valoracion por almacen.

```json
[
  {
    "id": "PROD-001-W1",
    "producto_id": "PROD-001",
    "producto_nombre": "Lamina de Acero Cal. 14",
    "almacen": "Almacen Central",
    "existencia": 2500,
    "costo_total": 187500.00,
    "punto_reorden": 200
  }
]
```

Campos minimos: `id`, `producto_id`, `existencia`.
Opcionales: `producto_nombre`, `almacen`, `costo_total`, `punto_reorden`.

---

## Webhook: Maximos y minimos

Sincroniza niveles de inventario optimos por producto y almacen.

```json
[
  {
    "id": "PROD-001-W1",
    "producto_id": "PROD-001",
    "producto_nombre": "Lamina de Acero Cal. 14",
    "almacen": "Almacen Central",
    "minimo": 100,
    "reorden": 300,
    "maximo": 5000
  }
]
```

Campos minimos: `id`, `producto_id`.
Opcionales: `producto_nombre`, `almacen`, `minimo`, `reorden`, `maximo`.

---

## Webhook: Documentos

Sincroniza documentos de texto para la base de conocimiento (RAG).
Los documentos se indexan automaticamente y quedan disponibles para
consulta en lenguaje natural por todo el equipo.

```json
[
  {
    "nombre": "Politica de vacaciones 2024",
    "contenido": "Todo empleado con mas de 1 anio tiene derecho a 12 dias habiles..."
  }
]
```

Campos: `nombre` (o `name`/`title`), `contenido` (o `content`), opcionalmente `url` para descargar archivo.

---

## Respuesta exitosa (200)

```json
{
  "status": "ok",
  "processed": 2,
  "errors": [],
  "total_records": 148
}
```

## Errores comunes

| Codigo | Causa |
|--------|-------|
| 401 | API key invalida |
| 404 | Webhook ID no existe |
| 422 | JSON mal formado |

---

## Configuracion del webhook en Kuvento

1. Entrar al portal web como admin
2. Ir a Integraciones > Webhooks
3. Crear un webhook: nombre, tipo de entidad (productos/clientes/facturas/antiguedad_saldos/compras/proveedores/saldos_proveedores/saldos_almacen/maximos_minimos/documentos), campo ID
4. Copiar la URL y el API Key generado
5. Configurar el ERP para enviar datos a esa URL con el API Key en el header

**Nota sobre campo ID**: Para antiguedad de saldos y saldos proveedores, usar `folio` como campo ID. Para los demas, usar `id` por defecto.

## sync_mode (modo de sincronizacion)

Al crear el webhook se puede elegir el modo de sincronizacion:
- `upsert` (default): si el ID ya existe actualiza, si no crea
- `full_sync`: igual que upsert, pero ademas elimina registros que NO vengan en el payload

## Campo ID configurable

Al crear el webhook se define que campo del JSON es el identificador unico.
Por defecto es `id`, pero puede ser `codigo`, `sku`, `folio`, etc.
Kuvento hace upsert: si el ID ya existe, actualiza; si no, crea.

## Field mapping (opcional)

Se puede configurar un mapeo de campos si el ERP usa nombres diferentes:
```json
{
  "Codigo": "id",
  "Descripcion": "nombre",
  "PrecioVenta": "precio",
  "Stock": "existencia"
}
```

## Limites

- Maximo recomendado por lote: 500 registros
- Sin limite de frecuencia, pero se recomienda max 1 request/segundo
- Documentos: maximo 50MB por archivo

## Ejemplo con curl

```bash
curl -X POST https://tu-dominio.com/api/webhooks/inbound/{webhook_id} \
  -H "X-API-Key: wh_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '[{"id":"SKU-001","nombre":"Producto ejemplo","precio":100,"existencia":50}]'
```

## Ejemplo con C# (.NET 6+)

```csharp
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "wh_tu_api_key");

var productos = new[] {
    new { id = "SKU-001", nombre = "Producto ejemplo", precio = 100, existencia = 50 }
};

var response = await client.PostAsJsonAsync(
    "https://tu-dominio.com/api/webhooks/inbound/{webhook_id}",
    productos
);
```

## Ejemplo con Python

```python
import requests

response = requests.post(
    "https://tu-dominio.com/api/webhooks/inbound/{webhook_id}",
    headers={"X-API-Key": "wh_tu_api_key"},
    json=[{"id": "SKU-001", "nombre": "Producto ejemplo", "precio": 100, "existencia": 50}]
)
```

## Capacidades del asistente IA

Kuvento usa los datos sincronizados via webhook para responder preguntas del equipo:
- Buscar productos, precios, existencias y cotizar
- Consultar datos de clientes, facturas y adeudos
- Analisis agregado de ventas (totales, por producto, por mes, por ano)
- **Cross-sell analysis**: cruce catalogo vs compras de un cliente para identificar oportunidades de venta. Filtra por `linea`, `sublinea` o `marca` para enfocarse en categorias especificas.
- **Analisis de compras**: top productos por costo, comparacion precios entre proveedores, tendencias mensuales
- **CxP**: saldos a proveedores, posicion neta CxC vs CxP, top acreedores
- **Inventarios**: valoracion por almacen, rotacion, alertas min/max/reorden, proyeccion de cobertura
- **Cambiario**: tipo de cambio promedio ponderado, efecto cambiario en compras USD

---

## Soporte

- Documentacion completa: https://www.kuvento.mx/llms.txt
- Contacto tecnico: contacto@sacti.mx

---

## Docs

- [Contenido completo](https://www.kuvento.mx/llms-full.txt): Todos los articulos en texto plano


## Atención al Cliente
- [Chatbots para empresas en México: guía completa para implementarlos](https://www.kuvento.mx/blog/chatbots-empresas-implementacion-mexico): Descubre cómo implementar un chatbot empresarial en tu PyME mexicana sin complejidad técnica. Reduce costos de atención