v1.0REST APIJSON

Khobar Technology — API Reference

وصّل أي نظام بمنصة الذكاء الاصطناعي المركزية عبر HTTP + JSON — بدون مكتبات خاصة أو إعداد معقد.

Base URL: https://ai.khobartech.com

Bearer Token (API Key)

البداية السريعة

يمكنك تشغيل أول طلب خلال دقيقتين — احصل على مفتاح API من لوحة التحكم → API Tokens ثم استخدم أي مثال أدناه.

أنشئ مفتاح API

من لوحة التحكم → API Tokens → إنشاء مفتاح جديد

أرسل طلب HTTP

POST /api/v1/chat مع المفتاح في الـ Authorization header

استقبل JSON

الرد دائماً JSON موحد بغض النظر عن لغة برمجتك

أول طلب لك

curl

curl -X POST https://your-domain.com/api/v1/chat \
  -H "Authorization: Bearer kt_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"action":"chat","message":"مرحبا"}'

Response 200 OK

{
  "success": true,
  "request_id": "req_001",
  "conversation_id": "conv_abc123",
  "response": {
    "message": "أهلاً وسهلاً! كيف يمكنني مساعدتك؟",
    "data": null
  },
  "execution": {
    "model": "qwen2.5:7b",
    "tools_used": [],
    "duration_ms": 842
  },
  "error": null
}

المصادقة والتوثيق

مهم: المفتاح يظهر مرة واحدة فقط عند الإنشاء — احفظه فوراً في مكان آمن. لا يمكن استرجاعه لاحقاً.

إرسال المفتاح

أضف المفتاح في كل طلب داخل header الـ Authorization:

HTTP Header

Authorization: Bearer kt_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

صلاحيات المفتاح

النوع	الوصف	الاستخدام
read	قراءة البيانات وطرح الأسئلة	ERP، HR، التقارير
write	إنشاء وتحديث البيانات عبر MCP	POS، CRM، الطلبات
full	وصول كامل لجميع العمليات	أنظمة متكاملة

نقطة النهاية الرئيسية — /api/v1/chat

POST/api/v1/chat

نقطة النهاية الوحيدة التي يحتاجها نظامك. ترسل سؤالاً أو مهمة، وتعيد المنصة رداً ذكياً.

مخطط الطلب (Request Body)

الحقل	النوع	مطلوب	الوصف
action	string	✅	نوع العملية — راجع قسم الإجراءات
message	string	✅	رسالة المستخدم أو التعليمة
request_id	string	لا	معرف الطلب للتتبع (يُنشأ تلقائياً إن لم يُرسل)
conversation_id	string	لا	معرف المحادثة لاستمرار الحوار
user_id	string	لا	معرف المستخدم في نظامك (للعزل)
context.language	string	لا	"ar" أو "en" — الافتراضي: "ar"
context.timezone	string	لا	المنطقة الزمنية — الافتراضي: Asia/Riyadh
data	object	لا	بيانات JSON إضافية يحللها الذكاء الاصطناعي
options.stream	boolean	لا	تفعيل البث (SSE) — الافتراضي: false

مثال 1 — سؤال بسيط

curl

curl -X POST https://your-domain.com/api/v1/chat \
  -H "Authorization: Bearer kt_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_001",
    "action": "chat",
    "message": "كم إجمالي مبيعات اليوم؟",
    "context": {
      "language": "ar",
      "timezone": "Asia/Riyadh"
    }
  }'

مثال 2 — تحليل بيانات

curl

curl -X POST https://your-domain.com/api/v1/chat \
  -H "Authorization: Bearer kt_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "analyze",
    "message": "حلل هذه المبيعات وأعطني ملخصاً",
    "data": {
      "sales": [
        {"invoice": "INV-1001", "amount": 5000, "customer": "شركة أ"},
        {"invoice": "INV-1002", "amount": 7500, "customer": "شركة ب"},
        {"invoice": "INV-1003", "amount": 3200, "customer": "شركة أ"}
      ]
    },
    "context": {"language": "ar"}
  }'

مثال 3 — محادثة متعددة الرسائل

curl

# الرسالة الأولى — بدون conversation_id
curl -X POST .../api/v1/chat \
  -H "Authorization: Bearer kt_..." \
  -d '{
    "action": "chat",
    "message": "من هو أكبر عميل لدينا؟",
    "user_id": "emp_42"
  }'

# الرد سيحتوي على conversation_id جديد مثل: "conv_abc123"

# الرسالة الثانية — استمرار المحادثة
curl -X POST .../api/v1/chat \
  -H "Authorization: Bearer kt_..." \
  -d '{
    "action": "chat",
    "message": "وكم حجم مشترياته الشهر الماضي؟",
    "conversation_id": "conv_abc123",
    "user_id": "emp_42"
  }'

الإجراءات المتاحة (Actions)

حقل action يحدد نوع العملية:

chatمحادثة عامة

أسئلة ومحادثة حرة مع الذكاء الاصطناعي

"كيف حال المخزون؟"

analyzeتحليل بيانات

تحليل البيانات المرسلة في حقل data

"حلل هذه المبيعات"

summarizeتلخيص

تلخيص نص أو بيانات في data.content

"لخص هذا التقرير"

queryاستعلام

البحث والتصفية في البيانات

"أوجد الفواتير المتأخرة"

structured_outputمخرجات منظمة

إرجاع JSON منظم حسب طلبك

"أعطني قائمة JSON للعملاء"

reportتقرير

توليد تقرير مفصل ومنسق

"اصنع تقرير المبيعات الشهري"

tool_executionتنفيذ أداة

استدعاء أداة MCP محددة مباشرة

"نفّذ أداة get_inventory"

البث المباشر (Streaming)

البث يتيح للمستخدم رؤية الرد حرفاً بحرف بدلاً من الانتظار حتى اكتمال الرد كاملاً.

تفعيل البث

أضف "options": {"stream": true} في الطلب. الاستجابة ستكون text/event-stream.

python

# Python — SSE Streaming
import httpx

with httpx.stream("POST", f"{API_URL}/api/v1/chat",
    headers=headers,
    json={
        "action": "chat",
        "message": "اكتب تقريراً مفصلاً عن المبيعات",
        "options": {"stream": True}
    }
) as resp:
    for line in resp.iter_lines():
        if line.startswith("data:"):
            chunk = json.loads(line[5:].strip())
            if chunk.get("done"):
                break
            print(chunk["delta"], end="", flush=True)

javascript

// JavaScript — Fetch SSE
const resp = await fetch(`${API_URL}/api/v1/chat`, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "chat",
    message: "اكتب تقريراً مفصلاً",
    options: { stream: true },
  }),
});

const reader = resp.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const lines = decoder.decode(value).split("\n");
  for (const line of lines) {
    if (line.startsWith("data:")) {
      const chunk = JSON.parse(line.slice(5).trim());
      if (chunk.done) return;
      process.stdout.write(chunk.delta);
    }
  }
}

SSE Event format:

data: {"delta":"إجمالي","done":false}
data: {"delta":" المبيعات","done":false}
data: {"delta":" هو 12,500 ريال","done":false}
data: {"done":true,"conversation_id":"conv_abc","tools_used":[]}

رموز الأخطاء

HTTP	الرمز	المعنى	الحل
401	MISSING_TOKEN	لا يوجد Authorization header	أضف Bearer token في الـ header
401	INVALID_TOKEN	المفتاح غير صالح أو ملغي	تحقق من المفتاح في لوحة التحكم
403	FORBIDDEN_ACTION	الإجراء غير مسموح لهذا التطبيق	راجع صلاحيات التطبيق
403	TOOL_NOT_PERMITTED	أداة MCP غير مصرح بها	فعّل الأداة في إعدادات التطبيق
422	VALIDATION_ERROR	بيانات الطلب غير صحيحة	راجع مخطط الطلب
429	RATE_LIMITED	تجاوز حد الطلبات	انتظر وحاول مجدداً — راجع Retry-After header
502	MODEL_ERROR	فشل نموذج الذكاء الاصطناعي	تحقق من حالة Ollama
500	INTERNAL_ERROR	خطأ داخلي في الخادم	تواصل مع فريق الدعم

مثال على استجابة خطأ

JSON

{
  "success": false,
  "request_id": "req_001",
  "response": null,
  "execution": null,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "API token is invalid or has been revoked",
    "details": null
  }
}

تكامل MCP — أدوات نظامك

بدلاً من إرسال البيانات في كل طلب، يمكنك توصيل نظامك كـ MCP Server حتى يستطيع الذكاء الاصطناعي جلب البيانات مباشرة عند الحاجة.

الفرق بين الطريقتين

📤

إرسال البيانات في الطلب

✓بسيط — لا إعداد إضافي

✓مناسب للبيانات المتغيرة

–تحتاج تجميع البيانات بنفسك

–غير مناسب للبيانات الكبيرة

🔌

MCP Server (موصى به)

✓الذكاء الاصطناعي يجلب ما يحتاجه فقط

✓لا بيانات زائدة في الطلبات

–يتطلب بناء MCP server صغير

–إعداد أولي مرة واحدة

بناء MCP Server بسيط (Python)

python

# pip install mcp
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My ERP Tools")

@mcp.tool()
def get_sales_total(date_from: str, date_to: str) -> dict:
    """احسب إجمالي المبيعات في فترة زمنية."""
    # منطق نظامك هنا
    return {"total": 125000, "currency": "SAR", "count": 47}

@mcp.tool()
def get_stock_level(product_id: str) -> dict:
    """اجلب مستوى مخزون منتج."""
    return {"product_id": product_id, "quantity": 150, "unit": "pcs"}

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)

خطوات التسجيل

1
شغّل MCP Server الخاص بك على خادمك
2
افتح لوحة التحكم → MCP Servers → تسجيل خادم جديد
3
أدخل URL الخادم مثل: https://erp.khobartech.com/mcp
4
اضغط "اختبار الاتصال" للتحقق
5
اضغط "اكتشاف الأدوات" لمزامنة الأدوات تلقائياً
6
حدد مستوى الصلاحية لكل أداة (قراءة / كتابة / حساس)

Khobar Technology — Company AI Platform v1.0

Swagger UI التفاعلي