Skip to Content
APIReferencia API

API Reference

BiVelio expone una API REST para integrar tu organizacion con sistemas externos, automatizar workflows, gestionar contactos, enviar comunicaciones y operar agentes de IA de forma programatica.

La API soporta autenticacion JWT y API Keys. Contacta con nuestro equipo para obtener acceso a la API.

Autenticacion

JWT Authentication (disponible ahora)

Todos los usuarios autenticados en BiVelio pueden hacer peticiones a la API usando su token JWT de sesion. Este token se obtiene al autenticarse via la API de BiVelio.

Obtener un token:

curl -X POST 'https://api.bivelio.com/v1/auth/token?grant_type=password' \
  -H 'apikey: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "tu@email.com",
    "password": "tu_password"
  }'

Respuesta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MR...",
  "user": {
    "id": "uuid-del-usuario",
    "email": "tu@email.com"
  }
}

Usar el token en peticiones:

curl -X POST 'https://api.bivelio.com/v1/workflows' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{ "action": "list" }'

El JWT incluye el org_id del workspace del usuario. Todos los datos devueltos se filtran automaticamente por organizacion.

Los tokens JWT expiran cada 60 minutos. Usa el refresh_token para obtener un nuevo access_token sin necesidad de reautenticarse.

API Key Authentication

Las API Keys permiten a desarrolladores externos integrar sus sistemas sin necesidad de una cuenta de usuario interactiva. Contacta con nuestro equipo para obtener acceso a la API.

Formato del header:

curl -X POST 'https://api.bivelio.com/v1/workflows' \
  -H 'X-API-Key: bv_live_sk_a1b2c3d4e5f6...' \
  -H 'Content-Type: application/json' \
  -d '{ "action": "list" }'

Tipos de clave:

PrefijoTipoEntorno
bv_live_sk_Secret KeyProduccion
bv_test_sk_Secret KeySandbox
bv_live_pk_Publishable KeyProduccion (solo lectura)

Scopes disponibles:

ScopePermisos
readLeer datos: listar workflows, contactos, mensajes, facturas
writeCrear y modificar datos: ejecutar workflows, enviar mensajes, crear contactos
adminGestion completa: configurar webhooks, gestionar agentes, acceso a billing

Las API Keys se gestionan desde app.bivelio.com/settings/api donde podras crear, rotar y revocar claves, asi como asignar scopes granulares.

Base URL

Produccion:

https://api.bivelio.com/v1/

Rate Limiting

Los limites de tasa se aplican a todas las peticiones de la API segun tu plan.

PlanLimiteBurst
Starter100 peticiones/minuto20 peticiones/segundo
Pro500 peticiones/minuto50 peticiones/segundo
EnterpriseIlimitadoPersonalizado

Headers de respuesta:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1712505600

Cuando se excede el limite, la API devuelve 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Has excedido el limite de 100 peticiones por minuto.",
    "retry_after": 23
  }
}

Endpoints

Todos los endpoints aceptan y devuelven JSON. El header Content-Type: application/json es obligatorio en todas las peticiones con body.

Workflows

POST /v1/workflows — Listar workflows

Devuelve los workflows configurados en tu organizacion.

Scope requerido: read

Request:

{
  "action": "list",
  "data": {
    "status": "active",
    "page": 1,
    "per_page": 20
  }
}

Response:

{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "wf_a1b2c3d4",
        "name": "Onboarding de cliente",
        "description": "Workflow automatico de bienvenida y configuracion",
        "status": "active",
        "trigger_type": "manual",
        "steps_count": 7,
        "created_at": "2026-03-15T10:30:00Z",
        "updated_at": "2026-04-01T14:22:00Z"
      },
      {
        "id": "wf_e5f6g7h8",
        "name": "Facturacion mensual",
        "description": "Genera y envia facturas el dia 1 de cada mes",
        "status": "active",
        "trigger_type": "cron",
        "steps_count": 4,
        "created_at": "2026-02-20T09:00:00Z",
        "updated_at": "2026-03-28T16:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 2,
      "total_pages": 1
    }
  }
}

POST /v1/workflows/execute — Ejecutar un workflow

Lanza la ejecucion de un workflow. Devuelve el ID de la instancia para seguimiento.

Scope requerido: write

Request:

{
  "action": "execute",
  "data": {
    "workflow_id": "wf_a1b2c3d4",
    "input": {
      "client_name": "Empresa ABC",
      "client_email": "contacto@empresaabc.com",
      "plan": "pro"
    },
    "async": true
  }
}

Response:

{
  "success": true,
  "data": {
    "instance_id": "wfi_x9y8z7w6",
    "workflow_id": "wf_a1b2c3d4",
    "status": "running",
    "started_at": "2026-04-07T12:00:00Z",
    "current_step": 1,
    "total_steps": 7
  }
}

Con "async": true, la ejecucion se lanza en background y puedes consultar el estado con /v1/workflows/instances. Con "async": false, la respuesta espera a que el workflow termine (timeout de 60 segundos).

POST /v1/workflows/instances — Listar instancias

Consulta el estado de las ejecuciones de workflows.

Scope requerido: read

Request:

{
  "action": "list_instances",
  "data": {
    "workflow_id": "wf_a1b2c3d4",
    "status": "running",
    "page": 1,
    "per_page": 10
  }
}

Response:

{
  "success": true,
  "data": {
    "instances": [
      {
        "instance_id": "wfi_x9y8z7w6",
        "workflow_id": "wf_a1b2c3d4",
        "workflow_name": "Onboarding de cliente",
        "status": "running",
        "current_step": 3,
        "total_steps": 7,
        "input": {
          "client_name": "Empresa ABC"
        },
        "started_at": "2026-04-07T12:00:00Z",
        "updated_at": "2026-04-07T12:02:30Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 1,
      "total_pages": 1
    }
  }
}

Agentes IA

POST /v1/agents/invoke — Invocar un agente

Ejecuta un agente de IA con input estructurado y recibe su respuesta.

Scope requerido: write

Request:

{
  "action": "invoke",
  "data": {
    "agent_id": "ag_classifier_01",
    "input": {
      "text": "El cliente quiere cambiar su plan de suscripcion a Enterprise",
      "context": {
        "client_id": "ct_abc123",
        "current_plan": "pro"
      }
    },
    "stream": false
  }
}

Response:

{
  "success": true,
  "data": {
    "execution_id": "age_r4s5t6u7",
    "agent_id": "ag_classifier_01",
    "agent_name": "Clasificador de intenciones",
    "output": {
      "intent": "plan_upgrade",
      "confidence": 0.94,
      "suggested_action": "route_to_sales",
      "extracted_entities": {
        "target_plan": "enterprise",
        "client_id": "ct_abc123"
      }
    },
    "tokens_used": 342,
    "credits_consumed": 1,
    "duration_ms": 1850,
    "completed_at": "2026-04-07T12:05:00Z"
  }
}

POST /v1/agents/list — Listar agentes disponibles

Devuelve los agentes configurados y activos en tu organizacion.

Scope requerido: read

Request:

{
  "action": "list",
  "data": {
    "status": "active",
    "category": "all"
  }
}

Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "ag_classifier_01",
        "name": "Clasificador de intenciones",
        "description": "Analiza texto entrante y clasifica la intencion del usuario",
        "category": "nlp",
        "status": "active",
        "model": "gemini-2.5-flash",
        "avg_latency_ms": 1200,
        "invocations_today": 47
      },
      {
        "id": "ag_email_draft",
        "name": "Redactor de emails",
        "description": "Genera borradores de respuesta a emails entrantes",
        "category": "communication",
        "status": "active",
        "model": "gemini-2.5-flash",
        "avg_latency_ms": 2400,
        "invocations_today": 12
      }
    ]
  }
}

Contactos / CRM

POST /v1/contacts — Listar o buscar contactos

Busca y filtra contactos de tu CRM.

Scope requerido: read

Request:

{
  "action": "list",
  "data": {
    "search": "Empresa ABC",
    "type": "company",
    "tags": ["cliente", "activo"],
    "page": 1,
    "per_page": 25
  }
}

Response:

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "ct_abc123",
        "type": "company",
        "name": "Empresa ABC S.L.",
        "email": "contacto@empresaabc.com",
        "phone": "+34 612 345 678",
        "tags": ["cliente", "activo", "pro"],
        "custom_fields": {
          "sector": "tecnologia",
          "nif": "B12345678"
        },
        "created_at": "2026-01-10T08:00:00Z",
        "updated_at": "2026-04-05T11:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 1,
      "total_pages": 1
    }
  }
}

POST /v1/contacts/create — Crear contacto

Crea un nuevo contacto en el CRM.

Scope requerido: write

Request:

{
  "action": "create",
  "data": {
    "type": "person",
    "name": "Maria Garcia",
    "email": "maria@ejemplo.com",
    "phone": "+34 600 111 222",
    "company_id": "ct_abc123",
    "tags": ["lead", "inbound"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise"
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "ct_def456",
    "type": "person",
    "name": "Maria Garcia",
    "email": "maria@ejemplo.com",
    "phone": "+34 600 111 222",
    "company_id": "ct_abc123",
    "tags": ["lead", "inbound"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise"
    },
    "created_at": "2026-04-07T12:10:00Z"
  }
}

POST /v1/contacts/update — Actualizar contacto

Actualiza un contacto existente. Solo se modifican los campos incluidos.

Scope requerido: write

Request:

{
  "action": "update",
  "data": {
    "id": "ct_def456",
    "tags": ["cliente", "activo"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise",
      "converted": true
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "ct_def456",
    "type": "person",
    "name": "Maria Garcia",
    "email": "maria@ejemplo.com",
    "tags": ["cliente", "activo"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise",
      "converted": true
    },
    "updated_at": "2026-04-07T12:15:00Z"
  }
}

Comunicaciones

POST /v1/messages/send — Enviar mensaje

Envia un mensaje a traves de WhatsApp, Telegram o Email.

Scope requerido: write

Request:

{
  "action": "send",
  "data": {
    "channel": "whatsapp",
    "to": "+34 612 345 678",
    "message": {
      "type": "text",
      "body": "Hola, tu pedido ha sido procesado correctamente. Numero de referencia: #ORD-2026-0451"
    },
    "metadata": {
      "workflow_id": "wf_a1b2c3d4",
      "contact_id": "ct_abc123"
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "message_id": "msg_v1w2x3y4",
    "channel": "whatsapp",
    "to": "+34 612 345 678",
    "status": "sent",
    "sent_at": "2026-04-07T12:20:00Z",
    "whatsapp_message_id": "wamid.HBgLMzQ2MTIzNDU2NzgVAgA..."
  }
}

Canales soportados:

CanalValor channelRequisitos
WhatsAppwhatsappNumero verificado en WhatsApp Business API
TelegramtelegramBot de Telegram conectado
EmailemailCuenta de Gmail o SMTP configurada

POST /v1/messages/list — Listar conversaciones

Obtiene el historial de conversaciones con un contacto.

Scope requerido: read

Request:

{
  "action": "list",
  "data": {
    "contact_id": "ct_abc123",
    "channel": "whatsapp",
    "page": 1,
    "per_page": 50
  }
}

Response:

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg_v1w2x3y4",
        "channel": "whatsapp",
        "direction": "outbound",
        "from": "+34 600 000 000",
        "to": "+34 612 345 678",
        "message": {
          "type": "text",
          "body": "Hola, tu pedido ha sido procesado correctamente."
        },
        "status": "delivered",
        "sent_at": "2026-04-07T12:20:00Z"
      },
      {
        "id": "msg_a2b3c4d5",
        "channel": "whatsapp",
        "direction": "inbound",
        "from": "+34 612 345 678",
        "to": "+34 600 000 000",
        "message": {
          "type": "text",
          "body": "Perfecto, gracias!"
        },
        "status": "received",
        "sent_at": "2026-04-07T12:22:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 2,
      "total_pages": 1
    }
  }
}

Documentos

POST /v1/documents/extract — Extraccion OCR

Extrae datos estructurados de un documento (factura, escritura, contrato, etc.).

Scope requerido: write

Request:

{
  "action": "extract",
  "data": {
    "document_url": "https://storage.example.com/docs/factura_2026_001.pdf",
    "document_type": "invoice",
    "language": "es",
    "fields": ["invoice_number", "date", "total", "line_items", "issuer", "recipient"]
  }
}

Response:

{
  "success": true,
  "data": {
    "extraction_id": "ext_m1n2o3p4",
    "document_type": "invoice",
    "confidence": 0.96,
    "extracted": {
      "invoice_number": "FAC-2026-001",
      "date": "2026-04-01",
      "total": 1210.00,
      "currency": "EUR",
      "issuer": {
        "name": "Proveedor XYZ S.L.",
        "nif": "B98765432"
      },
      "recipient": {
        "name": "Empresa ABC S.L.",
        "nif": "B12345678"
      },
      "line_items": [
        {
          "description": "Servicio de consultoria - Marzo 2026",
          "quantity": 1,
          "unit_price": 1000.00,
          "tax_rate": 21,
          "total": 1210.00
        }
      ]
    },
    "credits_consumed": 3,
    "processed_at": "2026-04-07T12:30:00Z"
  }
}

POST /v1/documents/classify — Clasificar documento

Clasifica automaticamente un documento segun su tipo y contenido.

Scope requerido: write

Request:

{
  "action": "classify",
  "data": {
    "document_url": "https://storage.example.com/docs/doc_sin_clasificar.pdf",
    "categories": ["invoice", "contract", "deed", "receipt", "report", "other"]
  }
}

Response:

{
  "success": true,
  "data": {
    "classification": "contract",
    "confidence": 0.91,
    "subcategory": "service_agreement",
    "summary": "Contrato de prestacion de servicios entre dos partes por 12 meses.",
    "detected_language": "es",
    "page_count": 8,
    "credits_consumed": 2,
    "processed_at": "2026-04-07T12:32:00Z"
  }
}

POST /v1/documents/upload — Subir documento

Sube un documento al almacenamiento de BiVelio y opcionalmente lo procesa.

Scope requerido: write

Request:

{
  "action": "upload",
  "data": {
    "filename": "contrato_cliente_abc.pdf",
    "content_base64": "JVBERi0xLjQKMSAwIG9iago8PAov...",
    "folder": "contracts",
    "tags": ["cliente_abc", "2026"],
    "auto_classify": true,
    "auto_extract": false
  }
}

Response:

{
  "success": true,
  "data": {
    "document_id": "doc_q5r6s7t8",
    "filename": "contrato_cliente_abc.pdf",
    "url": "https://storage.example.com/docs/contracts/contrato_cliente_abc.pdf",
    "size_bytes": 245780,
    "mime_type": "application/pdf",
    "folder": "contracts",
    "tags": ["cliente_abc", "2026"],
    "classification": {
      "type": "contract",
      "confidence": 0.89
    },
    "uploaded_at": "2026-04-07T12:35:00Z"
  }
}

Calendario

POST /v1/calendar/events — Listar eventos

Obtiene los eventos del calendario de la organizacion.

Scope requerido: read

Request:

{
  "action": "list",
  "data": {
    "from": "2026-04-07T00:00:00Z",
    "to": "2026-04-14T23:59:59Z",
    "calendar_id": "primary",
    "include_cancelled": false
  }
}

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "evt_u8v9w0x1",
        "title": "Reunion con cliente ABC",
        "description": "Revision trimestral del proyecto",
        "start": "2026-04-08T10:00:00Z",
        "end": "2026-04-08T11:00:00Z",
        "location": "Google Meet",
        "attendees": [
          { "email": "contacto@empresaabc.com", "status": "accepted" },
          { "email": "team@bivelio.com", "status": "accepted" }
        ],
        "source": "google_calendar",
        "google_event_id": "abc123def456"
      }
    ]
  }
}

POST /v1/calendar/create — Crear evento

Crea un nuevo evento en el calendario.

Scope requerido: write

Request:

{
  "action": "create",
  "data": {
    "title": "Demo de producto",
    "description": "Presentacion de nuevas funcionalidades a Empresa XYZ",
    "start": "2026-04-10T15:00:00Z",
    "end": "2026-04-10T16:00:00Z",
    "location": "https://meet.google.com/abc-defg-hij",
    "attendees": ["cliente@xyz.com", "team@bivelio.com"],
    "reminders": [
      { "method": "email", "minutes_before": 60 },
      { "method": "popup", "minutes_before": 15 }
    ],
    "sync_to_google": true
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "evt_y2z3a4b5",
    "title": "Demo de producto",
    "start": "2026-04-10T15:00:00Z",
    "end": "2026-04-10T16:00:00Z",
    "attendees_notified": true,
    "google_event_id": "xyz789ghi012",
    "created_at": "2026-04-07T12:40:00Z"
  }
}

Facturacion

POST /v1/invoices/list — Listar facturas

Obtiene las facturas emitidas o recibidas por la organizacion.

Scope requerido: read

Request:

{
  "action": "list",
  "data": {
    "type": "issued",
    "status": "pending",
    "from_date": "2026-01-01",
    "to_date": "2026-04-07",
    "page": 1,
    "per_page": 20
  }
}

Response:

{
  "success": true,
  "data": {
    "invoices": [
      {
        "id": "inv_c6d7e8f9",
        "number": "FAC-2026-042",
        "type": "issued",
        "status": "pending",
        "client": {
          "id": "ct_abc123",
          "name": "Empresa ABC S.L."
        },
        "subtotal": 5000.00,
        "tax": 1050.00,
        "total": 6050.00,
        "currency": "EUR",
        "issue_date": "2026-04-01",
        "due_date": "2026-04-30",
        "line_items": [
          {
            "description": "Licencia BiVelio Pro - Abril 2026",
            "quantity": 10,
            "unit_price": 500.00,
            "tax_rate": 21,
            "total": 6050.00
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}

POST /v1/invoices/create — Crear factura

Crea una nueva factura en el sistema.

Scope requerido: write

Request:

{
  "action": "create",
  "data": {
    "client_id": "ct_abc123",
    "issue_date": "2026-04-07",
    "due_date": "2026-05-07",
    "currency": "EUR",
    "line_items": [
      {
        "description": "Consultoria tecnica - 20 horas",
        "quantity": 20,
        "unit_price": 150.00,
        "tax_rate": 21
      },
      {
        "description": "Licencia software mensual",
        "quantity": 1,
        "unit_price": 500.00,
        "tax_rate": 21
      }
    ],
    "notes": "Pago a 30 dias. Transferencia bancaria.",
    "auto_send": false
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "inv_g0h1i2j3",
    "number": "FAC-2026-043",
    "status": "draft",
    "client": {
      "id": "ct_abc123",
      "name": "Empresa ABC S.L."
    },
    "subtotal": 3500.00,
    "tax": 735.00,
    "total": 4235.00,
    "currency": "EUR",
    "issue_date": "2026-04-07",
    "due_date": "2026-05-07",
    "pdf_url": "https://storage.example.com/invoices/FAC-2026-043.pdf",
    "created_at": "2026-04-07T12:45:00Z"
  }
}

MCP (Integraciones Externas)

POST /v1/mcp/execute — Ejecutar herramienta MCP

Ejecuta una accion MCP (Model Context Protocol) en un proveedor externo conectado.

Scope requerido: write

Request:

{
  "action": "execute",
  "data": {
    "provider": "google_sheets",
    "tool": "read_range",
    "parameters": {
      "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
      "range": "Sheet1!A1:D50"
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "execution_id": "mcp_k4l5m6n7",
    "provider": "google_sheets",
    "tool": "read_range",
    "result": {
      "values": [
        ["Nombre", "Email", "Plan", "Estado"],
        ["Empresa ABC", "abc@ejemplo.com", "pro", "activo"],
        ["Empresa XYZ", "xyz@ejemplo.com", "starter", "trial"]
      ],
      "rows_count": 3,
      "columns_count": 4
    },
    "duration_ms": 450,
    "completed_at": "2026-04-07T12:50:00Z"
  }
}

Los proveedores MCP disponibles dependen de las integraciones configuradas en tu organizacion. Visita app.bivelio.com/settings/integrations para conectar nuevos servicios.

Webhooks (salientes)

Los webhooks salientes permiten recibir notificaciones en tiempo real cuando ocurren eventos en BiVelio.

POST /v1/webhooks/create — Registrar webhook

Registra una URL para recibir notificaciones de eventos.

Scope requerido: admin

Request:

{
  "action": "create",
  "data": {
    "url": "https://tu-servidor.com/api/bivelio-webhook",
    "events": ["workflow.completed", "message.received", "invoice.paid"],
    "secret": "whsec_tu_secreto_de_verificacion",
    "description": "Webhook principal de integracion"
  }
}

Response:

{
  "success": true,
  "data": {
    "webhook_id": "wh_o8p9q0r1",
    "url": "https://tu-servidor.com/api/bivelio-webhook",
    "events": ["workflow.completed", "message.received", "invoice.paid"],
    "status": "active",
    "signing_secret": "whsec_s2t3u4v5w6x7y8z9...",
    "created_at": "2026-04-07T13:00:00Z"
  }
}

POST /v1/webhooks/list — Listar webhooks

Devuelve los webhooks registrados en tu organizacion.

Scope requerido: admin

Request:

{
  "action": "list",
  "data": {}
}

Response:

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "webhook_id": "wh_o8p9q0r1",
        "url": "https://tu-servidor.com/api/bivelio-webhook",
        "events": ["workflow.completed", "message.received", "invoice.paid"],
        "status": "active",
        "last_triggered_at": "2026-04-07T12:55:00Z",
        "success_rate": 0.98,
        "created_at": "2026-04-07T13:00:00Z"
      }
    ]
  }
}

Eventos disponibles:

EventoDescripcion
workflow.completedUn workflow ha finalizado su ejecucion
workflow.failedUn workflow ha fallado durante la ejecucion
message.receivedSe ha recibido un mensaje (WhatsApp, Telegram, Email)
message.sentSe ha enviado un mensaje exitosamente
contact.createdSe ha creado un nuevo contacto
contact.updatedSe ha actualizado un contacto existente
invoice.createdSe ha creado una nueva factura
invoice.paidUna factura ha sido marcada como pagada
case.createdSe ha creado un nuevo caso/expediente
case.updatedSe ha actualizado un caso/expediente
agent.executedUn agente IA ha completado una ejecucion
document.processedUn documento ha sido procesado (OCR/clasificacion)

Formato del payload del webhook:

{
  "event": "workflow.completed",
  "timestamp": "2026-04-07T13:05:00Z",
  "webhook_id": "wh_o8p9q0r1",
  "data": {
    "instance_id": "wfi_x9y8z7w6",
    "workflow_id": "wf_a1b2c3d4",
    "workflow_name": "Onboarding de cliente",
    "status": "completed",
    "duration_ms": 45000,
    "output": {
      "client_configured": true,
      "welcome_email_sent": true
    }
  }
}

Politica de reintentos:

IntentoDelay
1Inmediato
230 segundos
32 minutos
410 minutos
51 hora

Despues de 5 intentos fallidos, el webhook se desactiva automaticamente.

Verificacion de firma:

Cada peticion de webhook incluye un header X-BiVelio-Signature con un HMAC-SHA256 del body usando tu signing secret:

const crypto = require('crypto');
 
function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

SDKs

Los SDKs oficiales estan disponibles para JavaScript/TypeScript y Python. Tambien puedes usar cualquier cliente HTTP con los endpoints documentados.

JavaScript / TypeScript

npm install @bivelio/sdk
import { BiVelio } from '@bivelio/sdk';
 
const bivelio = new BiVelio({
  apiKey: 'bv_live_sk_a1b2c3d4e5f6...',
});
 
// Listar workflows
const workflows = await bivelio.workflows.list({ status: 'active' });
 
// Ejecutar un workflow
const instance = await bivelio.workflows.execute('wf_a1b2c3d4', {
  client_name: 'Empresa ABC',
  plan: 'pro',
});
 
// Enviar mensaje por WhatsApp
const message = await bivelio.messages.send({
  channel: 'whatsapp',
  to: '+34 612 345 678',
  body: 'Tu pedido ha sido procesado.',
});
 
// Invocar agente IA
const result = await bivelio.agents.invoke('ag_classifier_01', {
  text: 'El cliente quiere cambiar su plan',
});

Python

pip install bivelio
from bivelio import BiVelio
 
client = BiVelio(api_key="bv_live_sk_a1b2c3d4e5f6...")
 
# Listar contactos
contacts = client.contacts.list(search="Empresa ABC")
 
# Crear factura
invoice = client.invoices.create(
    client_id="ct_abc123",
    line_items=[
        {
            "description": "Consultoria tecnica",
            "quantity": 20,
            "unit_price": 150.00,
            "tax_rate": 21,
        }
    ],
)
 
# Extraer datos de documento
extraction = client.documents.extract(
    document_url="https://storage.example.com/docs/factura.pdf",
    document_type="invoice",
)

Manejo de errores

Todas las respuestas de error siguen un formato estandar:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo 'email' es obligatorio.",
    "details": {
      "field": "email",
      "constraint": "required"
    }
  }
}

Codigos de error HTTP

CodigoNombreDescripcion
400Bad RequestLa peticion tiene un formato incorrecto o faltan campos obligatorios
401UnauthorizedToken invalido, expirado o ausente
403ForbiddenEl token no tiene permisos para esta operacion o el recurso pertenece a otra organizacion
404Not FoundEl recurso solicitado no existe
409ConflictConflicto de estado (ej. intentar ejecutar un workflow ya en ejecucion)
422Unprocessable EntityLos datos son sintacticamente correctos pero semanticamente invalidos
429Too Many RequestsSe ha excedido el limite de peticiones. Espera el tiempo indicado en retry_after
500Internal Server ErrorError interno del servidor. Reintenta con backoff exponencial
503Service UnavailableServicio temporalmente no disponible. Reintenta en unos minutos

Codigos de error internos

CodigoSignificado
AUTH_INVALID_TOKENEl token JWT o API Key no es valido
AUTH_EXPIRED_TOKENEl token ha expirado
AUTH_INSUFFICIENT_SCOPELa API Key no tiene el scope necesario
VALIDATION_ERRORError de validacion en los datos de entrada
RESOURCE_NOT_FOUNDEl recurso solicitado no existe
RATE_LIMIT_EXCEEDEDLimite de peticiones excedido
CREDITS_EXHAUSTEDSin creditos de IA disponibles
WORKFLOW_ALREADY_RUNNINGEl workflow ya tiene una instancia en ejecucion
AGENT_INACTIVEEl agente no esta activo
INTEGRATION_ERRORError en la integracion externa (MCP, WhatsApp, etc.)
INTERNAL_ERRORError interno inesperado

Modo Sandbox

El entorno sandbox te permite probar la API sin afectar datos reales.

El modo sandbox permite probar la API sin afectar datos reales:

  • API Key de test: bv_test_sk_xxxxx (generada desde el dashboard)
  • Base URL sandbox: https://sandbox.api.bivelio.com/v1/
  • Los datos creados en sandbox se eliminan automaticamente cada 24 horas
  • Las integraciones externas (WhatsApp, email) se simulan sin enviar mensajes reales
  • Los creditos de IA consumidos en sandbox no se descuentan del balance real
# Ejemplo de peticion en sandbox
curl -X POST 'https://sandbox.api.bivelio.com/v1/messages/send' \
  -H 'X-API-Key: bv_test_sk_a1b2c3d4e5f6...' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "send",
    "data": {
      "channel": "whatsapp",
      "to": "+34 600 000 000",
      "message": {
        "type": "text",
        "body": "Mensaje de prueba desde sandbox"
      }
    }
  }'

Modelo IA

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

Cada operacion de IA consume creditos segun la complejidad:

OperacionCreditos
Invocar agente (texto corto)1
Invocar agente (texto largo / con contexto)2-5
Extraccion OCR3
Clasificacion de documento2
Generacion de workflow5
Generacion de formulario3

Changelog

v1.0.0

Version actual de la API publica. Los endpoints JWT y API Key estan operativos.

Funcionalidades incluidas en v1.0.0:

  • Sistema de API Keys con scopes granulares
  • Rate limiting por plan
  • Webhooks salientes con verificacion de firma
  • SDKs oficiales (JavaScript, Python)
  • Entorno sandbox
  • Dashboard de gestion de claves en app.bivelio.com/settings/api

Necesitas ayuda? Contacta con nuestro equipo en support@bivelio.com o a traves del chat de la aplicacion en app.bivelio.com .

SeguridadPrograma BVOP