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ă:

• Trimiti 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-urile REST
• Un instrument pentru a face cereri HTTP (curl, Postman sau codul aplicației tale)

---

Obținerea acreditivelor API

Pasul 1: Accesarea setărilor 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: Generarea tokenului API

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

⚠️ Avertisment de securitate: Nu expune niciodată tokenul tău API în codul de client sau în repozitorii publice.

---

Endpoint-uri API

URL de bază

https://api.aismarttalk.tech/v1

Autentificare

Toate cererile necesită tokenul tău API în antet:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Toate cererile necesită tokenul dumneavoastră API în antet:

Authorization: Bearer YOUR_API_TOKEN

---

Import Documents

Endpoint

POST /documents/import

Request Body

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

Parameters

Field	Type	Required	Description
chatModelId	string	✅	Identificatorul unic al modelului dumneavoastră 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

Response

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

Example: 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 Începere",
        "content": "Bine ați venit pe platforma noastră. Iată cum să începeți...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Query Documents

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

Endpoint

POST /chat/query

Request Body

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

Response

{
  "success": true,
  "response": "Pentru a vă reseta parola, navigați la Setări > Securitate > Schimbați Parola...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Ghid de Securitate",
      "relevance": 0.95
    }
  ]
}

---

Retrieve Documents

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

Endpoint

POST /documents/search

Request Body

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

Response

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

# Importa un document
result = import_document(
    title="FAQ: 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();
}

// Importa un document
importDocument(
  'FAQ: Returnări',
  'Puteț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ții Produs',
            '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

Integrare CMS Personalizat

Sincronizați conținutul dintr-un CMS proprietar:

• Conectați-vă la evenimentele de publicare ale CMS-ului
• Trimiteți conținut nou/actualizat către AI SmartTalk
• Îndepărtați conținutul șters

Pipeline de Date

Importați din depozite de date:

• Exportați datele relevante în JSON
• Import în loturi prin API
• Programați actualizări regulate

Produse E-commerce

Sincronizați datele produselor din sisteme personalizate:

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

Sisteme Interne

Conectați instrumente interne care nu sunt suportate nativ:

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

---

Limitele 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. Contactați 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	Faceți upgrade sau contactați suportul

---

Depanare

Autentificarea Eșuează

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 cu backoff
Limitat de rată	Implementați backoff exponențial

---

Cele Mai Bune Practici

1. Importuri batch: Trimiteți mai multe documente per cerere (până la 100)
2. Titluri unice: Utilizaț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: Utilizați metadate pentru categorizare ș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
• Webhook-uri SmartFlow — Primiți evenimente