@riyadah/nabaa · v0.2

بوّابة مطوّري نبأ

واجهة برمجية واحدة لكل قنوات التواصل وتجربة العميل: الرسائل النصية وواتساب والبريد الإلكتروني والتذاكر والفوترة والتقارير. ابدأ خلال دقائق بحزمة @riyadah/nabaa الرسمية.

عنوان القاعدة

https://api.nabaa.riyadah.cloud

المصادقة (ترويسات)

X-API-Key: <key>X-API-Secret: <secret>

المصادقة

كل طلبات الواجهة البرمجية تُصادَق عبر مفتاح ومفتاح سرّي يُمرّران في ترويسات HTTP. أنشئ بيانات اعتمادك من لوحة التحكّم، ثم أرفقها مع كل طلب. لا تكشف X-API-Secret في كود يعمل على المتصفّح — استخدم الواجهة البرمجية من الخادم فقط.

curl

curl https://api.nabaa.riyadah.cloud/api/sms/send \
  -H "X-API-Key: $NABAA_API_KEY" \
  -H "X-API-Secret: $NABAA_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "9665XXXXXXXX", "message": "مرحبا" }'

البدء السريع مع الحزمة (SDK)

حزمة @riyadah/nabaa الرسمية لـ TypeScript تغلّف كل الأسطح خلف عميل واحد بإكمال تلقائي كامل وأنواع آمنة. ثبّتها عبر مدير الحزم المفضّل لديك:

terminal

npm install @riyadah/nabaa

example.ts

import { Nabaa } from '@riyadah/nabaa';

// One client for every Nabaa surface — same credentials.
const nabaa = new Nabaa({
  apiKey: process.env.NABAA_API_KEY!,
  apiSecret: process.env.NABAA_API_SECRET!,
  baseUrl: 'https://api.nabaa.riyadah.cloud/api',
});

// Send an SMS
await nabaa.sms.send({ phone: '9665XXXXXXXX', message: 'مرحباً بك في نبأ' });

// Send a pre-approved WhatsApp template
await nabaa.whatsapp.sendTemplate({
  phone: '9665XXXXXXXX',
  templateName: 'invoice_payment',
  params: ['INV-1024', '250 SAR'],
});

// Ask a report question in natural language
const report = await nabaa.reports.nlQuery({
  question: 'كم عدد التذاكر المفتوحة حسب الأولوية؟',
});

تتوفّر أيضاً عملاء منفصلون لكل سطح (NabaaSms، NabaaWhatsApp، NabaaEmail، NabaaBilling …) من أجل التهيئة الأخفّ (tree-shaking).

كتالوج النقاط الطرفية

مجموعة مختارة من أكثر النقاط استخداماً، مجمّعة حسب المجال. للاطّلاع على القائمة الكاملة مع المخطّطات والتجربة المباشرة، افتح المرجع التفاعلي.

الرسائل النصية (SMS)

إرسال رسالة مفردة أو كلمة مرور لمرة واحدة (OTP) أو حملة جماعية، وقراءة السجلّات.

POST
/api/sms/sendإرسال رسالة نصية واحدة
POST
/api/sms/otpإرسال رمز تحقّق (OTP) عبر قالب
POST
/api/sms/bulkجدولة حملة رسائل جماعية
GET
/api/sms/logsسجلّات الرسائل النصية

واتساب للأعمال

رسائل القوالب المعتمدة من Meta، والرسائل النصية ضمن نافذة 24 ساعة، والحملات الجماعية.

POST
/api/whatsapp/sendإرسال رسالة بقالب معتمد
POST
/api/whatsapp/textرسالة نصية ضمن نافذة الجلسة
POST
/api/whatsapp/invoiceقالب فاتورة جاهز
POST
/api/whatsapp/reminderقالب تذكير عام
POST
/api/whatsapp/bulkحملة قوالب جماعية
GET
/api/whatsapp/templatesالقوالب المعتمدة المتاحة
GET
/api/whatsapp/logsسجلّات واتساب

البريد الإلكتروني

إرسال بريد مفرد أو دفعة حتى 500 رسالة، وقراءة سجلّات التسليم.

POST
/api/mail/sendإرسال بريد إلكتروني واحد
POST
/api/mail/send-bulkإرسال دفعة (حتى 500 رسالة)
GET
/api/mail/logsسجلّات البريد
GET
/api/mail/suppressionsقائمة الحظر (suppressions)

التذاكر

إدارة التذاكر والرسائل وتتبّع الوقت والربط بالمكالمات والحوادث الجماعية.

GET
/api/ticketsقائمة التذاكر مع الفلترة
POST
/api/ticketsإنشاء تذكرة جديدة
GET
/api/tickets/:idتفاصيل تذكرة
PATCH
/api/tickets/:idتحديث تذكرة
POST
/api/tickets/:id/messagesإضافة رسالة إلى التذكرة
POST
/api/tickets/:id/time-entriesتسجيل وقت على التذكرة

الفوترة

الخطط والاشتراك والمحفظة والاستهلاك المقنّن والفواتير.

GET
/api/billing/plansكتالوج الخطط العامّة
GET
/api/billing/me/subscriptionاشتراكك الحالي
POST
/api/billing/me/subscription/changeتغيير الخطة
GET
/api/billing/me/walletرصيد المحفظة
POST
/api/billing/me/usageتسجيل استهلاك مقنّن
GET
/api/billing/me/invoicesفواتيرك

الحقول المخصّصة

تعريفات الحقول المخصّصة لكل كيان، وقراءة وكتابة قيمها لكل سجلّ.

GET
/api/custom-fields/defs/:clientId/:entityتعريفات الحقول لكيان
POST
/api/custom-fields/defs/:clientId/:entityإنشاء تعريف حقل
GET
/api/custom-fields/values/:entity/:recordIdقيم سجلّ
PUT
/api/custom-fields/values/:entity/:recordIdتحديث قيم سجلّ

التقارير

استعلامات بلغة طبيعية، وتقارير منظّمة، وحفظ التقارير وإدارتها.

POST
/api/reports/nl-queryسؤال بلغة طبيعية
POST
/api/reports/queryاستعلام تقرير منظّم
POST
/api/reportsحفظ تقرير
GET
/api/reportsقائمة التقارير المحفوظة

الخط الزمني (Contact 360)

عرض موحّد لكل تفاعلات جهة الاتصال عبر القنوات.

GET
/api/timeline/contacts/:contactIdالخط الزمني الموحّد لجهة اتصال

إدارة خدمات تقنية المعلومات (ITSM)

الحوادث وطلبات التغيير (مع الموافقات) وسجلّ الأصول (CMDB).

GET
/api/itsm/incidentsقائمة الحوادث
POST
/api/itsm/incidentsإنشاء حادث
GET
/api/itsm/changesقائمة طلبات التغيير
POST
/api/itsm/changes/:id/approveاعتماد طلب تغيير
GET
/api/itsm/assetsسجلّ الأصول (CMDB)

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

تُوقَّع أحداث الـ webhook وفق معيار Standard Webhooks (متوافق مع Svix). يحمل كل طلب الترويسات webhook-id وwebhook-timestamp وwebhook-signature. تحقّق دائماً من التوقيع باستخدام جسم الطلب الخام (raw body) قبل معالجته — لا تُعد تسلسل JSON المُحلَّل.

توقيع HMAC-SHA256 على {id}.{timestamp}.{body} مع نافذة سماح زمنية ±5 دقائق لمنع إعادة التشغيل، ودعم تدوير المفاتيح بلا توقّف.

verify-webhook.ts

import { verifyWebhook } from '@riyadah/nabaa/webhooks';

// In your raw-body webhook handler:
const event = verifyWebhook(rawBody, req.headers, endpointSecret);
// throws WebhookVerificationError on a bad signature / replay
console.log(event.type, event.id);

جرّب الواجهة البرمجية مباشرة

استكشف كل النقاط الطرفية مع المخطّطات وأرسل طلبات حقيقية من المتصفّح.