دليل المطوّرين

عنوان الواجهة

الطلبات والردود بصيغة JSON، وتغذية BI تدعم CSV أيضًا. الحد الأقصى لحجم الطلب 1 ميغابايت. يحمل رد JSON معرّف request_id في الجسم والترويسة X-Request-Id؛ ويحمله CSV في الترويسة.

https://nabdcx.com/api/public/v1

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

أنشئ مفتاحًا من الإعدادات › التكاملات وأرسله في ترويسة Authorization. يظهر المفتاح مرة واحدة فقط.

Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

read — قراءة الاستبيانات والردود والملخصات والملاحظات.
write — تحديث الملاحظات وإدارة جهات الاتصال والدعوات.
ingest — إرسال ملاحظات جديدة.

واجهة API متاحة في الباقة الكاملة وباقة المؤسسات. إذا فقدت المؤسسة الإتاحة تتوقف المفاتيح (403) ولا يُحذف شيء.

حد الطلبات

120 طلبًا في الدقيقة لكل مفتاح. عند التجاوز يعود الرمز 429 مع الترويسة Retry-After بالثواني.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

التصفح بين الصفحات

القوائم تستخدم المؤشر: limit افتراضيًا 50 وأقصاه 100. مرّر next_cursor في cursor للصفحة التالية؛ تكون null في آخر صفحة.

GET https://nabdcx.com/api/public/v1/feedback?limit=100&cursor=eyJ0Ijoi…

الأخطاء

شكل ثابت لكل خطأ، مع رسالة بالإنجليزية في message وبالعربية في message_ar.

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "This key does not have the required scope.",
    "message_ar": "لا يملك هذا المفتاح الصلاحية المطلوبة.",
    "details": { "required": "ingest", "granted": ["read"] }
  },
  "request_id": "req_…"
}

400 BAD_REQUEST · INVALID_JSON
401 UNAUTHORIZED · KEY_REVOKED · KEY_EXPIRED
403 PLAN_REQUIRED · SCOPE_REQUIRED
404 NOT_FOUND
409 IDEMPOTENCY_CONFLICT · CONFLICT
413 PAYLOAD_TOO_LARGE
422 VALIDATION_FAILED
429 RATE_LIMITED
500 INTERNAL

منع التكرار

أرسل الترويسة Idempotency-Key (حتى 100 حرف) مع طلبات POST. المفتاح نفسه مع الجسم نفسه يعيد النتيجة نفسها؛ ومع جسم مختلف يعود 409 idempotency_conflict. تُحفظ المفاتيح 24 ساعة.

نقاط الواجهة

GET /surveys · scope: read — قائمة الاستبيانات مع عدد الردود الحقيقية.

curl https://nabdcx.com/api/public/v1/surveys?limit=50 \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "data": [
    {
      "id": "0b7c…",
      "title": { "ar": "رضا العملاء", "en": "Customer satisfaction" },
      "status": "active",
      "language": "ar",
      "workspace": { "id": "5d1e…", "name": "Main" },
      "created_at": "2026-10-01T09:00:00Z",
      "response_count": 412
    }
  ],
  "next_cursor": null,
  "request_id": "req_4f2a…"
}

GET /surveys/{id} · scope: read — تفاصيل الاستبيان وأسئلته بالترتيب مع الخيارات ونطاقات المقاييس.

curl https://nabdcx.com/api/public/v1/surveys/0b7c… \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "data": {
    "id": "0b7c…",
    "questions": [
      {
        "id": "q1", "type": "nps", "required": true,
        "text": { "ar": "ما مدى احتمال أن توصي بنا؟", "en": "How likely are you to recommend us?" },
        "scale": { "min": 0, "max": 10 }
      },
      {
        "id": "q2", "type": "single",
        "options": [{ "id": "opt_a", "label_ar": "الفرع", "label_en": "Branch" }]
      }
    ]
  },
  "request_id": "req_…"
}

GET /surveys/{id}/responses · scope: read — الردود المكتملة الحقيقية فقط (لا ردود تجريبية أو اصطناعية أو محذوفة). في الاستبيانات المجهولة لا تظهر بيانات الهوية.

curl "https://nabdcx.com/api/public/v1/surveys/0b7c…/responses?since=2026-10-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "data": [
    {
      "id": "r_91…",
      "submitted_at": "2026-10-12T14:03:11Z",
      "hidden_fields": { "branch": "riyadh" },
      "answers": [
        { "question_id": "q1", "type": "nps", "value": 9 },
        { "question_id": "q2", "type": "single_choice", "option_ids": ["opt_a"],
          "labels": [{ "ar": "الفرع", "en": "Branch" }] }
      ]
    }
  ],
  "next_cursor": "eyJ0Ijoi…",
  "request_id": "req_…"
}

GET /surveys/{id}/responses/{responseId} · scope: read — رد واحد بالشكل نفسه.

curl https://nabdcx.com/api/public/v1/surveys/0b7c…/responses/r_91… \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{ "data": { "id": "r_91…", "answers": [ … ] }, "request_id": "req_…" }

GET /surveys/{id}/summary · scope: read — عدد الردود، ولكل سؤال NPS/CSAT/CES الدرجة محسوبة بتعريفات المقاييس الخاصة بمؤسستك.

curl "https://nabdcx.com/api/public/v1/surveys/0b7c…/summary?since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "data": {
    "survey_id": "0b7c…",
    "responses": { "total": 430, "completed": 412, "completion_rate": 0.958 },
    "questions": [
      { "question_id": "q1", "type": "nps", "answered": 398, "metric": "nps", "score": 42.5,
        "config": { "promoterMin": 9, "detractorMax": 6 } }
    ]
  },
  "request_id": "req_…"
}

GET /feedback · scope: read — ملاحظات صوت العميل مع التصفية حسب التاريخ والمصدر والحالة وحالة المتابعة.

curl "https://nabdcx.com/api/public/v1/feedback?since=2026-10-01T00:00:00Z&case_status=new" \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "data": [
    { "id": "f_12…", "source": "email", "body": "…", "language": "ar", "sentiment": "negative", "case_status": "new" }
  ],
  "next_cursor": null,
  "request_id": "req_…"
}

GET /feedback/{id} · scope: read — ملاحظة واحدة.

curl https://nabdcx.com/api/public/v1/feedback/f_12… \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{ "data": { "id": "f_12…", "case_status": "new", "themes": ["payment"] }, "request_id": "req_…" }

PATCH /feedback/{id} · scope: write — تحديث حالة المتابعة والحل وتاريخ الاستحقاق (التحقق والسجل نفسه الموجود في الواجهة).

curl -X PATCH https://nabdcx.com/api/public/v1/feedback/f_12… \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"case_status":"resolved","resolution_en":"Refund issued"}'

{ "data": { "id": "f_12…", "case_status": "resolved" }, "request_id": "req_…" }

POST /feedback · scope: ingest — إرسال ملاحظة. تمر بالمسار نفسه لإضافة الملاحظات يدويًا (تحليل نبض AI، الأرصدة، حدود الباقة، التنبيهات). تكرار external_source + external_id يعيد العنصر الموجود مع duplicate: true.

curl -X POST https://nabdcx.com/api/public/v1/feedback \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9d-2026-10-16-001" \
  -d '{
    "source": "email",
    "body": "تأخر الاسترداد أسبوعين",
    "language": "ar",
    "external_source": "zendesk",
    "external_id": "T-1042",
    "customer": { "email": "customer@example.com" },
    "metadata": { "channel": "support" }
  }'

{ "data": { "id": "f_88…", "duplicate": false }, "request_id": "req_…" }

POST /feedback/batch · scope: ingest — حتى 100 عنصر في طلب واحد، مع نتيجة لكل عنصر.

curl -X POST https://nabdcx.com/api/public/v1/feedback/batch \
  -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"source":"email","body":"Great staff"},{"source":"email","body":"Late refund","external_source":"zendesk","external_id":"T-1042"}]}'

{
  "data": {
    "created": 1,
    "results": [
    { "index": 0, "status": 201, "id": "f_90…", "duplicate": false },
    { "index": 1, "status": 200, "id": "f_88…", "duplicate": true }
    ]
  },
  "request_id": "req_…"
}

جهات الاتصال والدعوات الشخصية

GET /contacts · read
GET /contacts/{id} · read
POST /contacts · write
POST /contacts/batch · write
PATCH /contacts/{id} · write
DELETE /contacts/{id} · write
POST /surveys/{id}/invitations · write
POST /surveys/{id}/invitations/batch · write
GET /surveys/{id}/invitations · read
GET /invitations/{id} · read
POST /invitations/{id}/cancel · write

POST /contacts يحدّث جهة الاتصال الموجودة عند تطابق external_source + external_id؛ البريد ورقم الجوال المتكرران مع هوية مختلفة يعيدان CONFLICT. PATCH يحفظ الحقول غير المرسلة. DELETE يمحو الهوية والسمات ويسجل العملية مع الإبقاء على الإجابات. الدفعات تقبل items بحد أقصى 500 وتعطي نتيجة لكل عنصر.

تصفية جهات الاتصال: search، language، workspace_id، external_source، consent مع channel (email أو whatsapp)، attribute_key مع attribute_value، last_invited_before. القوائم تدعم limit وcursor. قائمة الدعوات تدعم status. لا تتضمن النتائج أسرارًا أو بصمة الرابط.

أرسل contact_id أو contact (واحدًا فقط) مع channel وhidden_fields وsend_at وexpires_in_days اختياريًا. قناة link تعيد رابط /i/ لإرساله من نظامك. البريد وواتساب ينتظران وقت الإرسال المسموح والسقف اليومي؛ إيقاف القناة يمنع الإرسال. واتساب تجريبي ومعطّل حتى تأكيد إعدادات Unifonic. حدود الباقة نفسها المطبقة في الواجهة؛ الباقة المجانية لا تتيح API افتراضيًا.

الرد المرتبط في GET responses وresponse.completed يتضمن contact {id, external_source, external_id} وinvitation_id. الاستبيان المجهول يحفظ عدّ الدعوات فقط؛ لا تُخزن روابط الهوية على الرد ولا تظهر في النتائج أو API أو Webhook. جهات الاتصال الممحوة لا تُعاد هويتها.

{ "data": { "invitation_id": "550e8400-e29b-41d4-a716-446655440000", "url": "https://nabdcx.com/i/<derived-token>", "status": "sent" }, "request_id": "req_…" }

مثال Zendesk: إغلاق تذكرة

عند إغلاق التذكرة، أرسل دعوة شخصية بقناة link ثم ضع data.url في رد التذكرة. استخدم معرّف التذكرة في Idempotency-Key لمنع التكرار عند إعادة المحاولة؛ لا تنشئ مفتاحًا جديدًا لكل محاولة.

curl -X POST https://nabdcx.com/api/public/v1/surveys/550e8400-e29b-41d4-a716-446655440000/invitations   -H "Authorization: Bearer nabd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"   -H "Content-Type: application/json"   -H "Idempotency-Key: zendesk-ticket-1042-closed"   -d '{"contact":{"external_source":"zendesk","external_id":"customer-42","name":"Customer","email":"customer@example.com","language":"en"},"channel":"link","hidden_fields":{"ticket":"1042"},"expires_in_days":30}'

أحداث Webhook

كل حدث يُرسل كطلب POST إلى رابطك بهذا الشكل. تُستخدم المعرّفات نفسها التي في الواجهة البرمجية.

response.completed — اكتمال رد حقيقي على استبيان.
feedback.created — إضافة ملاحظة جديدة.
feedback.analyzed — انتهى تحليل نبض AI (المشاعر، المحاور، الاستعجال).
case.updated — تغيّرت حالة المتابعة أو الحل أو المسؤول أو تاريخ الاستحقاق.
alert.triggered — انطلق تنبيه من قواعد التنبيه.
invitation.sent — إرسال دعوة شخصية.
invitation.failed — فشل إرسال دعوة بعد المحاولات المسموحة.
contact.opted_out — إيقاف جهة اتصال رسائل قناة محددة.
webhook.test — حدث تجريبي من زر «إرسال حدث تجريبي».

POST /your-endpoint
X-Nabd-Event: feedback.created
X-Nabd-Event-Id: evt_3c1f…
X-Nabd-Timestamp: 1760630400
X-Nabd-Signature: v1=5d41402abc4b2a76b9719d911017c592…

{
  "event_id": "evt_3c1f…",
  "type": "feedback.created",
  "created_at": "2026-10-16T12:00:00Z",
  "organization_id": "9a2b…",
  "data": { "id": "f_88…", "source": "email", "language": "ar" }
}

أعد أي رمز 2xx خلال 10 ثوانٍ. لا نتبع التحويلات. نعيد المحاولة حتى 8 مرات (من دقيقة إلى 6 ساعات)، ويتوقف الرابط تلقائيًا بعد 50 إخفاقًا متتاليًا. قد يصلك الحدث أكثر من مرة: تجاهل event_id المكرر.

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

التوقيع هو HMAC-SHA256 بسرّ الرابط على «الطابع الزمني + نقطة + الجسم الخام». ارفض الطوابع الأقدم من 5 دقائق. أثناء تدوير السر يُرسل توقيعان لمدة 24 ساعة.

Node.js

import crypto from "node:crypto";

// raw = the exact request body as a string; secret = your endpoint signing secret
export function verifyNabd(raw, headers, secret) {
  const ts = Number(headers["x-nabd-timestamp"]);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${raw}`).digest("hex");
  // During a secret rotation the header can carry two values: "v1=…,v1=…"
  return String(headers["x-nabd-signature"] ?? "")
    .split(",")
    .map((s) => s.trim().replace(/^v1=/, ""))
    .some((sig) => sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));
}

Python

import hmac, hashlib, time

def verify_nabd(raw: bytes, headers: dict, secret: str) -> bool:
    ts = int(headers.get("X-Nabd-Timestamp", "0"))
    if not ts or abs(time.time() - ts) > 300:  # older than 5 minutes
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
    sigs = [s.strip().removeprefix("v1=") for s in headers.get("X-Nabd-Signature", "").split(",")]
    return any(hmac.compare_digest(s, expected) for s in sigs)

ربط Power BI

أنشئ مفتاح read من الإعدادات › التكاملات. في Power BI اختر Get Data → Blank Query → Advanced Editor، وأضف معلمة نصية خاصة باسم NabdApiKey ثم الصق النص التالي. اختر Anonymous لمصدر الويب لأن النص يرسل ترويسة Authorization. لا تشارك المفتاح أو ملفًا يحتويه.

let
    BaseUrl = "https://nabdcx.com",
    ApiKey = NabdApiKey,
    GetPage = (cursor as nullable text) as record =>
        Json.Document(Web.Contents(BaseUrl, [
            RelativePath = "api/public/v1/export/responses",
            Headers = [Authorization = "Bearer " & ApiKey],
            Query = if cursor = null then [limit = "1000"]
                    else [limit = "1000", cursor = cursor]
        ])),
    Pages = List.Generate(
        () => [Page = GetPage(null), Continue = true],
        each [Continue],
        each if [Page][next_cursor] = null
             then [Page = [data = {}, next_cursor = null], Continue = false]
             else [Page = GetPage([Page][next_cursor]), Continue = true],
        each [Page][data]
    ),
    Result = Table.FromRecords(List.Combine(Pages))
in
    Result

استبدل export/responses بـ export/feedback أو metrics/daily عند الحاجة. التصدير مسطح: صف لكل إجابة؛ مؤشرات daily صف لكل يوم UTC واستبيان. since شامل وuntil غير شامل، بصيغة ISO. الدرجة تحسب بتعريفات مؤسستك نفسها.

Excel

Excel: Data → Get Data → From Other Sources → Blank Query، واستخدم نص Power Query نفسه. يدعم الرابط From Web عبر Web.Contents مع ترويسة Authorization، لا بإدخال المفتاح في الرابط. CSV: أضف format=csv في طلب مصرح ثم افتح الملف عبر From Text/CSV؛ يحتوي BOM للعربية. تابع الترويسة X-Next-Cursor لجميع الصفحات.

Google Sheets وLooker Studio

الرابط العام CSV لا يعمل لأن المصادقة تتطلب ترويسة. في Apps Script احفظ المفتاح في Script Properties باسم NABD_API_KEY وأنشئ ورقة Nabd ثم شغّل النص أدناه. صِل الورقة بـLooker Studio عبر موصل Google Sheets، أو استخدم موصل JSON موثوقًا يدعم الترويسات والمؤشرات. صلاحيات الورقة تحدد من يرى البيانات؛ لا تجعلها عامة.

function refreshNabd() {
  const key = PropertiesService.getScriptProperties().getProperty('NABD_API_KEY');
  if (!key) throw new Error('Set NABD_API_KEY in Script Properties');
  const base = 'https://nabdcx.com/api/public/v1/export/responses?limit=1000';
  let cursor = null, rows = [];
  do {
    const response = UrlFetchApp.fetch(base + (cursor ? '&cursor=' + encodeURIComponent(cursor) : ''), {
      headers: {Authorization: 'Bearer ' + key}, muteHttpExceptions: true
    });
    if (response.getResponseCode() !== 200) throw new Error('Nabd HTTP ' + response.getResponseCode());
    const page = JSON.parse(response.getContentText());
    rows = rows.concat(page.data);
    cursor = page.next_cursor;
  } while (cursor);
  const sheet = SpreadsheetApp.getActive().getSheetByName('Nabd');
  if (!sheet) throw new Error('Create a sheet named Nabd');
  sheet.clearContents();
  if (!rows.length) return;
  const columns = Object.keys(rows[0]);
  const safe = value => {
    if (typeof value === 'number') return value;
    const text = value == null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
    return /^[=+@\-\t\r]/.test(text) ? "'" + text : text;
  };
  sheet.getRange(1, 1, rows.length + 1, columns.length).setValues(
    [columns].concat(rows.map(row => columns.map(column => safe(row[column]))))
  );
}

Zapier وMake وn8n

Make: رد جديد إلى Google Sheets · تنزيل القالب n8n: حدث موقّع إلى Slack · تنزيل القالب n8n: ردود كل ساعة إلى Google Sheets · تنزيل القالب

استخدم وحدات HTTP وWebhook العامة؛ لا يوجد تطبيق رسمي في المتاجر في هذه الجولة. اختبر الاتصال عبر GET /me بأي مفتاح صالح. تحتاج القراءة إلى read، والاشتراك والإلغاء إلى write، مع إتاحة API وإتاحة Webhooks المدفوعة.

GET /me
POST /hooks
{"target_url":"https://YOUR_WEBHOOK_HOST/path","events":["response.completed"],"description":"Sheets"}
GET /hooks
DELETE /hooks/{id}
GET /hooks/samples/response.completed

POST يعيد data.id وdata.secret مرة واحدة وevents وcreated_at. احفظ السر في إعدادات آمنة. الحد 20 رابطًا عبر API لكل مؤسسة؛ HOOK_LIMIT عند التجاوز، INVALID_TARGET_URL للرابط غير الآمن، PLAN_REQUIRED لغياب الإتاحة. DELETE يعيد 204 حتى إن كان الرابط محذوفًا أو لا يخص مؤسستك. GET لا يعيد أسرارًا. العينات ثابتة ووهمية.

Zapier: اختر Webhooks by Zapier ثم Catch Hook، وانسخ الرابط إلى POST /hooks. استخدم API Request أو Custom Request للأفعال مع Authorization: Bearer. يمكن إضافة خطوة Code للتحقق من HMAC باستخدام الجسم الخام وترويسات Nabd؛ إن لم تصل هذه البيانات الخام فلا تدّعِ التحقق من التوقيع. تجاهل event_id المكرر.

Make: استورد القالب، أنشئ Custom webhook واختر اتصال Google Sheets والملف والورقة والأعمدة. اشترك برابط الوحدة عبر HTTP module وPOST /hooks. استبدل جميع المواضع الإرشادية قبل التشغيل؛ القالب لا يحتوي اتصالات حسابات.

n8n: استورد القالب غير النشط. لقالب Slack فعّل الجسم الخام في Webhook، واضبط NABD_WEBHOOK_SECRET واتصال Slack والقناة. Code يحتاج crypto وURL مع السماح بالوحدة المدمجة؛ استخدم إعدادات بيئتك الموثوقة. لا يُعاد تكوين JSON للتحقق، ويُرفض الطابع الأقدم من خمس دقائق أو المستقبلي.

قالب الاستطلاع: اضبط NABD_API_KEY وGoogle Sheets وعمود id. يقرأ كل الصفحات كل ساعة، ويحدّث صف id الموجود لتجنب التكرار. يستخدم بيانات سير العمل الثابتة لحفظ الحد الزمني؛ لا يتقدم الحد إلا بعد نجاح الكتابة. اختبر في بيئتك قبل التفعيل.

تحديث جهة اتصال CRM عند رد NPS منخفض.
إنشاء تذكرة عند alert.triggered دون بيانات هوية المجيب.
تسجيل الردود في ورقة مع إزالة التكرار.

الاستطلاع الدوري وإزالة التكرار

GET /responses و/surveys/{id}/responses: المكتمل فقط حسب submitted_at؛ /feedback حسب created_at؛ /contacts و/invitations و/surveys/{id}/invitations حسب updated_at؛ /alerts حسب created_at. since بصيغة ISO مع منطقة زمنية وحدّ حصري (>). الترتيب الأحدث أولًا ثم id تنازليًا عند تعادل الزمن. اتبع next_cursor حتى null ولا تنشئ المؤشر بنفسك.

مفتاح إزالة التكرار: id للردود والملاحظات والتنبيهات؛ id + updated_at لجهات الاتصال والدعوات. التغييرات المتعددة بين طلبين تظهر كأحدث حالة، وليست سجل أحداث. احفظ حد بدء الجولة قبل الطلب، وتقدّم إليه بعد معالجة جميع الصفحات بنجاح. استخدم تداخلًا زمنيًا صغيرًا مع إزالة التكرار لمقاومة تأخر المعالجة. التنبيهات لا تعرض الرسالة الحرة أو البريد أو الجوال.

موصلات مكاتب المساعدة وإدارة العملاء

اربط Zendesk أو Freshdesk أو Zoho Desk لإنشاء تذكرة تلقائيًا، أو Dynamics 365 أو Salesforce أو Zoho CRM أو HubSpot لتحديث جهة الاتصال وتسجيل نشاط — من الإعدادات › التكاملات دون كتابة كود. تُرسَل بيانات هوية العميل فقط عند تفعيل «مشاركة بيانات العميل» ويكون الرد غير مجهول.

تفضّل الطريق اليدوي؟ كل ما تفعله الموصلات متاح عبر أحداث Webhook (response.completed وalert.triggered) أو واجهة API، وعبر Zapier وMake وn8n كما في قسم الأتمتة.

بيانات الاعتماد: مكاتب المساعدة

Zendesk — البريد الإلكتروني للحساب + رمز API: مركز الإدارة › القنوات › API › رموز API. الرابط الأساسي https://<subdomain>.zendesk.com.
Freshdesk — مفتاح API: صورة ملفك › إعدادات الملف › مفتاح API. الرابط https://<subdomain>.freshdesk.com.
Zoho Desk — عميل ذاتي في Zoho API Console (api-console.zoho.com) بنطاق Desk.tickets.CREATE وDesk.contacts.READ، ثم رمز تحديث + معرّف وسر العميل + مركز البيانات. الرابط https://desk.zoho.<dc>.

بيانات الاعتماد: أنظمة CRM

HubSpot — تطبيق خاص: الإعدادات › التكاملات › التطبيقات الخاصة، بصلاحيتي crm.objects.contacts وcrm.objects.notes. الرابط الثابت https://api.hubapi.com.
Salesforce — تطبيق متصل مع تفعيل Client Credentials Flow وصلاحيات api؛ الرابط https://<your>.my.salesforce.com ويُدار التوكن تلقائيًا عبر login.salesforce.com.
Zoho CRM — عميل ذاتي بنطاق ZohoCRM.modules.contacts.CREATE وZohoCRM.modules.tasks.CREATE؛ الرابط https://www.zohoapis.<dc>.
Dynamics 365 — تسجيل تطبيق في Entra مع Client Credentials، ثم إنشاء مستخدم تطبيق في Power Platform ومنحه دورًا يكتب جهات الاتصال والمهام؛ الرابط https://<org>.crm4.dynamics.com.

التوكنات المؤقتة (Zoho وSalesforce وDynamics) تُحدَّث تلقائيًا عند انتهائها؛ لا تحتاج تجديدًا يدويًا.

المحفزات الواردة — دليل الإعداد

آلية عامة واحدة، بلا موصلات خاصة بالأدوات. القنوات والبريد وساعات الإرسال والسقف اليومي تعتمد على مسار دعوات نبض الحالي. قناة الرابط لا ترسل رسالة ولا تؤخر إنشاء الرابط. واتساب معطّل حاليًا.

POST https://nabdcx.com/api/public/inbound/<public_id>
Authorization: Bearer <source-secret>
Content-Type: application/json

{"event_id":"fake-delivery-42","customer":{"name":"Example","mobile":"+966500000042","email":"example@example.invalid"},"data":{"order":{"id":"fake-42"}}}

HMAC: ترويسة X-Signature افتراضيًا، hex لـ HMAC-SHA256(secret, raw_body)، مع بادئة sha256= اختيارية. سر الرابط: ?secret=<source-secret>. كل مصدر يستخدم طريقة واحدة فقط. 256 كيلوبايت، 120 طلبًا/دقيقة، معرّف الحدث يمنع التكرار 30 يومًا. 202 لقبول/تجاوز الحدث و200 للمكرر. لا تُخزن الأجسام الخام.

Salla — دليل الإعداد

اختر حدث اكتمال الطلب أو تحديث حالته في إعدادات Webhook للتطبيق أو المتجر المتاحة لحسابك. يتيح سجل Webhook عنوان POST وترويسات حسب نوع التطبيق؛ استخدم Bearer إذا أمكن تعيين Authorization، أو وسيطًا يولّد HMAC مطابقًا لنبض. لا تفترض أن توقيع سلة الأصلي يستخدم العقد نفسه.

أسماء الحقول تختلف حسب الحساب والإصدار؛ افحص النموذج في صندوق الاختبار المحلي قبل التفعيل. هذا المثال توضيحي وليس عقدًا رسميًا للأداة.

{
  "event_id_path": "event_id",
  "field_mapping": {
    "name": "customer.name",
    "mobile": "customer.mobile",
    "email": "customer.email",
    "external_id": "customer.id",
    "reference": "data.order.id",
    "metadata": {
      "item": "items[0].name"
    }
  }
}