دليل لوحتك

ما هي اللوحة

لوحة دعم متعددة العلامات التجارية: أنت تخدم عملاءك أنت، تحت علامتك أنت، على بنيتنا التحتية نحن.

لوحة الدعم هي قائمة انتظار واحدة لحالات عمليتك: يفتح عملاؤك الحالات من موقعك (الودجات) أو عبر API أو بالبريد الإلكتروني، ويتولاها فريقك من لوحة تحكم خاصة على dash.elportaldelcliente.com. كل حالة تدخل وتتقدّم وتتصعّد دون أن يكون أحد مستيقظًا — لكنها لا تُغلق دون اسم يقف خلفها.

لوحتك مستأجر معزول: حالاتك وعملاؤك النهائيون ووكلاؤك لا يختلطون بأحد سواك. العزل جزء من تصميم النظام، لا إعداد يمكن نسيانه. إن لمس فريقنا حالة من حالاتك بصفته دعمًا من المستوى الأخير، يُسجَّل الوصول ويمكنك الاطلاع عليه.

دليل البدء

من الصفر إلى التشغيل، في خمس خطوات.

1. أنشئ حسابك على dash.elportaldelcliente.com.
2. فعّل خطة. تُدفع من رصيد حسابك (المحفظة نفسها للمنظومة كلها)؛ وإن نقصك رصيد، تعرض عليك الشاشة شحن المبلغ الناقص بالضبط.
3. ادعُ وكلاءك من تبويب «الوكلاء»: البريد الإلكتروني والدور (وكيل أو مدير). ستتلقى رابط دخول لتسليمه لهم.
4. شغّل ودجة من «الودجات وAPI»: سجّل نطاق موقعك كمصدر مصرّح به، وانسخ السكربت وألصقه في موقعك.
5. هل تتكامل برمجيًا؟ أصدر بيانات اعتمادك tab_live_ من التبويب نفسه واتبع مرجع API في هذه الصفحة.

لوحة التحكم

لوحة تحكم المستأجر على dash.elportaldelcliente.com، تبويبًا تبويبًا.

الوكلاء الذين تدعوهم يرون حالات لوحتك ويتولونها؛ ويدير المديرون فوق ذلك الاشتراك والفريق والتكاملات.

ودجات لموقعك

ثلاث ودجات، سطر سكربت واحد لكل منها. بلا iframes من أطراف ثالثة، وبلا ملفات تعريف ارتباط للتتبع.

من تبويب «الودجات وAPI» في لوحة تحكمك: شغّل الودجة، وسجّل نطاق موقعك كمصدر مصرّح به وانسخ السكربت المولَّد. تقبل المعلمة data-color لون علامتك التجارية.

<script src="https://api.elportaldelcliente.com/api/tablero/widget/tablero.js"
        data-tenant="su-tablero" data-widget="contacto" data-color="#a177ff"></script>

حماية الودجات

تقبل الودجات المجهولة 10 محاولات لكل زائر (IP) كل 10 دقائق لكل لوحة. إذا كانت الودجة مطفأة، أو المصدر غير مصرّح به، أو الاشتراك منتهيًا، ترد الودجة بـ 404 widget no disponible — بشكل متعمد لا يمكن تمييزه، حتى لا تنكشف إعدادات لوحتك.

ودجة «اللوحة»: التعرف على عميلك

تعرض ودجة اللوحة لكل عميل نهائي حالاته هو فقط. لذلك يستبدل خادمك رمزًا مؤقتًا لكل عميل: استدعِ POST /v1/clientes/:ref/token-widget ببيانات اعتماد API (من جانب الخادم، وليس من المتصفح أبدًا) وسلّم الرمز إلى الودجة.

curl -X POST https://api.elportaldelcliente.com/api/tablero/v1/clientes/cli-842/token-widget \
  -H "Authorization: Bearer $TABLERO_KEY"

HTTP/1.1 201
{"success":true,"data":{"token":"tabw_…","expires_at":"2026-08-18 21:15:00"}}

window.TableroPortal.setToken(token);

بيانات اعتماد API

بيانات اعتماد Bearer واحدة لكل تكامل، بنطاق مقيّد وقابلة للإلغاء.

تُصدر بيانات الاعتماد من لوحة تحكمك («الودجات وAPI» ← «بيانات اعتماد API»). لها الشكل tab_live_… وتُعرض مرة واحدة فقط: احفظها في مدير أسرارك. نحن لا نخزّن سوى الـ hash الخاص بها.

curl -H "Authorization: Bearer tab_live_…" \
  https://api.elportaldelcliente.com/api/tablero/v1/

عند إصدارها يمكنك تقييد نطاقاتها (scopes). بيانات اعتماد بلا نطاقات صريحة تصل إلى لوحتك كاملة:

• بحد أقصى 5 بيانات اعتماد نشطة لكل لوحة. ألغِ ما لم تعد تستخدمه.
• بيانات الاعتماد تحدد هوية لوحتك: لا ترسل أبدًا tenant_id في المتن — ترفضه الواجهة بالرمز 400.
• مع اشتراك منتهٍ تواصل بيانات الاعتماد القراءة (GET)؛ وكل كتابة ترد بـ 402 suscripcion_vencida.
• بيانات الاعتماد الملغاة ترد بـ 401 فورًا على جميع المسارات.

مرجع API

REST فوق HTTPS، وJSON في الاتجاهين، وردود بالشكل {success, data}.

الاصطلاحات: المتون تُرسل بـ Content-Type: application/json؛ والتواريخ UTC بصيغة YYYY-MM-DD HH:MM:SS؛ والقوائم المقسّمة إلى صفحات تعيد total وpage وlimit. ما ليس لك يرد بـ 404، وليس 403 أبدًا: الواجهة لا تؤكد وجود موارد الغير.

https://api.elportaldelcliente.com/api/tablero/v1

الجذر: الهوية والخطة والاستخدام

GET / هو العقد الذي لا يستطيع الكذب: يعيد من أنت، وما نطاقات بيانات الاعتماد هذه، وخطتك بحدودها، ووضع اشتراكك، وكم استهلكت.

curl -H "Authorization: Bearer $TABLERO_KEY" \
  https://api.elportaldelcliente.com/api/tablero/v1/

{"success":true,"data":{
  "tenant":{"slug":"su-tablero","nombre":"Su Marca"},
  "scopes_de_esta_credencial":["casos.read","casos.write"],
  "plan":{"id":"tablero-base","nombre":"BASE","limites":{"max_agentes":5,"max_departamentos":5,"max_articulos_kb":100}},
  "suscripcion":{"estado":"active","current_period_end":"2027-08-18"},
  "uso":{"agentes":3,"departamentos":2},
  "recursos":["/casos","/clientes","/departamentos","/accesos","/webhooks"],
  "version":"v1"}}

العملاء النهائيون

العميل النهائي هو عميل لك أنت (وليس حسابًا في منظومتنا). يُعرَّف بـ external_ref: المعرّف الذي يحمله ذلك العميل في نظامك أنت.

curl -X POST https://api.elportaldelcliente.com/api/tablero/v1/clientes \
  -H "Authorization: Bearer $TABLERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref":"cli-842","email":"[email protected]","name":"Maria Rojas"}'

الحالات

المورد المركزي. للحالة وضع وأولوية وعميل نهائي اختياري ومحادثة من الردود. الملاحظات الداخلية للوكلاء لا تُكشف أبدًا عبر API.

إنشاء حالة مرتبطة بعميل نهائي:

curl -X POST https://api.elportaldelcliente.com/api/tablero/v1/casos \
  -H "Authorization: Bearer $TABLERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"No puedo entrar al panel","cliente_ref":"cli-842","priority":"high",
       "body":"Al iniciar sesion la pagina queda en blanco."}'

HTTP/1.1 201
{"success":true,"data":{"id":"…","numero":"SOLC-1051"}}

السرد بمرشحات، والمزامنة التزايدية عبر updated_since (ISO 8601): في هذا الوضع يكون الترتيب حسب updated_at تصاعديًا، وهو مصمم للتقدم صفحة صفحة دون فقدان تغييرات. احفظ أعلى updated_at عالجته واستخدمه مؤشرًا للجولة التالية.

curl -H "Authorization: Bearer $TABLERO_KEY" \
  "https://api.elportaldelcliente.com/api/tablero/v1/casos?estado=open&cliente=cli-842&limit=50&page=1"

# مزامنة تزايدية (الترتيب: updated_at تصاعديًا)
curl -H "Authorization: Bearer $TABLERO_KEY" \
  "https://api.elportaldelcliente.com/api/tablero/v1/casos?updated_since=2026-08-18T00:00:00Z&limit=100"

الرد على حالة. دون en_nombre_de يوقَّع الرد باسم فريقك (author_type: agent)؛ ومع en_nombre_de يوقَّع باسم ذلك العميل النهائي (author_type: client):

curl -X POST https://api.elportaldelcliente.com/api/tablero/v1/casos/$CASO_ID/respuestas \
  -H "Authorization: Bearer $TABLERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Ya lo revisamos: intente de nuevo.","autor_nombre":"Soporte Acme"}'

# ...أو باسم العميل النهائي:
  -d '{"body":"Sigue igual desde mi lado.","en_nombre_de":"cli-842"}'

الأقسام

قوائم انتظار داخلية للوحتك (مبيعات، فوترة، دعم تقني…). يمكن لكل قسم أن يملك صندوق بريد IMAP خاصًا به: تستطلعه اللوحة وتحوّل الرسائل الواردة إلى حالات.

الصندوق يتحدث IMAP دائمًا (email_protocol: imap)؛ كلمة المرور تُشفَّر في حال السكون ولا تُعاد أبدًا. مع email_polling_enabled: 1 يجري الاستطلاع تلقائيًا.

تدقيق الوصول

كل وصول من فريقنا إلى حالات لوحتك يُسجَّل. هذا هو سجل التدقيق نفسه الموجود في تبويب «وصول المزوّد»، قابلًا للقراءة عبر API:

curl -H "Authorization: Bearer $TABLERO_KEY" \
  https://api.elportaldelcliente.com/api/tablero/v1/accesos

Webhooks

نظامك يعلم في اللحظة نفسها: كل حدث يُرسل موقَّعًا إلى عنوان HTTPS الخاص بك.

سجّل ما تحتاجه عبر POST /webhooks: عنوان https، والأحداث التي تريدها، وسر من 16 حرفًا على الأقل نوقّع به كل تسليم.

curl -X POST https://api.elportaldelcliente.com/api/tablero/v1/webhooks \
  -H "Authorization: Bearer $TABLERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://su-sistema.com/hooks/tablero",
       "eventos":["caso.creado","caso.respondido","caso.estado_cambiado"],
       "secret":"un-secreto-de-al-menos-16-caracteres"}'

كل تسليم هو POST يحمل الحدث ولحظة الإصدار والحد الأدنى من البيانات للتفاعل. يغطي التوقيع timestamp.body:

POST /hooks/tablero
Content-Type: application/json
X-Tablero-Evento: caso.respondido
X-Tablero-Timestamp: 1765432100
X-Tablero-Firma: 3f1a…  # HMAC-SHA256(secret, timestamp + "." + body)

{"evento":"caso.respondido","emitido_at":"2026-08-18T20:15:00.000Z",
 "data":{"caso_id":"…","numero":"SOLC-1051","respuesta_id":"…","autor_tipo":"agent"}}

التحقق من التوقيع

ارفض كل تسليم لا يجتاز توقيعه التحقق أو يبعد طابعه الزمني أكثر من 5 دقائق عن الساعة. وقارن بوقت ثابت.

// Node.js
const crypto = require('node:crypto');

function verificarFirma(rawBody, headers, secret) {
  const ts  = headers['x-tablero-timestamp'];
  const sig = headers['x-tablero-firma'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperado = crypto.createHmac('sha256', secret)
    .update(ts + '.' + rawBody).digest('hex');
  return sig.length === esperado.length &&
    crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(sig));
}

# Python
import hashlib, hmac, time

def verificar_firma(raw_body: bytes, headers: dict, secret: str) -> bool:
    ts  = headers.get("x-tablero-timestamp", "")
    sig = headers.get("x-tablero-firma", "")
    if abs(time.time() - float(ts or 0)) > 300:
        return False
    esperado = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, sig)

دلالات التسليم (اقرأها قبل أن تثق)

• محاولة واحدة لكل حدث، دون إعادة. إن لم يرد نظامك بـ 2xx خلال 10 ثوانٍ، يضيع ذلك التسليم — الوضع الفعلي يظل قابلًا لإعادة القراءة عبر API.
• شبكة أمانك هي المزامنة التزايدية: جولة دورية على GET /casos?updated_since=… تسترد أي حدث ضائع.
• GET /webhooks يعرض fail_count وlast_ok_at وlast_error_at لكل Webhook: راجعها عند التصحيح.
• تُطلق الأحداث أيًا كانت القناة: API أو الودجات أو لوحة فريقك أو فريقنا أو البريد الوارد من عميلك النهائي.

الأخطاء

أخطاء JSON بـ success:false؛ ورمز HTTP هو الحكم.

{"success":false,"error":"…"}

رسائل error نص مقروء للبشر وقد تتغير. فرّع كودك حسب رمز HTTP وهذه المعرّفات (slugs) الثابتة:

الخطط

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

تُنشر الأسعار السارية في الصفحة الرئيسية وعبر API العامة (GET /api/public/tablero/plans). جميع الخطط تشمل حالات غير محدودة والودجات وAPI وWebhooks وتدقيق الوصول.

عند انتهاء اشتراكك توجد فترة سماح؛ بعدها تنتقل اللوحة إلى القراءة فقط (طلبات GET تظل ترد، والكتابات تعيد 402). بياناتك لا تُحذف.

الحدود التشغيلية

• الحالات: غير محدودة في جميع الخطط. تقبل القوائم limit من 1 إلى 100 لكل صفحة.
• العملاء النهائيون والتدقيق: تعيد القوائم حتى 500 صف (الأحدث أولًا). استخدم GET /clientes/:ref للقراءات المفردة.
• بيانات الاعتماد: حتى 5 نشطة لكل لوحة.
• الودجات المجهولة: 10 محاولات لكل زائر (IP) كل 10 دقائق.
• المرفقات: لا تقبل API الملفات بعد؛ مرفقات البريد الوارد تُحفظ مع الحالة.

لا تفرض الواجهة اليوم حصة صارمة للاستدعاءات؛ اعمل بإيقاع معقول (توقفات بين الصفحات، وإعادة محاولة بتراجع أُسي). إن احتاج تكامل ما إلى حجم مضمون، فلنتحدث أولًا.