Programeri
Gradite na VEPRA
Svaka radnja koju osoba obavi u aplikaciji je imenovana komanda sa šemom i dozvolom. Iste komande se pozivaju API ključem, iz webhook-ova i od strane agenta. Ne postoji drugi API.
API ključevi
Ključ je „service“ akter biznisa sa dozvolama koje izaberete pri kreiranju (samo iz vaših sopstvenih, nikada members.manage). Napravite ga u Biznis → Agent i API ključevi; token se prikazuje jednom i čuva se samo njegov heš.
Ključ dopire samo do sopstvenog biznisa (svaka druga ruta odgovara sa 403), ističe kada vi kažete i opoziva se jednim klikom. Nema MFA: komande koje traže svež kod uvek se odbijaju.
Poziv komande
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"}'Potvrda
{
"operationId": "3f1c...", "command": "contact.save", "status": "applied",
"resources": [{ "type": "Contact", "id": "a51d...", "version": 1 }],
"eventIds": ["..."], "correlationId": "...", "warnings": []
}Statusi: applied, awaiting_approval (odobrenje unutar platforme), pending_external (čeka spoljnu stranu). Greške: 401 nepoznat ili istekao ključ, 403 izvan dozvola ili biznisa, 409 zastarela verzija (expectedVersion), 422 nevažeći unos sa fieldErrors.
Idempotency-Key: ista vrednost dvaput vraća istu potvrdu bez ponavljanja radnje.
Komande
Potpuna lista sa šemama unosa nalazi se u OpenAPI dokumentu: /v1/openapi.json (ruta komande: POST /v1/businesses/{businessId}/commands/{name}). Šeme se zovu Input_<command with underscores>, npr. Input_contact_save.
Najčešće korišćene: contact.save, lead.save, booking.hold / booking.confirm, quote.draft / quote.send, task.create, work.create, consent.record.
Čitanja koriste iste GET rute kao aplikacija, npr. GET /v1/businesses/{businessId}/contacts?limit=50, sa odgovarajućom .read dozvolom.
Ulazni webhook-ovi
Javna adresa na koju vaši sistemi (obrasci, plaćanja, Activepieces, n8n, Zapier) šalju POST. Napravite je na istoj stranici: ime, šta radi (samo pokreće tokove rada ili izvršava komandu iz šablona) i tajna, prikazana jednom.
Pošiljalac dokazuje tajnu pomoću X-Vepra-Signature: sha256=<HMAC-SHA256 of the body> ili, kada ne može da potpiše, pomoću X-Vepra-Token: <secret>. Bez dokaza: 401. Nepoznata ili isključena adresa: 404. Odbijeni pozivi se nikada ne beleže.
Poziv sa tokenom
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"}'Potpisivanje (Node.js)
import { createHmac } from 'node:crypto';
const signature = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
// -> header X-Vepra-Signature: sha256=...Šablon komande
{ "displayName": "{{name}}", "kind": "person", "email": "{{email}}", "phone": "{{phone}}", "notes": "Nga {{source}}" }{{field.subfield}} uzima vrednost iz tela isporuke; cela vrednost zadržava svoj tip (broj, lista), a nedostajuća vrednost izostavlja polje. Svaka isporuka pokreće WebhookReceived, okidač toka rada, sa contactId kada je komanda proizvela kontakt.
Izlazni webhook-ovi
Vepra šalje događaje vašeg biznisa na javnu https adresu koju date: kontakt sačuvan, upit, rezervacija potvrđena, ponuda prihvaćena, posao kreiran… (svi ili samo oni koje izaberete). Privatne adrese (10.x, 192.168.x, localhost) se odbijaju.
Svaka isporuka je JSON POST sa tri zaglavlja: X-Vepra-Event, X-Vepra-Delivery i X-Vepra-Signature (sha256=HMAC-SHA256 tela sa tajnom koju ste dobili jednom). Odgovorite sa 2xx u roku od 10 sekundi; preusmeravanja se ne prate.
Ponovni pokušaji posle 1 min, 5 min, 30 min, 2 h i 12 h; posle 5 pokušaja isporuka se odbacuje, posle 20 uzastopnih neuspeha adresa se isključuje (ponovo je uključite sa stranice). „Test“ šalje HookTest.
Telo isporuke
{
"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
}Provera (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);
}Provera (PHP)
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_VEPRA_SIGNATURE'] ?? '');
Agent
Agent prima cilj običnim rečima i sam gradi pozive: njegovi alati su tačno komande ugovora u okviru dozvola aktera. Fakture, plaćanja, plate, licence, periode i članstva agent nikada ne izvršava; ostaju predlozi koje izvršava osoba.
Zakazana pokretanja izvršavaju cilj po rasporedu (svakog sata, dnevno, radnim danima, nedeljno) kao sopstveni akter, ostavljaju zadatak u Zadacima i obaveštavaju autora. Potreban je model sa tool-use povezan u API vezama.
Tokovi rada
Korak „Pozovi komandu“ toka rada takođe se izvršava kroz pipeline, kao akter „Workflow“ biznisa, sa tipiziranim parametrima (oznaka kontakta, radnja rezervacije, kanal razgovora…). Događaji koje taj akter izaziva ne pokreću druge tokove rada, pa nema beskrajnih lanaca. Okidač WebhookReceived povezuje spoljne sisteme sa tokovima rada.
Bezbednost
Tokeni nikada u URL-ovima; ključevi se čuvaju kao heš, tajne zapečaćene. Svaki poziv se revidira sa service akterom koji ga je obavio. Ograničenja: do 10 ključeva, 10 rasporeda, 20 ulaznih webhook-ova i 10 izlaznih adresa po biznisu; ulazno telo do 1 MB. Ograničenje učestalosti API-ja važi i za ključeve.
Za pitanja ili veće ograničenje: [email protected].