WeirdBot API - Documentación

Documentación

Flujos del Chatbot

Diagrama interactivo de todos los flujos conversacionales y estados del sistema

Configuración de APIs

Guía completa de todos los campos para integrar APIs externas

Configuración MySQL

Documentación de Hybrid Search y conexión a bases de datos

Endpoints Principales

Endpoints estables con GPT-4o. Incluye herramientas de texto, traducción y detección de idioma exclusivas de v1.

Endpoints con GPT-5.4 para operaciones principales y GPT-5.4 mini para operaciones rápidas (traducción de templates, SQL). Los parámetros opcionales model y model_mini permiten personalizar el modelo usado.

GET Health Check

/health

Verifica el estado del servicio.

curl https://model.apconecta.com/health

POST Chatbot RAG GPT-4o GPT-5.4

/v1/chatbot

/v2/chatbot

Endpoint principal del chatbot conversacional con RAG y búsqueda híbrida.

Parámetros Requeridos:

query string REQUERIDO

Pregunta o consulta del usuario

suffix string REQUERIDO

Identificador del modelo (ej: "modelo1")

customer string REQUERIDO

Identificador del cliente

Parámetros Opcionales:

language string Opcional

Idioma: "es" o "en" (default: "es")

timezone string Opcional

Zona horaria (default: "America/Panama")

token string Opcional

Token para API externa configurada

remove boolean Opcional

Si true, elimina el historial previo del cliente (default: false)

openai_temperature float Opcional

Override de temperatura OpenAI (0.0 - 2.0)

model string Opcional

Modelo principal (default: GPT-5.4)

model_mini string Opcional

Modelo para operaciones rápidas (default: GPT-5.4 mini)

curl -X POST https://model.apconecta.com/v1/chatbot \
  -H "Authorization: Bearer TOKEN" \
  -F "query=¿Qué servicios ofrecen?" \
  -F "suffix=modelo1" \
  -F "customer=test"

curl -X POST https://model.apconecta.com/v2/chatbot \
  -H "Authorization: Bearer TOKEN" \
  -F "query=¿Qué servicios ofrecen?" \
  -F "suffix=modelo1" \
  -F "customer=test"

POST Chatbot DB MySQL GPT-4o GPT-5.4

/v1/chatbotdb

/v2/chatbotdb

Chatbot especializado en operaciones MySQL (SELECT / INSERT / UPDATE / DELETE). Elimina 2-3 llamadas OpenAI respecto al chatbot completo porque asume que toda operación va a base de datos — sin clasificación de fuente.

Requisito previo: el sufijo debe tener database_config.json configurado (se envía en /add_data o /sql_config).

Parámetros Requeridos:

query string REQUERIDO

Consulta del usuario sobre la base de datos

suffix string REQUERIDO

Identificador del modelo

customer string REQUERIDO

Identificador del cliente

Parámetros Opcionales:

language string Opcional

Idioma: "es" o "en" (default: "es")

timezone string Opcional

Zona horaria (default: "America/Panama")

model string Opcional

Modelo principal (default: GPT-5.4)

model_mini string Opcional

Modelo para operaciones rápidas (default: GPT-5.4 mini)

curl -X POST https://model.apconecta.com/v1/chatbotdb \
  -H "Authorization: Bearer TOKEN" \
  -F "query=Busca las facturas de Angel Hidalgo" \
  -F "suffix=chatbotdb" \
  -F "customer=test"

curl -X POST https://model.apconecta.com/v2/chatbotdb \
  -H "Authorization: Bearer TOKEN" \
  -F "query=Busca las facturas de Angel Hidalgo" \
  -F "suffix=chatbotdb" \
  -F "customer=test"

POST Analizar Conversación GPT-4o GPT-5.4

/v1/analyze_conversation

/v2/analyze_conversation

Analiza el historial de conversación y el estado de un cliente para determinar si se debe enviar un mensaje proactivo. No genera respuesta para el usuario — retorna un análisis interno. Útil para automatizaciones y reportes.

Parámetros Requeridos:

suffix string REQUERIDO

Identificador del modelo

customer string REQUERIDO

Identificador del cliente a analizar

Parámetros Opcionales:

language string Opcional

Idioma: "es" o "en" (default: "es")

temperature float Opcional

Temperatura OpenAI entre 0.0 y 2.0 (default: 0.7)

timezone string Opcional

Zona horaria (default: "America/Panama")

model string Opcional

Modelo principal para el análisis (default: GPT-5.4)

model_mini string Opcional

Modelo para operaciones rápidas (default: GPT-5.4 mini)

curl -X POST https://model.apconecta.com/v1/analyze_conversation \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=modelo1" \
  -F "customer=test"

curl -X POST https://model.apconecta.com/v2/analyze_conversation \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=modelo1" \
  -F "customer=test"

POST Configurar SQL Chat Text-to-SQL GPT-4o GPT-5.4 mini

/v1/sql_config

/v2/sql_config

Configura la conexión MySQL para el servicio Text-to-SQL conversacional. No requiere archivos ni FAISS — solo guarda la configuración de base de datos y las reglas de negocio opcionales.

En v2, la traducción automática del b_template usa GPT-5.4 mini para mayor velocidad.

Parámetros Requeridos:

suffix string REQUERIDO

Identificador del modelo

database_config json REQUERIDO

Configuración MySQL: host, username, password, database, port (default 3306), allowed_tables (ver docs)

Parámetros Opcionales:

b_template string Opcional

Reglas de negocio para generación de SQL (ej: "La tabla clientes usa el campo id_cliente como PK")

curl -X POST https://model.apconecta.com/v1/sql_config \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=reportes" \
  -F 'database_config={"host":"db.empresa.com","username":"reader","password":"pass","database":"ventas_db","allowed_tables":["facturas","clientes"]}'

curl -X POST https://model.apconecta.com/v2/sql_config \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=reportes" \
  -F 'database_config={"host":"db.empresa.com","username":"reader","password":"pass","database":"ventas_db","allowed_tables":["facturas","clientes"]}'

POST SQL Chat Text-to-SQL GPT-4o GPT-5.4 mini

/v1/sql_chat

/v2/sql_chat

Chatbot Text-to-SQL puro — convierte lenguaje natural en consultas SELECT y devuelve los datos con una respuesta conversacional. Mantiene historial multi-turno por session_id. No usa FAISS ni vectorstore. Requiere haber configurado la BD con sql_config previamente.

Solo consultas SELECT. INSERT / UPDATE / DELETE son bloqueados por seguridad.

En v2, todas las operaciones Text-to-SQL usan GPT-5.4 mini para reducir costos manteniendo precisión.

Parámetros Requeridos:

query string REQUERIDO

Pregunta en lenguaje natural sobre los datos

suffix string REQUERIDO

Identificador del modelo (debe tener BD configurada con sql_config)

session_id string REQUERIDO

ID de sesión para mantener contexto entre turnos (ej: ID de usuario o conversación)

Parámetros Opcionales:

language string Opcional

Idioma de la respuesta: "es" o "en" (default: "es")

model string Opcional

Modelo para SQL (default: GPT-5.4 mini)

model_mini string Opcional

Modelo mini (default: GPT-5.4 mini)

Respuesta:

{
  "success": true,
  "answer": "El cliente Juan García tuvo 3 facturas por $15,000 en enero.",
  "sql": "SELECT * FROM facturas WHERE cliente = 'Juan García' AND mes = 1",
  "data": [{ "id": 1, "monto": 5000 }, ...],
  "rows_count": 3,
  "columns": ["id", "monto", "fecha"],
  "session_id": "user_123"
}

curl -X POST https://model.apconecta.com/v1/sql_chat \
  -H "Authorization: Bearer TOKEN" \
  -F "query=Muéstrame las facturas de enero de Juan García" \
  -F "suffix=reportes" \
  -F "session_id=user_123"

curl -X POST https://model.apconecta.com/v2/sql_chat \
  -H "Authorization: Bearer TOKEN" \
  -F "query=Muéstrame las facturas de enero de Juan García" \
  -F "suffix=reportes" \
  -F "session_id=user_123"

DELETE Borrar Historial SQL Chat solo v1

/v1/sql_chat/history

Elimina el historial de una sesión de /v1/sql_chat. Útil para iniciar una conversación desde cero sin contexto previo.

Parámetros Requeridos:

suffix string REQUERIDO

Identificador del modelo

session_id string REQUERIDO

ID de sesión a eliminar

curl -X DELETE https://model.apconecta.com/v1/sql_chat/history \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=reportes" \
  -F "session_id=user_123"

POST Agregar Datos GPT-4o GPT-5.4 mini

/v1/add_data

/v2/add_data

Carga documentos y configuraciones para el chatbot. Al menos un campo es obligatorio (archivo, templates, configuración de BD o APIs).

En v2, la traducción automática del b_template al idioma secundario usa GPT-5.4 mini para mayor velocidad y menor costo.

suffix string REQUERIDO

Identificador del modelo

files file[] Opcional

Archivos (pdf, docx, txt, csv, json, md, html, xml, xlsx)

a_template string Opcional

Contexto del negocio (Template A)

b_template string Opcional

Instrucciones del chatbot (Template B). Se traduce automáticamente al idioma secundario.

database_config json Opcional

Configuración MySQL (ver docs)

apis_config json Opcional

Configuración de APIs externas (ver docs)

openai_api_key string Opcional

API key de OpenAI específica para este suffix

remove boolean Opcional

Si true, elimina el contenido previo antes de cargar (default: false)

curl -X POST https://model.apconecta.com/v1/add_data \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=modelo1" \
  -F "files=@documento.pdf" \
  -F "b_template=Eres un asistente de ventas..."

curl -X POST https://model.apconecta.com/v2/add_data \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=modelo1" \
  -F "files=@documento.pdf" \
  -F "b_template=Eres un asistente de ventas..."

POST Generar Texto solo v1

/v1/generate_text

Genera texto con OpenAI GPT-4o a partir de un prompt libre. Sin historial ni RAG.

prompt string REQUERIDO

Texto de entrada para el modelo

curl -X POST https://model.apconecta.com/v1/generate_text \
  -H "Authorization: Bearer TOKEN" \
  -F "prompt=Escribe un resumen de inteligencia artificial"

POST Traducir Texto solo v1

/v1/translate_text

Traduce texto entre idiomas usando GPT-4o.

text string REQUERIDO

Texto a traducir

target_language string REQUERIDO

Idioma destino (ej: "en", "es", "fr")

curl -X POST https://model.apconecta.com/v1/translate_text \
  -H "Authorization: Bearer TOKEN" \
  -F "text=Hola mundo" \
  -F "target_language=en"

POST Detectar Idioma solo v1

/v1/detect_language

Detecta el idioma de un texto usando OpenAI.

text string REQUERIDO

Texto cuyo idioma se quiere detectar

curl -X POST https://model.apconecta.com/v1/detect_language \
  -H "Authorization: Bearer TOKEN" \
  -F "text=Hello, how are you?"

POST Generar Template SQL solo v1

/v1/sql_generate_template

Genera automáticamente reglas de negocio (b_template) para SQL Chat a partir del esquema de la base de datos conectada.

suffix string REQUERIDO

Identificador del modelo (debe tener BD configurada)

curl -X POST https://model.apconecta.com/v1/sql_generate_template \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=reportes"

Webhooks

Sistema de notificaciones HTTP en tiempo real. WeirdBot dispara un POST a tu URL cuando ocurren eventos importantes.

POST Registrar Webhook

/v1/alerts/webhooks

Suscribe una URL a uno o varios eventos. Cada vez que el evento ocurra, WeirdBot enviará un POST con el payload del evento. Reintentos automáticos: hasta 3 intentos con timeout de 10 segundos.

curl -X POST https://tu-servidor/v1/alerts/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-sistema.com/webhook",
    "events": ["model_config_completed", "model_config_translation_completed", "model_config_error", "lead_created", "proactive_message"]
  }'

GET Listar Webhooks

/v1/alerts/webhooks

curl -X GET https://tu-servidor/v1/alerts/webhooks \
  -H "Authorization: Bearer TOKEN"

DELETE Eliminar Webhook

/v1/alerts/webhooks/{webhook_id}

curl -X DELETE https://tu-servidor/v1/alerts/webhooks/1 \
  -H "Authorization: Bearer TOKEN"

Eventos Soportados

Operaciones CRUD

Evento	Cuándo se dispara
`lead_created`	Después de POST exitoso a API externa
`lead_updated`	Después de PUT/PATCH exitoso a API externa
`lead_deleted`	Después de DELETE exitoso a API externa
`lead_confirmed`	Cuando el usuario confirma los datos capturados
`lead_queried`	Después de GET exitoso a API externa

Configuracion de Modelos

Evento	Cuándo se dispara
`model_config_started`	Al iniciar proceso en `/v1/add_data`, `/v1/sql_config`, `/v1/sql_generate_template` o `/v2/generate_chatbot_template`. En el caso de `generate_chatbot_template` incluye `job_id` en el payload.
`model_config_completed`	Al finalizar exitosamente la configuracion del modelo. En `/v2/generate_chatbot_template` se dispara desde el background job (puede tardar 30-90s) e incluye `job_id`, `flow_type` y `table_names` en el payload. El template completo se obtiene via `GET /v2/generate_chatbot_template/status?job_id=...`
`model_config_translation_completed`	Al finalizar la traduccion automatica del `b_template` en background. Incluye `target_language` y `translated_chars` en el payload
`model_config_error`	Cuando ocurre una excepcion durante la configuracion. En `/v2/generate_chatbot_template` se dispara desde el background job e incluye `job_id` en el payload.

Sistema

Evento	Cuándo se dispara
`limit_exceeded`	Cuando se supera el límite diario configurado
`error_429`	Cuando OpenAI retorna rate limit (quota excedida)
`error_general`	Error general no específico durante el procesamiento
`daily_report`	Reporte diario de uso (manual o programado)
`proactive_message`	Seguimiento proactivo recomendado por IA. Se dispara desde `scripts/proactive_followup.py` (cron) cuando GPT detecta que se debe enviar un mensaje al cliente (registro incompleto, conversacion abandonada, cita pendiente, etc.). Payload incluye `suggested_message`, `message_type`, `urgency`, `recommended_timing` e `idle_minutes`.

Configuración de APIs y Campos Calculados

Estructura de apis_config.json

El archivo apis_config.json define la estructura de datos y comportamiento de cada API integrada. Se almacena en resources/vectorstore/{suffix}/apis_config.json

{
  "apis": {
    "API_Name": {
      "method": "POST|GET|PUT|DELETE",
      "base_url": "https://api.example.com",
      "endpoint": "/api/v1/resource",
      "fields": {
        "field_name": {
          "type": "string|number|date|array",
          "required": true|false,
          "auto_generated": true|false,
          "calculated_from": ["field1", "field2"],
          "calculation_formula": "field1 * field2"
        }
      }
    }
  }
}
        

Propiedades de Campos

Propiedad	Descripción	Ejemplo
`type`	Tipo de dato del campo. Soporta: string, number, date, boolean, array, object	`"string"` o `"array"`
`required`	Si `true`, el campo es obligatorio y la validación fallará si no está presente	`true`
`auto_generated`	Si `true`, el campo es generado automáticamente por GPT-4o/GPT-5.4 basado en `b_template` (instrucciones). Ejemplos: InvoiceNumber, timestamps, IDs únicos. OpenAI extrae ejemplos de formato de las instrucciones.	`true`
`calculated_from`	Array de nombres de campos usados para calcular este campo. Se resuelven mediante fuzzy matching (tolerante a variaciones de nombre)	`["Quantity", "Unit_Price"]`
`calculation_formula`	Fórmula Python para calcular el valor. Solo se ejecuta si `calculated_from` está definido. Variables disponibles: campo = valor mapeado. Ejemplo: `Quantity * Unit_Price`	`"Quantity * Unit_Price"`

Fórmulas de Cálculo (Campos Computados)

Los campos calculados se regeneran automáticamente cuando se actualizan sus dependencias. Útil para recalcular subtotales, impuestos, totales cuando los items cambian.

Ejemplo: Factura con Items y Cálculos

"Invoice": {
  "method": "POST",
  "fields": {
    "InvoiceNumber": {
      "type": "string",
      "required": true,
      "auto_generated": true
      // OpenAI extrae formato de b_template: "FAC-20260604-0001"
    },
    "Items": {
      "type": "array",
      "required": true,
      "item_schema": {
        "Description": {"type": "string"},
        "Quantity": {"type": "number"},
        "Unit_Price": {"type": "number"},
        "Net_line": {
          "type": "number",
          "calculated_from": ["Quantity", "Unit_Price"],
          "calculation_formula": "Quantity * Unit_Price"
          // Se recalcula automáticamente para cada item
        }
      }
    },
    "Subtotal": {
      "type": "number",
      "calculated_from": ["Items"],
      "calculation_formula": "sum([item.get('Net_line', 0) for item in Items])"
    },
    "Tax": {
      "type": "number",
      "calculated_from": ["Subtotal"],
      "calculation_formula": "Subtotal * 0.07"
    },
    "Total": {
      "type": "number",
      "calculated_from": ["Subtotal", "Tax"],
      "calculation_formula": "Subtotal + Tax"
    }
  }
}
        

Cómo Funcionan los Cálculos

Mapeo de Campos: Se normalizan los nombres de campos (ej: "product_name" → "Description") mediante fuzzy matching
Validación: Se validan los tipos de datos
Cálculo de Dependencias: Los campos calculados se procesan en orden de dependencias (Subtotal → Tax → Total)
Ejecución de Fórmula: Se ejecuta la calculation_formula con contexto de variables disponibles
Regeneración Automática: Cuando se actualizan items o cantidades, todas las fórmulas dependientes se recalculan automáticamente

Casos de Uso

Facturación

InvoiceNumber auto (FAC-fecha-seq), Subtotal, Tax, Total con recálculo automático

Órdenes de Compra

PO_Number, Quantity * Unit_Cost por línea, Total con impuestos

Reportes

IDs automáticos, dates, totalizaciones complejas de múltiples fuentes

⚠️ Nota Importante: Las fórmulas de cálculo se extraen del formato de instrucciones (b_template). El sistema es 100% instruction-driven: no hay hardcoding de formatos. Si cambias el formato en las instrucciones, OpenAI automáticamente lo seguirá en próximas generaciones.

Características

RAG con FAISS

Búsqueda semántica en documentos estáticos con embeddings de OpenAI

Hybrid Search

Text-to-SQL con GPT-4o / GPT-5.4 para consultas MySQL en tiempo real

API Integration

Sistema genérico para llamadas automáticas a APIs externas

GPT-5.4 (v2)

Modelos GPT-5.4 y GPT-5.4 mini con selección dinámica por operación