API Integracija

Programatsko pošiljanje podatkov v vašo AI SmartTalk bazo znanja z uporabo našega REST API. Idealno za prilagojene integracije, avtomatizirane cevi in vsak vir podatkov, ki ni pokrit z našimi naravnimi povezavami.

---

Pregled

API integracija vam omogoča:

• Pošiljanje dokumentov neposredno v vašo bazo znanja
• Posodabljanje vsebine programatsko
• Brisanje zastarelih vnosov
• Gradnjo prilagojenih podatkovnih cevi
• Integracijo z vsakim sistemom, ki lahko izvaja HTTP poizvedbe

---

Predpogoji

Preden začnete, se prepričajte, da imate:

• Aktivno AI SmartTalk račun
• Omogočen dostop do API (preverite svoj načrt)
• Osnovno znanje o REST API-jih
• Orodje za izvajanje HTTP poizvedb (curl, Postman ali vaša aplikacijska koda)

---

Pridobitev vaših API poverilnic

Korak 1: Dostop do nastavitev API

1. Prijavite se v svoj AI SmartTalk račun
2. Pojdite na Nastavitve → Integracije
3. Poiščite API in kliknite Konfiguriraj

Korak 2: Ustvarite API žeton

1. Kliknite Ustvari nov žeton
2. Kopirajte svoj ID modela klepeta in API žeton
3. Te shranite na varnem mestu—žeton je prikazan le enkrat!

⚠️ Opozorilo o varnosti: Nikoli ne izpostavljajte svojega API žetona v kodi na strani odjemalca ali javnih repozitorijih.

---

API Končne točke

Osnovni URL

https://api.aismarttalk.tech/v1

Avtentikacija

Vse poizvedbe zahtevajo vaš API žeton v glavi:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Osnovni URL

https://api.aismarttalk.tech/v1

Avtentikacija

Vse zahteve zahtevajo vaš API žeton v glavi:

Authorization: Bearer YOUR_API_TOKEN

---

Uvoz Dokumentov

Končna točka

POST /documents/import

Telo zahteve

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Dokumentacija o izdelku",
      "content": "Celotna vsebina vašega dokumenta gre sem...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametri

Polje	Tip	Obvezno	Opis
chatModelId	string	✅	Vaš edinstven identifikator chat modela
documents	array	✅	Množica objektov dokumentov
documents[].title	string	✅	Naslov dokumenta za identifikacijo
documents[].content	string	✅	Celotna besedilna vsebina
documents[].url	string	❌	Izvorni URL (za referenco)
documents[].metadata	object	❌	Prilagojeni ključ-vrednost pari

Odgovor

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

Primer: 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": "Vodnik za začetek",
        "content": "Dobrodošli na naši platformi. Tukaj je, kako začeti...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Poizvedba po Dokumentih

Postavljajte vprašanja proti svoji bazi znanja programatično.

Končna točka

POST /chat/query

Telo zahteve

{
  "chatModelId": "your-chat-model-id",
  "query": "Kako ponastavim svoje geslo?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Odgovor

{
  "success": true,
  "response": "Za ponastavitev gesla pojdite na Nastavitve > Varnost > Spremeni geslo...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Varnostni vodnik",
      "relevance": 0.95
    }
  ]
}

---

Pridobitev Dokumentov

Pridobite dokumente, ki ustrezajo poizvedbi (brez AI odgovora).

Končna točka

POST /documents/search

Telo zahteve

{
  "chatModelId": "your-chat-model-id",
  "query": "varnost gesla",
  "limit": 10
}

Odgovor

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Najboljše prakse varnosti",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Primeri kode

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

# Uvoz dokumenta
result = import_document(
    title="Pogosta vprašanja: Dostava",
    content="Nudimo brezplačno dostavo za naročila 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();
}

// Uvoz dokumenta
importDocument(
  'Pogosta vprašanja: Vračila',
  'Predmete lahko vrnete v 30 dneh po nakupu...',
  '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' => 'Specifikacije izdelka',
            'content' => 'Naš izdelek ima naslednje specifikacije...',
            '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));

---

Uporabniški primeri

Integracija po meri CMS

Sinhronizacija vsebine iz lastnega CMS:

• Povezava na dogodke objave CMS
• Potisnite novo/posodobljeno vsebino v AI SmartTalk
• Odstranite izbrisano vsebino

Podatkovni cevovod

Uvoz iz podatkovnih skladišč:

• Izvoz relevantnih podatkov v JSON
• Serijski uvoz prek API
• Načrtovanje rednih posodobitev

E-trgovinski izdelki

Sinhronizacija podatkov o izdelkih iz lastnih sistemov:

• Opisi izdelkov
• Specifikacije
• Informacije o cenah

Notranji sistemi

Povezava notranjih orodij, ki niso nativno podprta:

• Prilagojeni wikipediji
• Stare baze podatkov
• Lastne aplikacije

---

Omejitve hitrost

Končni točki	Omejitev hitrost
Uvoz dokumentov	100 zahtevkov/minuto
Poizvedba	60 zahtevkov/minuto
Iskanje	60 zahtevkov/minuto

Opomba: Omejitve hitrost se razlikujejo glede na načrt. Kontaktirajte podporo za višje omejitve.

---

Obvladovanje napak

Oblika odgovora napake

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Zagotovljen API žeton je neveljaven ali potekel"
  }
}

Pogosti kodi napak

Koda	Opis	Rešitev
INVALID_TOKEN	Neveljaven ali potekel žeton	Ponovno ustvarite API žeton
INVALID_MODEL_ID	Neznana ID chat modela	Preverite svoj ID chat modela
RATE_LIMITED	Preveč zahtevkov	Uvedite upočasnitev, poskusite kasneje
INVALID_REQUEST	Nepravilno oblikovan telo zahtevka	Preverite strukturo JSON
DOCUMENT_TOO_LARGE	Vsebina presega omejitev	Razdelite na manjše dokumente
QUOTA_EXCEEDED	Dosežene omejitve načrta	Nadgradite ali kontaktirajte podporo

---

Odpravljanje težav

Napake pri avtentikaciji

Težava	Rešitev
401 Neavtorizirano	Preverite, ali je žeton pravilen in aktiven
Žeton ne deluje	Ponovno ustvarite žeton v nastavitvah
Potekel žeton	Žetoni ne potečejo, lahko pa se prekličejo

Težave pri uvozu

Težava	Rešitev
Prazn odgovor	Preverite, ali je Content-Type application/json
Dokument se ne prikazuje	Počakajte na obdelavo; preverite razdelek Znanje
Delni uvoz	Nekateri dokumenti imajo lahko napake pri validaciji

Težave s hitrostjo

Težava	Rešitev
Počasni uvozi	Skupinsko obdelajte dokumente (maksimalno 100 na zahtevek)
Časovne omejitve	Zmanjšajte velikost skupine, poskusite z upočasnitvijo
Omejena hitrost	Uvedite eksponentno upočasnitev

---

Najboljše prakse

1. Skupinski uvozi: Pošljite več dokumentov na zahtevek (do 100)
2. Edinstveni naslovi: Uporabite opisne, edinstvene naslove za vsak dokument
3. Strukturirana vsebina: Dobro oblikovana vsebina izboljša odgovore AI
4. Označevanje metapodatkov: Uporabite metapodatke za kategorizacijo in filtriranje
5. Varnost žetonov: Shranite žetone v okoljske spremenljivke
6. Obvladovanje napak: Uvedite logiko ponovnega poskusa z eksponentno upočasnitvijo
7. Spremljanje uporabe: Sledite API klicem glede na omejitve vašega načrta

---

Sorodna dokumentacija

• Pregled integracij
• Celotna API dokumentacija
• Upravljanje znanja
• SmartFlow Webhooki — Prejemajte dogodke