بياناتك في نظامك
اسحب المحادثات والعملاء والعروض إلى نظامك الداخلي واعرضها كما تشاء.
GET /api/v1/conversations- الرئيسية
- للمطوّرين
مواصفة الواجهة البرمجية والأحداث
ما في هذه الصفحة مواصفة: شكل الطلبات والأحداث منشور وثابت لتبني عليه، وتُفعَّل لنشاطك عند الطلب في الباقة الاحترافية فأعلى. المنفَّذ اليوم نقطة فحص الحالة /health وحدها، وحالة كل نقطة مكتوبة في الدليل.
المصادقة
مفتاح في الترويسة
كل طلب يحمل مفتاحك في ترويسة Authorization. نصدر لك المفتاح عند التفعيل ونلغيه متى طلبت، ولا يُعرض مرة أخرى بعد تسليمه.
ننصح بمفتاح مستقل لكل تكامل، فإلغاء أحدها لا يوقف البقية.
والعنوان الأساسي هو نطاقك أنت، لأن لكل عميل نسخته الخاصة من ناطق.
# طلب بيانات عميل — استبدل النطاق بنطاق خادمك curl https://bot.example.sa/api/v1/customers/966501234567 \ -H "Authorization: Bearer $NAATEQ_KEY" \ -H "Accept: application/json"
Webhooks
الأحداث التي تصلك عند تفعيلها
تسجّل رابطاً واحداً، فتصلك كل الأحداث عليه بصيغة JSON مع توقيع X-Naateq-Signature.
هذه الأحداث مواصفة: شكلها ثابت ومنشور لتبني عليه، وتُفعَّل لنشاطك عند الطلب. حالة كل حدث في الدليل.
message.receivedوصلت رسالة من عميل. تحمل النص، ورقم المرسل، والنية المصنَّفة.reply.sentردّ النظام. تحمل الرد، والمصدر (آلي / أداة / بشري)، وزمن المعالجة.stage.changedانتقل العميل بين المراحل الأربع. تحمل المرحلة السابقة والجديدة.quote.issuedصدر عرض سعر. تحمل رقم المستند والإجمالي ورابط PDF.contract.approvedوافق المالك على إرسال عقد. تحمل رقم العقد والقيمة.handoff.requestedطلب تصعيد لموظف بشري. تحمل سبب التصعيد ونص المحادثة كاملاً.guard.blockedحجب فلتر المدخلات رسالة. تحمل نوع المحاولة والنص المحجوب.POST /your-endpoint
X-Naateq-Signature: t=1780000000,v1=5f2b…
{
"event": "quote.issued",
"created_at": "2026-08-04T09:31:02.771Z",
"data": {
"doc_number": "NQ-Q-260804-058",
"customer": { "number": "966501234567", "name": "محمد الحربي" },
"total": 420000,
"currency": "SAR",
"pdf_url": "https://bot.example.sa/api/v1/documents/NQ-Q-260804-058/pdf"
}
}
التحقق من التوقيع
لا تثق بأي طلب غير موقّع
احسب HMAC-SHA256 على t + "." + body بمفتاح الويبهوك، وقارنه بالقيمة v1. ارفض أي طلب أقدم من خمس دقائق.
import crypto from "node:crypto";
export function verify(raw, header, secret) {
const [t, v1] = header.split(",").map(p => p.split("=")[1]);
if (Math.abs(Date.now()/1000 - +t) > 300) return false;
const expect = crypto
.createHmac("sha256", secret)
.update(`${t}.${raw}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expect), Buffer.from(v1)
);
}
حالات الاستعمال
ما الذي يُبنى فوق هذه الواجهة بعد تفعيلها
مزامنة مع الـCRM
مع كل عميل جديد يصلك ويبهوك بمرحلته ومصدره، فيدخل مسار مبيعاتك في ثوانٍ دون إدخال يدوي.
stage.changedتنبيه فريقك حيث يعمل
صعّد المحادثة إلى سلاك أو تيليجرام أو نظام تذاكرك لحظة يطلب العميل موظفاً، أو يطلب خصماً فوق السقف الذي وضعته أنت.
handoff.requestedالحدود وسياسة البيانات
حدود الطلبات وإعادة المحاولة والمهلة أدناه مواصفة، وتسري حين تُفعَّل الواجهة لنشاطك.
| البند | القيمة |
|---|---|
| حد الطلبات | 120 / دقيقة لكل مفتاح |
| تجاوز الحد | 429 مع ترويسة Retry-After |
| إعادة محاولة الويبهوك | 5 محاولات بتباعد أُسّي خلال 24 ساعة |
| مهلة استجابة نقطتك | 5 ثوانٍ |
| أين تُخزَّن البيانات | على خادمك إن شغّلته عندك، أو على خوادمنا في التشغيل المُدار. ونص المحادثة في التشغيل المُدار يُعالَج عند مزوّد ذكاء اصطناعي سحابي نسمّيه لك في العقد |
| الاحتفاظ والحذف | تضبطهما أنت، والنظام لا يحذف شيئاً تلقائياً |
تحتاج نقطة نهاية غير موجودة؟
نبني نقاط النهاية عند الطلب، فأخبرنا بما تبنيه.