كل أدلة الربط

ربط التذاكر

عملاؤك يفتحون تذاكر الدعم ويتابعونها من تطبيقك وموقعك، وفريقك يعمل عليها من لوحة التذاكر بدخول من لوحة منصتك، وتصل منصتك إشعارات كل تغيير.

العناوين

  • واجهة APIhttps://api-support-ticket.alhawsaba.com/api
  • لوحة التذاكرhttps://support-tickets.alhawsaba.com

المفاتيح

  • مفتاح المشروعproject_key
    يسمّي مشروعك في كل توكن وكل نداء.
  • سر التوقيع (JWT)jwt_secret
    يوقّع به سيرفرك توكنات الناس.
  • مفتاح APIapi_key
    يصل مع إشعارات التذاكر ونداءاتها إلى سيرفرك لتتحقق منه، وترسله مع تحديثات الناس.

تظهر المفاتيح مرة واحدة عند إضافة الخدمة إلى المشروع، وتجدها بعد ذلك داخل الخدمة في إعدادات المشروع.

توكن الشخص

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

الحقلمطلوبالمعنى
project_keyنعممفتاح مشروعك.
user_id (أو sub)نعمرقم الشخص عندك.
roleنعمuser للعميل، admin لموظفك، guest لزائر دون حساب (يرى تذاكره فقط).
expنعموقت الانتهاء.
// npm i jsonwebtoken
import jwt from 'jsonwebtoken'

export function serviceToken(user, role) {
  return jwt.sign({
    project_key: process.env.ALHAWSABA_PROJECT_KEY,
    user_id: String(user.id),
    role,                      // 'user' | 'admin' | 'guest'
    name: user.name,
    email: user.email,
  }, process.env.ALHAWSABA_JWT_SECRET, { algorithm: 'HS256', expiresIn: '7d' })
}

تطبيقك وموقعك

  1. اطلب التوكن من سيرفرك

    بالدور user للعميل المسجّل، أو guest لزائر لا حساب له.

  2. التذاكر

    كلها بالترويسة Authorization: Bearer {JWT}.

    • GET/api/integration/meالشخص الحالي.
    • GET/api/integration/ticket-typesأنواع التذاكر.
    • GET/api/integration/ticket-categoriesالتصنيفات.
    • GET/api/integration/ticketsتذاكر العميل.
    • POST/api/integration/ticketsتذكرة جديدة.
    • GET/api/integration/tickets/{id}تذكرة وردودها.
    • POST/api/integration/tickets/{id}/replyرد العميل.
    • PUT/api/integration/tickets/{id}/closeإغلاق.
    • PUT/api/integration/tickets/{id}/reopenإعادة فتح.
    • POST/api/integration/tickets/{id}/rateتقييم بعد الحل.
    • POST/api/integration/tickets/{id}/attachmentsمرفقات.
    • POST/api/integration/tickets/{id}/escalation-requestطلب تصعيد.
    • POST/api/integration/filesرفع ملف.
  3. قاعدة المعرفة قبل التذكرة

    تُقرأ دون توكن بالترويسة X-Project-Key، لتعرض إجابات قبل أن يفتح العميل تذكرة.

    • GET/api/integration/kb/categoriesالأقسام.
    • GET/api/integration/kb/articlesالمقالات.
    • GET/api/integration/kb/suggestمقالات مقترحة لما يكتبه العميل.