API Integracija

Programiškai siųskite duomenis į savo AI SmartTalk žinių bazę naudodami mūsų REST API. Idealu pritaikytoms integracijoms, automatizuotoms linijoms ir bet kokiam duomenų šaltiniui, kuris nėra padengtas mūsų natūraliais jungikliais.

---

Apžvalga

API integracija leidžia jums:

• Siųsti dokumentus tiesiogiai į savo žinių bazę
• Atnaujinti turinį programiškai
• Ištrinti pasenusius įrašus
• Kuriant pritaikytas duomenų linijas
• Integruotis su bet kuria sistema, galinčia atlikti HTTP užklausas

---

Reikalavimai

Prieš pradėdami, įsitikinkite, kad turite:

• Aktyvią AI SmartTalk paskyrą
• Įgalintą API prieigą (patikrinkite savo planą)
• Pagrindines žinias apie REST API
• Įrankį HTTP užklausoms atlikti (curl, Postman arba jūsų programos kodą)

---

API Akreditacijos Gavimo

1 žingsnis: Pasiekite API Nustatymus

1. Prisijunkite prie savo AI SmartTalk paskyros
2. Eikite į Nustatymai → Integracijos
3. Suraskite API ir spustelėkite Konfigūruoti

2 žingsnis: Sugeneruokite API Raktą

1. Spustelėkite Sugeneruoti naują raktą
2. Nukopijuokite savo Chat Model ID ir API raktą
3. Laikykite juos saugiai—raktas rodomas tik vieną kartą!

⚠️ Saugumo įspėjimas: Niekada neatskleiskite savo API rakto kliento pusės kode arba viešose saugyklose.

---

API Pabaigos Taškai

Pagrindinis URL

https://api.aismarttalk.tech/v1

Autentifikacija

Visoms užklausoms reikia jūsų API rakto antraštėje:

Authorization: Bearer YOUR_API_TOKEN

---

Importuoti Dokumentus

Pabaigos Taškas

POST /documents/import

Užklausos Kūnas

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Produkto Dokumentacija",
      "content": "Visas jūsų dokumento turinys čia...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametrai

Laukas	Tipas	Privalomas	Aprašymas
chatModelId	string	✅	Jūsų unikalus pokalbių modelio identifikatorius
documents	array	✅	Dokumentų objektų masyvas
documents[].title	string	✅	Dokumento pavadinimas identifikavimui
documents[].content	string	✅	Pilnas teksto turinys
documents[].url	string	❌	Šaltinio URL (nuorodai)
documents[].metadata	object	❌	Pritaikyti raktų-vertės poros

Atsakymas

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Produkto Dokumentacija",
      "status": "processing"
    }
  ]
}

Pavyzdys: 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": "Pradžios Vadovas",
        "content": "Sveiki atvykę į mūsų platformą. Štai kaip pradėti...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Užduoti Klausimus Dokumentams

Klausykite klausimų savo žinių bazei programiškai.

Pabaigos Taškas

POST /chat/query

Užklausos Kūnas

{
  "chatModelId": "your-chat-model-id",
  "query": "Kaip atnaujinti savo slaptažodį?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Atsakymas

{
  "success": true,
  "response": "Norėdami atnaujinti slaptažodį, eikite į Nustatymai > Saugumas > Keisti slaptažodį...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Saugumo Vadovas",
      "relevance": 0.95
    }
  ]
}

---

Gauti Dokumentus

Gaukite dokumentus, atitinkančius užklausą (be AI atsakymo).

Pabaigos Taškas

POST /documents/search

Užklausos Kūnas

{
  "chatModelId": "your-chat-model-id",
  "query": "slaptažodžio saugumas",
  "limit": 10
}

Atsakymas

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Saugumo Geriausios Praktikos",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Kodo Pavyzdžiai

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

# Importuoti dokumentą
result = import_document(
    title="DUK: Pristatymas",
    content="Mes siūlome nemokamą pristatymą užsakymams virš 50$...",
    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();
}

// Importuoti dokumentą
importDocument(
  'DUK: Grąžinimai',
  'Galite grąžinti prekes per 30 dienų nuo pirkimo...',
  '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' => 'Produkto Specifikacijos',
            'content' => 'Mūsų įrenginys turi šias specifikacijas...',
            '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));

---

Naudojimo Atvejai

Pritaikyta CMS Integracija

Sinchronizuokite turinį iš nuosavos CMS:

• Prijunkite prie CMS publikavimo įvykių
• Siųskite naują/atnaujintą turinį į AI SmartTalk
• Pašalinkite ištrintą turinį

Duomenų Linija

Importuokite iš duomenų sandėlių:

• Eksportuokite atitinkamus duomenis į JSON
• Grupinis importas per API
• Planuokite reguliarius atnaujinimus

E-komercijos Produktai

Sinchronizuokite produktų duomenis iš pritaikytų sistemų:

• Produktų aprašymai
• Specifikacijos
• Kainų informacija

Vidaus Sistemos

Prijunkite vidinius įrankius, kurie nėra palaikomi natūraliai:

• Pritaikyti vikiai
• Senosios duomenų bazės
• Nuosavos programos

---

Greičio Apribojimai

Pabaigos Taškas	Greičio Apribojimas
Dokumentų Importas	100 užklausų/minutę
Klausimas	60 užklausų/minutę
Paieška	60 užklausų/minutę

Pastaba: Greičio apribojimai skiriasi priklausomai nuo plano. Susisiekite su palaikymo tarnyba dėl didesnių apribojimų.

---

Klaidų Tvarkymas

Klaidų Atsakymo Format

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Pateiktas API raktas yra neteisingas arba pasibaigęs"
  }
}

Dažnos Klaidų Kodo

Kodas	Aprašymas	Sprendimas
INVALID_TOKEN	Neteisingas arba pasibaigęs raktas	Regeneruokite API raktą
INVALID_MODEL_ID	Nežinomas pokalbių modelio ID	Patikrinkite savo pokalbių modelio ID
RATE_LIMITED	Per daug užklausų	Įgyvendinkite atidėjimą, bandykite vėliau
INVALID_REQUEST	Neteisingai suformuota užklausos kūnas	Patikrinkite JSON struktūrą
DOCUMENT_TOO_LARGE	Turinys viršija limitą	Padalinkite į mažesnius dokumentus
QUOTA_EXCEEDED	Pasiekta plano riba	Atnaujinkite arba susisiekite su palaikymu

---

Problemos Sprendimas

Autentifikacija Nepavyksta

Problema	Sprendimas
401 Neautorizuota	Patikrinkite, ar raktas yra teisingas ir aktyvus
Raktas neveikia	Regeneruokite raktą nustatymuose
Pasibaigęs raktas	Raktai nesibaigia, tačiau gali būti atšaukti

Importavimo Problemos

Problema	Sprendimas
Tuščias atsakymas	Patikrinkite, ar Content-Type yra application/json
Dokumentas nepasirodo	Palaukite apdorojimo; patikrinkite Žinių skyrių
Dalinis importas	Kai kurie dokumentai gali turėti validacijos klaidų

Veikimo Problemos

Problema	Sprendimas
Lėti importai	Grupiuokite dokumentus (maks. 100 užklausai)
Laiko limitai	Sumažinkite grupės dydį, bandykite su atidėjimu
Greičio limitas	Įgyvendinkite eksponentinį atidėjimą

---

Geriausios Praktikos

1. Grupiniai importai: Siųskite kelis dokumentus užklausoje (iki 100)
2. Unikalūs pavadinimai: Naudokite aprašomuosius, unikalius pavadinimus kiekvienam dokumentui
3. Struktūruotas turinys: Gerai suformatuotas turinys pagerina AI atsakymus
4. Metaduomenų žymėjimas: Naudokite metaduomenis kategorijoms ir filtravimui
5. Saugūs raktai: Laikykite raktus aplinkos kintamuosiuose
6. Klaidų tvarkymas: Įgyvendinkite bandymo logiką su eksponentiniu atidėjimu
7. Naudojimo stebėjimas: Sekite API užklausas pagal savo plano ribas

---

Susijusi Dokumentacija

• Integracijų Apžvalga
• Pilna API Dokumentacija
• Žinių Bazės Valdymas
• SmartFlow Webhook'ai — Gauti įvykius