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

واجهات للمطورين: نقاط نهاية عامة، وأداة الدردشة، وتسجيل الدخول، والواجهة البرمجية (REST-API) بمفتاح API.

يصف مرجع الواجهة البرمجية (API) واجهات Zentor App التي يمكنكم استدعاءها من مواقعكم وبرامجكم الخاصة: نقاط نهاية عامة للنماذج، ومُهيّئ المنتج، والمحتوى، وأداة الدردشة، وروبوت الدردشة التجريبي، إضافةً إلى تسجيل الدخول بما في ذلك تسجيل الدخول الموحد. تذكر كل صفحة نقطة نهاية الطريقة، والمسار، والمصادقة، والمعاملات، ومثالًا على الطلب والاستجابة، ورموز الخطأ الموثَّقة.

المصادقة: نقاط النهاية الخاصة بالنماذج ومُهيّئ المنتج والمحتوى متاحة دون تسجيل دخول. تتوقع نقاط نهاية أداة الدردشة رمز التضمين (embed token) الخاص بأداتكم في الترويسة `X-Widget-Token`، ولا تقبل الاستدعاءات إلا من النطاقات المعتمدة للأداة. تُصدر نقاط نهاية تسجيل الدخول لجلسات المستخدمين رمز وصول (JWT) ورمز تجديد.

الوصول إلى الواجهة البرمجية بمفتاح API: للبرامج الخاصة بكم وللاتصالات من خادم إلى خادم، تتوفر الواجهة البرمجية (REST-API) على عنوان الأساس `https://zentor-app.de/api/v1`. تُفعِّل Zentor الوصول إلى الواجهة البرمجية لحسابكم عند الطلب. ثم يُنشئ المسؤولون في لوحة التحكم تحت «مفاتيح API» مفاتيحهم الخاصة ويحدِّدون صلاحياتها (Scopes) — للمواعيد والحجوزات، وروبوت الدردشة، والتواصل، والملفات، وقاعدة المعرفة، والتقارير، وبيانات الويب. ولكل مجال صلاحية قراءة (`<المجال>.read`، فقط GET) وصلاحية كتابة (`<المجال>.write`، تشمل القراءة)، على سبيل المثال `appointments.read` أو `knowledge.write`. أرسلوا المفتاح في الترويسة `Authorization: Bearer <مفتاح API>` أو بدلًا من ذلك في الترويسة `X-API-Key`. ومع `GET /api/v1/me` تتحققون من الحساب والصلاحيات المرتبطة بمفتاح معيّن.

يُعرض المفتاح الكامل مرة واحدة فقط عند إنشائه. احفظوه بأمان وعلى جانب الخادم فقط، ولا تضعوه أبدًا في كود المتصفح أو تطبيقات الهاتف المحمول. يمكن أن تحصل المفاتيح على تاريخ انتهاء، وتُدوَّر، وتُلغى. ولا يمكن الوصول عبر الواجهة البرمجية إلا إلى الوظائف المضمَّنة في باقتكم، وتبقى جميع البيانات مقصورة على حسابكم. أخطاء نمطية: 401 `API_KEY_INVALID` أو `API_KEY_EXPIRED` أو `API_KEY_REVOKED` (المفتاح غائب أو خاطئ أو منتهي أو مُلغى)، و403 `API_ACCESS_NOT_ENABLED` (الوصول إلى الواجهة البرمجية غير مُفعَّل للحساب)، و403 `API_SCOPE_MISSING` (المفتاح يفتقر إلى الصلاحية اللازمة)، و403 `TENANT_NOT_ACTIVE` أو `TENANT_LOCKED` (الحساب غير نشط أو مُقفَل)، و404 `API_ENDPOINT_NOT_AVAILABLE` (نقطة النهاية غير متاحة عبر الواجهة البرمجية).

الاستجابات والحدود: تستجيب جميع نقاط النهاية بصيغة JSON. تحمل الاستجابة الناجحة حالة 2xx و`"ok": true`؛ وتحتوي استجابة الخطأ على رمز خطأ قابل للقراءة الآلية (في الحقل `error` أو `error.code`) ورسالة. يُسمح لكل عنوان IP بـ2,000 طلب خلال 15 دقيقة؛ وتنطبق حدود أكثر صرامة على نقاط نهاية النماذج والتأكيد وتسجيل الدخول، وهي مذكورة في الصفحة المعنية. وعند التجاوز، يستجيب الخادم بـ429 `RATE_LIMIT_EXCEEDED`. ولا ينبغي إعادة المحاولة تلقائيًا بعد انقطاع الاتصال لنقاط النهاية المُعلَّمة بأنها غير idempotent، لأن ذلك قد يُولِّد طلبات أو رسائل مكرَّرة.

لا تنقلوا كلمات المرور والرموز ومفاتيح API ورموز التأكيد إلا في نص الطلب أو في الترويسات عبر HTTPS — لا في عناوين URL أو السجلات أو طلبات الدعم.

المصادقة (5)تسجيل الدخول، وتجديد الرمز، وإعادة تعيين كلمة المرور، وإتمام SSO — والوصول إلى الواجهة البرمجية (API) عبر مفتاح API.النماذج العامة (11)التواصل، وطلب الاستشارة، وطلب الوصول، والدفع، وتفعيل الحساب.مُهيّئ المنتج (5)كتالوج الباقات، ومعاينة السعر، وتأكيد البريد الإلكتروني، وتقديم تهيئة.المحتوى العام (6)النصوص القانونية، وصفحات التسويق، والسمة، وألوان النص الخاصة بالموقع الإلكتروني.أداة الدردشة (9)جميع نقاط النهاية التي تستخدمها أداة الدردشة المُضمَّنة في موقعكم الإلكتروني.روبوت الدردشة التجريبي وSSO (13)روبوت الدردشة التجريبي العام إضافةً إلى نقاط النهاية الخاصة بتسجيل الدخول الموحد (SAML/OIDC).
← العودة إلى النظرة العامة