Integrarea API

Trimite date programatic în baza ta de cunoștințe AI SmartTalk folosind API-ul nostru REST. Ideal pentru integrații personalizate, pipeline-uri automate și orice sursă de date care nu este acoperită de conectorii noștri nativi.

---

Prezentare generală

Integrarea API-ului îți permite să:

• Trimite documente direct în baza ta de cunoștințe
• Actualizezi conținutul programatic
• Ștergi intrările învechite
• Construiești pipeline-uri de date personalizate
• Integrezi cu orice sistem care poate face cereri HTTP

---

Cerințe preliminare

Înainte de a începe, asigură-te că ai:

• Un cont activ AI SmartTalk
• Acces API activat (verifică-ți planul)
• Cunoștințe de bază despre API-uri REST
• Un instrument pentru a face cereri HTTP (curl, Postman sau codul aplicației tale)

---

Obținerea acreditivelor API

Pasul 1: Accesează setările API

1. Conectează-te la contul tău AI SmartTalk
2. Navighează la Setări → Integrări
3. Găsește API și dă clic pe Configurează

Pasul 2: Generează token-ul API

1. Dă clic pe Generează token nou
2. Copiază ID-ul modelului de chat și Token-ul API
3. Stochează-le în siguranță—token-ul este afișat o singură dată!

⚠️ Avertisment de securitate: Nu expune niciodată token-ul tău API în codul de client sau în repositoare publice.

---

Endpoint-uri API

URL de bază

https://api.aismarttalk.tech/v1

Autentificare

Toate cererile necesită token-ul tău API în antet:

Authorization: Bearer YOUR_API_TOKEN

---

Importă Documente

Endpoint

POST /documents/import

Corpul cererii

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Documentația produsului",
      "content": "Conținutul complet al documentului tău merge aici...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentație",
        "language": "en"
      }
    }
  ]
}

Parametrii

Câmp	Tip	Necesare	Descriere
chatModelId	string	✅	Identificatorul tău unic al modelului de chat
documents	array	✅	Array de obiecte document
documents[].title	string	✅	Titlul documentului pentru identificare
documents[].content	string	✅	Conținutul text complet
documents[].url	string	❌	URL-ul sursă (pentru referință)
documents[].metadata	object	❌	Perechi cheie-valoare personalizate

Răspuns

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Documentația produsului",
      "status": "processing"
    }
  ]
}

Exemplu: 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": "Ghid de început",
        "content": "Bine ai venit pe platforma noastră. Iată cum să începi...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Interoghează Documente

Pune întrebări împotriva bazei tale de cunoștințe programatic.

Endpoint

POST /chat/query

Corpul cererii

{
  "chatModelId": "your-chat-model-id",
  "query": "Cum îmi resetez parola?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Răspuns

{
  "success": true,
  "response": "Pentru a-ți reseta parola, navighează la Setări > Securitate > Schimbă parola...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Ghid de securitate",
      "relevance": 0.95
    }
  ]
}

---

Recuperează Documente

Obține documente care se potrivesc unei interogări (fără răspuns AI).

Endpoint

POST /documents/search

Corpul cererii

{
  "chatModelId": "your-chat-model-id",
  "query": "securitatea parolei",
  "limit": 10
}

Răspuns

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Cele mai bune practici de securitate",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Exemple de Cod

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

# Importă un document
result = import_document(
    title="Întrebări frecvente: Livrare",
    content="Oferim livrare gratuită pentru comenzi de peste 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();
}

// Importă un document
importDocument(
  'Întrebări frecvente: Returnări',
  'Poți returna articole în termen de 30 de zile de la achiziție...',
  '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' => 'Specificațiile produsului',
            'content' => 'Widget-ul nostru are următoarele specificații...',
            '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));

---

Cazuri de utilizare

Integrarea CMS personalizat

Sincronizează conținut dintr-un CMS proprietar:

• Conectează-te la evenimentele de publicare ale CMS-ului
• Trimite conținut nou/actualizat către AI SmartTalk
• Elimină conținutul șters

Pipeline de date

Importă din depozite de date:

• Exportă date relevante în JSON
• Importă în loturi prin API
• Programează actualizări regulate

Produse de comerț electronic

Sincronizează datele produselor din sisteme personalizate:

• Descrieri ale produselor
• Specificații
• Informații despre prețuri

Sisteme interne

Conectează instrumente interne care nu sunt suportate nativ:

• Wiki-uri personalizate
• Baze de date moștenite
• Aplicații proprietare

---

Limite de rată

Endpoint	Limită de rată
Import document	100 cereri/minut
Interogare	60 cereri/minut
Căutare	60 cereri/minut

Notă: Limitele de rată variază în funcție de plan. Contactează suportul pentru limite mai mari.

---

Gestionarea Erorilor

Formatul Răspunsului de Eroare

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Tokenul API furnizat este invalid sau a expirat"
  }
}

Coduri Comune de Eroare

Cod	Descriere	Soluție
INVALID_TOKEN	Token invalid sau expirat	Regenerați tokenul API
INVALID_MODEL_ID	ID-ul modelului de chat necunoscut	Verificați ID-ul modelului de chat
RATE_LIMITED	Prea multe cereri	Implementați backoff, încercați mai târziu
INVALID_REQUEST	Corpul cererii este formatat greșit	Verificați structura JSON
DOCUMENT_TOO_LARGE	Conținutul depășește limita	Împărțiți în documente mai mici
QUOTA_EXCEEDED	Limitele planului au fost atinse	Upgrade sau contactați suportul

---

Depanare

Eșecuri de Autentificare

Problemă	Soluție
401 Neautorizat	Verificați dacă tokenul este corect și activ
Tokenul nu funcționează	Regenerați tokenul în setări
Token expirat	Tokenurile nu expiră, dar pot fi revocate

Probleme de Import

Problemă	Soluție
Răspuns gol	Verificați dacă Content-Type este application/json
Documentul nu apare	Așteptați procesarea; verificați secțiunea Cunoștințe
Import parțial	Unele documente pot avea erori de validare

Probleme de Performanță

Problemă	Soluție
Importuri lente	Batch documente (max 100 per cerere)
Timeout-uri	Reduceți dimensiunea batch-ului, încercați din nou cu backoff
Limită de rată	Implementați backoff exponențial

---

Cele Mai Bune Practici

1. Importuri în loturi: Trimiteți mai multe documente per cerere (până la 100)
2. Titluri unice: Folosiți titluri descriptive și unice pentru fiecare document
3. Conținut structurat: Conținutul bine formatat îmbunătățește răspunsurile AI
4. Etichetarea metadatelor: Folosiți metadate pentru categorisire și filtrare
5. Tokenuri securizate: Stocați tokenurile în variabile de mediu
6. Gestionați erorile: Implementați logică de retry cu backoff exponențial
7. Monitorizați utilizarea: Urmăriți apelurile API în raport cu limitele planului dumneavoastră

---

Documentație Asemănătoare

• Prezentare Generală a Integrărilor
• Documentația Completă API
• Gestionarea Bazei de Cunoștințe
• Webhooks SmartFlow — Primiți evenimente