API Integracija

Programatsko pošiljanje podatkov v vašo bazo znanja AI SmartTalk z uporabo našega REST API. Idealno za prilagojene integracije, avtomatizirane pipeline in katerikoli vir podatkov, ki ga ne pokrivajo naši privzeti povezovalniki.

---

Pregled

Integracija API omogoča:

• Pošiljanje dokumentov neposredno v vašo bazo znanja
• Posodabljanje vsebine programatsko
• Brisanje zastarelih vnosov
• Gradnjo prilagojenih podatkovnih pipeline
• 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
• Orodje za izvajanje HTTP poizvedb (curl, Postman ali vaš aplikacijski 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. Najdite API in kliknite Konfiguriraj

Korak 2: Generirajte API žeton

1. Kliknite Generiraj nov žeton
2. Kopirajte svoj ID modela klepeta in API žeton
3. Shranite to varno—žeton se prikaže le enkrat!

⚠️ Opozorilo o varnosti: Nikoli ne razkrivajte 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

---

Uvoz dokumentov

Končna točka

POST /documents/import

Telo poizvedbe

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

---

Poizvedba dokumentov

Postavljajte vprašanja proti vaši bazi znanja programatsko.

Končna točka

POST /chat/query

Telo poizvedbe

{
  "chatModelId": "your-chat-model-id",
  "query": "Kako ponastavim 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 priročnik",
      "relevance": 0.95
    }
  ]
}

---

Pridobitev dokumentov

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

Končna točka

POST /documents/search

Telo poizvedbe

{
  "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š pripomoček 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

Prilagojena integracija CMS

Sinhronizirajte vsebino iz lastnega CMS:

• Priključite se na dogodke objave CMS
• Pošljite novo/posodobljeno vsebino v AI SmartTalk
• Odstranite izbrisano vsebino

Podatkovni pipeline

Uvoz iz podatkovnih skladišč:

• Izvozite relevantne podatke v JSON
• Serijski uvoz preko API
• Načrtujte redne posodobitve

Izdelki e-trgovine

Sinhronizirajte podatke o izdelkih iz prilagojenih sistemov:

• Opisi izdelkov
• Specifikacije
• Informacije o cenah

Notranji sistemi

Povežite notranja orodja, ki niso podprta nativno:

• Prilagojeni wikis
• Stare baze podatkov
• Lastne aplikacije

---

Omejitve hitrosti

Končna točka	Omejitev hitrosti
Uvoz dokumentov	100 zahtevkov/minuto
Poizvedba	60 zahtevkov/minuto
Iskanje	60 zahtevkov/minuto

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

---

Obvladovanje napak

Oblika odgovora ob napaki

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

Pogoste kode napak

Koda	Opis	Rešitev
INVALID_TOKEN	Neveljaven ali potekel žeton	Ponovno ustvarite API žeton
INVALID_MODEL_ID	Neznana ID številka chat modela	Preverite svoj ID chat modela
RATE_LIMITED	Preveč zahtevkov	Uvedite upočasnitev, poskusite znova pozneje
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

Neuspešna avtentikacija

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

Težave pri uvozu

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

Težave z zmogljivostjo

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

---

Najboljše prakse

1. Skupinski uvozi: Pošljite več dokumentov na zahtevo (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 klicem API v primerjavi z omejitvami vašega načrta

---

Sorodna dokumentacija

• Pregled integracij
• Polna dokumentacija API
• Upravljanje znanja
• SmartFlow Webhooks — Prejmite dogodke