API İnteqrasiyası

Məlumatları proqramatik olaraq AI SmartTalk bilik bazanıza REST API vasitəsilə göndərin. Xüsusi inteqrasiyalar, avtomatlaşdırılmış boru xətləri və yerli bağlantılarımızla əhatə olunmayan hər hansı bir məlumat mənbəsi üçün idealdır.

---

Ümumi Məlumat

API inteqrasiyası sizə imkan verir:

• Sənədləri birbaşa bilik bazanıza göndərin
• Məzmunu proqramatik olaraq yeniləyin
• Köhnəlmiş yazıları silin
• Xüsusi məlumat boru xətləri yaradın
• İnteqrasiya edin, HTTP sorğuları göndərə bilən hər hansı bir sistemlə

---

Tələblər

Başlamazdan əvvəl, aşağıdakılara əmin olun:

• Aktiv AI SmartTalk hesabınız var
• API giriş imkanı aktivdir (planınızı yoxlayın)
• REST API-ləri haqqında əsas biliklər
• HTTP sorğuları göndərmək üçün bir alət (curl, Postman və ya tətbiq kodunuz)

---

API Məlumatlarınızı Almaq

Addım 1: API Parametrlərinə Giriş

1. AI SmartTalk hesabınıza daxil olun
2. Parametrlər → İnteqrasiyalar bölməsinə keçin
3. API tapın və Konfiqurasiya düyməsini basın

Addım 2: API Tokenini Yaratmaq

1. Yeni Token Yarat düyməsini basın
2. Söhbət Modeli ID və API Tokeninizi kopyalayın
3. Bunları təhlükəsiz şəkildə saxlayın—token yalnız bir dəfə göstərilir!

⚠️ Təhlükəsizlik Xəbərdarlığı: API tokeninizi müştəri tərəfindəki kodda və ya ictimai repositoriyalarda heç vaxt açıqlamayın.

---

API Son Nöqtələri

Əsas URL

https://api.aismarttalk.tech/v1

Doğrulama

Bütün sorğular başlıqda API tokeninizi tələb edir:

Authorization: Bearer YOUR_API_TOKEN

---

API Son Nöqtələri

Əsas URL

https://api.aismarttalk.tech/v1

Doğrulama

Bütün sorğular başlıqda API tokeninizi tələb edir:

Authorization: Bearer YOUR_API_TOKEN

---

Sənədləri İdxal Etmək

Son Nöqtə

POST /documents/import

Sorğu Gövdəsi

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Məhsul Sənədi",
      "content": "Sənədinizin tam məzmunu burada...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametrlər

Sahə	Tip	Tələb olunur	Təsvir
chatModelId	string	✅	Unikal chat model identifikatorunuz
documents	array	✅	Sənəd obyektləri massivi
documents[].title	string	✅	Tanıma üçün sənəd başlığı
documents[].content	string	✅	Tam mətn məzmunu
documents[].url	string	❌	Mənbə URL (istinad üçün)
documents[].metadata	object	❌	Xüsusi açar-dəyər cütləri

Cavab

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Məhsul Sənədi",
      "status": "işlənir"
    }
  ]
}

Nümunə: 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": "Başlanğıc Bələdçisi",
        "content": "Platformamıza xoş gəlmisiniz. Başlamaq üçün burada necə edəcəyiniz...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Sənədləri Sorğu Etmək

Bilgi bazanıza qarşı proqramlı şəkildə suallar verin.

Son Nöqtə

POST /chat/query

Sorğu Gövdəsi

{
  "chatModelId": "your-chat-model-id",
  "query": "Şifrəmi necə sıfırlaya bilərəm?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Cavab

{
  "success": true,
  "response": "Şifrənizi sıfırlamaq üçün Parametrlər > Təhlükəsizlik > Şifrəni Dəyişdirin...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Təhlükəsizlik Bələdçisi",
      "relevance": 0.95
    }
  ]
}

---

Sənədləri Geri Almaq

Sorğuya uyğun sənədləri əldə edin (AI cavabı olmadan).

Son Nöqtə

POST /documents/search

Sorğu Gövdəsi

{
  "chatModelId": "your-chat-model-id",
  "query": "şifrə təhlükəsizliyi",
  "limit": 10
}

Cavab

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Təhlükəsizlik Üçün Ən Yaxşı Təcrübələr",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Kod Nümunələri

Python

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()

# Bir sənəd idxal et
result = import_document(
    title="FAQ: Göndərmə",
    content="50 dollardan yuxarı sifarişlərdə pulsuz göndərmə təklif edirik...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

JavaScript / 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();
}

// Bir sənəd idxal et
importDocument(
  'FAQ: Qayıtma',
  'Alışdan 30 gün ərzində əşyaları qaytara bilərsiniz...',
  'https://shop.example.com/faq/returns'
).then(console.log);

PHP

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

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'Məhsul Spesifikasiyaları',
            'content' => 'Bizim widget aşağıdakı spesifikasiyalara malikdir...',
            '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));

---

İstifadə Halları

Xüsusi CMS İnteqrasiyası

Mülkiyyət CMS-dən məzmunu senkronlaşdırın:

• CMS yayımlama hadisələrinə qoşulun
• Yeni/yenilənmiş məzmunu AI SmartTalk-a göndərin
• Silinmiş məzmunu çıxarın

Məlumat Boru Kəməri

Məlumat anbarlarından idxal edin:

• Müvafiq məlumatları JSON-a ixrac edin
• API vasitəsilə toplu idxal edin
• Müntəzəm yeniləmələri planlaşdırın

E-ticarət Məhsulları

Xüsusi sistemlərdən məhsul məlumatlarını senkronlaşdırın:

• Məhsul təsvirləri
• Spesifikasiyalar
• Qiymət məlumatları

Daxili Sistemlər

Təbii olaraq dəstəklənməyən daxili alətləri birləşdirin:

• Xüsusi vikilər
• Köhnə verilənlər bazaları
• Mülkiyyət tətbiqləri

---

İstifadə Limitləri

Endpoint	İstifadə Limiti
Sənəd İdxalı	100 sorğu/dəqiqə
Sorğu	60 sorğu/dəqiqə
Axtarış	60 sorğu/dəqiqə

Qeyd: İstifadə limitləri planlara görə dəyişir. Yüksək limitlər üçün dəstək ilə əlaqə saxlayın.

---

Xəta İdarəetməsi

Xəta Cavabı Formatı

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Verilmiş API tokeni etibarsızdır və ya müddəti bitmişdir"
  }
}

Ümumi Xəta Kodları

Kod	Təsvir	Həll
INVALID_TOKEN	Pis və ya müddəti bitmiş token	API tokenini yenidən yaradın
INVALID_MODEL_ID	Tanınmayan söhbət modeli ID-si	Sizin Söhbət Modeli ID-nizi yoxlayın
RATE_LIMITED	Çox sayda sorğu	Geri çəkilmə tətbiq edin, sonra yenidən cəhd edin
INVALID_REQUEST	Yanlış formatlı sorğu bədəni	JSON strukturunu yoxlayın
DOCUMENT_TOO_LARGE	Məzmun limitləri aşır	Kiçik sənədlərə bölün
QUOTA_EXCEEDED	Plan limitlərinə çatılıb	Yüksəldin və ya dəstək ilə əlaqə saxlayın

---

Problemlərin Həlli

Doğrulama Uğursuzluğu

Problemlər	Həll
401 İcazəsiz	Tokenin düzgün və aktiv olduğunu yoxlayın
Token işləməyir	Parametrlərdə tokeni yenidən yaradın
Müddəti bitmiş token	Tokenlər müddəti bitmir, amma ləğv edilə bilər

İdxal Problemləri

Problemlər	Həll
Boş cavab	Content-Type-in application/json olduğunu yoxlayın
Sənəd görünmür	Emal üçün gözləyin; Bilgi bölməsini yoxlayın
Qismən idxal	Bəzi sənədlərdə təsdiq xətaları ola bilər

Performans Problemləri

Problemlər	Həll
Yavaş idxallar	Sənədləri partiyalara ayırın (sorğu başına maksimum 100)
Zaman aşımı	Partiya ölçüsünü azaldın, geri çəkilmə ilə yenidən cəhd edin
İstifadə limiti	Eksponensial geri çəkilmə tətbiq edin

---

Ən Yaxşı Təcrübələr

1. Partiya idxalları: Hər sorğuda bir neçə sənəd göndərin (maksimum 100)
2. Unikal başlıqlar: Hər sənəd üçün təsviredici, unikal başlıqlar istifadə edin
3. Strukturlu məzmun: Yaxşı formatlanmış məzmun AI cavablarını yaxşılaşdırır
4. Metadata etiketləmə: Kateqoriyalaşdırma və filtrasiya üçün metadata istifadə edin
5. Təhlükəsiz tokenlər: Tokenləri mühit dəyişənlərində saxlayın
6. Xətaları idarə edin: Eksponensial geri çəkilmə ilə yenidən cəhd məntiqini tətbiq edin
7. İstifadəni izləyin: API çağırışlarını plan limitlərinizlə izləyin

---

Əlaqəli Sənədlər

• İnteqrasiyalar Ümumi Məlumatı
• Tam API Sənədi
• Bilgi Bazası İdarəetməsi
• SmartFlow Webhooks — Hadisələri qəbul edin