WeirdBot API

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 basados en GPT-4o para operaciones principales y GPT-4o mini para tareas rápidas (detección de idioma, clasificación inicial). Incluye herramientas de texto, traducción y detección de idioma exclusivas de v1.

Modelos soportados v1: gpt-4o (principal, configurable vía OPENAI_MODEL) · gpt-4o-mini (mini). Acepta temperaturas 0-2.

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 en cada request.

Modelos soportados v2: gpt-5.4 (principal) · gpt-5.4-mini (rápido). Compatibles también: gpt-5, gpt-5.1, gpt-5-mini (via override por parámetro).

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"

Modelos Locales (Ollama)

Endpoints que invocan modelos corriendo localmente via Ollama. Sin costos por token, sin enviar datos a OpenAI. Modelo default: phi4-mini:latest (configurable via OLLAMA_DEFAULT_MODEL). Otros modelos probados: phi4:latest, qwen3.5:9b, qwen2.5-coder:7b, deepseek-coder:6.7b, llama3:8b.

Configuracion (.env)

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_DEFAULT_MODEL=phi4-mini:latest
OLLAMA_TEMPERATURE_DEFAULT=0.7
OLLAMA_MAX_TOKENS_DEFAULT=1000
OLLAMA_TIMEOUT=120
OLLAMA_MAX_FILE_SIZE_MB=10
OLLAMA_MAX_CHARS=400000
OLLAMA_MAX_TOKENS=100000
OLLAMA_CHUNK_SIZE=2000
OLLAMA_CHUNK_OVERLAP=200

GET Estado de Ollama

/ollama/status

Verifica si el servidor Ollama local esta corriendo. No requiere token.

curl https://model.apconecta.com/ollama/status

# {
#   "success": true,
#   "ollama_available": true,
#   "base_url": "http://localhost:11434",
#   "default_model": "phi4-mini:latest"
# }

GET Listar modelos instalados

/ollama/models

Lista todos los modelos que Ollama tiene descargados localmente (los que salieron en ollama list).

curl https://model.apconecta.com/ollama/models \
  -H "Authorization: Bearer TOKEN"

POST Chat con modelo local

/ollama/chat

Conversacion multi-turno con un modelo Ollama. Acepta el parametro model para elegir uno especifico (default phi4-mini:latest).

curl -X POST https://model.apconecta.com/ollama/chat \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "Eres un asistente util."},
      {"role": "user", "content": "Explicame RAG en 2 lineas."}
    ],
    "model": "phi4-mini:latest"
  }'

POST Generar texto

/ollama/generate

Generacion single-shot con un prompt simple (sin historial). Util para OCR, resumen, o extraccion puntual.

curl -X POST https://model.apconecta.com/ollama/generate \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Resume el siguiente texto en 3 bullets: ...",
    "model": "qwen2.5:7b",
    "temperature": 0.3
  }'

POST Analizar logs del sistema

/ollama/maintenance/analyze

Envia los logs de las ultimas N horas al modelo y devuelve un analisis estructurado: errores frecuentes, causas probables, acciones recomendadas. Util para operacion autonoma del servidor.

curl -X POST https://model.apconecta.com/ollama/maintenance/analyze \
  -H "Authorization: Bearer TOKEN" \
  -F "hours=24" -F "model=phi4-mini:latest"

POST Procesar documento local

/ollama/documents/process

Sube un PDF/txt/md y lo procesa con el modelo local: extraccion, resumen, QA. Job async con webhook de progreso.

curl -X POST https://model.apconecta.com/ollama/documents/process \
  -H "Authorization: Bearer TOKEN" \
  -F "files=@contrato.pdf" -F "model=phi4-mini:latest"

POST Vectorizar para RAG

/ollama/documents/vectorize

Toma archivos y los vectoriza en un store FAISS local con embeddings del modelo elegido. Ideal para construir bases de conocimiento privadas sin enviar datos a OpenAI.

curl -X POST https://model.apconecta.com/ollama/documents/vectorize \
  -H "Authorization: Bearer TOKEN" \
  -F "files=@manual.pdf" \
  -F "suffix=kb_local" -F "model=nomic-embed-text"

Familia de modelos locales probados

Modelo	Tamano	Caso de uso recomendado
`phi4-mini:latest`	~2.5 GB	Default. Clasificacion, mantenimiento, Q&A ligero
`phi4:latest`	9.1 GB	Phi-4 full, mejor razonamiento
`qwen3.5:9b-q4_K_M`	6.6 GB	Multilingue rapido, buena calidad general
`qwen2.5:7b`	4.7 GB	Generico balanceado
`qwen2.5-coder:7b`	4.7 GB	Sugerir fixes de codigo, SQL
`deepseek-coder:6.7b`	3.8 GB	Code review, refactoring
`llama3:8b`	4.7 GB	Chat conversacional general
`nomic-embed-text`	~0.3 GB	Embeddings para RAG/vectorizacion

Modelos Soportados (OpenAI)

Catalogo completo de modelos GPT que el sistema puede invocar. Cada version de la API (/v1/ y /v2/) tiene un modelo por defecto, pero cualquier modelo de la lista puede inyectarse por parametro sin tocar el codigo.

Modelos disponibles

Modelo	Variable en `config.py`	Default para	Temperatura
`gpt-4o`	`OPENAI_MODEL` (env-override)	v1 principal (chatbot, chatbotdb, sql_chat, analyze_conversation)	0-2 libre
`gpt-4o-mini`	`OPENAI_MODEL_MINI`	v1 mini (sql_chat, deteccion de idioma, query classifier)	0-2 libre
`gpt-5`	`OPENAI_MODEL_GPT5`	v2 alternativo (no es default)	solo `1`
`gpt-5.1`	`OPENAI_MODEL_GPT5_1`	v2 alternativo (no es default)	solo `1`
`gpt-5.4`	`OPENAI_MODEL_GPT5_4`	v2 principal (chatbot, chatbotdb, analyze_conversation)	solo `1`
`gpt-5-mini`	`OPENAI_MODEL_GPT5_MINI`	v2 alternativo mini (no default)	solo `1`
`gpt-5.4-mini`	`OPENAI_MODEL_GPT5_4_MINI`	v2 mini (sql_chat, traduccion de templates, operaciones rapidas)	solo `1`

Cambiar el modelo default de v1

El modelo principal de v1 es el unico que se puede sobreescribir via variable de entorno (no requiere recompilar).

# .env
# Por defecto usa gpt-4o. Cambiar a gpt-4o-mini o gpt-5 (forzando temperature=1) es tan facil como:
OPENAI_MODEL=gpt-4o-mini
# o
OPENAI_MODEL=gpt-5.4

Reiniciar el servicio despues de cambiar el .env.

Override por request (solo `/v2/`)

Los endpoints v2 aceptan model y model_mini como parametros form-data para usar un modelo distinto en una llamada especifica sin cambiar el default del sistema.

curl -X POST https://model.apconecta.com/v2/chatbotdb \
  -H "Authorization: Bearer TOKEN" \
  -F "query=Listame las facturas de julio" \
  -F "suffix=chatbotdb" \
  -F "customer=cliente_123" \
  -F "model=gpt-5.4-mini" \
  -F "model_mini=gpt-5-mini"

# Si omites los parametros, el endpoint usa:
#   model      = gpt-5.4
#   model_mini = gpt-5.4-mini

Nota: los modelos GPT-5.x imponen temperature=1. El servicio detecta esto automaticamente y ajusta la temperatura.

Que modelo usa cada endpoint

Endpoint	v1 default	v2 principal	v2 mini
`chatbot`	`gpt-4o`	`gpt-5.4`	`gpt-5.4-mini`
`chatbotdb`	`gpt-4o`	`gpt-5.4`	`gpt-5.4-mini`
`analyze_conversation`	`gpt-4o`	`gpt-5.4`	`gpt-5.4-mini`
`sql_chat`	`gpt-4o-mini`	`gpt-5.4-mini`	`gpt-5.4-mini`
`sql_generate_template`	`gpt-4o-mini`	`gpt-5.4-mini`	`gpt-5.4-mini`
`generate_text` / `translate_text` / `detect_language`	`gpt-4o`	-	-

Clasificador DGI Panama

Detecta el tipo de documento electronico segun el catalogo oficial de la Direccion General de Ingresos (Ficha Tecnica v1.00, campo B06). Reconoce 9 tipos: 01 Factura Op. Interna, 02 Importacion, 03 Exportacion, 04 NC referente a FE, 05 ND referente a FE, 06 NC Generica, 07 ND Generica, 08 Zona Franca, 09 Reembolso. Estrategia: CUFE (mas confiable), regex, Phi-4 mini como ultimo fallback.

GET Listar tipos soportados

/v1/documents/types

Devuelve el catalogo completo de tipos DGI (codigo, nombre en espanol/ingles y categoria).

curl -X GET https://model.apconecta.com/v1/documents/types \
  -H "Authorization: Bearer TOKEN"

POST Clasificar (sincrono)

/v1/documents/classify

Clasifica el texto en el momento. Regex primero (~1ms); si no hay match fuerte, llama a Phi-4 mini (puede tardar 5-60s). Ideal para integraciones pequenas o cuando el caller puede esperar.

text string REQUERIDO

Texto del documento (CAFE, factura impresa, JSON equivalente, etc.)

model string OPCIONAL

Modelo Ollama a usar como fallback. Default: phi4-mini:latest

use_llm_fallback bool OPCIONAL

Si true y regex no alcanza umbral, consulta Phi-4. Default: true

curl -X POST https://model.apconecta.com/v1/documents/classify \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Comprobante Auxiliar de Factura Electrónica ... CUFE: FE0420000155733287..."
  }'

# Respuesta:
# {
#   "success": true,
#   "classification": {
#     "code": "04",
#     "doc_type": "nota_credito_fe",
#     "label_es": "Nota de Credito Referente a una o Varias FE",
#     "category": "nota_credito",
#     "confidence": "high",
#     "method": "cufe",
#     "source": "DGI Ficha Tecnica v1.00 campo B06"
#   },
#   "model_used": "phi4-mini:latest"
# }

POST Clasificar (asincrono)

/v1/documents/classify/async

Encola el job, responde 202 inmediatamente con el job_id, y dispara el webhook cuando Phi-4 termina. Evita que el request HTTP se cuelgue esperando al LLM.

text string REQUERIDO

Texto a clasificar

suffix string OPCIONAL

Contexto del chatbot, viajara en el webhook payload

customer string OPCIONAL

Contexto del cliente, viajara en el webhook payload

curl -X POST https://model.apconecta.com/v1/documents/classify/async \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Comprobante Auxiliar de Factura Electrónica ... CUFE: FE0420...",
    "suffix": "mi_suffix",
    "customer": "cliente_123"
  }'

# Respuesta (HTTP 202):
# {
#   "success": true,
#   "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
#   "status": "pending",
#   "created_at": "2026-08-18T10:00:00"
# }

GET Estado del job

/v1/documents/classify/job/{job_id}

Consulta el estado de un job async. Alternativa al webhook para quien no quiera exponer endpoint HTTP.

curl -X GET https://model.apconecta.com/v1/documents/classify/job/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer TOKEN"

GET Listar jobs

/v1/documents/classify/jobs

Lista los jobs persistidos. Query params: status (pending/running/completed/failed), limit (default 50).

curl -X GET "https://model.apconecta.com/v1/documents/classify/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer TOKEN"

Flujo end-to-end recomendado

Registra el webhook escuchando los 3 eventos: document_classification_started, document_classification_completed, document_classification_failed.
Dispara la clasificacion async con POST /v1/documents/classify/async. Recibiras un job_id en milisegundos.
Phi-4 procesa en background (5-60s). Tu request no se cuelga.
Recibes el webhook document_classification_completed con data.result.code (codigo oficial DGI 01-09) listo para enrutar por categoria.
Si Phi-4 falla: llega document_classification_failed con el error original en data.error.

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`.

Clasificacion de Documentos (DGI Panama)

Emitidos por POST /v1/documents/classify/async. El catalogo oficial usa el codigo B06 del CUFE (Ficha Tecnica DGI v1.00, tipos 01-09).

Evento	Cuando se dispara
`document_classification_started`	Al encolar el job en `POST /v1/documents/classify/async`. Payload incluye `job_id`, `model` y `text_chars`.
`document_classification_completed`	Cuando Phi-4 termina y devuelve el `doc_type`. `data.result.code` trae el codigo oficial DGI (`"01"`-`"09"`) y `data.result.method` indica si la deteccion vino del CUFE, regex o LLM.
`document_classification_failed`	Cuando Phi-4 lanza excepcion (Ollama caido, timeout, etc.). `data.error` contiene el mensaje original.

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 / GPT-4o (v1 + v2)

v1: gpt-4o + gpt-4o-mini. v2: gpt-5.4 + gpt-5.4-mini con selección dinámica por endpoint y override por request.

Clasificador DGI Panama

Detecta tipo de documento electronico DGI (codigo B06 del CUFE: 01-09). Regex primero; Phi-4 mini local como fallback. Modo async con webhook al terminar.

Modelos Locales (Ollama)

Endpoints /ollama/* para invocar modelos locales sin costo por token. Default phi4-mini:latest. Soporta mantenimiento autonomo, soporte al developer, procesamiento de documentos y el clasificador DGI.

Documentación

Flujos del Chatbot

Configuración de APIs

Configuración MySQL

Endpoints Principales

GET Health Check

POST Chatbot RAG GPT-4o GPT-5.4

Parámetros Requeridos:

Parámetros Opcionales:

POST Chatbot DB MySQL GPT-4o GPT-5.4

Parámetros Requeridos:

Parámetros Opcionales:

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

Parámetros Requeridos:

Parámetros Opcionales:

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

Parámetros Requeridos:

Parámetros Opcionales:

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

Parámetros Requeridos:

Parámetros Opcionales:

Respuesta:

DELETE Borrar Historial SQL Chat solo v1

Parámetros Requeridos:

POST Agregar Datos GPT-4o GPT-5.4 mini

POST Generar Texto solo v1

POST Traducir Texto solo v1

POST Detectar Idioma solo v1

POST Generar Template SQL solo v1

Modelos Locales (Ollama)

Configuracion (.env)

GET Estado de Ollama

GET Listar modelos instalados

POST Chat con modelo local

POST Generar texto

POST Analizar logs del sistema

POST Procesar documento local

POST Vectorizar para RAG

Familia de modelos locales probados

Modelos Soportados (OpenAI)

Modelos disponibles

Cambiar el modelo default de v1

Override por request (solo /v2/)

Que modelo usa cada endpoint

Clasificador DGI Panama

GET Listar tipos soportados

POST Clasificar (sincrono)

POST Clasificar (asincrono)

GET Estado del job

GET Listar jobs

Flujo end-to-end recomendado

Webhooks

POST Registrar Webhook

GET Listar Webhooks

DELETE Eliminar Webhook

Eventos Soportados

Operaciones CRUD

Configuracion de Modelos

Sistema

Clasificacion de Documentos (DGI Panama)

Configuración de APIs y Campos Calculados

Estructura de apis_config.json

Propiedades de Campos

Fórmulas de Cálculo (Campos Computados)

Ejemplo: Factura con Items y Cálculos

Cómo Funcionan los Cálculos

Casos de Uso

Facturación

Órdenes de Compra

Reportes

Características

RAG con FAISS

Hybrid Search

API Integration

GPT-5.4 / GPT-4o (v1 + v2)

Clasificador DGI Panama

Modelos Locales (Ollama)

Override por request (solo `/v2/`)