دليل فريق التطوير

إنصاف × Velents — توثيق الـ API

كل الـ endpoints التي توفرها Velents لإنصاف، والـ webhook الصادر من الـ chat widget، وتكامل صفحة لاستخراج المستندات — مع إمكانية تجربة كل طلب مباشرة.

1POST

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

إجابة سؤال عن نظام المحاماة ولوائحه من قاعدة المعرفة.

/insaf/knowledge-answer

2POST

تصنيف الشكوى على المخالفات

تصنيف الشكوى على قائمة المخالفات المعتمدة لنوع الطلب.

/insaf/violation-classification

3POST

تحسين صياغة وصف الشكوى

صياغة فصحى أوضح لوصف الشكوى مع تقييم جودته.

/insaf/description-refinement

4POST

اقتراح القرار على ملف شكوى

اقتراح قرار على ملف شكوى ضد محامٍ وفق 19 قاعدة.

/insaf/complaint-recommendation

5POST

الإبلاغ عن نتيجة خاطئة

إرسال ملاحظة على نتيجة غير دقيقة لتصحيح الخدمة.

/insaf/prompts/improve

6WEBHOOK

Webhook المحادثات

Velents ترسل أحداث محادثات الـ chat widget إلى سيرفر إنصاف.

POST على URL تحدده إنصاف

7POST

صفحة — OCR واستخراج المستندات

رفع مستند إلى صفحة واستخراج بياناته لاستخدامها في attachments.

/Integration/upload · /Integration/templates

0. الأساسيات المشتركة (للـ endpoints من 1 إلى 5)

Base URL: https://inbound-api-gateway.velents.ai

Headers: x-velents-api-key: {clientId}|{secret} و Content-Type: application/json

لكل environment (test / staging / production) key منفصلة.

طريقة التشغيل: sync أو async

•الـ endpoints من 1 إلى 4 تعمل sync أو async.
•بدون webhook: يبقى الاتصال مفتوحاً وترجع النتيجة بـ 200.
•مع webhook: يرجع الرد فوراً بـ 202، وتُرسل النتيجة POST على الـ URL.

الحقل	النوع	الشرح
`webhook`	string (URL)	إن وُجد يُنفّذ الطلب async.
`webhook_headers`	object	headers إضافية مع الـ delivery (مثلاً token للـ receiver).
`webhook_body`	object	حقول إضافية تُدمج في الـ body على top level (مثلاً reference id).

async responses

// 202 — الرد الفوري
{ "status": "accepted", "event": "<event>", "message": "Processing started. The result will be delivered to the provided webhook." }

// delivery — نجاح
{ "event": "<event>", "status": "success", "request": { ...الطلب الأصلي }, "data": { ...نفس body الـ 200 } }

// delivery — فشل
{ "event": "<event>", "status": "error", "request": { ...الطلب الأصلي },
  "retry": { "retryable": true, "method": "POST", "endpoint": "/api/insaf/...", "message": "..." } }

•قيم event: insaf-knowledge-answer أو insaf-violation-classification أو insaf-description-refinement أو insaf-complaint-recommendation.
•بعد الـ 202 يصل الفشل على الـ webhook فقط، ودون تفاصيل الخطأ الداخلي.
•في الـ async، إذا كان الفشل مؤقتاً (408 أو 429 أو 5xx) يُعاد الطلب تلقائياً مرة بعد 15 ثانية قبل إرسال الفشل.
•لإعادة المحاولة: أرسل طلباً جديداً على نفس الـ gateway URL الذي استدعيته (retry.endpoint فيه المسار الداخلي /api/insaf/...) وأضف webhook و webhook_headers و webhook_body. إذا كانت retryable = false فلا تُعد نفس الطلب.
•في webhook_headers يُحذف Content-Type وأي header يبدأ بـ x-velents-. وفي webhook_body تُحذف المفاتيح event و status و request و data و retry.

أخطاء مشتركة

Status	Code	السبب
400	`INVALID_INPUT`	حقل ناقص أو خاطئ؛ الـ message تحدده. {"error":"Validation Error","message":"...","code":"INVALID_INPUT"}
401	`missing / malformed / invalid API key`	مشكلة في x-velents-api-key.
401	`MISSING_CLIENT`	Missing gateway client identity — الطلب لم يمر عبر الـ gateway.
403	`route not allowed`	الـ key غير مفعّل عليها هذا الـ endpoint.
403	`UNKNOWN_INSAF_CLIENT`	الـ key غير مرتبطة بأي environment من environments إنصاف.
429	`rate limit exceeded`	انتظر وأعد المحاولة.
500 / 502 / 503	`{status, event, retry}`	الخدمة غير متاحة مؤقتاً؛ أعد المحاولة إذا كانت retry.retryable = true.

•الـ code في جدول أخطاء كل endpoint للتوضيح فقط. أخطاء 400 و 401 و 403 وحدها تحتوي code في الـ body. أي فشل وقت التنفيذ (500 / 502 / 503) يرجع {status, event, retry} دون code، فاعتمد على HTTP status و retry.retryable.
•ثوابت: كل response فيه apiProcessingDuration (بالثواني) و apiProcessingDurationFormatted (MM:SS). كل حقول الـ response بصيغة camelCase.