Sviluppatori

Costruisci su VEPRA

Ogni azione che una persona compie nell’app è un comando con nome, schema e permesso. Gli stessi comandi si richiamano con una chiave API, da webhook e dall’agente. Non esiste un secondo API.

OpenAPI (/v1/openapi.json) · Accedi

Chiavi API

Una chiave è un attore «servizio» dell’attività con i permessi che scegli quando la crei (solo tra i tuoi, mai members.manage). Creala in Attività → Agente e chiavi API; il token appare una volta sola e si conserva solo il suo hash.

Una chiave raggiunge solo la propria attività (qualsiasi altra rotta risponde 403), scade quando lo decidi e si revoca con un clic. Non ha MFA: i comandi che richiedono un codice recente vengono sempre rifiutati.

Chiamare un comando

curl -X POST https://vepra.ai/v1/businesses/<BIZNESI>/commands/contact.save \
  -H "Authorization: Bearer vak_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Arta Leka","kind":"person","email":"[email protected]","phone":"+355691234567"}'

La ricevuta

{
  "operationId": "3f1c...", "command": "contact.save", "status": "applied",
  "resources": [{ "type": "Contact", "id": "a51d...", "version": 1 }],
  "eventIds": ["..."], "correlationId": "...", "warnings": []
}

Stati: applied, awaiting_approval (approvazione all’interno della piattaforma), pending_external (in attesa di una parte esterna). Errori: 401 chiave sconosciuta o scaduta, 403 fuori dai permessi o dall’attività, 409 versione obsoleta (expectedVersion), 422 input non valido con fieldErrors.

Idempotency-Key: lo stesso valore due volte restituisce la stessa ricevuta senza ripetere l’azione.

Comandi

L’elenco completo con gli schemi di input è nel documento OpenAPI: /v1/openapi.json (rotta dei comandi: POST /v1/businesses/{businessId}/commands/{name}). Gli schemi si chiamano Input_<comando con trattini bassi>, es. Input_contact_save.

I più usati: contact.save, lead.save, booking.hold / booking.confirm, quote.draft / quote.send, task.create, work.create, consent.record.

Le letture usano le stesse rotte GET dell’app, es. GET /v1/businesses/{businessId}/contacts?limit=50, con il permesso .read corrispondente.

Webhook in ingresso

Un indirizzo pubblico a cui i tuoi sistemi (moduli, pagamenti, Activepieces, n8n, Zapier) fanno POST. Crealo nella stessa pagina: un nome, cosa fa (solo avviare workflow, o eseguire un comando da modello) e il segreto, mostrato una sola volta.

Il mittente prova il segreto con X-Vepra-Signature: sha256=<HMAC-SHA256 del corpo> oppure, se non può firmare, con X-Vepra-Token: <segreto>. Nessuna prova: 401. Indirizzo sconosciuto o disattivato: 404. Le chiamate rifiutate non vengono mai registrate.

Una chiamata con il token

curl -X POST https://vepra.ai/v1/hooks/<HOOK_ID> \
  -H "X-Vepra-Token: vhk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Arta Leka","email":"[email protected]","phone":"+355691234567"}'

Firma (Node.js)

import { createHmac } from 'node:crypto';
const signature = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
// -> header X-Vepra-Signature: sha256=...

Il modello del comando

{ "displayName": "{{name}}", "kind": "person", "email": "{{email}}", "phone": "{{phone}}", "notes": "Nga {{source}}" }

{{field.subfield}} prende il valore dal corpo della consegna; un valore intero mantiene il suo tipo (numero, elenco), un valore mancante elimina il campo. Ogni consegna solleva WebhookReceived, un trigger di workflow, con contactId quando il comando ha prodotto un contatto.

Webhook in uscita

Vepra invia gli eventi della tua attività a un indirizzo https pubblico che indichi: contatto salvato, lead, prenotazione confermata, preventivo accettato, lavoro creato… (tutti, o solo quelli che scegli). Gli indirizzi privati (10.x, 192.168.x, localhost) vengono rifiutati.

Ogni consegna è un POST JSON con tre header: X-Vepra-Event, X-Vepra-Delivery e X-Vepra-Signature (sha256=HMAC-SHA256 del corpo con il segreto ricevuto una volta sola). Rispondi 2xx entro 10 secondi; i reindirizzamenti non vengono seguiti.

Nuovi tentativi dopo 1 min, 5 min, 30 min, 2 h e 12 h; dopo 5 tentativi la consegna viene abbandonata, dopo 20 errori consecutivi l’indirizzo viene disattivato (riattivalo dalla pagina). «Test» invia un HookTest.

Il corpo della consegna

{
  "id": "d3b7...",                 // X-Vepra-Delivery
  "event": "ContactSaved",         // X-Vepra-Event
  "occurredAt": "2026-09-17T18:40:00.000Z",
  "business": "58a7...",
  "aggregate": { "type": "Contact", "id": "a51d...", "version": 3 },
  "payload": { "...": "..." },
  "attempt": 1
}

Verifica (Node.js)

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyVepra(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  const a = Buffer.from(signatureHeader ?? ''), b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Verifica (PHP)

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_VEPRA_SIGNATURE'] ?? '');

L’agente

L’agente riceve un obiettivo a parole semplici e costruisce da solo le chiamate: i suoi strumenti sono esattamente i comandi del contratto entro i permessi dell’attore. Fatture, pagamenti, buste paga, licenze, periodi e iscrizioni non vengono mai eseguiti dall’agente; restano proposte che una persona esegue.

Le esecuzioni programmate eseguono un obiettivo con una cadenza (ogni ora, ogni giorno, nei giorni lavorativi, ogni settimana) come attore proprio, lasciano un compito in Compiti e avvisano chi l’ha creato. Serve un modello con uso di strumenti collegato in Collegamenti API.

Workflow

Anche il passo «Invoca comando» di un workflow passa dalla pipeline, come attore «Workflow» dell’attività, con parametri tipizzati (l’etichetta del contatto, l’azione di prenotazione, il canale della conversazione…). Gli eventi generati da quell’attore non avviano mai altri workflow, quindi non ci sono catene infinite. Il trigger WebhookReceived collega i sistemi esterni ai workflow.

Sicurezza

Token mai negli URL; le chiavi si conservano con hash, i segreti sigillati. Ogni chiamata è registrata nell’audit con l’attore di servizio che l’ha fatta. Limiti: fino a 10 chiavi, 10 programmazioni, 20 webhook in ingresso e 10 indirizzi in uscita per attività; corpo in ingresso fino a 1 MB. Il limite di frequenza dell’API vale anche per le chiavi.

Domande o un limite più alto: [email protected].