ربط الاستبيانات
عملاؤك يجيبون استبيانات مشروعك من داخل تطبيقك وموقعك بحساباتهم عندك، وفريقك يتابع النتائج من لوحة الاستبيانات، ويعرف سيرفرك كل ردّ لحظة وصوله. أو شارك رابط الاستبيان العام دون أي ربط.
العناوين
- واجهة API
https://api-survey.alhawsaba.com/api - لوحة الاستبيانات
https://survey.alhawsaba.com
المفاتيح
- مفتاح المشروعيسمّي مشروعك في كل توكن.
project_key - سر التوقيع (JWT)يوقّع به سيرفرك توكنات الناس.
jwt_secret - مفتاح APIيصل مع إشعار كل ردّ إلى سيرفرك لتتحقق منه، وترسله مع تحديثات الناس.
api_key - سر الإشعاراتتتحقق به من توقيع كل إشعار (X-Webhook-Signature).
webhook_secret
تظهر المفاتيح مرة واحدة عند إضافة الخدمة إلى المشروع، وتجدها بعد ذلك داخل الخدمة في إعدادات المشروع.
توكن الشخص
سيرفرك يوقّع توكن 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' })
}تطبيقك وموقعك
اطلب التوكن من سيرفرك
للعميل المسجّل. لا تضع سر التوقيع في التطبيق.
الاستبيانات والإجابة
كلها بالترويسة 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 لاختيار واحد.
- GET