انتقل إلى المحتوى

اربط نظامك بكونكت.

واجهةٌ برمجيّة REST تقرأ عملاءك ومحادثاتك وطلباتك، وتنشئ جهات الاتصال والطلبات والمهامّ — وأحداثٌ موقّعة تصل نظامك لحظة وقوعها. كلُّ مفتاحٍ مقيّدٌ بمنشأته، فلا يبلغ أحدٌ بيانات غيره.

الطلب
curl https://api.abtech.sa/api/v1/contacts?search=0501234567 \
  -H "Authorization: Bearer abc_…"
الردّ 200
{
  "data": [{
    "id": 4812,
    "name": "عبدالله الخالدي",
    "phone": "966501234567",
    "city": "الدمام",
    "tags": ["vip"]
  }],
  "meta": { "current_page": 1, "total": 1 }
}

البدء

  1. في كونكت افتح الإعدادات ← مفاتيح الواجهة وأصدر مفتاحًا. اختر «قراءة فقط» إن كان نظامك يقرأ ولا يكتب.
  2. انسخ المفتاح فورًا — يُعرض مرّةً واحدة، والمحفوظ عندنا تجزئةٌ لا يُستخرج منها.
  3. أرسله في كلّ طلب بترويسة Authorization: Bearer إلى العنوان الأساسيّ: https://api.abtech.sa/api/v1
curl https://api.abtech.sa/api/v1/account -H "Authorization: Bearer $CONNECT_KEY"

المفاتيح والصلاحيّات

المفتاحُ يتبع من أصدره ويعمل بصلاحيّاته لا بأكثر: من لا يرى صندوق الوارد لا يقرأ محادثةً بمفتاحه، ومن عُطّل حسابه توقّف مفتاحه في اللحظة نفسها. وفوق ذلك نطاقان:

قراءة فقط
كلُّ نقاط GET.
قراءة وكتابة
ومعها إنشاء جهات الاتصال وتعديلها، وفتح الطلبات وتغيير حالتها، وإنشاء المهامّ وتغيير حالتها.

والمنشأةُ تُستنتج من المفتاح وحده. أيُّ ترويسةٍ أو حقلٍ يحاول تسمية منشأةٍ أو دور (مثل organization_id) يُرفض بـ 422.

الحدود والصفحات

٦٠ طلبًا في الدقيقة لكلّ مفتاح. تجاوزُها يردّ 429 مع Retry-After، وكلُّ ردٍّ يحمل X-RateLimit-Remaining. القوائمُ صفحاتٌ بـ page وper_page (حتى ١٠٠)، وفي meta العددُ الكلّيّ.

الأخطاء

{ "error": { "code": "read_only_key", "message": "This API key is read-only…" } }
401مفتاحٌ مفقود أو أُلغي أو انتهى، أو الحساب معطّل.
403صاحبُ المفتاح لا يملك الصلاحيّة، أو مفتاح قراءة نادى نقطة كتابة.
404غير موجود في منشأتك — سجلّاتُ غيرك تردّ هكذا أيضًا.
409جهةُ اتصالٍ بالجوال أو البريد نفسه موجودة؛ معرّفها في error.contact_id.
422حقلٌ غير صالح، أو رفض سيرُ العمل الانتقال مع ذكر السبب.

النقاط

التفاصيلُ الكاملة للحقول والقيم في مواصفة OpenAPI — تُفتح في Postman أو Swagger أو أيّ مولّد عملاء.

المساحة

  • GET /account Your workspace
  • GET /integrations List connected integrations
  • GET /integrations/{id} Get an integration

جهات الاتصال

  • GET /contacts List contacts
  • POST /contacts Create a contact كتابة
  • GET /contacts/{id} Get a contact
  • PATCH /contacts/{id} Update a contact كتابة

المحادثات والرسائل

  • GET /conversations List conversations
  • GET /conversations/{id} Get a conversation
  • GET /conversations/{id}/messages List messages

الطلبات

  • GET /service-requests List service requests
  • POST /service-requests Open a service request كتابة
  • GET /service-requests/{id} Get a service request
  • POST /service-requests/{id}/transitions Change request status كتابة

المهامّ

  • GET /tasks List tasks
  • POST /tasks Create a task كتابة
  • GET /tasks/{id} Get a task
  • POST /tasks/{id}/transitions Change task status كتابة

عروض الأسعار والفواتير

  • GET /quotes List quotes
  • GET /quotes/{id} Get a quote
  • GET /invoices List invoices

Sales

  • GET /opportunities List opportunities
  • GET /opportunities/{id} Get an opportunity
  • GET /commerce-orders List store orders
  • GET /commerce-orders/{id} Get a store order

الكتالوج

  • GET /products List products
  • GET /products/{id} Get a product

مثال: فتح طلب من نظامك

curl -X POST https://api.abtech.sa/api/v1/service-requests \
  -H "Authorization: Bearer $CONNECT_KEY" -H "Content-Type: application/json" \
  -d '{"external_reference":"ERP-10042","phone":"0501234567",
       "customer_name":"سارة","summary":"صيانة كاميرات","priority":"high"}'

تكرارُ الطلب بالمرجع نفسه يعيد الطلبَ الموجود ولا يفتح ثانيًا — آمنٌ لإعادة المحاولة.

الويبهوك

من الإعدادات ← الويبهوك أضف رابط https في نظامك واختر الأحداث. نرسل كلَّ حدثٍ بـ POST وجسمٍ JSON، ونعيد المحاولة حتى أربع مرّات (بعد دقيقة، ثمّ خمس، ثمّ ثلاثين) إن تأخّر ردُّك أو جاء بـ 408 أو 429 أو 5xx. وكلُّ تسليمٍ يظهر في سجلّ الشاشة نفسها.

message.receivedرسالة جديدة من عميل على أيّ قناة
contact.createdجهة اتصال جديدة — من واتساب أو متجر أو نظام محاسبي أو الواجهة
service_request.createdطلب جديد فُتح
service_request.status_changedتغيّرت حالة طلب، ومعها الحالة السابقة
conversation.updatedتغيّرت حالة محادثة أو أولويتها
POST /hooks/connect
X-AB-Event-Id: 6f1c…
X-AB-Timestamp: 1793534400
X-AB-Signature: sha256=9d2b…

{
  "id": "6f1c…", "type": "service_request.status_changed", "version": "1",
  "occurred_at": "2026-10-31T09:12:44+03:00",
  "organization": { "id": 42 },
  "data": { "service_request_id": 311, "reference": "AB-2026-0311",
            "workflow_state": "scheduled", "previous_workflow_state": "assigned" }
}

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

التوقيعُ HMAC-SHA256 لـ {timestamp}.{raw body} بسرّ التوقيع الذي عُرض لك مرّةً عند إضافة الوجهة. قارنه بمقارنةٍ ثابتة الزمن، وارفض حدثًا طابعُه الزمنيّ أقدم من خمس دقائق.

// Node.js
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
  .update(`${req.headers['x-ab-timestamp']}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected),
  Buffer.from(req.headers['x-ab-signature'] || ''));
# Python
expected = "sha256=" + hmac.new(secret.encode(),
    f"{ts}.{raw_body}".encode(), hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, signature)
// PHP
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_AB_SIGNATURE'] ?? '');

ومن شاشة الويبهوك يرسل زرّ «حدث تجريبي» حدثًا من نوع webhook.test لتختبر تحقّقك قبل أوّل حدثٍ حقيقيّ.

ربط Odoo

لمن يعمل على Odoo 16 أو 17 أو 18 — Odoo Online أو على خادمه — ربطٌ جاهز لا يحتاج سطر برمجة:

  1. في Odoo: الإعدادات ← المستخدمون ← افتح المستخدم ← الأمان ← مفاتيح API ← أنشئ مفتاحًا.
  2. في كونكت: التكاملات ← Odoo واكتب الرابط واسم قاعدة البيانات والبريد والمفتاح، ثمّ «اختبر واربط».
  3. تُسحب جهاتُ الاتصال والمنتجات وأسعارها والفواتير وحالة دفعها كلّ ساعة. ومن عرض السعر في كونكت: «أرسل إلى Odoo» ثمّ «أكّد أمر البيع».

العميلُ يُطابَق بالجوال ثمّ البريد في الاتجاهين، فلا يتكرّر في كونكت ولا في Odoo. ولا نطلب كلمة المرور ولا نحفظها.

ما لا تفعله الواجهة

لا ترسل الواجهةُ رسائل للعملاء على واتساب أو غيره. الإرسالُ يمرّ بالفريق والوكيل داخل كونكت وبسياسات واتساب للأعمال — وهذا يحمي رقمك من الحظر وعملاءك من رسائل لم يطلبوها.

راسلنا على واتساب