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

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

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

# استبدل النطاق بنطاق خادمك
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": "جهّزنا لك العرض، تحب نرسله؟"
}

العملاء

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

{
  "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"
}

المستندات

عروض الأسعار والعقود. يُبنى رقم المستند من بادئة نشاطك وحرف النوع والتاريخ وتسلسل من ثلاث خانات:

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": "NQ-Q-260804-058",
    "customer": { "number": "966501234567", "name": "محمد الحربي" },
    "total": 420000,
    "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 على كل ردّ منها، وتبقى تعمل طوال المدّة.

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

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