كل أدلة الربط

ربط الاستبيانات

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

العناوين

  • واجهة APIhttps://api-survey.alhawsaba.com/api
  • لوحة الاستبياناتhttps://survey.alhawsaba.com

المفاتيح

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

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

توكن الشخص

سيرفرك يوقّع توكن JWT بخوارزمية HS256 وسر توقيع مشروعك. رقم الشخص في user_id أو sub.

الحقلمطلوبالمعنى
project_keyنعممفتاح مشروعك.
user_id (أو sub)نعمرقم الشخص عندك.
roleيُفضَّلuser للعميل (الافتراضي)، admin لموظفك.
name, email, phone, image_pathيُفضَّلبطاقة الشخص.
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' = customer, 'admin' = staff
    name: user.name,
    email: user.email,
  }, process.env.ALHAWSABA_JWT_SECRET, { algorithm: 'HS256', expiresIn: '7d' })
}

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

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

    للعميل المسجّل. لا تضع سر التوقيع في التطبيق.

  2. الاستبيانات والإجابة

    كلها بالترويسة Authorization: Bearer {JWT}. تظهر للعميل الاستبيانات المفتوحة في مشروعك التي يحق له الإجابة عنها، ومع كل واحد هل أجاب عنه.

    • GET/api/integration/meالشخص الحالي.
    • GET/api/integration/surveysالاستبيانات المفتوحة له، و answered لكل واحد.
    • GET/api/integration/surveys/{id}الاستبيان وأسئلته وخياراتها.
    • POST/api/integration/surveys/{id}/respondإرسال الإجابات.
    • GET/api/integration/surveys/{id}/my-responseإجابته السابقة.
    جسم الإجابة
    {
      "answers": {
        "12": { "text": "Fast delivery" },
        "13": { "numeric": 5 },
        "14": { "option_id": 31 }
      }
    }

    المفتاح في answers رقم السؤال: text للأسئلة النصية، numeric للتقييم والأرقام، option_id لاختيار واحد.