API Integráció

Programozottan küldjön adatokat az AI SmartTalk tudásbázisába a REST API-nk segítségével. Ideális egyedi integrációkhoz, automatizált folyamatokhoz és bármilyen adatforráshoz, amelyet nem fednek le a natív csatlakozók.

---

Áttekintés

Az API integráció lehetővé teszi, hogy:

• Dokumentumokat közvetlenül küldjön a tudásbázisába
• Frissítse a tartalmat programozottan
• Törölje az elavult bejegyzéseket
• Egyedi adatfolyamatokat építsen
• Integráljon bármely olyan rendszerrel, amely HTTP kéréseket tud küldeni

---

Előfeltételek

Mielőtt elkezdené, győződjön meg arról, hogy rendelkezik:

• Aktív AI SmartTalk fiókkal
• Engedélyezett API hozzáféréssel (ellenőrizze a csomagját)
• Alapvető ismeretekkel a REST API-król
• Olyan eszközzel, amely HTTP kéréseket tud küldeni (curl, Postman, vagy az alkalmazás kódja)

---

API Hitelesítő Adatok Megszerzése

1. lépés: API Beállítások Elérése

1. Jelentkezzen be az AI SmartTalk fiókjába
2. Navigáljon a Beállítások → Integrációk menüpontra
3. Keresse meg az API lehetőséget, és kattintson a Konfigurálás gombra

2. lépés: API Token Generálása

1. Kattintson a Új Token Generálása gombra
2. Másolja a Chat Model ID-t és az API Tokent
3. Tárolja ezeket biztonságosan—az token csak egyszer jelenik meg!

⚠️ Biztonsági Figyelmeztetés: Soha ne tegye közzé az API tokenjét kliensoldali kódban vagy nyilvános tárolókban.

---

API Végpontok

Alap URL

https://api.aismarttalk.tech/v1

Hitelesítés

Minden kéréshez szükséges az API token a fejlécben:

Authorization: Bearer YOUR_API_TOKEN

---

API Végpontok

Alap URL

https://api.aismarttalk.tech/v1

Hitelesítés

Minden kéréshez szükséges az API token a fejlécben:

Authorization: Bearer YOUR_API_TOKEN

---

Dokumentumok Importálása

Végpont

POST /documents/import

Kérés Törzs

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Termék Dokumentáció",
      "content": "A dokumentum teljes tartalma itt található...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Paraméterek

Mező	Típus	Kötelező	Leírás
chatModelId	string	✅	Az Ön egyedi chat modell azonosítója
documents	array	✅	Dokumentum objektumok tömbje
documents[].title	string	✅	A dokumentum azonosításához szükséges cím
documents[].content	string	✅	Teljes szöveges tartalom
documents[].url	string	❌	Forrás URL (referenciaként)
documents[].metadata	object	❌	Egyedi kulcs-érték párok

Válasz

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Termék Dokumentáció",
      "status": "feldolgozás alatt"
    }
  ]
}

Példa: 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": "Kezdő Útmutató",
        "content": "Üdvözöljük platformunkon. Íme, hogyan kezdje el...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Dokumentumok Lekérdezése

Kérdéseket tehet fel a tudásbázisának programozottan.

Végpont

POST /chat/query

Kérés Törzs

{
  "chatModelId": "your-chat-model-id",
  "query": "Hogyan állíthatom vissza a jelszavamat?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Válasz

{
  "success": true,
  "response": "A jelszó visszaállításához lépjen a Beállítások > Biztonság > Jelszó megváltoztatása menüpontra...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Biztonsági Útmutató",
      "relevance": 0.95
    }
  ]
}

---

Dokumentumok Lekérése

Dokumentumok lekérése, amelyek megfelelnek egy lekérdezésnek (AI válasz nélkül).

Végpont

POST /documents/search

Kérés Törzs

{
  "chatModelId": "your-chat-model-id",
  "query": "jelszó biztonság",
  "limit": 10
}

Válasz

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "A legjobb biztonsági gyakorlatok",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Kód Példák

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

# Dokumentum importálása
result = import_document(
    title="GYIK: Szállítás",
    content="Ingyenes szállítást kínálunk 50 dollár feletti rendeléseknél...",
    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();
}

// Dokumentum importálása
importDocument(
  'GYIK: Visszatérések',
  'A termékeket 30 napon belül vissza lehet küldeni a vásárlást követően...',
  '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' => 'Termék specifikációk',
            'content' => 'A widgetünk a következő specifikációkkal rendelkezik...',
            '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));

---

Felhasználási Esetek

Egyedi CMS Integráció

Tartalom szinkronizálása egy saját CMS-ből:

• Csatlakozás a CMS közzétételi eseményeihez
• Új/frissített tartalom küldése az AI SmartTalk-ra
• Törölt tartalom eltávolítása

Adat Pipeline

Importálás adat raktárakból:

• Releváns adatok exportálása JSON formátumban
• Csoportos importálás API-n keresztül
• Rendszeres frissítések ütemezése

E-kereskedelmi Termékek

Termékadatok szinkronizálása egyedi rendszerekből:

• Termékleírások
• Specifikációk
• Árazási információk

Belső Rendszerek

Kapcsolódás olyan belső eszközökhöz, amelyek nincsenek natívan támogatva:

• Egyedi wikipédiák
• Örökölt adatbázisok
• Saját alkalmazások

---

Korlátozások

Végpont	Korlátozás
Dokumentum importálás	100 kérés/perc
Lekérdezés	60 kérés/perc
Keresés	60 kérés/perc

Megjegyzés: A korlátozások a tervtől függően változnak. Magasabb korlátokért lépjen kapcsolatba a támogatással.

---

Hiba kezelés

Hiba válasz formátum

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "A megadott API token érvénytelen vagy lejárt"
  }
}

Gyakori hiba kódok

Kód	Leírás	Megoldás
INVALID_TOKEN	Hibás vagy lejárt token	Generálja újra az API tokent
INVALID_MODEL_ID	Ismeretlen chat modell azonosító	Ellenőrizze a Chat Modell azonosítóját
RATE_LIMITED	Túl sok kérés	Valósítson meg visszalépést, próbálja újra később
INVALID_REQUEST	Hibás kérés törzs	Ellenőrizze a JSON struktúrát
DOCUMENT_TOO_LARGE	A tartalom meghaladja a határt	Ossza fel kisebb dokumentumokra
QUOTA_EXCEEDED	A terv korlátai elérve	Frissítse a tervet vagy lépjen kapcsolatba a támogatással

---

Hibaelhárítás

Hitelesítési hibák

Probléma	Megoldás
401 Jogosulatlan	Ellenőrizze, hogy a token helyes és aktív
Token nem működik	Generálja újra a tokent a beállításokban
Lejárt token	A tokenek nem járnak le, de visszavonhatók

Importálási problémák

Probléma	Megoldás
Üres válasz	Ellenőrizze, hogy a Content-Type application/json
Dokumentum nem jelenik meg	Várjon a feldolgozásra; ellenőrizze a Tudás szekciót
Részleges importálás	Néhány dokumentumnak lehetnek érvényességi hibái

Teljesítmény problémák

Probléma	Megoldás
Lassú importálás	Csoportosítsa a dokumentumokat (max 100 kérésenként)
Időtúllépések	Csökkentse a csoport méretét, próbálja újra visszalépéssel
Korlátozva van	Valósítson meg exponenciális visszalépést

---

Legjobb gyakorlatok

1. Csoportos importálás: Küldjön több dokumentumot egy kérésben (legfeljebb 100)
2. Egyedi címek: Használjon leíró, egyedi címeket minden dokumentumhoz
3. Strukturált tartalom: A jól formázott tartalom javítja az AI válaszokat
4. Metaadatok címkézése: Használjon metaadatokat a kategorizáláshoz és szűréshez
5. Biztonságos tokenek: Tárolja a tokeneket környezeti változókban
6. Hibák kezelése: Valósítson meg újrapróbálkozási logikát exponenciális visszalépéssel
7. Használat figyelése: Kövesse nyomon az API hívásokat a terv korlátaihoz képest

---

Kapcsolódó dokumentáció

• Integrációk áttekintése
• Teljes API dokumentáció
• Tudásbázis kezelése
• SmartFlow Webhookok — Események fogadása