Développeurs
Construisez sur VEPRA
Chaque action qu’une personne effectue dans l’application est une commande nommée, avec un schéma et une autorisation. Les mêmes commandes sont appelées avec une clé d’API, depuis des webhooks et par l’agent. Il n’y a pas de seconde API.
Clés d’API
Une clé est un acteur « service » de l’entreprise, avec les autorisations que vous choisissez à sa création (uniquement parmi les vôtres, jamais members.manage). Créez-la sous Entreprise → Agent et clés d’API ; le jeton ne s’affiche qu’une fois et seule son empreinte est conservée.
Une clé n’atteint que sa propre entreprise (toute autre route répond 403), expire quand vous le décidez et se révoque en un clic. Elle n’a pas de MFA : les commandes qui exigent un code récent sont toujours refusées.
Appeler une commande
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"}'Le reçu
{
"operationId": "3f1c...", "command": "contact.save", "status": "applied",
"resources": [{ "type": "Contact", "id": "a51d...", "version": 1 }],
"eventIds": ["..."], "correlationId": "...", "warnings": []
}États : applied, awaiting_approval (approbation au sein de la plateforme), pending_external (attente d’une partie extérieure). Erreurs : 401 clé inconnue ou expirée, 403 hors des autorisations ou de l’entreprise, 409 version périmée (expectedVersion), 422 saisie invalide avec fieldErrors.
Idempotency-Key : la même valeur envoyée deux fois renvoie le même reçu sans répéter l’action.
Commandes
La liste complète avec les schémas d’entrée se trouve dans le document OpenAPI : /v1/openapi.json (route des commandes : POST /v1/businesses/{businessId}/commands/{name}). Les schémas se nomment Input_<commande avec tirets bas>, p. ex. Input_contact_save.
Les plus utilisées : contact.save, lead.save, booking.hold / booking.confirm, quote.draft / quote.send, task.create, work.create, consent.record.
Les lectures utilisent les mêmes routes GET que l’application, p. ex. GET /v1/businesses/{businessId}/contacts?limit=50, avec l’autorisation .read correspondante.
Webhooks entrants
Une adresse publique sur laquelle vos systèmes (formulaires, paiements, Activepieces, n8n, Zapier) font un POST. Créez-la sur la même page : un nom, ce qu’elle fait (seulement démarrer des workflows, ou exécuter une commande à modèle) et le secret, affiché une seule fois.
L’émetteur prouve le secret avec X-Vepra-Signature: sha256=<HMAC-SHA256 du corps> ou, s’il ne peut pas signer, avec X-Vepra-Token: <secret>. Sans preuve : 401. Adresse inconnue ou désactivée : 404. Les appels refusés ne sont jamais enregistrés.
Un appel avec le jeton
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"}'Signature (Node.js)
import { createHmac } from 'node:crypto';
const signature = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
// -> header X-Vepra-Signature: sha256=...Le modèle de commande
{ "displayName": "{{name}}", "kind": "person", "email": "{{email}}", "phone": "{{phone}}", "notes": "Nga {{source}}" }{{field.subfield}} prend sa valeur dans le corps de la livraison ; une valeur entière garde son type (nombre, liste), une valeur absente supprime le champ. Chaque livraison déclenche WebhookReceived, un déclencheur de workflow, avec contactId quand la commande a produit un contact.
Webhooks sortants
Vepra envoie les événements de votre entreprise à une adresse https publique que vous indiquez : contact enregistré, prospect, réservation confirmée, devis accepté, intervention créée… (tous, ou seulement ceux que vous choisissez). Les adresses privées (10.x, 192.168.x, localhost) sont refusées.
Chaque livraison est un POST JSON avec trois en-têtes : X-Vepra-Event, X-Vepra-Delivery et X-Vepra-Signature (sha256=HMAC-SHA256 du corps avec le secret reçu une seule fois). Répondez 2xx en moins de 10 secondes ; les redirections ne sont pas suivies.
Nouvelles tentatives après 1 min, 5 min, 30 min, 2 h et 12 h ; après 5 tentatives, la livraison est abandonnée, après 20 échecs consécutifs l’adresse est désactivée (réactivez-la depuis la page). « Test » envoie un HookTest.
Le corps de la livraison
{
"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
}Vérification (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);
}Vérification (PHP)
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_VEPRA_SIGNATURE'] ?? '');
L’agent
L’agent reçoit un objectif en langage courant et construit lui-même les appels : ses outils sont exactement les commandes du contrat dans les limites des autorisations de l’acteur. Les factures, paiements, paies, licences, périodes et abonnements ne sont jamais exécutés par l’agent ; ils restent des propositions qu’une personne exécute.
Les exécutions planifiées lancent un objectif selon une cadence (toutes les heures, tous les jours, jours ouvrés, chaque semaine) en tant qu’acteur propre, laissent une tâche dans Tâches et notifient le créateur. Un modèle à appel d’outils connecté sous Connexions API est requis.
Workflows
L’étape « Invoquer une commande » d’un workflow passe aussi par le pipeline, en tant qu’acteur « Workflow » de l’entreprise, avec des paramètres typés (l’étiquette du contact, l’action de réservation, le canal de conversation…). Les événements que cet acteur déclenche ne lancent jamais d’autres workflows, il n’y a donc pas de chaînes sans fin. Le déclencheur WebhookReceived relie les systèmes extérieurs aux workflows.
Sécurité
Jamais de jetons dans les URL ; les clés sont stockées hachées, les secrets scellés. Chaque appel est audité avec l’acteur de service qui l’a émis. Limites : jusqu’à 10 clés, 10 planifications, 20 webhooks entrants et 10 adresses sortantes par entreprise ; corps entrant jusqu’à 1 Mo. La limite de débit de l’API s’applique aussi aux clés.
Des questions ou une limite plus élevée : [email protected].