API Integrácia

Posielajte dáta programaticky do vašej AI SmartTalk znalostnej bázy pomocou našej REST API. Ideálne pre vlastné integrácie, automatizované pipeline a akýkoľvek zdroj dát, ktorý nie je pokrytý našimi natívnymi konektormi.

---

Prehľad

API integrácia vám umožňuje:

• Posielať dokumenty priamo do vašej znalostnej bázy
• Aktualizovať obsah programaticky
• Odstrániť zastarané záznamy
• Vytvárať vlastné dátové pipeline
• Integrácia s akýmkoľvek systémom, ktorý dokáže vykonávať HTTP požiadavky

---

Požiadavky

Predtým, ako začnete, zabezpečte, aby ste mali:

• Aktívny účet AI SmartTalk
• Povolený prístup k API (skontrolujte svoj plán)
• Základné znalosti o REST API
• Nástroj na vykonávanie HTTP požiadaviek (curl, Postman alebo váš aplikačný kód)

---

Získanie vašich API prihlasovacích údajov

Krok 1: Prístup k nastaveniam API

1. Prihláste sa do svojho účtu AI SmartTalk
2. Prejdite na Nastavenia → Integrácie
3. Nájdite API a kliknite na Konfigurovať

Krok 2: Vygenerovanie API tokenu

1. Kliknite na Vygenerovať nový token
2. Skopírujte svoj Chat Model ID a API Token
3. Uložte ich bezpečne—token je zobrazený iba raz!

⚠️ Bezpečnostné upozornenie: Nikdy nezverejňujte svoj API token v kóde na strane klienta alebo v verejných repozitároch.

---

API Endpoints

Základná URL

https://api.aismarttalk.tech/v1

Autentifikácia

Všetky požiadavky vyžadujú váš API token v hlavičke:

Authorization: Bearer YOUR_API_TOKEN

---

Import Dokumentov

Endpoint

POST /documents/import

Telo požiadavky

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Dokumentácia produktu",
      "content": "Celý obsah vášho dokumentu ide sem...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametre

Pole	Typ	Povinné	Popis
chatModelId	string	✅	Váš jedinečný identifikátor chat modelu
documents	array	✅	Pole objektov dokumentov
documents[].title	string	✅	Názov dokumentu na identifikáciu
documents[].content	string	✅	Celý textový obsah
documents[].url	string	❌	Zdrojová URL (na referenciu)
documents[].metadata	object	❌	Vlastné kľúč-hodnota páry

Odpoveď

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Dokumentácia produktu",
      "status": "processing"
    }
  ]
}

Príklad: 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": "Sprievodca začiatkom",
        "content": "Vitajte na našej platforme. Tu je, ako začať...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Dotaz na Dokumenty

Pýtajte sa otázky voči vašej znalostnej báze programaticky.

Endpoint

POST /chat/query

Telo požiadavky

{
  "chatModelId": "your-chat-model-id",
  "query": "Ako resetujem svoje heslo?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Odpoveď

{
  "success": true,
  "response": "Ak chcete resetovať svoje heslo, prejdite na Nastavenia > Bezpečnosť > Zmeniť heslo...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Sprievodca bezpečnosťou",
      "relevance": 0.95
    }
  ]
}

---

Získať Dokumenty

Získajte dokumenty zodpovedajúce dotazu (bez AI odpovede).

Endpoint

POST /documents/search

Telo požiadavky

{
  "chatModelId": "your-chat-model-id",
  "query": "bezpečnosť hesla",
  "limit": 10
}

Odpoveď

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Najlepšie praktiky bezpečnosti",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Príklady Kódu

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

# Importovať dokument
result = import_document(
    title="Často kladené otázky: Doprava",
    content="Ponúkame bezplatnú dopravu na objednávky nad 50 dolárov...",
    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();
}

// Importovať dokument
importDocument(
  'Často kladené otázky: Vrátenia',
  'Môžete vrátiť položky do 30 dní od nákupu...',
  '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' => 'Špecifikácie produktu',
            'content' => 'Náš widget má nasledujúce špecifikácie...',
            '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));

---

Prípady Použitia

Vlastná Integrácia CMS

Synchronizujte obsah z proprietárneho CMS:

• Pripojte sa k udalostiam publikovania CMS
• Posielajte nový/aktualizovaný obsah do AI SmartTalk
• Odstráňte odstránený obsah

Dátová Pipeline

Importujte z dátových skladov:

• Exportujte relevantné dáta do JSON
• Hromadný import cez API
• Naplánujte pravidelné aktualizácie

E-commerce Produkty

Synchronizujte údaje o produktoch z vlastných systémov:

• Opisy produktov
• Špecifikácie
• Informácie o cenách

Interné Systémy

Pripojte interné nástroje, ktoré nie sú podporované natívne:

• Vlastné wiky
• Dedičské databázy
• Proprietárne aplikácie

---

Limity Požiadaviek

Endpoint	Limit požiadaviek
Import dokumentov	100 požiadaviek/minúta
Dotaz	60 požiadaviek/minúta
Vyhľadávanie	60 požiadaviek/minúta

Poznámka: Limity požiadaviek sa líšia podľa plánu. Kontaktujte podporu pre vyššie limity.

---

Správa Chýb

Formát Odpovede na Chybu

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Poskytnutý API token je neplatný alebo expirovaný"
  }
}

Bežné Kódy Chýb

Kód	Popis	Riešenie
INVALID_TOKEN	Zlý alebo expirovaný token	Regenerujte API token
INVALID_MODEL_ID	Neznámy ID chat modelu	Skontrolujte svoj ID chat modelu
RATE_LIMITED	Príliš veľa požiadaviek	Implementujte spätné oneskorenie, skúste to neskôr
INVALID_REQUEST	Chybne formátovaný obsah požiadavky	Skontrolujte štruktúru JSON
DOCUMENT_TOO_LARGE	Obsah presahuje limit	Rozdeľte na menšie dokumenty
QUOTA_EXCEEDED	Dosiahnuté limity plánu	Upgradujte alebo kontaktujte podporu

---

Odstraňovanie Problémov

Zlyhanie Autentifikácie

Problém	Riešenie
401 Unauthorized	Skontrolujte, či je token správny a aktívny
Token nefunguje	Regenerujte token v nastaveniach
Expirujúci token	Tokeny neexpirujú, ale môžu byť odobraté

Problémy s Importom

Problém	Riešenie
Prázdna odpoveď	Skontrolujte, či je Content-Type application/json
Dokument sa nezobrazuje	Počkajte na spracovanie; skontrolujte sekciu Znalosti
Čiastočný import	Niektoré dokumenty môžu mať validačné chyby

Problémy s Výkonom

Problém	Riešenie
Pomalé importy	Skupinové dokumenty (max 100 na požiadavku)
Časové limity	Znížte veľkosť dávky, skúste to znova so spätným oneskorením
Obmedzené rýchlosti	Implementujte exponenciálne spätné oneskorenie

---

Najlepšie Praktiky

1. Skupinové importy: Posielajte viacero dokumentov na požiadavku (až 100)
2. Jedinečné názvy: Používajte popisné, jedinečné názvy pre každý dokument
3. Štruktúrovaný obsah: Dobre formátovaný obsah zlepšuje odpovede AI
4. Označovanie metadát: Používajte metadata na kategorizáciu a filtrovanie
5. Bezpečné tokeny: Ukladajte tokeny do premenných prostredia
6. Správa chýb: Implementujte logiku opakovania so exponenciálnym spätným oneskorením
7. Monitorovanie používania: Sledujte API volania v súlade s limitmi vášho plánu

---

Súvisiaca Dokumentácia

• Prehľad Integrácií
• Úplná API Dokumentácia
• Správa Znalostnej Základy
• SmartFlow Webhooky — Prijímajte udalosti