​

مركز التفضيلات: صفحة التفضيل الإلكترونية العامة

النسخة الإنجليزية الأصلية: Preference center: the public opt-in/opt-out page.

​

1. كوّن مرة واحدة: POST/GET /preference-center

​

حقول التكوين

​

مواضيع الاشتراك

• name (1–120 حرفًا) — الاسم المُعروض على الصفحة.
• description (اختياري، ≤500) — سطر سياق واحد معروض بجانب المفتاح.
• defaultOptIn (افتراضي false) — كيف تُعامَل جهة اتصال بدون تفضيل مُسجَّل.
• archived (اختياري) — المواضيع المؤرشفة تبقى في مسار التدقيق لكنها لم تعد تظهر على الصفحة.

​

2. أنشئ رابطًا لكل جهة اتصال

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "cnt_01H…" }'

• الرابط يستهدف الصفحة المُستضافة، ليس نقطة النهاية JSON. انسخه حرفيًا في قوالب التذييل/المرسل؛ الصفحة نفسها تجلب نقطة النهاية البيانات في الخلفية.
• TTL 30 يومًا. بعد ذلك يتم التحقق من الرمز كمنتهي الصلاحية ويجب على جهة الاتصال طلب رابط جديد (إنشاء جديد يأخذ استدعاء API واحد).
• الصفحة لا تعرف اللغة عند الإنشاء. تطبيق الويب يُحل إعادة توجيه مع الحفاظ على استعلام ?token=، لذا لا تحتاج لتخمين لغة جهة الاتصال.

​

أين يوضع

• تذييل البريد الإلكتروني (الأساسي). أرفق الرابط المُولَّد (أو المتغير القصير المُتتبَّع الذي يستخدمه مرسلك) في منطقة إلغاء الاشتراك في قوالب التسويق.
• احتياط SMS / WhatsApp. عندما لا يحتوي الرسالة على كتلة تذييل، أرفق الرابط في السطر: {optOutMessage}: {link}. المُساعِد الذي يبني أجسام الصادرة يقبل رابطًا قصيرًا مُسبَّقًا، لذا ما زالت نقرة إلغاء الاشتراك تأخذ التَنسِيب العادي للنقر.
• إعادة اشتراك موجَّهة بالحظر. عندما تعيد جهة اتصال الاشتراك عبر تدفق آخر، يمكنك إعطاؤها رابطًا جديدًا لتأخذ نفس صفحة الخدمة الذاتية.

​

3. صفحة الرمز العامة

• GET /preferences/:token — تُعيد حمولة الصفحة.
• PUT /preferences/:token — تُطبَّق التحديثات.

​

استجابة GET

{
  "contactId": "cnt_01H…",
  "displayName": "…",
  "email": "m*****@example.com",
  "phone": "+15551****…",
  "channelPreferences": { "sms": "opted_in", "email": "opted_out" },
  "frequencyPreference": "all",
  "channels": ["sms", "email"],
  "topics": [ { "id": "newsletter", "name": "Newsletter", "defaultOptIn": false } ],
  "topicPreferences": { "newsletter": "opted_in" },
  "consentHistory": [
    { "channel": "all", "state": "opted_out", "topicId": "newsletter", "occurredAt": "2026-09-01T…" }
  ],
  "config": { /* تكوين مركز التفضيلات */ }
}

​

جسم طلب PUT

{
  "channelPreferences": {
    "sms": "opted_in",
    "email": "opted_out"
  },
  "frequencyPreference": "important_only",
  "topicPreferences": { "newsletter": "opted_in" },
  "requestDataDeletion": false
}

• channelPreferences — خريطة جزئية مسموحة (Zod سجل جزئي)؛ متطلب قناة واحدة على الأقل.
• frequencyPreference — اختياري، واحد من all, important_only, weekly_digest, monthly_digest.
• topicPreferences — خريطة { topicId: opted_in | opted_out } اختيارية مُتحقَّقة مقابل موضوعاتك المُكوَّنة؛ الـ id غير المعروفة تُتجاهَل.
• requestDataDeletion — تُعيَّن طلب حذف GDPR بجانب إلغاء الاشتراك (انظر القسم 6).

​

4. كيف تتدفق التحديثات

• دفتر الموافقة. صف consent_records واحد لكل قناة (أو لكل موضوع) يُرفَق بـ source: preference_center — مسار تدقيق عبء البراهين GDPR المادة 7.
• قائمة الحظر. على أي قناة مُلغاة الاشتراك، يُدخَل الهاتف/البريد الإلكتروني القانوني لجهة الاتصال بمجال all — حظر عبر القنوات تقرأه كل بوابة إرسال.
• سور STOP. يُوضَع سور مسار سريع Redis عند إلغاء الاشتراك (ويُمحى عند إعادة الاشتراك الكامل)، لذا تُطْلع دفعات الحملات أثناء الطيران على التغيير قبل أن تنتشر الحظر الأبطأ من قاعدة البيانات.
• سجل التدقيق. compliance.preference_center_updated يُسجَّل عند تغيير التكوين، وأحداث opt-in/out على مستوى جهة الاتصال تُلتقَط في دفتر الموافقة.

​

5. دلاليّات مفتاح حذف GDPR

​

6. اختبارها

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Logistics",
    "primaryColor": "#1d4ed8",
    "channels": ["sms", "email"],
    "headerText": "Manage how Acme contacts you",
    "topics": [
      { "id": "shipping-updates", "name": "Shipping updates", "defaultOptIn": true },
      { "id": "promotions", "name": "Promotions", "defaultOptIn": false }
    ]
  }'

LINK=$(curl -s -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"cnt_01H…"}' | jq -r '.link')

TOKEN="${LINK#*token=}"

curl -s "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" | jq

curl -s -X PUT "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelPreferences":{"sms":"opted_out"}}' | jq

​

متعلق

• حُواجز الإرسال وحُرَّاس ما قبل الإرسال — أين يعيش مُلخَّص مركز التفضيلات بجانب ساعات الصمت، الإيقاف الطارئ، والقِيود.
• إلغاء الاشتراك وقوائم الحظر — كيف يتعلق مجال all واستيراد CSV الضخم بهذا السطح.
• إدارة الموافقة — API جانب المُشغِّل الذي يُخزِّن نفس دفتر الموافقة.
• مرجع DSAR — مسار الحذف المُتتبَّع الذي تُوجَّه إليه طلبات requestDataDeletion.