تكامل 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": "Product Documentation",
      "content": "Full content of your document goes here...",
      "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": "Product Documentation",
      "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": "Getting Started Guide",
        "content": "Welcome to our platform. Here is how to get started...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

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

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

نقطة النهاية

POST /chat/query

جسم الطلب

{
  "chatModelId": "your-chat-model-id",
  "query": "How do I reset my password?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

الاستجابة

{
  "success": true,
  "response": "To reset your password, navigate to Settings > Security > Change Password...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Security Guide",
      "relevance": 0.95
    }
  ]
}

---

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

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

نقطة النهاية

POST /documents/search

جسم الطلب

{
  "chatModelId": "your-chat-model-id",
  "query": "password security",
  "limit": 10
}

الاستجابة

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Security Best Practices",
      "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 مقابل حدود خطتك

---

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

• نظرة عامة على التكاملات
• الوثائق الكاملة لـ API
• إدارة قاعدة المعرفة
• Webhooks SmartFlow — استلام الأحداث