المطوّرون

ابنِ على VEPRA

كل إجراء يقوم به شخص في التطبيق أمر مسمّى بمخطط وصلاحية. تُستدعى الأوامر نفسها بمفتاح API ومن خطافات الويب ومن الوكيل. لا توجد واجهة API ثانية.

OpenAPI (/v1/openapi.json) · تسجيل الدخول

مفاتيح API

المفتاح فاعل «خدمة» للعمل بالصلاحيات التي تختارها عند إنشائه (من صلاحياتك فقط، ولا members.manage أبدًا). أنشئه تحت العمل ← الوكيل ومفاتيح API؛ يظهر الرمز مرة واحدة ولا تُحفظ إلا بصمته.

يصل المفتاح إلى عمله فقط (أي مسار آخر يجيب 403)، وينتهي حين تحدّد، ويُلغى بنقرة. لا تحقق بخطوتين له: الأوامر التي تتطلب رمزًا حديثًا تُرفض دائمًا.

استدعاء أمر

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 المطابقة.

خطافات الويب الواردة

عنوان عام ترسل إليه أنظمتك (النماذج والمدفوعات و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 عندما ينتج الأمر جهة اتصال.

خطافات الويب الصادرة

ترسل Vepra أحداث عملك إلى عنوان https عام تحدّده: حفظ جهة اتصال، عميل محتمل، تأكيد حجز، قبول عرض سعر، إنشاء عمل… (جميعها، أو ما تختاره فقط). تُرفض العناوين الخاصة (10.x و192.168.x وlocalhost).

كل تسليم طلب POST بصيغة JSON بثلاث ترويسات: X-Vepra-Event وX-Vepra-Delivery وX-Vepra-Signature (sha256=HMAC-SHA256 للمتن بالسر الذي حصلت عليه مرة واحدة). أجب بـ2xx خلال 10 ثوانٍ؛ ولا تُتبع إعادة التوجيه.

إعادة المحاولة بعد دقيقة و5 دقائق و30 دقيقة وساعتين و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.

سير العمل

خطوة «استدعاء أمر» في سير العمل تمرّ هي أيضًا عبر خط المعالجة، بصفة فاعل «سير العمل» للعمل، بمعاملات مصنَّفة (وسم جهة الاتصال وإجراء الحجز وقناة المحادثة…). والأحداث التي يثيرها هذا الفاعل لا تبدأ سير عمل آخر أبدًا، فلا سلاسل لا نهائية. ويربط المشغّل WebhookReceived الأنظمة الخارجية بسير العمل.

الأمان

الرموز لا تكون في الروابط أبدًا؛ تُحفظ المفاتيح مجزّأة (hash) والأسرار مختومة. يُدقَّق كل استدعاء مع فاعل الخدمة الذي أجراه. الحدود: حتى 10 مفاتيح و10 جداول و20 خطاف ويب وارد و10 عناوين صادرة لكل عمل؛ ومتن الوارد حتى 1 MB. ويسري حد معدل API على المفاتيح أيضًا.

للأسئلة أو لحدّ أعلى: [email protected].