API REST

Autenticación

Todos los endpoints requieren autenticación mediante API Key. Incluye tu API Key en el header o en el body de la solicitud según el endpoint.

Authorization: Bearer TU_API_KEY

Nota: Obtén tu API Key desde el panel de administración de tu cuenta.

Chat API

POST /api/v1/chat/query

Procesa una consulta y retorna una respuesta basada en la base de conocimiento configurada.

Parámetros del Body:

Parámetro	Tipo	Requerido	Descripción
`apiKey`	string	Sí	Tu API Key de autenticación
`query`	string	Sí	La consulta o pregunta del usuario
`knowledgeBaseId`	string	Sí	ID de la base de conocimiento a consultar
`topK`	int	No	Número de chunks relevantes a recuperar (default: 5)
`similarityThreshold`	double	No	Umbral de similitud mínimo (default: 0.7)
`maxTokens`	int	No	Máximo de tokens en la respuesta (default: 1000)
`model`	string	No	Modelo de LLM a usar (default: deepseek-chat)

Ejemplo de Request:

                POST /api/v1/chat/query
Content-Type: application/json

{
  "apiKey": "tu-api-key-aqui",
  "query": "¿Cuáles son los requisitos para abrir una cuenta?",
  "knowledgeBaseId": "kb-123-456",
  "topK": 5,
  "similarityThreshold": 0.7,
  "maxTokens": 1000
}
            

Ejemplo de Response (200 OK):

{
  "answer": "Para abrir una cuenta necesitas...",
  "sources": [
    {
      "chunkId": "chunk-123",
      "content": "Fragmento relevante...",
      "similarity": 0.95
    }
  ],
  "metadata": {
    "tokensUsed": 450,
    "model": "deepseek-chat"
  }
}

POST /api/v1/chat/stream

Procesa una consulta con streaming en tiempo real usando Server-Sent Events (SSE). Retorna la respuesta de forma incremental.

Parámetros:

Mismos parámetros que /api/v1/chat/query

Ejemplo de Request:

                POST /api/v1/chat/stream
Content-Type: application/json

{
  "apiKey": "tu-api-key-aqui",
  "query": "Explícame el proceso de facturación",
  "knowledgeBaseId": "kb-123-456"
}
            

Ejemplo de Response (SSE):

                Content-Type: text/event-stream

data: {"content": "El proceso de facturación"}
data: {"content": " incluye los siguientes pasos:"}
data: {"content": " 1. Generación de factura"}
data: [DONE]
            

POST /api/v1/chat/query-with-command

Procesa una consulta con un comando personalizado predefinido.

Parámetros Adicionales:

Parámetro	Tipo	Requerido	Descripción
`command`	string	Sí	Comando personalizado (ej: "siicontabilidad")

POST /api/v1/chat/save-message

Guarda un mensaje del usuario y la respuesta del asistente en el historial de chat.

Parámetros del Body:

Parámetro	Tipo	Requerido	Descripción
`apiKey`	string	Sí	Tu API Key
`sessionId`	string	Sí	ID de la sesión de chat
`userQuery`	string	Sí	Consulta del usuario
`assistantResponse`	string	Sí	Respuesta del asistente
`sourceType`	string	No	Tipo de fuente (document, database, etc.)
`fileName`	string	No	Nombre del archivo fuente

GET /api/v1/chat/history

Obtiene el historial de conversaciones de una sesión.

Query Parameters:

Parámetro	Tipo	Requerido	Descripción
`clientId`	string	Sí	ID del cliente
`sessionId`	string	Sí	ID de la sesión

Widget API

GET /api/v1/widget/config/{clientId}

Obtiene la configuración del widget para un cliente específico.

Ejemplo de Response (200 OK):

{
  "clientId": "client-123",
  "primaryColor": "#667eea",
  "secondaryColor": "#764ba2",
  "position": "bottom-right",
  "welcomeMessage": "¡Hola! ¿En qué puedo ayudarte?",
  "knowledgeBaseId": "kb-123-456",
  "embedScriptUrl": "https://tu-dominio.com/widgets/assistant-widget.js?clientId=client-123"
}

POST /api/v1/widget/configure

Crea o actualiza la configuración del widget.

Parámetros del Body:

                {
  "clientId": "client-123",
  "primaryColor": "#667eea",
  "secondaryColor": "#764ba2",
  "position": "bottom-right",
  "welcomeMessage": "¡Hola! ¿En qué puedo ayudarte?",
  "knowledgeBaseId": "kb-123-456"
}
            

PUT /api/v1/widget/config/{clientId}

Actualiza la configuración existente del widget.

GET /api/v1/widget/script/{clientId}

Obtiene la URL del script de integración para un cliente.

Subscription API

GET /api/v1/subscription/usage/{clientId}

Obtiene el uso mensual de un cliente para todas las características.

GET /api/v1/subscription/quota/{clientId}/{feature}

Verifica si un cliente tiene cuota disponible para una característica específica.

Valores de Feature:

ChatQueries - Consultas de chat
DocumentProcessing - Procesamiento de documentos
EmbeddingGeneration - Generación de embeddings

POST /api/v1/subscription/validate

Valida una API Key y retorna información del cliente asociado.

Parámetros del Body:

                {
  "apiKey": "tu-api-key-aqui"
}
            

Ejemplo de Response (200 OK):

{
  "valid": true,
  "clientId": "client-123",
  "clientName": "Mi Empresa",
  "status": "Active",
  "planName": "Professional"
}

Progress API

GET /api/v1/progress/{operationId}

Obtiene el estado de progreso de una operación asíncrona.

Ejemplo de Response (200 OK):

{
  "success": true,
  "data": {
    "operationId": "op-123-456",
    "operationName": "Procesamiento de Consulta",
    "status": "InProgress",
    "percentage": 65,
    "currentMessage": "Generando respuesta...",
    "steps": [
      {
        "name": "Validación",
        "message": "Validación completada",
        "percentage": 25,
        "completedAt": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

Códigos de Error

Código	Descripción
`200`	Éxito
`400`	Solicitud inválida (parámetros faltantes o incorrectos)
`401`	No autorizado (API Key inválida o faltante)
`404`	Recurso no encontrado
`429`	Cuota excedida (límite de uso alcanzado)
`500`	Error interno del servidor

Ejemplo de Error Response:

{
  "error": "API key inválida"
}

Ejemplos de Integración

JavaScript (Fetch API)

            async function sendQuery(query, knowledgeBaseId) {
  const response = await fetch('/api/v1/chat/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      apiKey: 'tu-api-key',
      query: query,
      knowledgeBaseId: knowledgeBaseId,
      topK: 5
    })
  });
  
  if (!response.ok) {
    throw new Error('Error en la solicitud');
  }
  
  const data = await response.json();
  return data;
}
        

Python (Requests)

            import requests

def send_query(query, knowledge_base_id):
    url = 'https://tu-dominio.com/api/v1/chat/query'
    payload = {
        'apiKey': 'tu-api-key',
        'query': query,
        'knowledgeBaseId': knowledge_base_id,
        'topK': 5
    }
    
    response = requests.post(url, json=payload)
    response.raise_for_status()
    return response.json()
        

C# (HttpClient)

            using System.Net.Http;
using System.Text.Json;

public async Task<ChatResponse> SendQueryAsync(string query, string knowledgeBaseId)
{
    var client = new HttpClient();
    var payload = new
    {
        apiKey = "tu-api-key",
        query = query,
        knowledgeBaseId = knowledgeBaseId,
        topK = 5
    };
    
    var json = JsonSerializer.Serialize(payload);
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    
    var response = await client.PostAsync("https://tu-dominio.com/api/v1/chat/query", content);
    response.EnsureSuccessStatusCode();
    
    var responseJson = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<ChatResponse>(responseJson);
}
        

Autenticación

Chat API

Parámetros del Body:

Ejemplo de Request:

Ejemplo de Response (200 OK):

Parámetros:

Ejemplo de Request:

Ejemplo de Response (SSE):

Parámetros Adicionales:

Parámetros del Body:

Query Parameters:

Widget API

Ejemplo de Response (200 OK):

Parámetros del Body:

Subscription API

Valores de Feature:

Parámetros del Body:

Ejemplo de Response (200 OK):

Progress API

Ejemplo de Response (200 OK):

Códigos de Error

Ejemplo de Error Response:

Ejemplos de Integración

JavaScript (Fetch API)

Python (Requests)

C# (HttpClient)

Procesando solicitud