Bizaldo Documentation
Bizaldo

مفاتيح واجهة برمجة التطبيقات وسجلات الويب

تتيح لك مفاتيح واجهة برمجة التطبيقات (API Keys) وسجلات الويب (Webhooks) ربط بيزالدو بالأنظمة الخارجية لمزامنة تخطيط موارد المؤسسات (ERP)، أو لوحات التحكم المخصصة، أو أتمتة المخزون، أو الأدوات الداخلية دون مشاركة بيانات اعتماد تسجيل دخول الموظفين.
أين تجدها: في شريط التنقل الجانبي للوحة تحكم بيزالدو، افتح الإعدادات. استخدم علامة تبويب مفاتيح واجهة برمجة التطبيقات لإنشاء المفاتيح وعلامة تبويب سجلات الويب لتسجيل نقاط النهاية. يعرض قسم عام في أعلى الإعدادات معرّف الشركة الحالي ومعرّف الفرع، واللذين تحتاجهما العديد من التكاملات بجانب المفتاح.

من يمكنه إدارة التكاملات

فقط المستخدمون الذين لديهم دور مسؤول (Admin) أو مسؤول خارق (Super Admin) يمكنهم رؤية علامات تبويب مفاتيح واجهة برمجة التطبيقات وسجلات الويب. الأدوار الأخرى (مدير، كاشير، موظف) يمكنهم استخدام الإعدادات للملف الشخصي وخيارات صفحة الطلب ولكن لا يمكنهم إنشاء أو إبطال المفاتيح.

الشركة والفرع

يتم إنشاء مفاتيح واجهة برمجة التطبيقات وسجلات الويب للـشركة والـفرع المحددين في رأس لوحة التحكم في وقت إنشائهما. حدد الشركة والفرع الصحيحين قبل إنشاء بيانات الاعتماد. انسخ معرّف الشركة ومعرّف الفرع من الإعدادات ← عام عند تهيئة التكامل الخاص بك.
صفحة مفاتيح واجهة برمجة تطبيقات الإعدادات مع سياق الشركة والفرع12345

الشكل 1 — علامة تبويب مفاتيح واجهة برمجة تطبيقات الإعدادات مع معرّفات الشركة والفرع

عناصر الشاشة

1
علامة تبويب مفاتيح واجهة برمجة التطبيقات

افتح الإعدادات وحدد مفاتيح واجهة برمجة التطبيقات لإدارة بيانات اعتماد التكامل.

2
معرّف الشركة

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

3
معرّف الفرع

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

4
إنشاء مفتاح واجهة برمجة تطبيق

بدء تدفق إنشاء المفاتيح.

5
إحصاءات الاستخدام

إجمالي المفاتيح، المفاتيح النشطة، إجمالي الطلبات، والطلبات اليوم.

مفاتيح واجهة برمجة التطبيقات

ما يحتويه مفتاح واجهة برمجة التطبيقات

يحتوي كل مفتاح واجهة برمجة تطبيقات على:
الحقلالوصف
الاسمتسمية مقروءة للبشر (3 أحرف كحد أدنى)، مثل `Production ERP`
الوصفملاحظة اختيارية حول ما يفعله التكامل
المفتاح العامالمعرّف الذي يمكنك الرجوع إليه في السجلات؛ مرئي دائماً في لوحة التحكم
المفتاح السريبيان الاعتماد المستخدم للمصادقة على طلبات واجهة برمجة التطبيقات؛ مخفي افتراضياً، كشفه بأيقونة العين
الأذوناتنطاقات دقيقة (انظر أدناه)
إحصاءات الاستخدامإجمالي الطلبات وطابع آخر استخدام زمني
تعرض لوحة التحكم إحصاءات مجمعة: إجمالي المفاتيح، المفاتيح النشطة، إجمالي الطلبات، والطلبات اليوم.

إنشاء مفتاح واجهة برمجة تطبيقات

  1. قم بتسجيل الدخول باستخدام حساب مسؤول أو مسؤول خارق.
  2. حدد الشركة والـفرع الصحيحين في رأس لوحة التحكم.
  3. انتقل إلى الإعدادات ← مفاتيح واجهة برمجة التطبيقات.
  4. انقر فوق إنشاء مفتاح واجهة برمجة التطبيقات.
  5. أدخل اسماً (3 أحرف على الأقل) ووصفاً اختيارياً.
  6. حدد الأذونات. امنح فقط ما يحتاجه التكامل (الحد الأدنى من الامتيازات).
  7. انقر فوق إنشاء مفتاح.
  8. انسخ المفتاح العام والمفتاح السري على الفور. قم بتخزين السر في مدير كلمات المرور أو متغير البيئة (مثل `BIZALDO_API_SECRET`). لا تقم أبداً بوضع الأسرار في نظام التحكم في الإصدارات أو تضمينها في التعليمات البرمجية من جانب العميل.
نموذج إنشاء مفتاح واجهة برمجة التطبيقات مع الاسم والوصف والأذونات1234

الشكل 2 — إنشاء مفتاح واجهة برمجة التطبيقات: الاسم والوصف ونطاقات الأذونات

عناصر الشاشة

1
اسم المفتاح

التسمية المطلوبة للمفتاح (3 أحرف كحد أدنى).

2
الوصف

ملاحظة اختيارية تصف ما يفعله هذا التكامل.

3
الأذونات

حدد النطاقات حسب مجموعة الكيانات. امنح فقط ما يحتاجه التكامل.

4
إنشاء المفتاح

توليد زوج المفتاح العام والسري.

الأذونات المتاحة

يتم تجميع الأذونات حسب الكيان. قم بتبديل مجموعة بأكملها أو نطاقات فردية:
الكيانالأذونات
المنتجاتعرض، إنشاء، تحديث، حذف، إدارة المخزون، إدارة الأسعار
الفئاتعرض، إنشاء، تحديث، حذف، إدارة التسلسل الهرمي
الطلباتعرض، إنشاء، تحديث، حذف، إدارة الحالة، معالجة المدفوعات، إدارة المبالغ المستردة
الطاولات *(للمطاعم فقط)*عرض، إنشاء، تحديث، حذف، إدارة الحجوزات، إدارة الحالة
الحجوزات *(للمطاعم فقط)*عرض، إنشاء، تحديث، حذف
العميلعرض، إنشاء
المكافآتعرض، إنشاء، تحديث، حذف، إدارة النقاط، إدارة عمليات الاسترداد
المستخدمونعرض، إنشاء، تحديث، حذف، إدارة الأدوار، إدارة الوصول
المخزونعرض
التقارير والتحليلاتعرض، تصدير، إنشاء تقارير مخصصة، إدارة التقارير المجدولة
إعدادات النظامعرض، تحديث، إدارة التكاملات، إدارة مفاتيح واجهة برمجة التطبيقات
ترى شركات المطاعم أيضاً مجموعات أذونات الطاولات والحجوزات. شركات التجزئة والصناعات الأخرى لا تراها.

استخدام مفتاح واجهة برمجة التطبيقات

أرسل الطلبات من خادم إلى خادم إلى خادم واجهة برمجة تطبيقات بيزالدو المفتوح (Bizaldo Open API server) باستخدام مفتاحك السري: 
GET /api/v1/products HTTP/1.1
Host: openapi.bizaldo.com
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json
قم بتضمين الشركة والفرع من اختيار لوحة التحكم الخاصة بك: 
x-company-id: YOUR_COMPANY_ID
x-branch-id: YOUR_BRANCH_ID
حالات الاستخدام الشائعة:
  • مزامنة الكتالوج: سحب أو دفع المنتجات والفئات
  • أتمتة المخزون: التفاعل مع تغييرات مستويات المخزون
  • التقارير المخصصة: بناء تقارير من بيانات فرعك
  • التصدير الليلي: سحب الطلبات المكتملة إلى أدوات المحاسبة

إدارة المفاتيح الحالية

الإجراءالأثر
نسخ العام / السرياستخدم أيقونة النسخ بجانب كل حقل مفتاح
إظهار / إخفاء السرأيقونة العين تبدل الرؤية
إعادة توليد السريولد سراً جديداً؛ يتوقف القديم عن العمل على الفور. قم بتحديث تكاملك قبل إبطال السر القديم.
تعطيليصبح المفتاح غير نشط؛ تفشل مكالمات واجهة برمجة التطبيقات بهذا السر
تنشيطإعادة تفعيل مفتاح تم تعطيله سابقاً
إظهار المفاتيح المعطلةتبديل لسرد المفاتيح غير النشطة للتدقيق

تدوير المفاتيح بأمان

قم بإنشاء مفتاح جديد، وانشر السر الجديد لتكاملك، وتأكد من نجاح زيارات الشبكة، ثم قم بتعطيل أو إعادة توليد المفتاح القديم. إعادة التوليد فورية. لا توجد فترة سماح.

خطافات الويب (Webhooks)

تدفع خطافات الويب إشعارات HTTP إلى خادمك عند حدوث أحداث بيزالدو، بحيث لا تحتاج إلى استطلاع واجهة برمجة التطبيقات.

الأحداث المدعومة

تتيح لك لوحة التحكم الاشتراك في أنواع الأحداث هذه (نفس المجموعة للمطاعم والتجزئة والصناعات الافتراضية):
الحدثمتى يتم إطلاقه
product.createdيتم إضافة منتج جديد
product.updatedيتم تغيير تفاصيل المنتج
product.deletedيتم إزالة منتج
product.stock_updatedتتغير مستويات المخزون
category.createdيتم إضافة فئة جديدة
category.updatedيتم تغيير تفاصيل الفئة
category.deletedيتم إزالة فئة
حدد حدثاً واحداً أو أكثر عند تسجيل أو تحرير خطاف ويب. مطلوب حدث واحد على الأقل.

تسجيل خطاف الويب

  1. حدد الشركة والـفرع الصحيحين في رأس لوحة التحكم.
  2. انتقل إلى الإعدادات ← خطافات الويب.
  3. انقر فوق تسجيل خطاف الويب.
  4. املا النموذج:
الحقلمطلوبملاحظات
عنوان نقطة النهاية (Endpoint URL)نعمعنوان HTTPS عام، مثل `https://your-server.com/webhooks/bizaldo`
الوصفلايساعد في تحديد نقطة النهاية لاحقاً
مفتاح واجهة برمجة التطبيقات (API Key)سلسلة السر التي اخترتها للتحقق من الحمولات الواردة. عند التعديل، اتركها فارغة للاحتفاظ بالمفتاح الحالي.
الأحداثنعمواحد أو أكثر من الجدول أعلاه
  1. انقر فوق تسجيل خطاف الويب.
صفحة إعدادات خطافات الويب مع نموذج تسجيل خطاف ويب جديد12345

الشكل 3 — تسجيل نقطة نهاية خطاف ويب والاشتراك في الأحداث

عناصر الشاشة

1
علامة تبويب خطافات الويب

التبديل من مفاتيح واجهة برمجة التطبيقات إلى خطافات الويب في الإعدادات.

2
الشركة والفرع

سياق الشركة والفرع الحالي لخطاف الويب الجاري تسجيله.

3
عنوان نقطة النهاية

عنوان HTTPS عام يتلقى طلبات POST للحدث.

4
مفتاح واجهة برمجة التطبيقات

سلسلة سريعة تستخدم للتحقق من حمولات خطاف الويب الواردة.

5
الاشتراك في الأحداث

اختر نوع حدث واحد أو أكثر لتلقيه.

بعد التسجيل، يعرض بيزالدو سر توقيع في لافتة صفراء: "مفتاح واجهة برمجة التطبيقات - احفظ هذا الآن!" تظهر هذه القيمة مرة واحدة فقط. انسخها قبل إغلاق اللافتة.
استخدم هذا السر للتحقق من ترويسة `X-Bizaldo-Signature` في كل طلب خطاف ويب وارد.

التحقق من تواقيع خطافات الويب

يتضمن كل تسليم ترويسة `X-Bizaldo-Signature`. احسب HMAC لـجسم الطلب الخام باستخدام سر التوقيع الخاص بك وقارنه بقيمة الترويسة. ارفض الطلبات التي لا تتطابق. يجب أن تقوم نقطة النهاية الخاصة بك بـ:
  • الاستجابة بـ 2xx في غضون ثوانٍ قليلة
  • تكون إيجابية التأثير (Idempotent). قد يتم تسليم نفس الحدث أكثر من مرة؛ قم بإلغاء التكرار باستخدام معرّف الحدث إذا تم توفيره في الحمولة
  • استخدام HTTPS في الإنتاج

إدارة خطافات الويب

تعرض قائمة خطافات الويب المسجلة كل نقطة نهاية مع:
  • العنوان والوصف
  • الأحداث المشترك فيها
  • الحالة نشط / غير نشط
  • تاريخ الإنشاء
الإجراءات لكل خطاف ويب:
الإجراءالوصف
تعديلتغيير العنوان، الوصف، الأحداث، أو مفتاح واجهة برمجة التطبيقات
سجل التسليمعرض آخر 100 محاولة تسليم (اسم الحدث، حالة HTTP، رقم المحاولة، الطابع الزمني)
حذفيزيل خطاف الويب وسجل تسليمه؛ ويتوقف إرسال الأحداث

التطوير المحلي

للاختبار المحلي، اعرض جهازك باستخدام نفق (ngrok، Cloudflare Tunnel، إلخ.) وسجل عنوان HTTPS للنفق كنقطة نهاية لخطاف الويب. استخدم سجل التسليم في لوحة التحكم لتصحيح المحاولات الفاشلة.

أفضل ممارسات الأمان

  • إصدار مفاتيح منفصلة لكل بيئة (التجريبية مقابل الإنتاجية) ولكل تكامل.
  • تطبيق أذونات الحد الأدنى من الامتيازات. لا تحتاج مزامنة الكتالوج للقراءة فقط إلى أذونات `orders:delete`.
  • تقييد عناوين URL لخطافات الويب لتكون HTTPS والتحقق من ترويسة `X-Bizaldo-Signature` في كل طلب.
  • لا تعرض أسرار واجهة برمجة التطبيقات في متصفح JavaScript أو تطبيقات الأجهزة المحمولة أو المستودعات العامة.
  • تمكين المصادقة ثنائية العامل على حسابات المسؤول التي يمكنها إدارة المفاتيح.
  • إذا تم الكشف عن سر، قم بـإعادة توليد أو تعطيل المفتاح فوراً ومراجعة إحصاءات الاستخدام الأخيرة.

الوثائق ذات الصلة

الوثائق ذات الصلة

إدارة الطلبات

دليل كامل لإدارة الطلبات طوال دورة حياتها.

إعدادات الشركة

تكوين خيارات الدفع والائتمان، والدفع اللاحق (BNPL)، وحارس الائتمان، وفواتير الاشتراك للشركة المحددة.

نظرة عامة على منصة بيزالدو

مقدمة لنظام بيزالدو لإدارة نقاط البيع وقدراته الأساسية.

الأسئلة الشائعة

أسئلة وإجابات شائعة حول بيزالدو.

السابقإدارة الطلباتالتالينظرة عامة على لوحة التحكم