API Integrace

Pushněte data programově do vaší znalostní báze AI SmartTalk pomocí našeho REST API. Ideální pro vlastní integrace, automatizované pipeline a jakýkoli datový zdroj, který není pokryt našimi nativními konektory.

---

Přehled

Integrace API vám umožňuje:

• Pushnout dokumenty přímo do vaší znalostní báze
• Aktualizovat obsah programově
• Smazat zastaralé záznamy
• Vytvořit vlastní datové pipeline
• Integrace s jakýmkoli systémem, který může provádět HTTP požadavky

---

Požadavky

Než začnete, ujistěte se, že máte:

• Aktivní účet AI SmartTalk
• Povolený přístup k API (zkontrolujte svůj plán)
• Základní znalosti o REST API
• Nástroj pro provádění HTTP požadavků (curl, Postman nebo váš aplikační kód)

---

Získání vašich API přihlašovacích údajů

Krok 1: Přístup k nastavení API

1. Přihlaste se do svého účtu AI SmartTalk
2. Přejděte na Nastavení → Integrace
3. Najděte API a klikněte na Konfigurovat

Krok 2: Vygenerovat API token

1. Klikněte na Vygenerovat nový token
2. Zkopírujte svůj ID modelu chatu a API token
3. Uložte je bezpečně—token je zobrazen pouze jednou!

⚠️ Bezpečnostní varování: Nikdy neexponujte svůj API token v kódu na straně klienta nebo veřejných repozitářích.

---

API Endpointy

Základní URL

https://api.aismarttalk.tech/v1

Autentizace

Všechny požadavky vyžadují váš API token v hlavičce:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Základní URL

https://api.aismarttalk.tech/v1

Autentizace

Všechny požadavky vyžadují váš API token v hlavičce:

Authorization: Bearer YOUR_API_TOKEN

---

Import Dokumentů

Endpoint

POST /documents/import

Tělo požadavku

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Dokumentace produktu",
      "content": "Celý obsah vašeho dokumentu zde...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametry

Pole	Typ	Povinné	Popis
chatModelId	string	✅	Váš jedinečný identifikátor chat modelu
documents	array	✅	Pole objektů dokumentů
documents[].title	string	✅	Název dokumentu pro identifikaci
documents[].content	string	✅	Celý textový obsah
documents[].url	string	❌	Zdrojová URL (pro referenci)
documents[].metadata	object	❌	Vlastní klíč-hodnota páry

Odpověď

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

Pří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": "Průvodce pro začátečníky",
        "content": "Vítejte na naší platformě. Zde je, jak začít...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Dotaz na Dokumenty

Položte otázky proti vaší znalostní bázi programově.

Endpoint

POST /chat/query

Tělo požadavku

{
  "chatModelId": "your-chat-model-id",
  "query": "Jak mohu resetovat své heslo?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Odpověď

{
  "success": true,
  "response": "Pro resetování vašeho hesla přejděte do Nastavení > Zabezpečení > Změnit heslo...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Průvodce zabezpečením",
      "relevance": 0.95
    }
  ]
}

---

Získání Dokumentů

Získejte dokumenty odpovídající dotazu (bez AI odpovědi).

Endpoint

POST /documents/search

Tělo požadavku

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

Odpověď

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Nejlepší praktiky zabezpečení",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Pří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()

# Import a document
result = import_document(
    title="FAQ: Doprava",
    content="Nabízíme bezplatnou dopravu na objednávky nad 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();
}

// Import a document
importDocument(
  'FAQ: Vrátí',
  'Můžete vrátit zboží 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' => 'Specifikace produktu',
            'content' => 'Naše zařízení má následující specifikace...',
            '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));

---

Případové studie

Integrace vlastního CMS

Synchronizace obsahu z proprietárního CMS:

• Napojení na události publikování CMS
• Odesílání nového/aktualizovaného obsahu do AI SmartTalk
• Odstranění smazaného obsahu

Datový kanál

Import z datových skladů:

• Export relevantních dat do JSON
• Hromadný import prostřednictvím API
• Naplánování pravidelných aktualizací

Produkty e-commerce

Synchronizace dat o produktech z vlastních systémů:

• Popisy produktů
• Specifikace
• Informace o cenách

Interní systémy

Propojení interních nástrojů, které nejsou nativně podporovány:

• Vlastní wikis
• Zastaralé databáze
• Proprietární aplikace

---

Limity požadavků

Endpoint	Limity požadavků
Import dokumentu	100 požadavků/minutu
Dotaz	60 požadavků/minutu
Vyhledávání	60 požadavků/minutu

Poznámka: Limity požadavků se liší podle plánu. Kontaktujte podporu pro vyšší limity.

---

Zpracování chyb

Formát odpovědi na chybu

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Poskytnutý API token je neplatný nebo vypršel"
  }
}

Běžné kódy chyb

Kód	Popis	Řešení
INVALID_TOKEN	Neplatný nebo vypršel token	Znovu vygenerujte API token
INVALID_MODEL_ID	Neznámé ID chat modelu	Zkontrolujte své ID chat modelu
RATE_LIMITED	Příliš mnoho požadavků	Implementujte zpětné odložení, zkuste to později
INVALID_REQUEST	Chybně formátovaný tělo požadavku	Zkontrolujte strukturu JSON
DOCUMENT_TOO_LARGE	Obsah překračuje limit	Rozdělte na menší dokumenty
QUOTA_EXCEEDED	Byly dosaženy limity plánu	Upgradujte nebo kontaktujte podporu

---

Řešení problémů

Selhání ověření

Problém	Řešení
401 Neautorizováno	Zkontrolujte, zda je token správný a aktivní
Token nefunguje	Znovu vygenerujte token v nastavení
Vypršel token	Tokeny nevyprší, ale mohou být odvolány

Problémy s importem

Problém	Řešení
Prázdná odpověď	Zkontrolujte, zda je Content-Type application/json
Dokument se nezobrazuje	Počkejte na zpracování; zkontrolujte sekci Znalosti
Částečný import	Některé dokumenty mohou mít validační chyby

Problémy s výkonem

Problém	Řešení
Pomalé importy	Zpracovávejte dokumenty po dávkách (max 100 na požadavek)
Časové limity	Snižte velikost dávky, zkuste to znovu se zpětným odložením
Omezena rychlost	Implementujte exponenciální zpětné odložení

---

Nejlepší postupy

1. Importy po dávkách: Odesílejte více dokumentů na požadavek (až 100)
2. Jedinečné názvy: Používejte popisné, jedinečné názvy pro každý dokument
3. Strukturovaný obsah: Dobře formátovaný obsah zlepšuje odpovědi AI
4. Označování metadat: Používejte metadata pro kategorizaci a filtrování
5. Bezpečné tokeny: Ukládejte tokeny do proměnných prostředí
6. Zpracování chyb: Implementujte logiku opakování se exponenciálním zpětným odložením
7. Sledování používání: Sledujte API volání vůči limitům vašeho plánu

---

Související dokumentace

• Přehled integrací
• Úplná dokumentace API
• Správa znalostní báze
• SmartFlow Webhooks — Přijímejte události