API Entegrasyonu

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

---

Genel Bakış

API entegrasyonu, aşağıdakileri yapmanıza olanak tanır:

• Belgeleri doğrudan bilgi tabanınıza gönderin
• İçeriği programatik olarak güncelleyin
• Eski girişleri silin
• Özel veri iş akışları oluşturun
• HTTP istekleri yapabilen herhangi bir sistemle entegre olun

---

Ön Koşullar

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

• Aktif bir AI SmartTalk hesabı
• API erişimi etkinleştirilmiş (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 bölümüne 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 genel depolarda asla açığa çıkarmayın.

---

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 Aktarma

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	Gereken	Açıklama
chatModelId	string	✅	Benzersiz sohbet model 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şlangıç Kılavuzu",
        "content": "Platformumuza hoş geldiniz. İşte nasıl başlayacağınız...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Belgeleri Sorgulama

Bilgi tabanınıza programatik 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 bölümüne gidin...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Güvenlik Kılavuzu",
      "relevance": 0.95
    }
  ]
}

---

Belgeleri Alma

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 kargo 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 İş Akışı

Veri ambarlarından içe aktarma:

• İlgili verileri JSON formatında dışa aktarın
• API aracılığıyla toplu içe aktarma yapın
• Düzenli güncellemeleri planlayın

E-ticaret Ürünleri

Özel sistemlerden ürün verilerini senkronize edin:

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

İç Sistemler

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

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

---

Hız Sınırları

Uç Nokta	Hız Sınırı
Belge İçe Aktarma	100 istek/dakika
Sorgu	60 istek/dakika
Arama	60 istek/dakika

Not: Hız sınırları plana göre değişiklik gösterir. Daha yüksek limitler için destekle iletişime geçin.

---

Hata Yönetimi

Hata Yanıt Formatı

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Sağlanan API token'ı geçersiz veya süresi dolmuş"
  }
}

Yaygın Hata Kodları

Kod	Açıklama	Çözüm
INVALID_TOKEN	Geçersiz veya süresi dolmuş token	API token'ını yeniden oluşturun
INVALID_MODEL_ID	Bilinmeyen sohbet modeli ID'si	Sohbet Modeli 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 sınırı aşıyor	Daha küçük belgelere ayırın
QUOTA_EXCEEDED	Plan limitleri aşıldı	Yükseltme yapın veya destekle iletişime geçin

---

Sorun Giderme

Kimlik Doğrulama Başarısız Olursa

Sorun	Çözüm
401 Yetkisiz	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

İçe Aktarma Sorunları

Sorun	Çözüm
Boş yanıt	Content-Type'ın application/json olduğundan emin olun
Belge görünmüyor	İşlem için bekleyin; Bilgi bölümünü kontrol edin
Kısmi içe aktarma	Bazı belgelerde doğrulama hataları olabilir

Performans Sorunları

Sorun	Çözüm
Yavaş içe aktarmalar	Belgeleri toplu gönderin (istek başına maksimum 100)
Zaman aşımı	Toplu boyutunu azaltın, geri çekilme ile tekrar deneyin
Hız sınırlı	Üstel geri çekilme uygulayın

---

En İyi Uygulamalar

1. Toplu içe aktarmalar: Her istekte birden fazla belge gönderin (100'e kadar)
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. Meta veri etiketleme: Kategorizasyon ve filtreleme için meta verileri kullanın
5. Güvenli token'lar: Token'ları ortam değişkenlerinde saklayın
6. Hataları yönetin: Üstel geri çekilme ile yeniden deneme mantığı uygulayın
7. Kullanımı izleyin: API çağrılarını plan limitlerinizle takip edin

---

İlgili Belgeler

• Entegrasyonlar Genel Bakış
• Tam API Belgeleri
• Bilgi Tabanı Yönetimi
• SmartFlow Webhook'ları — Olayları alın