API

BiVelio expone su funcionalidad a traves de Edge Functions desplegadas en Supabase. Todas las peticiones requieren autenticacion y operan dentro del contexto del workspace del usuario.

Autenticacion

Todas las peticiones a la API requieren un token en el header Authorization:


Authorization: Bearer <token>

Tipos de token

Tipo	Uso	Obtencion
JWT de usuario	Peticiones desde el frontend o integraciones externas	Login via Supabase Auth
Service Role Key	Llamadas internas entre Edge Functions	Variable de entorno del proyecto

El JWT de usuario incluye el org_id del workspace, que se utiliza para filtrar todos los datos devueltos por la API.

La Service Role Key tiene acceso completo a la base de datos. Nunca debe exponerse en el frontend ni compartirse con terceros.

Base URL


https://<project-ref>.supabase.co/functions/v1/<function-name>

Endpoints principales

Agentes IA

Endpoint	Metodo	Descripcion
`agent-structured`	POST	Ejecuta un agente invocable con input estructurado
`agent-runtime`	POST	Runtime de ejecucion de agentes autonomos
`agent-knowledge-ingest`	POST	Ingesta de documentos en la base de conocimiento
`agent-test-generator`	POST	Genera tests para validar un agente
`agent-test-runner`	POST	Ejecuta tests de validacion de agentes

Comunicaciones

Endpoint	Metodo	Descripcion
`email-classifier`	POST	Clasifica un email por categoria y urgencia
`email-draft-generator`	POST	Genera borrador de respuesta a un email
`conversation-router`	POST	Enruta conversaciones al agente o operador adecuado
`telegram-webhook`	POST	Webhook para mensajes entrantes de Telegram
`whatsapp-webhook`	POST	Webhook para mensajes entrantes de WhatsApp
`whatsapp-send`	POST	Envia un mensaje via WhatsApp Business API

Generacion IA

Endpoint	Metodo	Descripcion
`ai-generate-spec`	POST	Genera especificaciones, prompts o documentos con IA
`ai-generate-form`	POST	Genera formularios dinamicos a partir de descripcion
`ai-generate-workflow`	POST	Genera workflows BPM a partir de descripcion
`ai-generate-io-schema`	POST	Genera schemas de entrada/salida para agentes
`ai-data-classification`	POST	Clasifica datos segun categorias definidas
`ai-smart-attachments`	POST	Procesa adjuntos inteligentemente

Calendario y sincronizacion

Endpoint	Metodo	Descripcion
`calendar-sync`	POST	Sincroniza eventos de Google Calendar al sistema
`calendar-cron`	POST	Ejecuta sync batch para todas las conexiones activas
`gmail-sync`	POST	Sincroniza emails desde Gmail
`gmail-cron`	POST	Ejecuta sync batch de Gmail
`google-oauth`	POST	Flujo OAuth para conectar cuentas Google

Workflows y automatizaciones

Endpoint	Metodo	Descripcion
`workflow-engine`	POST	Ejecuta un workflow BPM paso a paso
`automation-engine`	POST	Evalua y ejecuta reglas de automatizacion
`event-dispatcher`	POST	Despacha eventos del sistema a agentes suscritos

Facturacion y pagos

Endpoint	Metodo	Descripcion
`create-checkout`	POST	Crea sesion de pago en Stripe
`stripe-webhook`	POST	Webhook para eventos de Stripe
`credit-engine`	POST	Gestiona el ledger de creditos IA
`billing-reminder-ai`	POST	Genera recordatorios de cobro con IA
`payment-receipt-ocr`	POST	Extrae datos de recibos de pago via OCR
`invoice-scheduler`	POST	Programa emision automatica de facturas

Documentos y extraccion

Endpoint	Metodo	Descripcion
`deed-extractor`	POST	Extrae datos estructurados de escrituras
`docx-tag-extractor`	POST	Extrae tags de plantillas DOCX
`document-requirement-checker`	POST	Verifica requisitos documentales de un expediente
`generate-minuta`	POST	Genera minutas a partir de plantillas

MCP (integraciones externas)

Endpoint	Metodo	Descripcion
`mcp-tool-call`	POST	Ejecuta una accion MCP en un proveedor externo

Fernando (asistente ejecutivo)

Endpoint	Metodo	Descripcion
`fernando-bridge`	POST	Puente de comunicacion con el VPS de Fernando
`fernando-memory`	POST	Operaciones de memoria (buscar, extraer, resumir)

Formato de peticion

Todas las peticiones usan JSON:


{
  "action": "nombre_de_la_accion",
  "data": {
    "campo1": "valor1",
    "campo2": "valor2"
  }
}

Formato de respuesta

Respuestas exitosas:


{
  "success": true,
  "data": { ... }
}

Respuestas de error:


{
  "success": false,
  "error": "Descripcion del error"
}

Modelo IA

BiVelio utiliza Google Gemini (Gemini 2.5 Flash) como modelo principal para operaciones de IA. Las peticiones a Gemini se realizan desde las Edge Functions, nunca desde el frontend.

Rate limiting

Las Edge Functions operan con los limites de Supabase:

Timeout por defecto: 60 segundos (ampliable por funcion)
Concurrencia gestionada automaticamente por el runtime

Errores comunes

Codigo	Significado
401	Token invalido o expirado
403	Sin permisos para esta operacion o agente inactivo
404	Recurso no encontrado
422	Datos de entrada invalidos
429	Limite de peticiones excedido
500	Error interno del servidor