دمج الخادم للخادم (Server-to-Server REST API)

تتيح لك واجهة برمجة التطبيقات (API) إرسال الموافقات مباشرة من الخادم (Backend) الخاص بك إلى نظام HashEntry بشكل آمن.

المصادقة (Authentication)

يجب أن تتضمن طلبات API رأس HTTP X-API-Key مع مفتاح API الخاص بموقعك من لوحة تحكم HashEntry.

توقيع طلبات HMAC

جميع طلبات POST يجب أن تكون موقعة بـ HMAC-SHA256 لضمان سلامة الطلب والحماية من هجمات الإعادة. يتعامل JS SDK مع هذا تلقائيًا؛ بالنسبة للتكاملات من جانب الخادم، يجب تنفيذ التوقيع يدويًا.

الترويسات المطلوبة

الترويسة	الوصف
X-API-Key	مفتاح API الخاص بموقعك
X-Signature	توقيع HMAC-SHA256 للطلب القياسي
X-Timestamp	طابع زمني Unix (ثوانٍ) — يجب أن يكون ضمن ±300 ثانية من وقت الخادم
X-Nonce	UUID فريد لكل طلب — يمنع هجمات الإعادة

خوارزمية التوقيع

1. timestamp = الطابع الزمني الحالي لـ Unix (ثوانٍ)
2. nonce = UUID عشوائي
3. bodyHash = SHA-256(جسم الطلب كسلسلة JSON)
4. canonical = "{METHOD}\n{PATH}\n{timestamp}\n{nonce}\n{bodyHash}"
5. signature = HMAC-SHA256(canonical, apiKey)

مصادقة S2S (خادم إلى خادم)

للتكاملات الخلفية الآلية، يمكنك استخدام تدفق S2S Auth الذي يجمع بين مصادقة مفتاح API ورموز JWT Bearer.

كيف يعمل

1. أنشئ عضوًا بدور api_user عبر لوحة تحكم HashEntry (الإعدادات → الفريق → دعوة)
2. يقوم مستخدم API بتسجيل الدخول عبر POST /api/v1/auth/login للحصول على رمز JWT
3. قم بتضمين كلا الترويستين في طلبات S2S:

X-API-Key: he_live_xxx
Authorization: Bearer {jwt_token}

نقاط نهاية S2S

الطريقة	نقطة النهاية	الوصف
POST	/tool/v1/s2s/consents	تسجيل موافقة فردية
POST	/tool/v1/s2s/consents/batch	تسجيل موافقات مجمعة
GET	/tool/v1/s2s/consents/export	تصدير سجلات الموافقة

ملاحظة: دور api_user مقتصر على الوصول إلى S2S API فقط — لا يُسمح بتسجيل الدخول إلى لوحة التحكم.

تسجيل الموافقة

رابط الاتصال (Endpoint): POST https://system.hashentry.com/tool/v1/consents

الترويسات المطلوبة:

Content-Type: application/json
X-API-Key: مفتاح_API_السري_الخاص_بك
X-Signature: {توقيع_hmac}
X-Timestamp: {طابع_زمني_unix}
X-Nonce: {uuid_فريد}

بيانات الإرسال (JSON Payload)

{
  "consent_type": "document_approval",
  "decision": "accept",
  "document_version_id": "سياسة-الخصوصية-رقم-النسخة"
}