دليل الواجهة البرمجية

بداية في خمس دقائق

النداء الوحيد الذي يعمل اليوم بلا مفتاح ولا إعداد هو فحص الحياة. ابدأ به لتتأكّد أن نسختك تعمل وأن الشبكة تصل إليها.

# استبدل النطاق بنطاق خادمك
curl https://bot.example.sa/health

# الرد
{ "ok": true }

ثم اطلب مفتاحاً من فريق التأسيس، واحفظه في متغيّر بيئة. لا تضعه في شيفرة الواجهة الأمامية — المفتاح يمنح صلاحية كاملة على سجلّات عملائك.

export NAATEQ_URL=https://bot.example.sa
export NAATEQ_KEY=nq_live_…

curl "$NAATEQ_URL/api/v1/conversations?limit=1" \
  -H "Authorization: Bearer $NAATEQ_KEY"

العنوان الأساسي هو نطاقك أنت

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

https://<نطاقك>/api/v1

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

التبعة المقابلة: الجاهزية مسؤوليتك. لا نَعِد بزمن تشغيل لخادم لا نديره، وما نلتزم به مكتوب في صفحة الدعم.

مفتاح واحد في الترويسة

كل طلب يحمل مفتاحك في Authorization. المفتاح يُعرض مرة واحدة عند الإنشاء ولا يُسترجع بعدها — إن ضاع، أنشئ غيره وألغِ القديم.

# مفتاح ناقص أو ملغى
HTTP/1.1 401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "key_revoked",
    "message": "المفتاح مُلغى. أنشئ مفتاحاً جديداً من لوحة التحكم.",
    "request_id": "req_01J8…"
  }
}

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

كل محادثة معزولة برقم العميل. والعزل ليس إعداداً تختاره — هو مبنيّ في النظام: لا يرى نداءٌ سجلَّ عميل آخر أبداً.

POST /api/v1/messages
Authorization: Bearer $NAATEQ_KEY
Idempotency-Key: a3f1c9de-…

{
  "to": "966501234567",
  "text": "جهّزنا لك العرض، تحب نرسله؟"
}

العملاء

سجلّ العميل هو نفسه الذي يكتبه النظام في crm.json — الحقول أدناه منسوخة من الكود لا مؤلَّفة للعرض. ولذلك ما تقرؤه من الواجهة هو ما يراه البوت لحظة الردّ، لا نسخة متأخّرة عنه.

{
  "number": "966501234567",
  "name": "محمد الحربي",
  "stage": "quoted",
  "project": "مجلس 12 متر — تفصيل",
  "quote": {
    "amount": 4200,
    "project": "مجلس 12 متر — تفصيل",
    "status": "sent",
    "date": "2026-08-04"
  },
  "contract": null,
  "milestones": [],
  "tickets": [],
  "payment_links": [],
  "next_payment_due": null,
  "created_at": "2026-08-04T09:12:44.108Z",
  "updated_at": "2026-08-04T09:31:02.771Z"
}

المستندات

عروض الأسعار والعقود. ورقم المستند ليس عشوائياً — يبنيه docNumber() من بادئة نشاطك وحرف النوع والتاريخ وتسلسل من ثلاث خانات:

HT-Q-260804-058
│    │    │        └── تسلسل اليوم
│    │    └────────── YYMMDD
│    └─────────────── Q عرض سعر · C عقد
└──────────────────── بادئة نشاطك

⚠ البادئة تتغيّر بتغيّر حزمة النشاط. لا تكتبها ثابتةً في تكاملك — طابِق النمط لا النصّ. (كتابتها بيدٍ في موضعين كسرت أمر اعتماد العقد عندنا مرّة، بصمت.)

المدفوعات

وخطة الدفع محسوبة لا مكتوبة. الدفعة الأخيرة تُحسب بالطرح لا بالضرب، فمجموع الدفعات يساوي الإجمالي بالضبط مهما فعل التقريب — لأن ريالاً ضائعاً في عقدٍ عيبٌ يُكتشف عند التحصيل:

[
  { "id": "moyasar", "label_ar": "مُيسّر",
    "configured": true, "mode": "live",
    "min_amount_minor": 100,
    "fields": ["secret_key"] },
  { "id": "paylink", "label_ar": "Paylink",
    "configured": false, "mode": null,
    "min_amount_minor": 500,
    "fields": ["api_id", "secret_key"] },
  { "id": "tap", "label_ar": "تاب",
    "configured": false, "mode": null,
    "min_amount_minor": 100,
    "fields": ["secret_key"] }
]

{
  "provider": "moyasar",
  "url": "https://…",
  "ref": "inv_01J8…",
  "status": "pending",
  "amount_minor": 210000,
  "currency": "SAR"
}

الويبهوكس

تسجّل رابطاً واحداً، فتصلك الأحداث المشتركة عليه بصيغة JSON مع توقيع X-Naateq-Signature.

الأحداث كلّها مواصفة — لا باعث لأيٍّ منها في الكود اليوم.

POST /your-endpoint
X-Naateq-Signature: t=1785838800,v1=5f2b…
X-Naateq-Delivery: whd_01J8…

{
  "event": "quote.issued",
  "created_at": "2026-08-04T09:31:02.771Z",
  "data": {
    "doc_number": "HT-Q-260804-058",
    "customer": { "number": "966501234567", "name": "محمد الحربي" },
    "total": 4200,
    "currency": "SAR",
    "payment_plan": "50% عند التوقيع • 30% عند التسليم الأولي • 20% عند التسليم النهائي"
  }
}

نقول «الترتيب غير مضمون» و«التكرار ممكن» لأنهما حقيقة كل نظام إعادة محاولة. من يَعِدك بترتيبٍ مضمون فوق شبكةٍ غير موثوقة، يَعِدك بما سيكسره أول انقطاع.

لا تثق بأي طلب غير موقّع

احسب HMAC-SHA256 على t + "." + الجسم الخام بمفتاح الويبهوك، وقارنه بـ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");

  // المقارنة ثابتة الزمن: == يسرّب الفرق عبر زمن التنفيذ
  const a = Buffer.from(expect), b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

⚠ timingSafeEqual يرمي استثناءً إن اختلف الطولان — ولذلك يسبقه فحص الطول. وهذه بالضبط الحالة التي تُسقط تكاملات كثيرة في الإنتاج.

واحسب التوقيع على الجسم الخام قبل أي تحليل JSON — إعادة ترتيب المفاتيح تكسر التوقيع.

التكرارية — لا تدفع مرّتين

كل POST يقبل Idempotency-Key. إن انقطع الاتصال ولم يصلك الرد، أعد نفس الطلب بنفس المفتاح: تحصل على نفس النتيجة لا على رابط دفع ثانٍ ولا رسالة مكرّرة.

الصفحات بمؤشّر لا برقم

لا page=2: سجلٌّ جديد بين طلبين يُزيح الترقيم فتفوتك عناصر أو تتكرّر. المؤشّر يثبّت الموضع.

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "cur_01J8…"
}

وللمزامنة الدورية استعمل updated_after بآخر updated_at استلمته — تنقل ما تغيّر فقط بدل السجلّ كلّه.

شكل واحد لكل خطأ

كل خطأ يحمل type للتصنيف وcode للتعامل البرمجي وmessage للعرض وrequest_id للدعم. عالج code لا message — النصّ قد يتحسّن، والرمز لا يتغيّر.

⚠ لا يُعاد نصّ اعتمادات البوابة في أي رسالة خطأ — لا كاملاً ولا مقتطعاً. وهذه قاعدة في طبقة الدفع لا مجرّد عادة: رسالة الخطأ أشيع مكانٍ يتسرّب منه مفتاح.

الحدود وسياسة البيانات

ملاحظة صادقة: ما دام النظام على خادمك، فحدّ الطلبات حمايةٌ لمواردك أنت. ورفعه إعدادٌ في نسختك لا طلبٌ تشتريه منّا.

الإصدار والإهمال

الإصدار في المسار: /api/v1/. وداخل الإصدار الواحد نضيف ولا نحذف.

وإن أهملنا شيئاً: إشعار قبل 180 يوماً، وترويسة Sunset على كل رد من النقطة المهمَلة، وبقاؤها عاملةً طوال المدّة.

سجلّ التغييرات

كل تغيير في هذا الدليل يُسجَّل هنا بتاريخه — بما فيه تصحيح ما كان مكتوباً خطأً.