Ndërto mbi Vepra AI

Çelësat API

Një çelës është një aktor "service" i biznesit me lejet që zgjedh ti kur e krijon (vetëm nga lejet e tua, kurrë members.manage). Krijohet te Biznesi → Agjenti & çelësat API; tokeni shfaqet vetëm një herë dhe ruhet vetëm me hash.

Çelësi arrin vetëm biznesin e vet (çdo rrugë tjetër kthen 403), skadon kur e cakton dhe revokohet me një klik. Nuk ka MFA: komandat që kërkojnë kod të freskët refuzohen gjithmonë.

Thirrje e një 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":"arta@shembull.al","phone":"+355691234567"}'

Fatura e përgjigjes (receipt)

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

Statuset: applied (u zbatua), awaiting_approval (pret miratim brenda platformës), pending_external (pret një palë të jashtme). Gabimet: 401 çelës i panjohur/i skaduar, 403 jashtë lejeve ose jashtë biznesit, 409 version i vjetëruar (expectedVersion), 422 input i pavlefshëm me fieldErrors.

Idempotency-Key: e njëjta vlerë dy herë kthen të njëjtën faturë pa e përsëritur veprimin.

Komandat

Lista e plotë me skemat e inputit është te dokumenti OpenAPI: /v1/openapi.json (rruga e komandave: POST /v1/businesses/{businessId}/commands/{name}). Skemat quhen Input_<komanda me nënvizë>, p.sh. Input_contact_save.

Të përdorura më shpesh: contact.save (klient), lead.save (lead), booking.hold / booking.confirm (rezervim), quote.draft / quote.send (ofertë), task.create (detyrë), work.create (urdhër pune), consent.record (pëlqim).

Leximi bëhet me GET te të njëjtat rrugë që përdor aplikacioni, p.sh. GET /v1/businesses/{businessId}/contacts?limit=50, me lejen përkatëse .read.

Webhook-et hyrëse

Një adresë publike që sistemet e tua (formularë, pagesa, Activepieces, n8n, Zapier) e thërrasin me POST. Krijohet te e njëjta faqe: zgjedh emrin, çfarë bën (vetëm nis workflow-t, ose ekzekuton një komandë me shabllon) dhe merr sekretin një herë.

Dërguesi provon sekretin me X-Vepra-Signature: sha256=<HMAC-SHA256 i trupit> ose, kur nuk nënshkruan dot, me X-Vepra-Token: <sekreti>. Pa provë: 401. Adresë e panjohur ose e çaktivizuar: 404. Asgjë nuk regjistrohet për thirrjet e refuzuara.

Thirrje me 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":"arta@shembull.al","phone":"+355691234567"}'

Nënshkrimi (Node.js)

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

Shablloni i komandës

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

{{fusha.nenfusha}} merr vlerën nga trupi i dërgesës; një vlerë e plotë ruan tipin (numër, listë), një vlerë që mungon e heq fushën. Çdo dërgesë lind ngjarjen WebhookReceived, trigger i workflow-ve, me contactId kur komanda prodhoi një kontakt.

Webhook-et dalëse

Vepra dërgon ngjarjet e biznesit tënd te një adresë https publike që jep ti: kontakt i ruajtur, lead, rezervim i konfirmuar, ofertë e pranuar, punë e krijuar… (të gjitha ose vetëm ato që zgjedh). Adresat private (10.x, 192.168.x, localhost) refuzohen.

Çdo dërgesë është një POST JSON me tri koka: X-Vepra-Event, X-Vepra-Delivery dhe X-Vepra-Signature (sha256=HMAC-SHA256 i trupit me sekretin që more një herë). Përgjigju 2xx brenda 10 sekondash; ridrejtimet nuk ndiqen.

Ripërpjekjet: pas 1 min, 5 min, 30 min, 2 h dhe 12 h; pas 5 përpjekjeve dërgesa braktiset, pas 20 dështimesh radhazi adresa çaktivizohet (e rindez nga faqja). "Provo" dërgon një HookTest.

Trupi i dërgesës

{
  "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
}

Verifikimi (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);
}

Verifikimi (PHP)

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

Agjenti

Agjenti merr një qëllim në gjuhë të lirë dhe ndërton vetë thirrjet: mjetet e tij janë pikërisht komandat e kontratës brenda lejeve të aktorit. Faturat, pagesat, pagat, licencat, periudhat dhe anëtarësitë nuk ekzekutohen kurrë nga agjenti; mbeten propozim që një person e zbaton.

Run-et e planifikuara ekzekutojnë një qëllim në orar (çdo orë, ditë, ditët e punës, javë) si aktor i vet, lënë detyrë te Detyrat dhe njoftojnë krijuesin. Kërkon një model me tool-use të lidhur te Lidhjet API.

Workflow-t

Hapi "Thirr komandë" i një workflow-i ekzekutohet po ashtu përmes pipeline-it, si aktori "Workflow" i biznesit, me parametra të tipizuar (etiketa e kontaktit, veprimi i rezervimit, kanali i bisedës…). Ngjarjet që lind ai aktor nuk nisin workflow të tjera, kështu nuk ka zinxhirë të pafund. Trigger-i WebhookReceived lidh sistemet e jashtme me workflow-t.

Siguria

Token-ët kurrë në URL; çelësat ruhen me hash, sekretet të vulosura. Çdo thirrje auditohet me aktorin service që e bëri. Kufij: deri në 10 çelësa, 10 plane, 20 webhook hyrës dhe 10 adresa dalëse për biznes; trupi i dërgesës hyrëse deri në 1 MB. Kufizimi i ritmit i API-t vlen edhe për çelësat.

Për pyetje ose një kufi më të lartë: kontakt@vepra.ai.