API Entegrasyonu

Verilerinizi programlı bir şekilde AI SmartTalk bilgi tabanınıza REST API'miz aracılığıyla gönderin. Özelleştirilmiş entegrasyonlar, otomatik boru hatları ve yerel bağlantılarımızla kapsanmayan herhangi bir veri kaynağı için idealdir.

---

Genel Bakış

API entegrasyonu size şunları sağlar:

• Belgeleri doğrudan bilgi tabanınıza gönderme
• İçeriği programlı olarak güncelleme
• Eski kayıtları silme
• Özelleştirilmiş veri boru hatları oluşturma
• HTTP istekleri yapabilen herhangi bir sistemle entegrasyon sağlama

---

Ön Koşullar

Başlamadan önce, aşağıdakilere sahip olduğunuzdan emin olun:

• Aktif bir AI SmartTalk hesabı
• API erişiminin etkinleştirilmiş olması (planınızı kontrol edin)
• REST API'leri hakkında temel bilgi
• HTTP istekleri yapmak için bir araç (curl, Postman veya uygulama kodunuz)

---

API Kimlik Bilgilerinizi Alma

Adım 1: API Ayarlarına Erişim

1. AI SmartTalk hesabınıza giriş yapın
2. Ayarlar → Entegrasyonlar sekmesine gidin
3. API'yi bulun ve Yapılandır butonuna tıklayın

Adım 2: API Token'ı Oluşturma

1. Yeni Token Oluştur butonuna tıklayın
2. Chat Model ID ve API Token'ınızı kopyalayın
3. Bunları güvenli bir yerde saklayın—token yalnızca bir kez gösterilir!

⚠️ Güvenlik Uyarısı: API token'ınızı istemci tarafı kodunda veya kamuya açık depolarda asla ifşa etmeyin.

---

API Uç Noktaları

Temel URL

https://api.aismarttalk.tech/v1

Kimlik Doğrulama

Tüm istekler, başlıkta API token'ınızı gerektirir:

Authorization: Bearer YOUR_API_TOKEN

---

API Uç Noktaları

Temel URL

https://api.aismarttalk.tech/v1

Kimlik Doğrulama

Tüm istekler, başlıkta API token'ınızı gerektirir:

Authorization: Bearer YOUR_API_TOKEN

---

Belgeleri İçe Aktar

Uç Nokta

POST /documents/import

İstek Gövdesi

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Ürün Belgeleri",
      "content": "Belgenizin tam içeriği buraya gelecek...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametreler

Alan	Tür	Gereklilik	Açıklama
chatModelId	string	✅	Benzersiz sohbet modeli tanımlayıcınız
documents	array	✅	Belge nesneleri dizisi
documents[].title	string	✅	Tanımlama için belge başlığı
documents[].content	string	✅	Tam metin içeriği
documents[].url	string	❌	Kaynak URL'si (referans için)
documents[].metadata	object	❌	Özel anahtar-değer çiftleri

Yanıt

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Ürün Belgeleri",
      "status": "işleniyor"
    }
  ]
}

Örnek: 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şlarken Kılavuzu",
        "content": "Platformumuza hoş geldiniz. İşte nasıl başlayacağınız...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Belgeleri Sorgula

Bilgi tabanınıza programlı olarak sorular sorun.

Uç Nokta

POST /chat/query

İstek Gövdesi

{
  "chatModelId": "your-chat-model-id",
  "query": "Şifremi nasıl sıfırlarım?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Yanıt

{
  "success": true,
  "response": "Şifrenizi sıfırlamak için Ayarlar > Güvenlik > Şifre Değiştir'e gidin...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Güvenlik Kılavuzu",
      "relevance": 0.95
    }
  ]
}

---

Belgeleri Al

Bir sorguya uyan belgeleri alın (AI yanıtı olmadan).

Uç Nokta

POST /documents/search

İstek Gövdesi

{
  "chatModelId": "your-chat-model-id",
  "query": "şifre güvenliği",
  "limit": 10
}

Yanıt

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Güvenlik En İyi Uygulamaları",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Kod Örnekleri

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 belgeyi içe aktar
result = import_document(
    title="SSS: Gönderim",
    content="50$ üzerindeki siparişlerde ücretsiz gönderim sunuyoruz...",
    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 belgeyi içe aktar
importDocument(
  'SSS: İade',
  'Satın alımdan itibaren 30 gün içinde ürünleri iade edebilirsiniz...',
  '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' => 'Ürün Özellikleri',
            'content' => 'Widget\'ımızın aşağıdaki özellikleri vardır...',
            '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));

---

Kullanım Senaryoları

Özel CMS Entegrasyonu

Özel bir CMS'den içerik senkronizasyonu:

• CMS yayın olaylarına bağlanın
• Yeni/güncellenmiş içeriği AI SmartTalk'a gönderin
• Silinen içeriği kaldırın

Veri Boru Hattı

Veri ambarlarından içe aktarım:

• İlgili verileri JSON formatında dışa aktarın
• API aracılığıyla toplu içe aktarım
• Düzenli güncellemeler için programlama yapın

E-ticaret Ürünleri

Özel sistemlerden ürün verilerini senkronize edin:

• Ürün açıklamaları
• Özellikler
• Fiyat bilgileri

Dahili Sistemler

Yerel olarak desteklenmeyen dahili araçları bağlayın:

• Özel wikis
• Eski veritabanları
• Özel uygulamalar

---

Rate Limits

Endpoint	Rate Limit
Document Import	100 requests/minute
Query	60 requests/minute
Search	60 requests/minute

Not: Rate limitleri plana göre değişiklik göstermektedir. Daha yüksek limitler için destekle iletişime geçin.

---

Error Handling

Error Response Format

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

Common Error Codes

Code	Description	Solution
INVALID_TOKEN	Geçersiz veya süresi dolmuş token	API token'ını yeniden oluşturun
INVALID_MODEL_ID	Bilinmeyen sohbet modeli ID'si	Chat Model ID'nizi kontrol edin
RATE_LIMITED	Çok fazla istek	Geri çekilme uygulayın, daha sonra tekrar deneyin
INVALID_REQUEST	Bozuk istek gövdesi	JSON yapısını kontrol edin
DOCUMENT_TOO_LARGE	İçerik limitleri aşıyor	Daha küçük belgelere ayırın
QUOTA_EXCEEDED	Plan limitlerine ulaşıldı	Yükseltme yapın veya destekle iletişime geçin

---

Troubleshooting

Authentication Fails

Issue	Solution
401 Unauthorized	Token'ın doğru ve aktif olduğunu kontrol edin
Token çalışmıyor	Ayarlarda token'ı yeniden oluşturun
Süresi dolmuş token	Token'lar süresi dolmaz, ancak iptal edilebilir

Import Issues

Issue	Solution
Boş yanıt	Content-Type'ın application/json olduğundan emin olun
Belge görünmüyor	İşlenmesini bekleyin; Knowledge bölümünü kontrol edin
Kısmi import	Bazı belgelerde doğrulama hataları olabilir

Performance Issues

Issue	Solution
Yavaş importlar	Belgeleri toplu gönderin (istek başına maksimum 100)
Zaman aşımı	Toplu boyutunu azaltın, geri çekilme ile tekrar deneyin
Rate limitli	Üstel geri çekilme uygulayın

---

Best Practices

1. Toplu importlar: Her istekte birden fazla belge gönderin (maksimum 100)
2. Benzersiz başlıklar: Her belge için tanımlayıcı, benzersiz başlıklar kullanın
3. Yapılandırılmış içerik: İyi formatlanmış içerik AI yanıtlarını iyileştirir
4. Metadata etiketleme: Kategorilendirme ve filtreleme için metadata kullanın
5. Güvenli token'lar: Token'ları ortam değişkenlerinde saklayın
6. Hataları yönetin: Üstel geri çekilme ile tekrar deneme mantığı uygulayın
7. Kullanımı izleyin: API çağrılarını plan limitlerinizle takip edin

---

Related Documentation

• Integrations Overview
• Full API Documentation
• Knowledge Base Management
• SmartFlow Webhooks — Olayları alın