API Integracija

Pomoću našeg REST API-ja programatski šaljite podatke u vašu AI SmartTalk bazu znanja. Idealno za prilagođene integracije, automatizovane tokove podataka i bilo koji izvor podataka koji nije pokriven našim nativnim konektorima.

---

Pregled

API integracija vam omogućava da:

• Šaljete dokumente direktno u vašu bazu znanja
• Ažurirate sadržaj programatski
• Brišete zastarjele unose
• Gradite prilagođene tokove podataka
• Integrirate sa bilo kojim sistemom koji može slati HTTP zahtjeve

---

Preduslovi

Prije nego što počnete, osigurajte da imate:

• Aktivni AI SmartTalk račun
• Omogućen API pristup (provjerite svoj plan)
• Osnovno znanje o REST API-jima
• Alat za slanje HTTP zahtjeva (curl, Postman ili vaš aplikacijski kod)

---

Dobijanje vaših API kredencijala

Korak 1: Pristupite API postavkama

1. Prijavite se na svoj AI SmartTalk račun
2. Idite na Postavke → Integracije
3. Pronađite API i kliknite na Konfiguriraj

Korak 2: Generišite API token

1. Kliknite na Generiši novi token
2. Kopirajte svoj ID modela za chat i API token
3. Sigurno ih pohranite—token se prikazuje samo jednom!

⚠️ Upozorenje o sigurnosti: Nikada ne izlažite svoj API token u klijentskom kodu ili javnim repozitorijima.

---

API Krajnje tačke

Osnovni URL

https://api.aismarttalk.tech/v1

Autentifikacija

Svi zahtjevi zahtijevaju vaš API token u zaglavlju:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Sve zahtjeve zahtijevaju vaš API token u zaglavlju:

Authorization: Bearer YOUR_API_TOKEN

---

Uvoz Dokumenata

Endpoint

POST /documents/import

Tijelo Zahtjeva

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Dokumentacija o Proizvodu",
      "content": "Cjelokupni sadržaj vašeg dokumenta ide ovdje...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametri

Polje	Tip	Obavezno	Opis
chatModelId	string	✅	Vaš jedinstveni identifikator chat modela
documents	array	✅	Niz objekata dokumenata
documents[].title	string	✅	Naslov dokumenta za identifikaciju
documents[].content	string	✅	Cjelokupni tekstualni sadržaj
documents[].url	string	❌	Izvorni URL (za referencu)
documents[].metadata	object	❌	Prilagođeni parovi ključ-vrijednost

Odgovor

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

Primjer: 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": "Vodič za Početnike",
        "content": "Dobrodošli na našu platformu. Evo kako započeti...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Upit za Dokumente

Postavljajte pitanja svojoj bazi znanja programatski.

Endpoint

POST /chat/query

Tijelo Zahtjeva

{
  "chatModelId": "your-chat-model-id",
  "query": "Kako da resetujem svoju lozinku?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Odgovor

{
  "success": true,
  "response": "Da biste resetovali svoju lozinku, idite na Postavke > Sigurnost > Promjena Lozinke...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Vodič za Sigurnost",
      "relevance": 0.95
    }
  ]
}

---

Preuzimanje Dokumenata

Dobijte dokumente koji odgovaraju upitu (bez AI odgovora).

Endpoint

POST /documents/search

Tijelo Zahtjeva

{
  "chatModelId": "your-chat-model-id",
  "query": "sigurnost lozinke",
  "limit": 10
}

Odgovor

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Najbolje Prakse u Sigurnosti",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Primjeri Koda

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

# Uvezi dokument
result = import_document(
    title="FAQ: Dostava",
    content="Nudimo besplatnu dostavu za narudžbe preko $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();
}

// Uvezi dokument
importDocument(
  'FAQ: Povrati',
  'Možete vratiti artikle u roku od 30 dana od kupovine...',
  '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 proizvoda',
            'content' => 'Naš uređaj ima sljedeće 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));

---

Upotrebe

Integracija prilagođenog CMS-a

Sinhronizacija sadržaja iz vlasničkog CMS-a:

• Povezivanje sa događajima objavljivanja u CMS-u
• Slanje novog/izmijenjenog sadržaja na AI SmartTalk
• Uklanjanje obrisanog sadržaja

Podatkovni Tok

Uvoz iz skladišta podataka:

• Izvoz relevantnih podataka u JSON
• Serijski uvoz putem API-ja
• Planiranje redovnih ažuriranja

E-trgovina Proizvodi

Sinhronizacija podataka o proizvodima iz prilagođenih sistema:

• Opisi proizvoda
• Specifikacije
• Informacije o cijenama

Interni Sistemi

Povezivanje internih alata koji nisu podržani nativno:

• Prilagođeni wikis
• Naslijeđene baze podataka
• Vlasničke aplikacije

---

Ograničenja Brzine

Endpoint	Ograničenje Brzine
Uvoz Dokumenata	100 zahtjeva/minut
Upit	60 zahtjeva/minut
Pretraga	60 zahtjeva/minut

Napomena: Ograničenja brzine variraju prema planu. Kontaktirajte podršku za veća ograničenja.

---

Rukovanje Greškama

Format Odgovora na Grešku

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided API token is invalid or expired"
  }
}

Uobičajeni Kodovi Grešaka

Kod	Opis	Rješenje
INVALID_TOKEN	Neispravan ili istekao token	Ponovno generišite API token
INVALID_MODEL_ID	Nepoznat ID chat modela	Provjerite svoj ID chat modela
RATE_LIMITED	Previše zahtjeva	Implementirajte backoff, pokušajte kasnije
INVALID_REQUEST	Neispravan format tijela zahtjeva	Provjerite strukturu JSON-a
DOCUMENT_TOO_LARGE	Sadržaj premašuje limit	Podijelite na manje dokumente
QUOTA_EXCEEDED	Dostignuta ograničenja plana	Nadogradite ili kontaktirajte podršku

---

Rješavanje Problema

Neuspjela Autentifikacija

Problem	Rješenje
401 Neautorizovano	Provjerite da li je token ispravan i aktivan
Token ne radi	Ponovno generišite token u postavkama
Istekao token	Tokeni ne isteknu, ali mogu biti opozvani

Problemi sa Uvozom

Problem	Rješenje
Prazan odgovor	Provjerite da li je Content-Type application/json
Dokument se ne pojavljuje	Sačekajte obradu; provjerite odjeljak Znanje
Djelomični uvoz	Neki dokumenti mogu imati greške u validaciji

Problemi sa Performansama

Problem	Rješenje
Spori uvozi	Grupirajte dokumente (maksimalno 100 po zahtjevu)
Istezanje	Smanjite veličinu grupe, pokušajte ponovo sa backoff-om
Ograničenje brzine	Implementirajte eksponencijalni backoff

---

Najbolje Prakse

1. Grupni uvozi: Pošaljite više dokumenata po zahtjevu (do 100)
2. Jedinstveni naslovi: Koristite opisne, jedinstvene naslove za svaki dokument
3. Strukturirani sadržaj: Dobro formatiran sadržaj poboljšava AI odgovore
4. Označavanje metapodataka: Koristite metapodatke za kategorizaciju i filtriranje
5. Sigurni tokeni: Čuvajte tokene u varijablama okruženja
6. Rukovanje greškama: Implementirajte logiku ponovnog pokušaja sa eksponencijalnim backoff-om
7. Praćenje korištenja: Pratite API pozive u odnosu na ograničenja vašeg plana

---

Povezana Dokumentacija

• Pregled Integracija
• Potpuna API Dokumentacija
• Upravljanje Bazom Znanja
• SmartFlow Webhook-ovi — Primajte događaje