الخدمة 1

إجابة سؤال من قاعدة المعرفة

POST/insaf/knowledge-answer

ترسل سؤالاً عن نظام المحاماة ولوائحه، فتُرجَع إجابة مبنية على قاعدة المعرفة فقط مع تفاصيل البحث.

يتحوّل السؤال إلى search query، ويتم البحث بالسؤال الأصلي وبالـ query معاً، ثم تُدمج النتائج وتُرتّب وتُكتب الإجابة منها. إن لم توجد نتيجة كافية يُرجع answered: false.

السؤال العربي (فصحى أو عامية) إجابته بالفصحى، والإنجليزي إجابته بالإنجليزية. يستغرق الطلب من 4 إلى 8 ثوانٍ.

•score: يُقارن داخل نفس الطلب فقط. حوالي 0.03 تطابق قوي، وحوالي 0.016 أضعف.
•usedInAnswer = true إذا بُنيت الإجابة على العنصر، ودائماً false إذا كانت answered = false.
•البحث يُرجع نتائج دائماً حتى لو السؤال لا علاقة له؛ اعتمد على answered وليس على عدد النتائج.
•سؤال خارج النطاق مثل "طقس الرياض اليوم" يُرجع answered: false مع رسالة "المعلومة غير متوفرة في قاعدة المعرفة".

جرّب الطلب

x-velents-api-key

المفتاح يُحفظ في متصفحك فقط ويُرسل مع الطلب عند التجربة.

POSThttps://inbound-api-gateway.velents.ai

Body (JSON)

Request

الحقل	النوع	مطلوب	الشرح
`question`	string	إجباري	من 3 إلى 2,000 حرف، عربي أو إنجليزي.
`webhook, webhook_headers, webhook_body`	—	اختياري	اختياري لتشغيل الطلب بشكل غير متزامن (انظر الأساسيات المشتركة).

request

curl --location 'https://inbound-api-gateway.velents.ai/insaf/knowledge-answer' \
--header 'x-velents-api-key: {clientId}|{secret}' \
--header 'Content-Type: application/json' \
--data '{
  "question": "هل يجوز لمكتب محاماة أجنبي أن يقدم استشارات في النظام السعودي؟"
}'

Response — 200

الحقل	النوع	الشرح
`question`	string	السؤال بعد الـ trim.
`answer`	string	الإجابة، أو رسالة بأن المعلومة غير متوفرة إذا كانت answered = false.
`answered`	boolean	false إذا لم تُجب النتائج عن السؤال أو كان خارج نطاق مهنة المحاماة.
`search.queries`	string[]	السؤال الأصلي ثم الـ query المولّدة (عنصر واحد إن تطابقا).
`search.topK`	number	أقصى عدد نتائج لكل query.
`search.resultCount`	number	عدد النتائج المختلفة بعد الدمج.
`search.durationMs`	number	زمن البحث.
`search.results[]`	array	النتائج الأعلى أولاً: chunkId، title، category، subcategory (string أو null)، score، matchedQueries[]، usedInAnswer.

response

{
  "question": "هل يجوز لمكتب محاماة أجنبي أن يقدم استشارات في النظام السعودي",
  "answer": "نعم، يجوز ذلك للمكتب الأجنبي المرخص، لكن وفق ضوابط محددة",
  "answered": true,
  "search": {
    "queries": ["هل يجوز لمكتب محاماة أجنبي ...", "foreign law firm Saudi law advice"],
    "topK": 20,
    "resultCount": 28,
    "durationMs": 409,
    "results": [
      {
        "chunkId": "foreign-law-firm-saudi-law-advice-conditions",
        "title": "What are the conditions for a foreign law firm to provide advice on Saudi regulations?",
        "category": "Foreign Law Firm",
        "subcategory": "Legal form and scope of practice",
        "score": 0.0325,
        "matchedQueries": ["...", "foreign law firm Saudi law advice"],
        "usedInAnswer": true
      }
    ]
  },
  "apiProcessingDuration": 6,
  "apiProcessingDurationFormatted": "00:06"
}

Errors

Status	Code	السبب
400	`INVALID_INPUT`	question ناقص أو طوله خارج 3–2,000 حرف، أو حقل webhook غير صحيح.
503	`—`	قاعدة المعرفة غير متاحة مؤقتاً (retryable).

→ الأساسيات تصنيف الشكوى على المخالفات ←