Програмери
Градете врз VEPRA
Секое дејство што го прави човек во апликацијата е наредба со име, шема и дозвола. Истите наредби се повикуваат со API клуч, од webhook-ови и од агентот. Нема второ API.
API клучеви
Клучот е „service“ актер на бизнисот со дозволите што ги избирате при создавањето (само од вашите сопствени, никогаш members.manage). Создајте го под Бизнис → Агент и API клучеви; токенот се покажува еднаш, а се чува само неговиот хеш.
Клучот стигнува само до својот бизнис (секоја друга рута одговара 403), истекува кога ќе определите и се отповикува со еден клик. Нема MFA: наредби што бараат свеж код секогаш се одбиваат.
Повик на наредба
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"}'Потврдата за прием
{
"operationId": "3f1c...", "command": "contact.save", "status": "applied",
"resources": [{ "type": "Contact", "id": "a51d...", "version": 1 }],
"eventIds": ["..."], "correlationId": "...", "warnings": []
}Состојби: applied, awaiting_approval (одобрување во платформата), pending_external (чека надворешна страна). Грешки: 401 непознат или истечен клуч, 403 надвор од дозволите или бизнисот, 409 застарена верзија (expectedVersion), 422 неважечки внес со fieldErrors.
Idempotency-Key: истата вредност двапати враќа иста потврда без да го повтори дејството.
Наредби
Целосниот список со шеми на внесот е во документот OpenAPI: /v1/openapi.json (рута на наредбите: POST /v1/businesses/{businessId}/commands/{name}). Шемите се викаат Input_<наредба со долни црти>, на пр. Input_contact_save.
Најчесто користени: contact.save, lead.save, booking.hold / booking.confirm, quote.draft / quote.send, task.create, work.create, consent.record.
Читањата ги користат истите GET руте како апликацијата, на пр. GET /v1/businesses/{businessId}/contacts?limit=50, со соодветната .read дозвола.
Дојдовни webhook-ови
Јавна адреса на која вашите системи (формулари, плаќања, Activepieces, n8n, Zapier) праќаат POST. Создајте ја на истата страница: име, што прави (само започнува работни текови или извршува наредба по шаблон) и тајната, прикажана еднаш.
Испраќачот ја докажува тајната со X-Vepra-Signature: sha256=<HMAC-SHA256 на телото> или, кога не може да потпише, со X-Vepra-Token: <тајна>. Без доказ: 401. Непозната или исклучена адреса: 404. Одбиените повици никогаш не се евидентираат.
Повик со токен
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"}'Потпишување (Node.js)
import { createHmac } from 'node:crypto';
const signature = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
// -> header X-Vepra-Signature: sha256=...Шаблонот на наредбата
{ "displayName": "{{name}}", "kind": "person", "email": "{{email}}", "phone": "{{phone}}", "notes": "Nga {{source}}" }{{field.subfield}} ја зема својата вредност од телото на испораката; целата вредност го задржува својот тип (број, список), недостасувачка вредност го отфрла полето. Секоја испорака предизвикува WebhookReceived, активатор на работен тек, со contactId кога наредбата создала контакт.
Појдовни webhook-ови
Vepra ги праќа настаните на вашиот бизнис до јавна https адреса што ја давате: зачуван контакт, заинтересиран, потврдена резервација, прифатена понуда, создадена работа… (сите или само оние што ги избирате). Приватните адреси (10.x, 192.168.x, localhost) се одбиваат.
Секоја испорака е JSON POST со три заглавија: X-Vepra-Event, X-Vepra-Delivery и X-Vepra-Signature (sha256=HMAC-SHA256 на телото со тајната што ја добивте еднаш). Одговорете 2xx во рок од 10 секунди; пренасочувањата не се следат.
Повторни обиди по 1 мин, 5 мин, 30 мин, 2 ч и 12 ч; по 5 обиди испораката се напушта, по 20 последователни неуспеси адресата се исклучува (повторно вклучете ја од страницата). „Тест“ праќа HookTest.
Телото на испораката
{
"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
}Проверка (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);
}Проверка (PHP)
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_VEPRA_SIGNATURE'] ?? '');
Агентот
Агентот зема цел со обични зборови и сам ги гради повиците: неговите алатки се точно наредбите од договорот во рамките на дозволите на актерот. Фактури, плаќања, плати, лиценци, периоди и членства агентот никогаш не ги извршува; тие остануваат предлози што ги извршува човек.
Закажаните извршувања извршуваат цел по ритам (на секој час, дневно, работни денови, неделно) како сопствен актер, оставаат задача во Задачи и го известуваат создавачот. Потребен е модел со употреба на алатки поврзан под API врски.
Работни текови
Чекорот „Повикај наредба“ на работен тек исто така минува низ цевководот, како актерот „Workflow“ на бизнисот, со типизирани параметри (ознаката на контактот, дејството на резервацијата, каналот на разговорот…). Настаните што ги предизвикува тој актер никогаш не започнуваат други работни текови, па нема бесконечни ланци. Активаторот WebhookReceived ги поврзува надворешните системи со работните текови.
Безбедност
Токени никогаш во URL; клучевите се чуваат хеширани, тајните запечатени. Секој повик се ревидира со service актерот што го направил. Граници: до 10 клучеви, 10 распореди, 20 дојдовни webhook-ови и 10 појдовни адреси по бизнис; дојдовно тело до 1 MB. Ограничувањето на ритамот на API важи и за клучевите.
Прашања или поголема граница: [email protected].