Integración de API

Envía datos programáticamente a tu base de conocimientos de AI SmartTalk utilizando nuestra API REST. Ideal para integraciones personalizadas, pipelines automatizados y cualquier fuente de datos no cubierta por nuestros conectores nativos.

---

Descripción general

La integración de API te permite:

• Enviar documentos directamente a tu base de conocimientos
• Actualizar contenido programáticamente
• Eliminar entradas obsoletas
• Construir pipelines de datos personalizados
• Integrarte con cualquier sistema que pueda hacer solicitudes HTTP

---

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Una cuenta activa de AI SmartTalk
• Acceso a la API habilitado (verifica tu plan)
• Conocimientos básicos de REST APIs
• Una herramienta para hacer solicitudes HTTP (curl, Postman o el código de tu aplicación)

---

Obtención de tus credenciales de API

Paso 1: Acceder a la configuración de API

1. Inicia sesión en tu cuenta de AI SmartTalk
2. Navega a Configuración → Integraciones
3. Busca API y haz clic en Configurar

Paso 2: Generar token de API

1. Haz clic en Generar nuevo token
2. Copia tu ID de modelo de chat y token de API
3. Almacena esto de forma segura—¡el token se muestra solo una vez!

⚠️ Advertencia de seguridad: Nunca expongas tu token de API en código del lado del cliente o en repositorios públicos.

---

Puntos finales de API

URL base

https://api.aismarttalk.tech/v1

Autenticación

Todas las solicitudes requieren tu token de API en el encabezado:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Todas las solicitudes requieren su token de API en el encabezado:

Authorization: Bearer YOUR_API_TOKEN

---

Importar Documentos

Endpoint

POST /documents/import

Cuerpo de la Solicitud

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Documentación del Producto",
      "content": "El contenido completo de su documento va aquí...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parámetros

Campo	Tipo	Requerido	Descripción
chatModelId	string	✅	Su identificador único del modelo de chat
documents	array	✅	Array de objetos de documento
documents[].title	string	✅	Título del documento para identificación
documents[].content	string	✅	Contenido de texto completo
documents[].url	string	❌	URL de origen (para referencia)
documents[].metadata	object	❌	Pairs clave-valor personalizados

Respuesta

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Documentación del Producto",
      "status": "processing"
    }
  ]
}

Ejemplo: cURL

curl -X POST https://api.aismarttalk.tech/v1/documents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatModelId": "your-chat-model-id",
    "documents": [
      {
        "title": "Guía para Comenzar",
        "content": "Bienvenido a nuestra plataforma. Aquí está cómo empezar...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Consultar Documentos

Haga preguntas contra su base de conocimientos programáticamente.

Endpoint

POST /chat/query

Cuerpo de la Solicitud

{
  "chatModelId": "your-chat-model-id",
  "query": "¿Cómo restablezco mi contraseña?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Respuesta

{
  "success": true,
  "response": "Para restablecer su contraseña, navegue a Configuración > Seguridad > Cambiar Contraseña...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Guía de Seguridad",
      "relevance": 0.95
    }
  ]
}

---

Recuperar Documentos

Obtenga documentos que coincidan con una consulta (sin respuesta de IA).

Endpoint

POST /documents/search

Cuerpo de la Solicitud

{
  "chatModelId": "your-chat-model-id",
  "query": "seguridad de contraseña",
  "limit": 10
}

Respuesta

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Mejores Prácticas de Seguridad",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Ejemplos de Código

Python

import requests

API_TOKEN = "your-api-token"
CHAT_MODEL_ID = "your-chat-model-id"

def import_document(title: str, content: str, url: str = None):
    response = requests.post(
        "https://api.aismarttalk.tech/v1/documents/import",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "chatModelId": CHAT_MODEL_ID,
            "documents": [{
                "title": title,
                "content": content,
                "url": url
            }]
        }
    )
    return response.json()

# Importar un documento
result = import_document(
    title="FAQ: Envío",
    content="Ofrecemos envío gratuito en pedidos superiores a $50...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

JavaScript / Node.js

const API_TOKEN = 'your-api-token';
const CHAT_MODEL_ID = 'your-chat-model-id';

async function importDocument(title, content, url = null) {
  const response = await fetch('https://api.aismarttalk.tech/v1/documents/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatModelId: CHAT_MODEL_ID,
      documents: [{
        title,
        content,
        url
      }]
    })
  });
  return response.json();
}

// Importar un documento
importDocument(
  'FAQ: Devoluciones',
  'Puedes devolver artículos dentro de los 30 días posteriores a la compra...',
  'https://shop.example.com/faq/returns'
).then(console.log);

PHP

<?php
$apiToken = 'your-api-token';
$chatModelId = 'your-chat-model-id';

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'Especificaciones del Producto',
            'content' => 'Nuestro widget tiene las siguientes especificaciones...',
            'url' => 'https://example.com/products/widget'
        ]
    ]
];

$ch = curl_init('https://api.aismarttalk.tech/v1/documents/import');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

---

Casos de Uso

Integración de CMS Personalizado

Sincronizar contenido desde un CMS propietario:

• Conectar con eventos de publicación del CMS
• Enviar contenido nuevo/actualizado a AI SmartTalk
• Eliminar contenido eliminado

Canal de Datos

Importar desde almacenes de datos:

• Exportar datos relevantes a JSON
• Importación por lotes a través de API
• Programar actualizaciones regulares

Productos de Comercio Electrónico

Sincronizar datos de productos desde sistemas personalizados:

• Descripciones de productos
• Especificaciones
• Información de precios

Sistemas Internos

Conectar herramientas internas no soportadas de forma nativa:

• Wikis personalizados
• Bases de datos heredadas
• Aplicaciones propietarias

---

Límites de Tasa

Endpoint	Límite de Tasa
Importación de Documentos	100 solicitudes/minuto
Consulta	60 solicitudes/minuto
Búsqueda	60 solicitudes/minuto

Nota: Los límites de tasa varían según el plan. Contacta al soporte para obtener límites más altos.

---

Manejo de Errores

Formato de Respuesta de Error

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "El token de API proporcionado es inválido o ha expirado"
  }
}

Códigos de Error Comunes

Código	Descripción	Solución
INVALID_TOKEN	Token inválido o expirado	Regenera el token de API
INVALID_MODEL_ID	ID de modelo de chat desconocido	Verifica tu ID de Modelo de Chat
RATE_LIMITED	Demasiadas solicitudes	Implementa retroceso, intenta más tarde
INVALID_REQUEST	Cuerpo de solicitud mal formado	Verifica la estructura JSON
DOCUMENT_TOO_LARGE	El contenido excede el límite	Divide en documentos más pequeños
QUOTA_EXCEEDED	Límites del plan alcanzados	Actualiza o contacta al soporte

---

Solución de Problemas

Fallos de Autenticación

Problema	Solución
401 No Autorizado	Verifica que el token sea correcto y esté activo
Token no funciona	Regenera el token en la configuración
Token expirado	Los tokens no expiran, pero pueden ser revocados

Problemas de Importación

Problema	Solución
Respuesta vacía	Verifica que el Content-Type sea application/json
Documento no aparece	Espera el procesamiento; verifica la sección de Conocimiento
Importación parcial	Algunos documentos pueden tener errores de validación

Problemas de Rendimiento

Problema	Solución
Importaciones lentas	Agrupa documentos (máx. 100 por solicitud)
Timeouts	Reduce el tamaño del lote, intenta de nuevo con retroceso
Límite de tasa alcanzado	Implementa retroceso exponencial

---

Mejores Prácticas

1. Importaciones por lotes: Envía múltiples documentos por solicitud (hasta 100)
2. Títulos únicos: Usa títulos descriptivos y únicos para cada documento
3. Contenido estructurado: Un contenido bien formateado mejora las respuestas de IA
4. Etiquetado de metadatos: Usa metadatos para categorización y filtrado
5. Tokens seguros: Almacena tokens en variables de entorno
6. Manejo de errores: Implementa lógica de reintento con retroceso exponencial
7. Monitorea el uso: Rastrea las llamadas a la API en relación con los límites de tu plan

---

Documentación Relacionada

• Descripción General de Integraciones
• Documentación Completa de API
• Gestión de Base de Conocimiento
• Webhooks de SmartFlow — Recibe eventos