واجهة برمجة التطبيقات والأداة

ضمِّن بحث LiKE بالذكاء الاصطناعي في تطبيقاتك أو موقعك أو أنظمتك الداخلية. ثلاث طرق للتكامل: REST API، أداة JS، iframe.

#REST API

التوفر حسب الخطة. لا تعمل واجهة API العامة والأداة العامة إلا على الخطط التي تتضمنها (انظر الخطط والفوترة). وعلى بقية الخطط لا يمكن إنشاء مفتاح أو أداة عامة، أما المُصدَرة مسبقًا فتتوقف عن الاستجابة: يتلقى الطلب بالمفتاح 403، ولا يظهر زر الأداة على الموقع. ولا تعتمد الأداة المؤسسية على هذا الإعداد.

#الخطوة 1 — إنشاء مفتاح API

1. التكاملات ← Public API ← "إنشاء مفتاح"
2. أدخِل اسمًا (على سبيل المثال، "تطبيق الجوال")
3. انسخ المفتاح — يُعرض مرة واحدة فقط

#الخطوة 2 — استخدام API

تُصرَّح جميع الطلبات عبر الترويسة:

X-API-Key: your-key

#نقاط النهاية الأساسية

#مثال: البحث بالذكاء الاصطناعي

curl -X POST https://your-account.lynkora.pro/api/public/search \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Как оформить отпуск?"}'

الاستجابة:

{
  "answer": "Для оформления отпуска...",
  "sources": [
    {"title": "Политика отпусков", "url": "..."}
  ]
}

#حدود المعدل

تُقيَّد طلبات API لكل مفتاح؛ وعند تجاوز الحد يُرجَع HTTP 429 مع ترويسة Retry-After.

#الأمان

1. خزِّن المفاتيح في متغيرات البيئة، لا في الكود
2. أنشئ مفتاحًا منفصلًا لكل تطبيق
3. احذف المفاتيح غير المستخدمة
4. قيِّد النطاقات في إعدادات المفتاح

#أداة JS

زر بحث عائم بالذكاء الاصطناعي للتضمين في أي موقع.

#الخطوة 1 — الحصول على الكود

1. التكاملات ← القنوات ← بطاقة «JS Widget» ← «إدارة الأدوات» ← «إنشاء أداة». حدّد «عنوان الموقع الذي ستوضع فيه الأداة»
2. اضبط المعاملات (انظر الجدول أدناه)
3. انسخ الكود

#الخطوة 2 — إضافته إلى موقعك

أدرِج <script> المنسوخ قبل وسم </body> الختامي:

#أين يُلصق الكود في منشئي المواقع

الكود واحد لكل المواقع، ولا حاجة إلى تعديله: فالأداة تجد مكانها في الصفحة بنفسها أينما وضع المنشئ السطر. الفرق الوحيد هو مكان اللصق.

أي موقع (HTML). ألصِق الكود قبل وسم </body> الختامي في كل صفحة تحتاج إلى البحث — أو في القالب المشترك للموقع.

WordPress. ثبّت إضافة WPCode (Insert Headers and Footers) ← Code Snippets → Header & Footer ← ألصِق الكود في Footer ← Save Changes. في WordPress.com لا تتوفر الإضافات في كل الخطط.

Tilda. للموقع كله: Site Settings → More → HTML code for the HEAD section ← ألصِق الكود ← Save ← أعد نشر كل الصفحات. لصفحة واحدة: أضف كتلة Other → T123 (HTML code) وألصِق الكود فيها.

Wix. في لوحة تحكم الموقع افتح Settings → Custom Code (بحسب إصدار الواجهة — ضمن «Advanced» أو «Development & integrations») ← Add Custom Code ← ألصِق الكود ← All pages ← Body — end ← Apply. لا تستخدم عنصر «Embed HTML» في الصفحة: فهو يُفتح داخل إطار على عنوان مختلف، ولن تعمل الأداة هناك. الكود المخصص في Wix متاح في خطة مميزة (premium) مع نطاق مربوط.

Webflow. Site settings → Custom code → Footer code ← ألصِق الكود ← Save ← انشر الموقع. الكود المخصص على مستوى الموقع متاح في خطط المواقع المدفوعة.

Squarespace. افتح Code Injection (في إعدادات الموقع؛ بحسب إصدار الواجهة — ضمن Developer tools أو Website Tools) ← ألصِق الكود في Footer ← Save. حقن الكود غير متاح في كل الخطط.

Shopify. Online Store → Themes → … → Edit code ← ملف layout/theme.liquid ← ألصِق الكود قبل </body> ← Save.

Framer. Site Settings → General → Custom Code ← ألصِق الكود في End of tag ← انشر الموقع.

Google Tag Manager. Tags → New → Custom HTML ← ألصِق الكود ← المشغّل All Pages ← Save ← Publish للحاوية.

Docusaurus. يوضع الكود في docusaurus.config.js، بالمفتاح نفسه:

scripts: [
  {
    src: 'https://your-account.lynkora.pro/api/public/widget.js',
    'data-key': 'wk_live_YOUR_KEY',
    async: true,
  },
],

عناوين الموقع. تعمل الأداة فقط على العناوين المدرجة في النطاقات المسموح بها، ويُطابَق العنوان حرفيًا: example.com وwww.example.com عنوانان مختلفان — أضف كليهما. وإذا كنت تختبر الموقع على عنوان المعاينة الخاص بالمنشئ (مثل *.tilda.ws و*.wixsite.com و*.webflow.io و*.myshopify.com)، فأضفه أيضًا.

لم يظهر الزر؟ تحقّق من ثلاثة أمور: أن الأداة مفعّلة؛ وأن عنوان الصفحة مدرج في النطاقات المسموح بها — بدقة، مع www أو بدونها؛ وأن الكود موضوع في إعدادات الموقع أو القالب، لا في عنصر يفتحه المنشئ داخل إطار.

#معاملات الأداة

#النتيجة

يظهر زر في زاوية موقعك (اللون — من إعدادات الأداة). انقر ← نافذة محادثة بحقل سؤال ← إجابة بالذكاء الاصطناعي من قاعدة معرفتك.

#اللغة

يغيّر الزائر اللغة بزر الكرة الأرضية في ترويسة النافذة؛ ويُحفظ اختياره في متصفحه لهذه الأداة. ودون اختيار، تأخذ الأداة أول لغة مناسبة من لغات المتصفح، ثم اللغة من إعدادات الأداة (data-lang)، ثم الإنجليزية. ولا تُؤخذ لغة صفحة موقعك في الحسبان. وبالعربية تُفتح النافذة من اليمين إلى اليسار.

#الربط بالموقع

تعمل الأداة فقط على العناوين المحددة عند الإنشاء («عنوان الموقع الذي ستوضع فيه الأداة»)؛ وتُرفض الطلبات من المواقع الأخرى. افصل بين عدة عناوين بفاصلة. لا يمكن تفعيل الأداة دون عنوان، ولا تُقبل النجمة «أي موقع». يُقارن العنوان بدقة: example.com وwww.example.com عنوانان مختلفان، فحدّد كليهما إن كان الموقع يُفتح بكليهما. وللتجربة المحلية حدّد العنوان مع المنفذ، مثل http://127.0.0.1:8899.

#ما يراه الزائر

• لا توجد في نص الإجابة علامات مصادر من نوع [2.3]؛ والعناوين والروابط منسّقة.
• أسفل الإجابة كتلة «المصادر»: يقود الرابط إلى الصفحة الأصلية، وإن لم توجد — إلى المقالة.
• رابط «فتح البحث الكامل» موجود في الأداة المؤسسية فقط.

#إذا نفد حد إجابات الذكاء الاصطناعي

تختفي الأداة العامة من الموقع بالكامل حتى يعود الحد. أما الأداة المؤسسية فتبقى في مكانها، لكنها لا تقبل الأسئلة وتعرض متى يعود البحث متاحًا.

#iframe

واجهة بحث كاملة الميزات مضمَّنة في صفحتك:

#كود التضمين

/embed هو عنوان البوابة الوحيد المسموح بفتحه داخل إطار على موقع آخر. لا يمكن تضمين جذر البوابة (https://your-account.lynkora.pro) — سيرفض المتصفح ذلك. لا يحتاج الإطار إلى مفتاح: فهو يعمل بشكل مجهول ويعرض تمامًا ما يراه زائر البوابة المجهول؛ ويأتي نطاقه من إعدادات الأداة.

#رابط مباشر

إذا لم يناسبك iframe، امنح المستخدمين رابطًا مباشرًا: https://your-account.lynkora.pro

#الوضع التجريبي

للاختبار دون مفتاح API، تتوفر نقطة نهاية تجريبية بقيود:

نقطة النهاية: POST /api/public/demo/search

#مقارنة أوضاع المصادقة

تدعم الأداة وضعَي مصادقة.

#الوضع A — الثقة بمنطقة الرابط

مصادقة من جانب العميل: أنت مسؤول عمّن يصل إلى الصفحات التي تحوي الأداة (VPN، SSO، مسارات محمية). لا تعرف Lynkora هوية المستخدم — فقط Origin/IP الخاص بالطلب. الأداة مرئية لكل من يفتح صفحة تحوي كود التضمين.

• كود الخلفية: 0 سطر
• زمن الإعداد: ~دقيقتان
• مناسب لـ: الشبكة الداخلية، البوابة الداخلية

#الوضع B — رمز الجلسة (JWT لكل مستخدم)

تُصدِر خلفيتك رمز جلسة قصير الأمد لكل مستخدم. تعرف Lynkora الهوية، وتحتفظ بتدقيق لكل مستخدم، وتدعم الإبطال وطلبات GDPR DSAR.

• كود الخلفية: ~10 أسطر (عبر SDK)
• زمن الإعداد: 1–2 ساعة
• مناسب لـ: SaaS متعدد المستأجرين، الصناعات المنظَّمة