API

BiVelio exposa la seva funcionalitat a través d’Edge Functions desplegades a Supabase. Totes les peticions requereixen autenticació i operen dins del context del workspace de l’usuari.

Autenticació

Totes les peticions a l’API requereixen un token a la capçalera Authorization:


Authorization: Bearer <token>

Tipus de token

Tipus	Ús	Obtenció
JWT d’usuari	Peticions des del frontend o integracions externes	Login via Supabase Auth
Service Role Key	Crides internes entre Edge Functions	Variable d’entorn del projecte

El JWT d’usuari inclou l’org_id del workspace, que s’utilitza per filtrar totes les dades retornades per l’API.

La Service Role Key té accés complet a la base de dades. Mai no s’ha d’exposar al frontend ni compartir amb tercers.

Base URL


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

Endpoints principals

Agents IA

Endpoint	Mètode	Descripció
`agent-structured`	POST	Executa un agent invocable amb input estructurat
`agent-runtime`	POST	Runtime d’execució d’agents autònoms
`agent-knowledge-ingest`	POST	Ingesta de documents a la base de coneixement
`agent-test-generator`	POST	Genera tests per validar un agent
`agent-test-runner`	POST	Executa tests de validació d’agents

Comunicacions

Endpoint	Mètode	Descripció
`email-classifier`	POST	Classifica un email per categoria i urgència
`email-draft-generator`	POST	Genera esborrany de resposta a un email
`conversation-router`	POST	Enruta converses a l’agent o operador adequat
`telegram-webhook`	POST	Webhook per a missatges entrants de Telegram
`whatsapp-webhook`	POST	Webhook per a missatges entrants de WhatsApp
`whatsapp-send`	POST	Envia un missatge via WhatsApp Business API

Generació IA

Endpoint	Mètode	Descripció
`ai-generate-spec`	POST	Genera especificacions, prompts o documents amb IA
`ai-generate-form`	POST	Genera formularis dinàmics a partir de descripció
`ai-generate-workflow`	POST	Genera workflows BPM a partir de descripció
`ai-generate-io-schema`	POST	Genera schemas d’entrada/sortida per a agents
`ai-data-classification`	POST	Classifica dades segons categories definides
`ai-smart-attachments`	POST	Processa adjunts intel·ligentment

Calendari i sincronització

Endpoint	Mètode	Descripció
`calendar-sync`	POST	Sincronitza esdeveniments de Google Calendar al sistema
`calendar-cron`	POST	Executa sync batch per a totes les connexions actives
`gmail-sync`	POST	Sincronitza emails des de Gmail
`gmail-cron`	POST	Executa sync batch de Gmail
`google-oauth`	POST	Flux OAuth per connectar comptes Google

Workflows i automatitzacions

Endpoint	Mètode	Descripció
`workflow-engine`	POST	Executa un workflow BPM pas a pas
`automation-engine`	POST	Avalua i executa regles d’automatització
`event-dispatcher`	POST	Despatxa esdeveniments del sistema a agents subscrits

Facturació i pagaments

Endpoint	Mètode	Descripció
`create-checkout`	POST	Crea sessió de pagament a Stripe
`stripe-webhook`	POST	Webhook per a esdeveniments de Stripe
`credit-engine`	POST	Gestiona el ledger de crèdits IA
`billing-reminder-ai`	POST	Genera recordatoris de cobrament amb IA
`payment-receipt-ocr`	POST	Extreu dades de rebuts de pagament via OCR
`invoice-scheduler`	POST	Programa emissió automàtica de factures

Documents i extracció

Endpoint	Mètode	Descripció
`deed-extractor`	POST	Extreu dades estructurades d’escriptures
`docx-tag-extractor`	POST	Extreu tags de plantilles DOCX
`document-requirement-checker`	POST	Verifica requisits documentals d’un expedient
`generate-minuta`	POST	Genera minuts a partir de plantilles

MCP (integracions externes)

Endpoint	Mètode	Descripció
`mcp-tool-call`	POST	Executa una acció MCP en un proveïdor extern

Fernando (assistent executiu)

Endpoint	Mètode	Descripció
`fernando-bridge`	POST	Pont de comunicació amb el VPS de Fernando
`fernando-memory`	POST	Operacions de memòria (cercar, extreure, resumir)

Format de petició

Totes les peticions usen JSON:


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

Format de resposta

Respostes correctes:


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

Respostes d’error:


{
  "success": false,
  "error": "Descripció de l'error"
}

Model IA

BiVelio utilitza Google Gemini (Gemini 2.5 Flash) com a model principal per a operacions de IA. Les peticions a Gemini es realitzen des de les Edge Functions, mai des del frontend.

Rate limiting

Les Edge Functions operen amb els límits de Supabase:

Timeout per defecte: 60 segons (ampliable per funció)
Concurrència gestionada automàticament pel runtime

Errors comuns

Codi	Significat
401	Token invàlid o expirat
403	Sense permisos per a aquesta operació o agent inactiu
404	Recurs no trobat
422	Dades d’entrada invàlides
429	Límit de peticions excedit
500	Error intern del servidor