API Reference

BiVelio exposa una API REST per integrar la teva organitzacio amb sistemes externs, automatitzar workflows, gestionar contactes, enviar comunicacions i operar agents d’IA de forma programatica.

L’API suporta autenticacio JWT i API Keys. Contacta amb el nostre equip per obtenir acces a l’API.

Autenticacio

JWT Authentication (disponible ara)

Tots els usuaris autenticats a BiVelio poden fer peticions a l’API usant el seu token JWT de sessio. Aquest token s’obte en autenticar-se via l’API de BiVelio.

Obtenir 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": "el_teu@email.com",
    "password": "la_teva_contrasenya"
  }'

Resposta:


{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MR...",
  "user": {
    "id": "uuid-de-lusuari",
    "email": "el_teu@email.com"
  }
}

Usar el token en peticions:


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

El JWT inclou l’org_id del workspace de l’usuari. Totes les dades retornades es filtren automaticament per organitzacio.

Els tokens JWT expiren cada 60 minuts. Usa el refresh_token per obtenir un nou access_token sense necessitat de reautenticar-te.

API Key Authentication

Les API Keys permeten a desenvolupadors externs integrar els seus sistemes sense necessitat d’un compte d’usuari interactiu. Contacta amb el nostre equip per obtenir acces a l’API.

Format 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" }'

Tipus de clau:

Prefix	Tipus	Entorn
`bv_live_sk_`	Secret Key	Produccio
`bv_test_sk_`	Secret Key	Sandbox
`bv_live_pk_`	Publishable Key	Produccio (nomes lectura)

Scopes disponibles:

Scope	Permisos
`read`	Llegir dades: llistar workflows, contactes, missatges, factures
`write`	Crear i modificar dades: executar workflows, enviar missatges, crear contactes
`admin`	Gestio completa: configurar webhooks, gestionar agents, acces a billing

Les API Keys es gestionen des de app.bivelio.com/settings/api on podras crear, rotar i revocar claus, aixi com assignar scopes granulars.

Base URL

Produccio:


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

Rate Limiting

Els limits de taxa s’apliquen a totes les peticions de l’API segons el teu pla.

Pla	Limit	Burst
Starter	100 peticions/minut	20 peticions/segon
Pro	500 peticions/minut	50 peticions/segon
Enterprise	Il-limitat	Personalitzat

Headers de resposta:


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

Quan s’excedeix el limit, l’API retorna 429 Too Many Requests:


{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Has excedit el limit de 100 peticions per minut.",
    "retry_after": 23
  }
}

Endpoints

Tots els endpoints accepten i retornen JSON. El header Content-Type: application/json es obligatori en totes les peticions amb body.

Workflows

POST /v1/workflows — Llistar workflows

Retorna els workflows configurats a la teva organitzacio.

Scope requerit: read

Request:


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

Response:


{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "wf_a1b2c3d4",
        "name": "Onboarding de client",
        "description": "Workflow automatic de benvinguda i configuracio",
        "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": "Facturacio mensual",
        "description": "Genera i envia factures 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 — Executar un workflow

Llanca l’execucio d’un workflow. Retorna l’ID de la instancia per al seguiment.

Scope requerit: write

Request:


{
  "action": "execute",
  "data": {
    "workflow_id": "wf_a1b2c3d4",
    "input": {
      "client_name": "Empresa ABC",
      "client_email": "contacte@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
  }
}

Amb "async": true, l’execucio es llanca en background i pots consultar l’estat amb /v1/workflows/instances. Amb "async": false, la resposta espera a que el workflow acabi (timeout de 60 segons).

POST /v1/workflows/instances — Llistar instancies

Consulta l’estat de les execucions de workflows.

Scope requerit: 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 client",
        "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
    }
  }
}

Agents IA

POST /v1/agents/invoke — Invocar un agent

Executa un agent d’IA amb input estructurat i rep la seva resposta.

Scope requerit: write

Request:


{
  "action": "invoke",
  "data": {
    "agent_id": "ag_classifier_01",
    "input": {
      "text": "El client vol canviar el seu pla de subscripcio 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": "Classificador d'intencions",
    "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 — Llistar agents disponibles

Retorna els agents configurats i actius a la teva organitzacio.

Scope requerit: read

Request:


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

Response:


{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "ag_classifier_01",
        "name": "Classificador d'intencions",
        "description": "Analitza text entrant i classifica la intencio de l'usuari",
        "category": "nlp",
        "status": "active",
        "model": "gemini-2.5-flash",
        "avg_latency_ms": 1200,
        "invocations_today": 47
      },
      {
        "id": "ag_email_draft",
        "name": "Redactor d'emails",
        "description": "Genera esborranys de resposta a emails entrants",
        "category": "communication",
        "status": "active",
        "model": "gemini-2.5-flash",
        "avg_latency_ms": 2400,
        "invocations_today": 12
      }
    ]
  }
}

Contactes / CRM

POST /v1/contacts — Llistar o cercar contactes

Cerca i filtra contactes del teu CRM.

Scope requerit: read

Request:


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

Response:


{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "ct_abc123",
        "type": "company",
        "name": "Empresa ABC S.L.",
        "email": "contacte@empresaabc.com",
        "phone": "+34 612 345 678",
        "tags": ["client", "actiu", "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 contacte

Crea un nou contacte al CRM.

Scope requerit: write

Request:


{
  "action": "create",
  "data": {
    "type": "person",
    "name": "Maria Garcia",
    "email": "maria@exemple.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@exemple.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 — Actualitzar contacte

Actualitza un contacte existent. Nomes es modifiquen els camps inclosos.

Scope requerit: write

Request:


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

Response:


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

Comunicacions

POST /v1/messages/send — Enviar missatge

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

Scope requerit: write

Request:


{
  "action": "send",
  "data": {
    "channel": "whatsapp",
    "to": "+34 612 345 678",
    "message": {
      "type": "text",
      "body": "Hola, la teva comanda ha estat processada correctament. 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..."
  }
}

Canals suportats:

Canal	Valor `channel`	Requisits
WhatsApp	`whatsapp`	Numero verificat a WhatsApp Business API
Telegram	`telegram`	Bot de Telegram connectat
Email	`email`	Compte de Gmail o SMTP configurat

POST /v1/messages/list — Llistar converses

Obte l’historial de converses amb un contacte.

Scope requerit: 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, la teva comanda ha estat processada correctament."
        },
        "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": "Perfecte, gracies!"
        },
        "status": "received",
        "sent_at": "2026-04-07T12:22:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 2,
      "total_pages": 1
    }
  }
}

Documents

POST /v1/documents/extract — Extraccio OCR

Extreu dades estructurades d’un document (factura, escriptura, contracte, etc.).

Scope requerit: write

Request:


{
  "action": "extract",
  "data": {
    "document_url": "https://storage.example.com/docs/factura_2026_001.pdf",
    "document_type": "invoice",
    "language": "ca",
    "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": "Proveidor XYZ S.L.",
        "nif": "B98765432"
      },
      "recipient": {
        "name": "Empresa ABC S.L.",
        "nif": "B12345678"
      },
      "line_items": [
        {
          "description": "Servei de consultoria - Marc 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 — Classificar document

Classifica automaticament un document segons el seu tipus i contingut.

Scope requerit: write

Request:


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

Response:


{
  "success": true,
  "data": {
    "classification": "contract",
    "confidence": 0.91,
    "subcategory": "service_agreement",
    "summary": "Contracte de prestacio de serveis entre dues parts per 12 mesos.",
    "detected_language": "ca",
    "page_count": 8,
    "credits_consumed": 2,
    "processed_at": "2026-04-07T12:32:00Z"
  }
}

POST /v1/documents/upload — Pujar document

Puja un document a l’emmagatzematge de BiVelio i opcionalment el processa.

Scope requerit: write

Request:


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

Response:


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

Calendari

POST /v1/calendar/events — Llistar esdeveniments

Obte els esdeveniments del calendari de l’organitzacio.

Scope requerit: 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": "Reunio amb client ABC",
        "description": "Revisio trimestral del projecte",
        "start": "2026-04-08T10:00:00Z",
        "end": "2026-04-08T11:00:00Z",
        "location": "Google Meet",
        "attendees": [
          { "email": "contacte@empresaabc.com", "status": "accepted" },
          { "email": "team@bivelio.com", "status": "accepted" }
        ],
        "source": "google_calendar",
        "google_event_id": "abc123def456"
      }
    ]
  }
}

POST /v1/calendar/create — Crear esdeveniment

Crea un nou esdeveniment al calendari.

Scope requerit: write

Request:


{
  "action": "create",
  "data": {
    "title": "Demo de producte",
    "description": "Presentacio de noves funcionalitats a Empresa XYZ",
    "start": "2026-04-10T15:00:00Z",
    "end": "2026-04-10T16:00:00Z",
    "location": "https://meet.google.com/abc-defg-hij",
    "attendees": ["client@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 producte",
    "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"
  }
}

Facturacio

POST /v1/invoices/list — Llistar factures

Obte les factures emeses o rebudes per l’organitzacio.

Scope requerit: 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": "Llicencia 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 nova factura al sistema.

Scope requerit: 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 hores",
        "quantity": 20,
        "unit_price": 150.00,
        "tax_rate": 21
      },
      {
        "description": "Llicencia software mensual",
        "quantity": 1,
        "unit_price": 500.00,
        "tax_rate": 21
      }
    ],
    "notes": "Pagament a 30 dies. 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 (Integracions Externes)

POST /v1/mcp/execute — Executar eina MCP

Executa una accio MCP (Model Context Protocol) en un proveidor extern connectat.

Scope requerit: 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": [
        ["Nom", "Email", "Pla", "Estat"],
        ["Empresa ABC", "abc@exemple.com", "pro", "actiu"],
        ["Empresa XYZ", "xyz@exemple.com", "starter", "trial"]
      ],
      "rows_count": 3,
      "columns_count": 4
    },
    "duration_ms": 450,
    "completed_at": "2026-04-07T12:50:00Z"
  }
}

Els proveidors MCP disponibles depenen de les integracions configurades a la teva organitzacio. Visita app.bivelio.com/settings/integrations per connectar nous serveis.

Webhooks (sortints)

Els webhooks sortints permeten rebre notificacions en temps real quan es produeixen esdeveniments a BiVelio.

POST /v1/webhooks/create — Registrar webhook

Registra una URL per rebre notificacions d’esdeveniments.

Scope requerit: admin

Request:


{
  "action": "create",
  "data": {
    "url": "https://el-teu-servidor.com/api/bivelio-webhook",
    "events": ["workflow.completed", "message.received", "invoice.paid"],
    "secret": "whsec_el_teu_secret_de_verificacio",
    "description": "Webhook principal d'integracio"
  }
}

Response:


{
  "success": true,
  "data": {
    "webhook_id": "wh_o8p9q0r1",
    "url": "https://el-teu-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 — Llistar webhooks

Retorna els webhooks registrats a la teva organitzacio.

Scope requerit: admin

Request:


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

Response:


{
  "success": true,
  "data": {
    "webhooks": [
      {
        "webhook_id": "wh_o8p9q0r1",
        "url": "https://el-teu-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"
      }
    ]
  }
}

Esdeveniments disponibles:

Esdeveniment	Descripcio
`workflow.completed`	Un workflow ha finalitzat la seva execucio
`workflow.failed`	Un workflow ha fallat durant l’execucio
`message.received`	S’ha rebut un missatge (WhatsApp, Telegram, Email)
`message.sent`	S’ha enviat un missatge exitosament
`contact.created`	S’ha creat un nou contacte
`contact.updated`	S’ha actualitzat un contacte existent
`invoice.created`	S’ha creat una nova factura
`invoice.paid`	Una factura ha estat marcada com a pagada
`case.created`	S’ha creat un nou cas/expedient
`case.updated`	S’ha actualitzat un cas/expedient
`agent.executed`	Un agent IA ha completat una execucio
`document.processed`	Un document ha estat processat (OCR/classificacio)

Format 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 client",
    "status": "completed",
    "duration_ms": 45000,
    "output": {
      "client_configured": true,
      "welcome_email_sent": true
    }
  }
}

Politica de reintents:

Intent	Delay
1	Immediat
2	30 segons
3	2 minuts
4	10 minuts
5	1 hora

Despres de 5 intents fallits, el webhook es desactiva automaticament.

Verificacio de signatura:

Cada peticio de webhook inclou un header X-BiVelio-Signature amb un HMAC-SHA256 del body usant el teu 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

Els SDKs oficials estan disponibles per a JavaScript/TypeScript i Python. Tambe pots usar qualsevol client HTTP amb els endpoints documentats.

JavaScript / TypeScript


npm install @bivelio/sdk


import { BiVelio } from '@bivelio/sdk';
 
const bivelio = new BiVelio({
  apiKey: 'bv_live_sk_a1b2c3d4e5f6...',
});
 
// Llistar workflows
const workflows = await bivelio.workflows.list({ status: 'active' });
 
// Executar un workflow
const instance = await bivelio.workflows.execute('wf_a1b2c3d4', {
  client_name: 'Empresa ABC',
  plan: 'pro',
});
 
// Enviar missatge per WhatsApp
const message = await bivelio.messages.send({
  channel: 'whatsapp',
  to: '+34 612 345 678',
  body: 'La teva comanda ha estat processada.',
});
 
// Invocar agent IA
const result = await bivelio.agents.invoke('ag_classifier_01', {
  text: 'El client vol canviar el seu pla',
});

Python


pip install bivelio


from bivelio import BiVelio
 
client = BiVelio(api_key="bv_live_sk_a1b2c3d4e5f6...")
 
# Llistar contactes
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,
        }
    ],
)
 
# Extreure dades de document
extraction = client.documents.extract(
    document_url="https://storage.example.com/docs/factura.pdf",
    document_type="invoice",
)

Gestio d’errors

Totes les respostes d’error segueixen un format estandard:


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

Codis d’error HTTP

Codi	Nom	Descripcio
`400`	Bad Request	La peticio te un format incorrecte o falten camps obligatoris
`401`	Unauthorized	Token invalid, expirat o absent
`403`	Forbidden	El token no te permisos per a aquesta operacio o el recurs pertany a una altra organitzacio
`404`	Not Found	El recurs sol-licitat no existeix
`409`	Conflict	Conflicte d’estat (ex. intentar executar un workflow ja en execucio)
`422`	Unprocessable Entity	Les dades son sintacticament correctes pero semanticament invalides
`429`	Too Many Requests	S’ha excedit el limit de peticions. Espera el temps indicat a `retry_after`
`500`	Internal Server Error	Error intern del servidor. Reintenta amb backoff exponencial
`503`	Service Unavailable	Servei temporalment no disponible. Reintenta en uns minuts

Codis d’error interns

Codi	Significat
`AUTH_INVALID_TOKEN`	El token JWT o API Key no es valid
`AUTH_EXPIRED_TOKEN`	El token ha expirat
`AUTH_INSUFFICIENT_SCOPE`	L’API Key no te l’scope necessari
`VALIDATION_ERROR`	Error de validacio en les dades d’entrada
`RESOURCE_NOT_FOUND`	El recurs sol-licitat no existeix
`RATE_LIMIT_EXCEEDED`	Limit de peticions excedit
`CREDITS_EXHAUSTED`	Sense credits d’IA disponibles
`WORKFLOW_ALREADY_RUNNING`	El workflow ja te una instancia en execucio
`AGENT_INACTIVE`	L’agent no esta actiu
`INTEGRATION_ERROR`	Error en la integracio externa (MCP, WhatsApp, etc.)
`INTERNAL_ERROR`	Error intern inesperat

Mode Sandbox

L’entorn sandbox et permet provar l’API sense afectar dades reals.

El mode sandbox permet provar l’API sense afectar dades reals:

API Key de test: bv_test_sk_xxxxx (generada des del dashboard)
Base URL sandbox: https://sandbox.api.bivelio.com/v1/
Les dades creades en sandbox s’eliminen automaticament cada 24 hores
Les integracions externes (WhatsApp, email) es simulen sense enviar missatges reals
Els credits d’IA consumits en sandbox no es descompten del balanc real


# Exemple de peticio 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": "Missatge de prova des de sandbox"
      }
    }
  }'

Model IA

BiVelio utilitza Google Gemini (Gemini 2.5 Flash) com a model principal per a totes les operacions d’IA. Les peticions a Gemini s’executen des de les Edge Functions del servidor, mai des del frontend.

Cada operacio d’IA consumeix credits segons la complexitat:

Operacio	Credits
Invocar agent (text curt)	1
Invocar agent (text llarg / amb context)	2-5
Extraccio OCR	3
Classificacio de document	2
Generacio de workflow	5
Generacio de formulari	3

Changelog

v1.0.0

Versio actual de l’API publica. Els endpoints JWT i API Key son operatius.

Funcionalitats incloses a v1.0.0:

Sistema d’API Keys amb scopes granulars
Rate limiting per pla
Webhooks sortints amb verificacio de signatura
SDKs oficials (JavaScript, Python)
Entorn sandbox
Dashboard de gestio de claus a app.bivelio.com/settings/api

Necessites ajuda? Contacta amb el nostre equip a support@bivelio.com o a traves del xat de l’aplicacio a app.bivelio.com .