API Integracija

Programatski šaljite podatke u svoju AI SmartTalk bazu znanja koristeći naš REST API. Idealno za prilagođene integracije, automatizirane tokove podataka i bilo koji izvor podataka koji nije pokriven našim izvorima.

---

Pregled

API integracija omogućuje vam:

• Slanje dokumenata izravno u vašu bazu znanja
• Ažuriranje sadržaja programatski
• Brisanje zastarjelih unosa
• Izgradnju prilagođenih tokova podataka
• Integraciju s bilo kojim sustavom koji može slati HTTP zahtjeve

---

Preduvjeti

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-ima
• Alat za slanje HTTP zahtjeva (curl, Postman ili vaš aplikacijski kod)

---

Dobivanje vaših API vjerodajnica

Korak 1: Pristupite API postavkama

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

Korak 2: Generirajte API Token

1. Kliknite Generiraj novi token
2. Kopirajte svoj ID modela chata i API token
3. Pohranite ih sigurno—token se prikazuje samo jednom!

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

---

API Endpointi

Osnovni URL

https://api.aismarttalk.tech/v1

Autentifikacija

Svi zahtjevi 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": "Cjelovit 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 modela chata
documents	array	✅	Niz objekata dokumenata
documents[].title	string	✅	Naslov dokumenta za identifikaciju
documents[].content	string	✅	Cjelovit 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 resetiram svoju lozinku?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Odgovor

{
  "success": true,
  "response": "Da biste resetirali 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 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()

# Uvoz dokumenta
result = import_document(
    title="Česta pitanja: Dostava",
    content="Nudimo besplatnu dostavu za narudžbe iznad 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(
  'Česta pitanja: Povrati',
  'Možete vratiti artikle unutar 30 dana od kupnje...',
  '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));

---

Primjene

Prilagođena CMS Integracija

Sinkronizirajte sadržaj iz vlastitog CMS-a:

• Povežite se s događajima objavljivanja CMS-a
• Pošaljite novi/ažurirani sadržaj u AI SmartTalk
• Uklonite izbrisani sadržaj

Tok Podataka

Uvoz iz skladišta podataka:

• Izvezite relevantne podatke u JSON
• Batch uvoz putem API-ja
• Planirajte redovita ažuriranja

E-trgovina Proizvodi

Sinkronizirajte podatke o proizvodima iz prilagođenih sustava:

• Opisi proizvoda
• Specifikacije
• Informacije o cijenama

Interni Sustavi

Povežite interne alate koji nisu podržani izvorno:

• Prilagođene wikipedije
• Naslijeđene baze podataka
• Vlastite aplikacije

---

Ograničenja Brzine

Endpoint	Ograničenje Brzine
Uvoz Dokumenata	100 zahtjeva/minuta
Upit	60 zahtjeva/minuta
Pretraživanje	60 zahtjeva/minuta

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

---

Rukovanje pogreškama

Format odgovora na pogrešku

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Pruženi API token je nevažeći ili je istekao"
  }
}

Uobičajeni kodovi pogrešaka

Kod	Opis	Rješenje
INVALID_TOKEN	Nevažeći ili istekao token	Ponovno generirajte API token
INVALID_MODEL_ID	Nepoznat ID chat modela	Provjerite svoj Chat Model ID
RATE_LIMITED	Previše zahtjeva	Implementirajte backoff, pokušajte kasnije
INVALID_REQUEST	Neispravan sadržaj zahtjeva	Provjerite strukturu JSON-a
DOCUMENT_TOO_LARGE	Sadržaj premašuje ograničenje	Podijelite na manje dokumente
QUOTA_EXCEEDED	Dosegnuta ograničenja plana	Nadogradite ili kontaktirajte podršku

---

Rješavanje problema

Neuspjeh autentifikacije

Problem	Rješenje
401 Unauthorized	Provjerite je li token ispravan i aktivan
Token ne radi	Ponovno generirajte token u postavkama
Istekli token	Tokeni ne isteknu, ali mogu biti opozvani

Problemi s uvozom

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

Problemi s performansama

Problem	Rješenje
Spori uvozi	Grupirajte dokumente (maksimalno 100 po zahtjevu)
Timeouti	Smanjite veličinu grupe, pokušajte s 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: Pohranite tokene u varijablama okruženja
6. Rukovanje pogreškama: Implementirajte logiku ponovnog pokušaja s eksponencijalnim backoff-om
7. Praćenje korištenja: Pratite API pozive u odnosu na ograničenja vašeg plana

---

Povezana dokumentacija

• Pregled integracija
• Puna API dokumentacija
• Upravljanje bazom znanja
• SmartFlow Webhooks — Primajte događaje