API v1 — مستقرة

ابنوا على Kolva

واجهة API من نوع REST لربط أدواتكم بـ Kolva. أديروا العملاء والصفقات والزيارات وجهات الاتصال برمجيًّا. وWebhooks فورية لكل حدث.

المصادقةنقاط النهايةحدود المعدلWebhooksأمثلة
مواصفة OpenAPI 3.1

المصادقة

المصادقة بمفتاح API

أنشئوا مفاتيح API من الإعدادات ← المطوّر في لوحة إدارة Kolva لديكم. لكل مفتاح صلاحيات محدَّدة النطاق ويمكن إلغاؤه في أي وقت.

المصادقة عبر الترويسة

الطريقة الموصى بها

# الخيار 1: ترويسة X-Kolva-Key
X-Kolva-Key: kolva_sk_abc123...

# الخيار 2: رمز Bearer
Authorization: Bearer kolva_sk_abc123...

النطاقات المتاحة

صلاحيات دقيقة

read:clients
write:clients
read:deals
write:deals
read:visits
write:visits
read:finance
* (all)

نقاط النهاية

موارد RESTful

تتبع كل نقاط النهاية أعراف REST. والاستجابات بصيغة JSON. والترقيم الصفحي عبر ?page= و ?limit= (بحد أقصى 100).

العملاء

/api/v1/clients

إدارة قاعدة عملائك — العرض والإنشاء والتحديث والتعطيل.

GETPOSTPUTDELETE
النطاقات: read:clients, write:clients

جهات الاتصال

/api/v1/contacts

عمليات CRUD على جهات الاتصال داخل بطاقات العملاء (مصفوفة جهات اتصال JSONB).

GETPOSTPUTDELETE
النطاقات: read:clients, write:clients

الصفقات

/api/v1/deals

الطلبات والصفقات — الإنشاء، وتحديث الحالة، وتتبّع رقم الأعمال.

GETPOSTPUTDELETE
النطاقات: read:deals, write:deals

الزيارات

/api/v1/visits

الزيارات الميدانية — التخطيط، وتتبّع تسجيل الحضور والانصراف، وإدارة الجداول.

GETPOSTPUTDELETE
النطاقات: read:visits, write:visits

حدود المعدل

حدود الاستخدام العادل

100

طلب / دقيقة

429

الحالة عند التجاوز

Retry-After

ترويسة مُضمَّنة

Webhooks

إشعارات الأحداث الفورية

اشتركوا في الأحداث من الإعدادات ← المطوّر ← Webhooks. يرسل Kolva طلبات POST إلى عنوانكم مع التحقق من التوقيع بخوارزمية HMAC-SHA256.

deal_created

يُطلَق عند إنشاء صفقة أو طلب جديد

deal_updated

يُطلَق عند تغيّر حالة صفقة أو مبلغها

client_created

يُطلَق عند إضافة عميل جديد

client_updated

يُطلَق عند تعديل بيانات عميل

visit_completed

يُطلَق عند تسجيل مندوب ميداني انصرافه

invoice_created

يُطلَق عند إصدار فاتورة

order_created

يُطلَق عند تسجيل طلب

contact_updated

يُطلَق عند تعديل جهة اتصال لدى عميل

التحقق من التوقيع

يتضمن كل طلب POST من Webhook ترويسة X-Kolva-Signature . تحققوا منها بخوارزمية HMAC-SHA256 باستخدام سرّ Webhook الخاص بكم.

// التحقق في Node.js
const crypto = require('crypto');
const signature = req.headers['x-kolva-signature'];
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(signature), Buffer.from(expected)
);

سياسة إعادة المحاولة: 3 محاولات بتراجع أسّي (دقيقة، 5 دقائق، 30 دقيقة). بعد 10 إخفاقات متتالية، يُعطَّل Webhook تلقائيًّا.

أمثلة

بداية سريعة

cURL — عرض العملاء
curl -X GET "https://kolva.ai/api/v1/clients?page=1&limit=10" \
  -H "X-Kolva-Key: kolva_sk_your_key_here"
cURL — إنشاء صفقة
curl -X POST "https://kolva.ai/api/v1/deals" \
  -H "X-Kolva-Key: kolva_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "uuid", "total_ht": 1500, "currency": "EUR"}'
JavaScript — عرض الزيارات
const response = await fetch("https://kolva.ai/api/v1/visits?status=completed", {
  headers: { "X-Kolva-Key": process.env.KOLVA_API_KEY },
});
const { data, total } = await response.json();
console.log(`Found ${total} completed visits`);
JavaScript — إنشاء زيارة
const visit = await fetch("https://kolva.ai/api/v1/visits", {
  method: "POST",
  headers: {
    "X-Kolva-Key": process.env.KOLVA_API_KEY,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    client_id: "client-uuid",
    commercial_id: "rep-uuid",
    planned_date: "2026-03-15",
    type: "routine",
  }),
});
const { data } = await visit.json();
// Retry the same operation with the same UUID. A replay returns HTTP 200;
// the initial creation returns HTTP 201.

جاهزون للتكامل؟

أنشئوا مفتاح API في إعدادات Kolva، أو راجعوا مواصفة OpenAPI للمرجع الكامل.

ابدؤوا مجانًامواصفة OpenAPI