Geliştiriciler

VEPRA üzerinde geliştirin

Bir kişinin uygulamada yaptığı her eylem, şeması ve yetkisi olan adlandırılmış bir komuttur. Aynı komutlar bir API anahtarıyla, webhook’lardan ve ajan tarafından çağrılır. İkinci bir API yoktur.

OpenAPI (/v1/openapi.json) · Giriş yap

API anahtarları

Bir anahtar, oluştururken seçtiğiniz yetkilerle işletmenin bir «servis» aktörüdür (yalnızca kendi yetkilerinizden, asla members.manage değil). İşletme → Ajan ve API anahtarları altında oluşturun; belirteç bir kez görünür ve yalnızca özeti saklanır.

Bir anahtar yalnızca kendi işletmesine ulaşır (başka her yol 403 döner), siz söylediğinizde sona erer ve tek tıkla iptal edilir. MFA’sı yoktur: yeni kod gerektiren komutlar her zaman reddedilir.

Bir komutu çağırma

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

Makbuz

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

Durumlar: applied, awaiting_approval (platform içi onay), pending_external (dış taraf bekleniyor). Hatalar: 401 bilinmeyen veya süresi dolmuş anahtar, 403 yetkiler veya işletme dışı, 409 eski sürüm (expectedVersion), 422 fieldErrors ile geçersiz girdi.

Idempotency-Key: aynı değer iki kez, eylemi tekrarlamadan aynı makbuzu döndürür.

Komutlar

Girdi şemalarıyla tam liste OpenAPI belgesindedir: /v1/openapi.json (komut yolu: POST /v1/businesses/{businessId}/commands/{name}). Şemalar Input_<alt çizgili komut> diye adlandırılır, örn. Input_contact_save.

En çok kullanılanlar: contact.save, lead.save, booking.hold / booking.confirm, quote.draft / quote.send, task.create, work.create, consent.record.

Okumalar uygulamanın kullandığı aynı GET yollarını kullanır, örn. GET /v1/businesses/{businessId}/contacts?limit=50, eşleşen .read yetkisiyle.

Gelen webhook’lar

Sistemlerinizin (formlar, ödemeler, Activepieces, n8n, Zapier) POST yaptığı herkese açık bir adres. Aynı sayfada oluşturun: bir ad, ne yaptığı (yalnızca iş akışı başlatmak veya şablonlu bir komut çalıştırmak) ve bir kez gösterilen sır.

Gönderen sırrı X-Vepra-Signature: sha256=<gövdenin HMAC-SHA256’sı> ile veya imzalayamıyorsa X-Vepra-Token: <sır> ile kanıtlar. Kanıt yok: 401. Bilinmeyen veya devre dışı adres: 404. Reddedilen çağrılar asla kaydedilmez.

Belirteçli bir çağrı

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

İmzalama (Node.js)

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

Komut şablonu

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

{{field.subfield}} değerini teslimat gövdesinden alır; tam bir değer türünü korur (sayı, liste), eksik bir değer alanı düşürür. Her teslimat, komut bir kişi ürettiğinde contactId ile bir iş akışı tetikleyicisi olan WebhookReceived’i tetikler.

Giden webhook’lar

Vepra işletmenizin olaylarını verdiğiniz herkese açık bir https adresine gönderir: kişi kaydedildi, potansiyel müşteri, rezervasyon onaylandı, teklif kabul edildi, iş oluşturuldu… (hepsi veya yalnızca seçtikleriniz). Özel adresler (10.x, 192.168.x, localhost) reddedilir.

Her teslimat, üç başlıklı bir JSON POST’tur: X-Vepra-Event, X-Vepra-Delivery ve X-Vepra-Signature (bir kez aldığınız sırla gövdenin sha256=HMAC-SHA256’sı). 10 saniye içinde 2xx ile yanıt verin; yönlendirmeler izlenmez.

1 dk, 5 dk, 30 dk, 2 sa ve 12 sa sonra yeniden denemeler; 5 denemeden sonra teslimattan vazgeçilir, art arda 20 hatadan sonra adres devre dışı bırakılır (sayfadan yeniden etkinleştirin). “Test” bir HookTest gönderir.

Teslimat gövdesi

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

Doğrulama (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);
}

Doğrulama (PHP)

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

Ajan

Ajan, sade sözlerle bir hedef alır ve çağrıları kendisi kurar: araçları, aktörün yetkileri dâhilindeki sözleşme komutlarının tamamıdır. Faturalar, ödemeler, bordro, lisanslar, dönemler ve üyelikler ajan tarafından asla yürütülmez; bir kişinin yürüteceği öneri olarak kalır.

Zamanlanmış çalıştırmalar bir hedefi bir sıklıkla (saatlik, günlük, iş günleri, haftalık) kendi aktörleri olarak yürütür, Görevler’de bir görev bırakır ve oluşturanı bilgilendirir. API bağlantıları altında bağlı, araç kullanan bir model gerekir.

İş akışları

Bir iş akışının «Komut çağır» adımı da işletmenin «İş akışı» aktörü olarak, tipli parametrelerle (kişi etiketi, rezervasyon eylemi, konuşma kanalı…) işlem hattından geçer. O aktörün ürettiği olaylar başka iş akışlarını asla başlatmaz, bu yüzden sonsuz zincirler olmaz. WebhookReceived tetikleyicisi dış sistemleri iş akışlarına bağlar.

Güvenlik

Belirteçler asla URL’lerde değil; anahtarlar özetlenmiş, sırlar mühürlü saklanır. Her çağrı, yapan servis aktörüyle denetlenir. Sınırlar: işletme başına en çok 10 anahtar, 10 zamanlama, 20 gelen webhook ve 10 giden adres; gelen gövde en çok 1 MB. API hız sınırı anahtarlar için de geçerlidir.

Sorular veya daha yüksek bir sınır için: [email protected].