Προγραμματιστές

Χτίστε πάνω στη VEPRA

Κάθε ενέργεια που κάνει ένας άνθρωπος στην εφαρμογή είναι μια ονομασμένη εντολή με σχήμα και δικαίωμα. Οι ίδιες εντολές καλούνται με κλειδί API, από webhooks και από τον πράκτορα. Δεν υπάρχει δεύτερο API.

OpenAPI (/v1/openapi.json) · Σύνδεση

Κλειδιά API

Ένα κλειδί είναι ένας «service» actor της επιχείρησης με τα δικαιώματα που επιλέγετε κατά τη δημιουργία του (μόνο από τα δικά σας, ποτέ members.manage). Δημιουργήστε το στο Επιχείρηση → Πράκτορας και κλειδιά API· το token εμφανίζεται μία φορά και αποθηκεύεται μόνο το hash του.

Ένα κλειδί φτάνει μόνο στη δική του επιχείρηση (κάθε άλλη διαδρομή απαντά 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.

Εισερχόμενα webhooks

Μια δημόσια διεύθυνση στην οποία τα συστήματά σας (φόρμες, πληρωμές, Activepieces, n8n, Zapier) κάνουν POST. Δημιουργήστε την στην ίδια σελίδα: ένα όνομα, τι κάνει (μόνο ξεκινά ροές εργασίας ή εκτελεί εντολή με πρότυπο) και το μυστικό, που εμφανίζεται μία φορά.

Ο αποστολέας αποδεικνύει το μυστικό με X-Vepra-Signature: sha256=<HMAC-SHA256 του σώματος> ή, όταν δεν μπορεί να υπογράψει, με X-Vepra-Token: <μυστικό>. Χωρίς απόδειξη: 401. Άγνωστη ή απενεργοποιημένη διεύθυνση: 404. Οι απορριφθείσες κλήσεις δεν καταγράφονται ποτέ.

Μια κλήση με το 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"}'

Υπογραφή (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 όταν η εντολή παρήγαγε επαφή.

Εξερχόμενα webhooks

Η 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 διαδοχικές αποτυχίες η διεύθυνση απενεργοποιείται (ενεργοποιήστε την ξανά από τη σελίδα). Το «Test» στέλνει ένα 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'] ?? '');

Ο πράκτορας

Ο πράκτορας παίρνει έναν στόχο με απλά λόγια και χτίζει μόνος του τις κλήσεις: τα εργαλεία του είναι ακριβώς οι εντολές του συμβολαίου εντός των δικαιωμάτων του actor. Τιμολόγια, πληρωμές, μισθοδοσία, άδειες, περίοδοι και συνδρομές δεν εκτελούνται ποτέ από τον πράκτορα· μένουν προτάσεις που εκτελεί ένας άνθρωπος.

Οι προγραμματισμένες εκτελέσεις τρέχουν έναν στόχο με συχνότητα (ωριαία, καθημερινή, εργάσιμες, εβδομαδιαία) ως δικός τους actor, αφήνουν μια εργασία στις Εργασίες και ειδοποιούν τον δημιουργό. Απαιτείται μοντέλο με χρήση εργαλείων συνδεδεμένο στις Συνδέσεις API.

Ροές εργασίας

Το βήμα «Κλήση εντολής» μιας ροής εργασίας περνά επίσης από τη διοχέτευση, ως actor «Workflow» της επιχείρησης, με τυποποιημένες παραμέτρους (η ετικέτα επαφής, η ενέργεια κράτησης, το κανάλι συνομιλίας…). Τα γεγονότα που εκπέμπει αυτός ο actor δεν ξεκινούν ποτέ άλλες ροές, άρα δεν υπάρχουν ατέλειωτες αλυσίδες. Ο ενεργοποιητής WebhookReceived συνδέει εξωτερικά συστήματα με ροές εργασίας.

Ασφάλεια

Τα token ποτέ σε URL· τα κλειδιά αποθηκεύονται κατακερματισμένα, τα μυστικά σφραγισμένα. Κάθε κλήση ελέγχεται με τον actor υπηρεσίας που την έκανε. Όρια: έως 10 κλειδιά, 10 προγραμματισμοί, 20 εισερχόμενα webhooks και 10 εξερχόμενες διευθύνσεις ανά επιχείρηση· εισερχόμενο σώμα έως 1 MB. Το όριο ρυθμού του API ισχύει και για τα κλειδιά.

Ερωτήσεις ή υψηλότερο όριο: [email protected].