Configuración de APIs

Guía exhaustiva de todos los campos soportados en apis_config.json

Tabla de Contenidos

1. Visión General

El archivo apis_config.json define todas las APIs externas que el chatbot puede utilizar para operaciones CRUD (Create, Read, Update, Delete).

Sistema 100% Genérico: Funciona con CUALQUIER dominio (cotizaciones, reservas, pedidos, tickets, etc.) simplemente configurando este archivo JSON. Zero cambios de código Python.

Ubicación: resources/vectorstore/{suffix}/apis_config.json

2. Estructura del Archivo

{ "apis": { "Nombre de la API": { "enabled": true, "base_url": "https://api.example.com", "endpoint": "/api/v1/resource", "method": "POST", "operation": "create", "token": "tu-token-aqui", "resource_type": "quotation", "calculation_rules": { ... }, "fields": { ... }, "response_mapping": { ... } } } }

3. Campos de Configuración de API

3.1. Campos Obligatorios

enabled
Type: boolean | OBLIGATORIO

Descripción: Activa o desactiva la API.

Valores: true | false

Ejemplo:
"enabled": true
base_url
Type: string | OBLIGATORIO

Descripción: URL base del servidor API.

Formato: https://dominio.com (sin trailing slash)

Ejemplo:
"base_url": "https://api.miempresa.com"
endpoint
Type: string | OBLIGATORIO

Descripción: Endpoint específico de la API.

Formato: Ruta relativa con placeholders opcionales {id}, {resource_id}, etc.

Ejemplos:
"endpoint": "/api/v1/quotations"
"endpoint": "/api/v1/quotations/{id}"
"endpoint": "/api/v1/customers/{customer_id}/orders/{id}"
method
Type: string | OBLIGATORIO

Descripción: Método HTTP de la petición.

Valores: GET | POST | PUT | PATCH | DELETE

Ejemplo:
"method": "POST"
token
Type: string | OBLIGATORIO

Descripción: Token de autenticación para la API (Bearer token).

Formato: String del token (será enviado como Authorization: Bearer {token})

Ejemplo:
"token": "9|shIrISTPHEbvmpPPnGgH0ZtBxqTICxLYaw7MHpmq35b3d381"
fields
Type: object | OBLIGATORIO

Descripción: Schema completo de todos los campos que la API acepta.

Formato: Objeto con campos como keys. Ver sección Configuración de Campos.

3.2. Campos Opcionales

operation
Type: string | OPCIONAL

Descripción: Tipo de operación CRUD que realiza la API.

Valores: create | read | update | delete

Uso: Ayuda al sistema a clasificar la intención del usuario.

Ejemplo:
"operation": "create"
description
Type: string | OPCIONAL

Descripción: Descripción legible de lo que hace la API.

Uso: Para logging y debugging.

Ejemplo:
"description": "Crear nueva cotización con productos"
timeout
Type: integer | OPCIONAL (default: 30)

Descripción: Timeout de la petición HTTP en segundos.

Ejemplo:
"timeout": 10
response_mapping
Type: object | OPCIONAL

Descripción: Mapeo de la estructura de respuesta de la API.

Subopciones:

  • id_field: Ruta al ID del recurso (ej: "data.id")
  • data_field: Ruta a los datos del recurso (para GET)
  • message_field: Ruta al mensaje de respuesta
  • success_field: Ruta al campo que indica éxito/fallo
  • exclude_from_merge: Array de campos a excluir al mergear datos
Ejemplo:
"response_mapping": { "id_field": "data.id", "data_field": "data", "message_field": "message", "success_field": "success", "exclude_from_merge": ["id", "created_at", "updated_at"] }

3.3. Campos Nuevos (Sistema Genérico) NUEVO

resource_type
Type: string | NUEVO | OPCIONAL

Descripción: Tipo de recurso que maneja la API (para sistema genérico).

Valores sugeridos: quotation, reservation, order, appointment, ticket, booking, lead, customer

Uso: El sistema usa este valor para:

  • Guardar estado genérico (last_resource_id, last_resource_type)
  • Permitir referencias futuras ("modificar la última reserva")
  • Mensajes contextuales
Ejemplos por Dominio:
"resource_type": "quotation" // E-commerce
"resource_type": "reservation" // Hotel
"resource_type": "appointment" // Consultorio médico
"resource_type": "ticket" // Soporte técnico
calculation_rules
Type: object | NUEVO | OPCIONAL

Descripción: Reglas personalizadas para auto-generación de campos calculados.

Uso: Define lógica de negocio específica del dominio sin hardcodear en código Python.

Subopciones:

  • auto_fields_prompt (string): Instrucciones para OpenAI sobre cómo calcular campos auto_generated
Ejemplo - Cotizaciones:
"calculation_rules": { "auto_fields_prompt": "Para campos auto_generated: 1) Si el campo es 'subtotal' y hay un array 'details' con 'quantity' y 'unit_price', calcula la suma de (quantity * unit_price) para todos los items. 2) Si el campo es 'tax' y hay 'subtotal', calcula el 7% del subtotal. 3) Si el campo es 'total', calcula subtotal + tax - discount." }
Ejemplo - Reservas de Hotel:
"calculation_rules": { "auto_fields_prompt": "Para campos auto_generated: 1) Si el campo es 'total_nights' y hay 'check_in_date' y 'check_out_date', calcula la diferencia en días. 2) Si el campo es 'total_cost' y hay 'total_nights' y 'room_rate', multiplica ambos." }

4. Configuración de Campos (fields)

Cada campo en el objeto fields define un dato que la API espera recibir.

4.1. Campos Básicos

Campo Tipo ¿Requerido? Descripción
type string SÍ Tipo de dato: string, number, integer, boolean, date, datetime, array, object
required boolean SÍ Indica si el campo es obligatorio (true | false)
description string SÍ Descripción del campo para que OpenAI entienda su propósito (CRÍTICO para captura correcta)
Descripción CRÍTICA: OpenAI usa la descripción para entender qué dato capturar, validar que sea apropiado, y generar preguntas de captura. ¡Debe ser clara y específica!

4.2. Campos de Validación

Campo Tipo Descripción Ejemplo
pattern string Regex para validar formato "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
min number Valor mínimo (números) "min": 0.01
max number Valor máximo (números) "max": 10000
max_length integer Longitud máxima (strings) "max_length": 500

4.3. Campos de UI/Captura

Campo Tipo Descripción
display_label_es
display_label_en		 string Etiqueta amigable para mostrar al usuario en español/inglés. El chatbot usa esto en mensajes de captura.
capture_order integer Orden en que se capturan los campos (menor = primero). Define la secuencia de preguntas del chatbot.

4.4. Auto-Generación NUEVO

Campos Auto-Generados: El sistema NO pregunta por estos campos al usuario, los calcula automáticamente usando OpenAI basándose en la descripción, fórmula y datos disponibles.
auto_generated
Type: boolean | NUEVO

Descripción: Indica que el campo se genera automáticamente.

Valores: true | false

Ejemplo:
"quotation_date": { "type": "date", "auto_generated": true, "default": "today" }
default
Type: any | NUEVO

Descripción: Valor por defecto si no se puede calcular.

Valores especiales:

  • "today": Fecha actual (para type: date)
  • "now": Timestamp actual (para type: datetime)
  • 0: Cero numérico
  • "": String vacío
Ejemplo:
"discount": { "type": "number", "auto_generated": true, "default": 0, "description": "Descuento (0 si no se especifica)" }
formula
Type: string | NUEVO

Descripción: Fórmula Python para calcular el campo.

Uso: OpenAI genera código basado en esta fórmula + datos disponibles.

Formato: Expresión Python válida. Variables disponibles: Todos los campos capturados.

Ejemplos:
// Suma de items en array "formula": "sum(item['quantity'] * item['unit_price'] for item in details)" // Porcentaje "formula": "subtotal * 0.07" // Operación matemática "formula": "subtotal + tax - discount" // Diferencia de fechas "formula": "(check_out_date - check_in_date).days"
calculated_from
Type: array | NUEVO

Descripción: Lista de campos de los que depende este cálculo.

Uso: El sistema sabe qué datos necesita antes de calcular.

Formato: Array de strings con nombres de campos. Notación dot para arrays: "details.quantity"

Ejemplo:
"total": { "type": "number", "auto_generated": true, "formula": "subtotal + tax - discount", "calculated_from": ["subtotal", "tax", "discount"], "description": "Total final (subtotal + impuesto - descuento)" }

4.5. Campos de Tipo Array

Para campos tipo array, usa la estructura especial con items:

"details": { "type": "array", "required": true, "description": "Lista de productos a cotizar", "display_label_es": "productos", "display_label_en": "products", "items": { "product_name": { "type": "string", "required": true, "description": "Nombre del producto" }, "quantity": { "type": "number", "min": 0.01, "required": true, "description": "Cantidad" }, "unit_price": { "type": "number", "min": 0, "required": true, "description": "Precio unitario en USD" } } }

5. Ejemplos Completos por Dominio

E-commerce: Cotizaciones

{ "Creacion de Cotizacion": { "enabled": true, "base_url": "https://api.miempresa.com", "endpoint": "/api/v1/quotations", "method": "POST", "operation": "create", "token": "tu-token-aqui", "resource_type": "quotation", "calculation_rules": { "auto_fields_prompt": "Para 'subtotal': suma quantity*unit_price de items en 'details'. Para 'tax': calcula 7% del subtotal. Para 'total': suma subtotal + tax - discount." }, "fields": { "customer_name": { "type": "string", "required": true, "description": "Nombre completo del cliente", "display_label_es": "nombre completo", "capture_order": 1 }, "details": { "type": "array", "required": true, "description": "Lista de productos a cotizar", "items": { "product_name": {"type": "string", "required": true}, "quantity": {"type": "number", "required": true}, "unit_price": {"type": "number", "required": true} } }, "subtotal": { "type": "number", "auto_generated": true, "formula": "sum(item['quantity'] * item['unit_price'] for item in details)", "calculated_from": ["details.quantity", "details.unit_price"] }, "tax": { "type": "number", "auto_generated": true, "formula": "subtotal * 0.07", "calculated_from": ["subtotal"] }, "total": { "type": "number", "auto_generated": true, "formula": "subtotal + tax - discount", "calculated_from": ["subtotal", "tax", "discount"] } } } }

Hotelería: Reservas

{ "Crear Reserva": { "enabled": true, "base_url": "https://api.mihotel.com", "endpoint": "/api/v1/reservations", "method": "POST", "resource_type": "reservation", "calculation_rules": { "auto_fields_prompt": "Para 'total_nights': calcula días entre check_in_date y check_out_date. Para 'total_cost': multiplica total_nights * room_rate." }, "fields": { "guest_name": { "type": "string", "required": true, "description": "Nombre completo del huésped" }, "check_in_date": { "type": "date", "required": true, "description": "Fecha de entrada (YYYY-MM-DD)" }, "check_out_date": { "type": "date", "required": true, "description": "Fecha de salida (YYYY-MM-DD)" }, "total_nights": { "type": "integer", "auto_generated": true, "formula": "(check_out_date - check_in_date).days", "calculated_from": ["check_in_date", "check_out_date"] }, "total_cost": { "type": "number", "auto_generated": true, "formula": "total_nights * room_rate", "calculated_from": ["total_nights", "room_rate"] } } } }

6. Flujo de Trabajo

  1. Usuario inicia conversación: "Quiero hacer una cotización de 5 laptops"
  2. Sistema detecta intención: Detecta operación CREATE y carga API con operation: "create"
  3. Captura de datos: Sistema captura campos en orden según capture_order
  4. Enriquecimiento con AI: Busca en vectorstore, completa información faltante
  5. Generación de campos calculados: Usa formula y calculated_from para generar código Python y ejecutarlo
  6. Confirmación: Presenta todos los datos al usuario para confirmar
  7. Envío a API: POST/PUT/DELETE a la API externa con los datos capturados + calculados
  8. Guardado de estado: Guarda last_resource_id y last_resource_type para referencias futuras

7. Mejores Prácticas

Descripciones Claras

BUENO:
"description": "Teléfono del cliente (8-15 dígitos, puede incluir código de país con +)"
MALO:
"description": "Teléfono"

Validaciones Específicas

BUENO:
{ "pattern": "^\\+?[0-9]{8,15}$", "min": 8, "max_length": 15 }

Fórmulas Documentadas

BUENO:
{ "formula": "subtotal * 0.07", "calculated_from": ["subtotal"], "description": "Impuesto (7% del subtotal para Panamá)" }

Resource Type Específico

BUENO:
"resource_type": "appointment"
MALO:
"resource_type": "generic"

Recursos Adicionales