Documentación de APIs y Gestión de Wisdoms

Los Wisdoms son bases de datos que contienen información clave de tu empresa—conocimientos, productos y servicios—utilizada por liVO para responder a clientes con precisión, eliminando alucinaciones. Esta documentación detalla cómo gestionar Wisdoms mediante la API, subida de Excel, o la interfaz web. Solo los usuarios con permisos de administrador (gestores de la empresa asociada al Wisdom) pueden realizar estas acciones.

1. Gestión de Wisdoms vía API

Actualiza Wisdoms programáticamente enviando datos JSON a través de una solicitud POST. Ideal para integraciones automáticas, actualizaciones masivas, o ajustes de inventario.

Detalles de la API

Endpoint: https://livo.cl/wisdom_api/<uuid>/

Método: POST

Autenticación: Requiere una clave API en el encabezado X-API-Key. Obtén o regenera la clave desde el panel de gestión de Wisdoms.

Modos de solicitud:

  • Actualización completa: Usa un arreglo de items para actualizar todos los elementos del Wisdom.
  • Actualización de stock: Usa un arreglo de stock_updates para modificar cantidades de productos por SKU.
  • Bump processing: Usa bump_processing: true para continuar el procesamiento de embeddings tras un timeout.

Respuestas posibles:

  • Success (200): {"status": "success", "message": string, "warnings": [string]?}
  • Error (400/403): {"status": "error", "message": string}
  • Bump (503): {"status": "bump", "message": string, "bump_payload": {"bump_processing": true}} (indica que el procesamiento excede 28 segundos; reenviar con bump_processing: true).
1.1 Actualización Completa

Actualiza todos los elementos del Wisdom con un nuevo conjunto de items.

Estructura de un item:

  • title (obligatorio): Nombre del elemento (máx. 1000 caracteres).
  • sku (opcional): Código único para productos o servicios (máx. 100 caracteres).
  • long_text (opcional): Descripción detallada (máx. 12000 caracteres).
  • link (opcional): URL relevante (máx. 2000 caracteres).
  • category (opcional): Categoría para productos o servicios (máx. 500 caracteres).
  • price (opcional): Precio para productos o servicios (formato numérico, ej. "199.99"). Obligatorio para servicios.
  • quantity (opcional): Cantidad para productos (entero positivo). Usa "-1" para servicios o déjalo vacío.

Inferencia de tipo:

  • Conocimiento: Sin price ni quantity.
  • Producto: Incluye quantity (entero positivo).
  • Servicio: Incluye price pero no quantity, o quantity = "-1".

Ejemplo de solicitud:

cURL Python JavaScript cURL (Stock) Python (Stock) JavaScript (Stock) cURL (Bump) Python (Bump) JavaScript (Bump) 
curl -X POST \
  "https://livo.cl/wisdom_api/<uuid>/" \
  -H "X-API-Key: tu-clave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "title": "Política de Devolución",
        "long_text": "Devoluciones en 30 días con recibo",
        "category": "Políticas"
      },
      {
        "title": "Silla de Oficina",
        "sku": "SOF123",
        "long_text": "Silla ergonómica con soporte lumbar",
        "link": "https://tienda.com/silla",
        "category": "Mobiliario",
        "price": "50000",
        "quantity": "10"
      },
      {
        "title": "Consultoría SEO",
        "sku": "SEO2023",
        "long_text": "Optimización de tu sitio web en 3 meses",
        "category": "Marketing",
        "price": "200000",
        "quantity": "-1"
      }
    ]
}'
        
import requests

url = "https://livo.cl/wisdom_api/<uuid>/"
headers = {
  "X-API-Key": "tu-clave-api",
  "Content-Type": "application/json"
}
data = {
  "items": [
    {
      "title": "Política de Devolución",
      "long_text": "Devoluciones en 30 días con recibo",
      "category": "Políticas"
    },
    {
      "title": "Silla de Oficina",
      "sku": "SOF123",
      "long_text": "Silla ergonómica con soporte lumbar",
      "link": "https://tienda.com/silla",
      "category": "Mobiliario",
      "price": "50000",
      "quantity": "10"
    },
    {
      "title": "Consultoría SEO",
      "sku": "SEO2023",
      "long_text": "Optimización de tu sitio web en 3 meses",
      "category": "Marketing",
      "price": "200000",
      "quantity": "-1"
    }
  ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
        
fetch("https://livo.cl/wisdom_api/<uuid>/", {
  method: "POST",
  headers: {
    "X-API-Key": "tu-clave-api",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    items: [
      {
        title: "Política de Devolución",
        long_text: "Devoluciones en 30 días con recibo",
        category: "Políticas"
      },
      {
        title: "Silla de Oficina",
        sku: "SOF123",
        long_text: "Silla ergonómica con soporte lumbar",
        link: "https://tienda.com/silla",
        category: "Mobiliario",
        price: "50000",
        quantity: "10"
      },
      {
        title: "Consultoría SEO",
        sku: "SEO2023",
        long_text: "Optimización de tu sitio web en 3 meses",
        category: "Marketing",
        price: "200000",
        quantity: "-1"
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));
        
curl -X POST \
  "https://livo.cl/wisdom_api/<uuid>/" \
  -H "X-API-Key: tu-clave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "stock_updates": [
      {
        "SKU": "SOF123",
        "quantity": "15",
        "type": "absolute"
      },
      {
        "SKU": "SEO2023",
        "quantity": "5",
        "type": "additive"
      }
    ]
}'
        
import requests

url = "https://livo.cl/wisdom_api/<uuid>/"
headers = {
  "X-API-Key": "tu-clave-api",
  "Content-Type": "application/json"
}
data = {
  "stock_updates": [
    {
      "SKU": "SOF123",
      "quantity": "15",
      "type": "absolute"
    },
    {
      "SKU": "SEO2023",
      "quantity": "5",
      "type": "additive"
    }
  ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
        
fetch("https://livo.cl/wisdom_api/<uuid>/", {
  method: "POST",
  headers: {
    "X-API-Key": "tu-clave-api",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    stock_updates: [
      {
        SKU: "SOF123",
        quantity: "15",
        type: "absolute"
      },
      {
        SKU: "SEO2023",
        quantity: "5",
        type: "additive"
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));
        
curl -X POST \
  "https://livo.cl/wisdom_api/<uuid>/" \
  -H "X-API-Key: tu-clave-api" \
  -H "Content-Type: application/json" \
  -d '{"bump_processing": true}'
        
import requests

url = "https://livo.cl/wisdom_api/<uuid>/"
headers = {
  "X-API-Key": "tu-clave-api",
  "Content-Type": "application/json"
}
data = {"bump_processing": True}

response = requests.post(url, headers=headers, json=data)
print(response.json())
        
fetch("https://livo.cl/wisdom_api/<uuid>/", {
  method: "POST",
  headers: {
    "X-API-Key": "tu-clave-api",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({bump_processing: true})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Notas: Reemplaza <uuid> con el UUID de tu Wisdom y tu-clave-api con tu clave API. El campo title es obligatorio; sku es opcional pero recomendado para productos y servicios. Los tipos se infieren automáticamente. Los embeddings se regeneran tras la actualización.

1.2 Actualización de Stock

Actualiza las cantidades de productos existentes mediante su SKU sin modificar otros campos ni regenerar embeddings.

Estructura de stock_updates:

  • SKU (obligatorio): Código único del producto (debe existir en el Wisdom).
  • quantity (obligatorio): Nueva cantidad (entero no negativo).
  • type (opcional): Tipo de actualización ("absolute" para establecer la cantidad, "additive" para sumar/restar). Por defecto: "absolute".

Restricciones:

  • Solo aplica a productos (elementos con price y quantity positivo).
  • El SKU debe existir en el Wisdom.
  • La cantidad resultante no puede ser negativa para actualizaciones additive.

Ejemplo de solicitud: Ver pestañas de código arriba (cURL Stock, Python Stock, JavaScript Stock).

Notas: Las actualizaciones de stock son rápidas, ya que no regeneran embeddings. Si un SKU no está en los embeddings, se emite una advertencia, pero la cantidad se actualiza en items.

1.3 Bump Processing

Si el procesamiento de embeddings excede 28 segundos, la API devuelve un estado bump. Reenvía la solicitud con bump_processing: true para continuar.

Estructura de la solicitud:

  • bump_processing (obligatorio): true para reanudar el procesamiento de embeddings.

Comportamiento:

  • Usa los items previamente guardados en el Wisdom.
  • Genera o recupera embeddings, aprovechando los ya calculados para mayor rapidez.
  • Devuelve success si completa, bump si aún excede 28 segundos, o error si no hay items.

Ejemplo de solicitud: Ver pestañas de código arriba (cURL Bump, Python Bump, JavaScript Bump).

Notas: Usa reintentos con retroceso exponencial (ej. 1s, 2s, 4s) hasta recibir success o error. Este modo asume que items ya está validado.

2. Subida de Wisdoms vía Excel

Actualiza Wisdoms subiendo un archivo Excel (.xlsx) desde el panel de control. Ideal para actualizaciones manuales o datos exportados de otros sistemas.

Detalles de la Subida por Excel

Pasos:

  1. Descarga la plantilla de Excel o el Wisdom actual desde el panel de gestión.
  2. Completa la plantilla con tus datos, siguiendo la estructura de columnas.
  3. Sube el archivo en la sección "Gestión de Excel" del panel.
  4. El sistema procesará el archivo, actualizará el Wisdom y regenerará los embeddings si es necesario.

Estructura de la plantilla:

Columna Descripción Obligatorio Ejemplo
Title Nombre del elemento (máx. 1000 caracteres) Sí "Silla de Oficina"
SKU Código único para productos o servicios (máx. 100 caracteres) No "SOF123"
Long Text Descripción detallada (máx. 12000 caracteres) No "Silla ergonómica con soporte lumbar"
Link URL relevante (máx. 2000 caracteres) No "https://tienda.com/silla"
Category Categoría para productos o servicios (máx. 500 caracteres) No "Mobiliario"
Price Precio para productos o servicios (formato numérico) Sí para servicios "50000"
Quantity Cantidad para productos (entero positivo) o "-1" para servicios Sí para productos "10"

Inferencia de tipo:

  • Conocimiento: Sin Price ni Quantity.
  • Producto: Incluye Quantity (entero positivo).
  • Servicio: Incluye Price pero no Quantity, o Quantity = "-1".

Ejemplo de archivo Excel:

Title SKU Long Text Link Category Price Quantity
Política de Devolución Devoluciones en 30 días con recibo Políticas
Silla de Oficina SOF123 Silla ergonómica con soporte lumbar https://tienda.com/silla Mobiliario 50000 10
Consultoría SEO SEO2023 Optimización de tu sitio web en 3 meses Marketing 200000 -1

Notas: Descarga la plantilla para garantizar el formato correcto. Usa valores numéricos válidos para Price y Quantity. El campo SKU es opcional pero recomendado para productos y servicios.

3. Gestión de Clave API

La clave API es necesaria para autenticar solicitudes a la API. Puedes obtenerla o regenerarla desde el panel de gestión de Wisdoms.

Detalles de la Gestión de Clave API

Pasos:

  1. Accede al panel de gestión de Wisdoms como gestor autorizado.
  2. En la sección de "Clave API", visualiza la clave actual.
  3. Si necesitas una nueva clave, haz clic en "Regenerar Clave API".
  4. La nueva clave reemplazará a la anterior y será necesaria para todas las solicitudes futuras.

Notas:

  • La clave API se genera automáticamente al crear un Wisdom si no existe.
  • Guarda la clave en un lugar seguro, ya que no se mostrará nuevamente tras regenerarse.
  • Regenerar la clave invalida la anterior, afectando cualquier integración activa.

4. Permisos y Seguridad

La gestión de Wisdoms está restringida a usuarios con permisos de gestor, verificados contra la empresa asociada al Wisdom.

Detalles de Permisos

Requisitos:

  • El usuario debe estar autenticado (login_required).
  • El usuario debe ser un gestor de la empresa asociada al Wisdom, verificado mediante la relación con contact_form.company.
  • Si el Wisdom no está asociado a un contact_form o empresa, se deniega el acceso.

Acciones restringidas:

  • Subir archivos Excel.
  • Descargar plantillas o datos actuales.
  • Actualizar items vía formulario web.
  • Regenerar la clave API.

Notas:

  • Los errores de permiso devuelven un código HTTP 403 (Prohibido).
  • Los gestores son definidos en la configuración de la empresa en liVO.