تكامل API

قم بدفع البيانات برمجيًا إلى قاعدة معارف AI SmartTalk الخاصة بك باستخدام واجهة برمجة التطبيقات REST الخاصة بنا. مثالي للتكاملات المخصصة، وخطوط الأنابيب الآلية، وأي مصدر بيانات غير مغطى بواسطة الموصلات الأصلية لدينا.

---

نظرة عامة

يمكنك تكامل API من:

• دفع المستندات مباشرة إلى قاعدة المعارف الخاصة بك
• تحديث المحتوى برمجيًا
• حذف الإدخالات القديمة
• بناء خطوط بيانات مخصصة
• التكامل مع أي نظام يمكنه إجراء طلبات HTTP

---

المتطلبات الأساسية

قبل أن تبدأ، تأكد من أن لديك:

• حساب AI SmartTalk نشط
• تم تفعيل الوصول إلى API (تحقق من خطتك)
• معرفة أساسية بواجهات برمجة التطبيقات REST
• أداة لإجراء طلبات HTTP (curl، Postman، أو كود التطبيق الخاص بك)

---

الحصول على بيانات اعتماد API الخاصة بك

الخطوة 1: الوصول إلى إعدادات API

1. قم بتسجيل الدخول إلى حساب AI SmartTalk الخاص بك
2. انتقل إلى الإعدادات → التكاملات
3. ابحث عن API وانقر على تكوين

الخطوة 2: إنشاء رمز API

1. انقر على إنشاء رمز جديد
2. انسخ معرف نموذج الدردشة و رمز API الخاص بك
3. قم بتخزين هذه المعلومات بأمان - يتم عرض الرمز مرة واحدة فقط!

⚠️ تحذير أمني: لا تعرض رمز API الخاص بك في كود جانب العميل أو المستودعات العامة.

---

نقاط نهاية API

عنوان URL الأساسي

https://api.aismarttalk.tech/v1

المصادقة

تتطلب جميع الطلبات رمز API الخاص بك في الرأس:

Authorization: Bearer YOUR_API_TOKEN

---

نقاط نهاية API

عنوان URL الأساسي

https://api.aismarttalk.tech/v1

المصادقة

جميع الطلبات تتطلب رمز API الخاص بك في الرأس:

Authorization: Bearer YOUR_API_TOKEN

---

استيراد الوثائق

نقطة النهاية

POST /documents/import

جسم الطلب

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "وثائق المنتج",
      "content": "المحتوى الكامل لوثيقتك هنا...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

المعلمات

الحقل	النوع	مطلوب	الوصف
chatModelId	string	✅	معرف نموذج الدردشة الفريد الخاص بك
documents	array	✅	مصفوفة من كائنات الوثائق
documents[].title	string	✅	عنوان الوثيقة للتعرف عليها
documents[].content	string	✅	المحتوى النصي الكامل
documents[].url	string	❌	عنوان URL المصدر (للمرجع)
documents[].metadata	object	❌	أزواج المفتاح والقيمة المخصصة

الاستجابة

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "وثائق المنتج",
      "status": "processing"
    }
  ]
}

مثال: cURL

curl -X POST https://api.aismarttalk.tech/v1/documents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatModelId": "your-chat-model-id",
    "documents": [
      {
        "title": "دليل البدء",
        "content": "مرحبًا بك في منصتنا. إليك كيفية البدء...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

استعلام الوثائق

اطرح أسئلة ضد قاعدة المعرفة الخاصة بك برمجيًا.

نقطة النهاية

POST /chat/query

جسم الطلب

{
  "chatModelId": "your-chat-model-id",
  "query": "كيف يمكنني إعادة تعيين كلمة المرور الخاصة بي؟",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

الاستجابة

{
  "success": true,
  "response": "لإعادة تعيين كلمة المرور الخاصة بك، انتقل إلى الإعدادات > الأمان > تغيير كلمة المرور...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "دليل الأمان",
      "relevance": 0.95
    }
  ]
}

---

استرجاع الوثائق

احصل على الوثائق التي تتطابق مع استعلام (بدون استجابة AI).

نقطة النهاية

POST /documents/search

جسم الطلب

{
  "chatModelId": "your-chat-model-id",
  "query": "أمان كلمة المرور",
  "limit": 10
}

الاستجابة

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "أفضل ممارسات الأمان",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

أمثلة على الشيفرة

بايثون

import requests

API_TOKEN = "your-api-token"
CHAT_MODEL_ID = "your-chat-model-id"

def import_document(title: str, content: str, url: str = None):
    response = requests.post(
        "https://api.aismarttalk.tech/v1/documents/import",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "chatModelId": CHAT_MODEL_ID,
            "documents": [{
                "title": title,
                "content": content,
                "url": url
            }]
        }
    )
    return response.json()

# استيراد مستند
result = import_document(
    title="أسئلة شائعة: الشحن",
    content="نقدم شحنًا مجانيًا على الطلبات التي تزيد عن 50 دولارًا...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

جافا سكريبت / Node.js

const API_TOKEN = 'your-api-token';
const CHAT_MODEL_ID = 'your-chat-model-id';

async function importDocument(title, content, url = null) {
  const response = await fetch('https://api.aismarttalk.tech/v1/documents/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatModelId: CHAT_MODEL_ID,
      documents: [{
        title,
        content,
        url
      }]
    })
  });
  return response.json();
}

// استيراد مستند
importDocument(
  'أسئلة شائعة: الإرجاع',
  'يمكنك إرجاع العناصر خلال 30 يومًا من الشراء...',
  'https://shop.example.com/faq/returns'
).then(console.log);

بي إتش بي

<?php
$apiToken = 'your-api-token';
$chatModelId = 'your-chat-model-id';

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'مواصفات المنتج',
            'content' => 'يحتوي جهازنا على المواصفات التالية...',
            'url' => 'https://example.com/products/widget'
        ]
    ]
];

$ch = curl_init('https://api.aismarttalk.tech/v1/documents/import');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

---

حالات الاستخدام

تكامل نظام إدارة المحتوى المخصص

مزامنة المحتوى من نظام إدارة محتوى خاص:

• ربط أحداث نشر نظام إدارة المحتوى
• دفع المحتوى الجديد/المحدث إلى AI SmartTalk
• إزالة المحتوى المحذوف

خط أنابيب البيانات

الاستيراد من مستودعات البيانات:

• تصدير البيانات ذات الصلة إلى JSON
• استيراد دفعي عبر API
• جدولة تحديثات منتظمة

منتجات التجارة الإلكترونية

مزامنة بيانات المنتجات من الأنظمة المخصصة:

• أوصاف المنتجات
• المواصفات
• معلومات التسعير

الأنظمة الداخلية

ربط الأدوات الداخلية التي لا تدعم بشكل أصلي:

• ويكي مخصصة
• قواعد البيانات القديمة
• التطبيقات الخاصة

حدود المعدلات

نقطة النهاية	حد المعدل
استيراد المستندات	100 طلب/دقيقة
استعلام	60 طلب/دقيقة
بحث	60 طلب/دقيقة

ملاحظة: تختلف حدود المعدلات حسب الخطة. اتصل بالدعم للحصول على حدود أعلى.

---

معالجة الأخطاء

تنسيق استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided API token is invalid or expired"
  }
}

رموز الأخطاء الشائعة

الرمز	الوصف	الحل
INVALID_TOKEN	رمز غير صالح أو منتهي	إعادة توليد رمز API
INVALID_MODEL_ID	معرف نموذج الدردشة غير معروف	تحقق من معرف نموذج الدردشة الخاص بك
RATE_LIMITED	عدد كبير جداً من الطلبات	تنفيذ استراتيجية التراجع، إعادة المحاولة لاحقاً
INVALID_REQUEST	جسم الطلب مشوه	تحقق من بنية JSON
DOCUMENT_TOO_LARGE	المحتوى يتجاوز الحد	تقسيم إلى مستندات أصغر
QUOTA_EXCEEDED	تم الوصول إلى حدود الخطة	ترقية أو الاتصال بالدعم

---

استكشاف الأخطاء وإصلاحها

فشل المصادقة

المشكلة	الحل
401 غير مصرح	تحقق من أن الرمز صحيح ونشط
الرمز لا يعمل	إعادة توليد الرمز في الإعدادات
الرمز منتهي	الرموز لا تنتهي، ولكن يمكن إلغاؤها

مشاكل الاستيراد

المشكلة	الحل
استجابة فارغة	تحقق من أن نوع المحتوى هو application/json
المستند لا يظهر	انتظر المعالجة؛ تحقق من قسم المعرفة
استيراد جزئي	قد تحتوي بعض المستندات على أخطاء في التحقق

مشاكل الأداء

المشكلة	الحل
استيرادات بطيئة	قم بتجميع المستندات (حد أقصى 100 لكل طلب)
انتهاء المهلة	تقليل حجم الدفعة، إعادة المحاولة مع التراجع
حد المعدل	تنفيذ التراجع الأسي

---

أفضل الممارسات

1. استيراد الدفعات: إرسال مستندات متعددة لكل طلب (حتى 100)
2. عناوين فريدة: استخدام عناوين وصفية وفريدة لكل مستند
3. محتوى منظم: المحتوى المنسق جيداً يحسن استجابات الذكاء الاصطناعي
4. توسيم البيانات الوصفية: استخدام البيانات الوصفية للتصنيف والتصفية
5. تأمين الرموز: تخزين الرموز في متغيرات البيئة
6. معالجة الأخطاء: تنفيذ منطق إعادة المحاولة مع التراجع الأسي
7. مراقبة الاستخدام: تتبع استدعاءات API مقابل حدود خطتك

---

الوثائق ذات الصلة

• نظرة عامة على التكاملات
• الوثائق الكاملة لواجهة برمجة التطبيقات
• إدارة قاعدة المعرفة
• Webhooks SmartFlow — استلام الأحداث