انتقل إلى المحتوى
Sursa Developers

البدء السريع

يأخذك هذا الدليل من الصفر إلى تكامل يعمل في خمس دقائق: تنشئ مفتاح API، وتتحقق منه، وتضيف مستندًا إلى قاعدة المعرفة، وتجده، وتطرح سؤالًا عنه. وكل خطوة طلب HTTP واحد. اختر لغتك مرة واحدة في أي مثال، فتتبدل معه كل أمثلة الصفحة.

الأمثلة التي فيها مبدّل اللغة تستخدم عنوان API لهذه البوابة: https://api.sursa.com في سحابة Sursa، أو عنوان API لنسختك المثبتة. وحيث يعرض مثال العنوان https://api.example.com، ضع عنوان API الخاص بك مكانه. انظر عنوان API والبيئات إن لم تكن متأكدًا من عنوانك.

1. أنشئ مفتاح API

ينشئ مشرف المؤسسة المفاتيح في Sursa من Administration → API keys (الإدارة ← مفاتيح API). أعطِ المفتاح اسمًا يدل على مكان استخدامه (مثل «مزامنة CRM»)، واختر دوره، ونطاقات صلاحياته إن أردت تضييقه أكثر. يستطيع المفتاح فعل ما يستطيعه مستخدم بهذا الدور، ولا يتجاوز ما تسمح به نطاقاته. ويكفي الدور editor لهذا الدليل.

يُعرض المفتاح مرة واحدة. احفظه في مخزن الأسرار لديك ومرّره إلى شيفرتك في متغير بيئة:

export SURSA_API_KEY="kb_…"

يرسل كل طلب المفتاح في الترويسة Authorization بوصفه رمز Bearer. ويشرح دليل مفاتيح API ونطاقات الصلاحيات الأدوار والنطاقات وانتهاء الصلاحية والتدوير.

2. جهّز عميلًا

لا حاجة إلى أي مكتبة: واجهة API مجرد HTTPS وJSON. تستخدم أمثلة هذا الدليل دالة مساعدة صغيرة في كل لغة. انسخ الدالة الخاصة بلغتك، فالأدلة اللاحقة تستخدم الدالة المساعدة نفسها. والمكتبات الرسمية للعملاء مدرجة في صفحة حزم SDK.

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. تحقّق من المفتاح

تصف العملية GET /v1/me الجهة المستدعية: المؤسسة، والمفتاح، ودوره ونطاقاته، وحد المعدل الذي ينطبق عليه. وهي تعمل مع أي مفتاح صالح، لذا فهي أفضل طلب أول لكل تكامل.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

الحالة 401 مع الرمز auth.not_authenticated تعني أن المفتاح غائب أو مُبطَل أو مكتوب خطأً؛ والرمز api_keys.expired يعني أن صلاحيته انتهت.

4. اعثر على مجموعة

توجد البطاقات في المجموعات. وتسرد العملية GET /v1/collections المجموعات التي يراها مفتاحك:

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

دوّن قيمتي id وname للمجموعة التي تريد العمل بها. تستخدم الأمثلة أدناه المجموعة 3 التي اسمها support.

5. أضف مستندًا

تنشئ العملية PUT /v1/cards-by-external-id/{external_id} بطاقة بمعرّفك الخاص، أو تستبدلها إن كانت موجودة. وتشغيل الطلب مرتين آمن: في المرة الثانية لم يتغيّر المحتوى، فتكون الإجابة skipped مع السبب unchanged. استخدم معرّف السجل في نظامك قيمةً للحقل external_id.

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

يعود الطلب حين تصبح البطاقة جاهزة للعثور عليها: الحالة 201 مع "status": "ready" للبطاقة الجديدة، و200 للبطاقة المستبدلة. ويعمل HTML والنص العادي بالطريقة نفسها مع "content_type": "html" أو "text". أما الملفات (PDF وWord وExcel وغيرها) فتمر عبر نقطة النهاية نفسها بالصيغة multipart/form-data؛ ويغطي دليل استيراد المستندات الملفات والمجلدات والبيانات الوصفية واستيراد مستندات كثيرة.

تجد العملية POST /v1/search مقاطع البطاقات التي تطابق الاستعلام، الأفضل مطابقةً أولًا:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

يأخذ المعامل collection اسم المجموعة. ومن دونه يشمل البحث المجموعة التي اسمها default.

7. اطرح سؤالًا

تجيب العملية POST /v1/ask عن سؤال بلغة طبيعية وتعيد مصادر الإجابة. يجد المساعد المعرفة المطلوبة ويجيب فقط من البطاقات التي يُسمح للمفتاح بقراءتها.

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

حين لا يُعثر على شيء مناسب، تبقى الاستجابة بالحالة 200، مع "empty": "no_hits" وشرح قصير في answer. وشيفرتك هي التي تقرر ما يُعرض للمستخدم في هذه الحالة.

الخطوات التالية