Integrimi i API

Shtyni të dhënat programatikisht në bazën tuaj të njohurive AI SmartTalk duke përdorur API-në tonë REST. Ideale për integrime të personalizuara, pipeline automatizuar dhe çdo burim të dhënash që nuk mbulohet nga lidhësit tanë natyrorë.

---

Përmbledhje

Integrimi i API ju mundëson të:

• Shtyni dokumente direkt në bazën tuaj të njohurive
• Përditësoni përmbajtjen programatikisht
• Fshini hyrjet e vjetra
• Ndërtoni pipeline të dhënash të personalizuara
• Integroni me çdo sistem që mund të bëjë kërkesa HTTP

---

Kërkesat e Paraburgimit

Para se të filloni, sigurohuni që keni:

• Një llogari aktive AI SmartTalk
• Qasje në API të aktivizuar (kontrolloni planin tuaj)
• Njohuri bazike mbi REST APIs
• Një mjet për të bërë kërkesa HTTP (curl, Postman, ose kodi i aplikacionit tuaj)

---

Marrja e Kredencialeve tuaja të API

Hapi 1: Qasja në Cilësimet e API

1. Hyni në llogarinë tuaj AI SmartTalk
2. Shkoni te Cilësimet → Integrimet
3. Gjeni API dhe klikoni Konfiguro

Hapi 2: Gjeneroni Tokenin e API

1. Klikoni Gjeneroni Token të Ri
2. Kopjoni ID-në e Modelit të Bisedës dhe Tokenin e API
3. Ruani këto në mënyrë të sigurt—tokeni tregohet vetëm një herë!

⚠️ Kujdes për Sigurinë: Kurrë mos e ekspozoni tokenin tuaj të API në kodin e anës së klientit ose në depo publike.

---

Pikat e Fundit të API

URL Baze

https://api.aismarttalk.tech/v1

Autentifikimi

Të gjitha kërkesat kërkojnë tokenin tuaj të API në header:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Të gjitha kërkesat kërkojnë token-in tuaj të API në header:

Authorization: Bearer YOUR_API_TOKEN

---

Import Documents

Endpoint

POST /documents/import

Request Body

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Dokumentacioni i Produktit",
      "content": "Përmbajtja e plotë e dokumentit tuaj shkon këtu...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parameters

Field	Type	Required	Description
chatModelId	string	✅	Identifikuesi juaj unik i modelit të bisedës
documents	array	✅	Array e objekteve të dokumenteve
documents[].title	string	✅	Titulli i dokumentit për identifikim
documents[].content	string	✅	Përmbajtja e plotë e tekstit
documents[].url	string	❌	URL burimi (për referencë)
documents[].metadata	object	❌	Çiftet e çelësit-vlerës

Response

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Dokumentacioni i Produktit",
      "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": "Udhëzuesi për Fillestarët",
        "content": "Mirë se vini në platformën tonë. Ja si të filloni...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Query Documents

Bëni pyetje ndaj bazës suaj të njohurive në mënyrë programatike.

Endpoint

POST /chat/query

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "Si ta rivendos password-in tim?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Response

{
  "success": true,
  "response": "Për të rivendosur password-in tuaj, navigoni në Cilësimet > Siguria > Ndrysho Password-in...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Udhëzuesi për Sigurinë",
      "relevance": 0.95
    }
  ]
}

---

Retrieve Documents

Merrni dokumente që përputhen me një kërkesë (pa përgjigje nga AI).

Endpoint

POST /documents/search

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "siguria e password-it",
  "limit": 10
}

Response

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Praktikat më të Mira të Sigurisë",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Shembuj Kodi

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 a document
result = import_document(
    title="FAQ: Dërgesa",
    content="Ne ofrojmë dërgesë falas për porositë mbi $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 a document
importDocument(
  'FAQ: Kthimet',
  'Mund të ktheni artikuj brenda 30 ditëve nga blerja...',
  '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' => 'Specifikimet e Produktit',
            'content' => 'Widgeti ynë ka këto specifikime...',
            '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));

---

Rastet e Përdorimit

Integrimi i CMS të Personalizuar

Sinkronizoni përmbajtjen nga një CMS pronësor:

• Lidheni me ngjarjet e publikimit të CMS
• Dërgoni përmbajtje të reja/ të përditësuara në AI SmartTalk
• Hiqni përmbajtjen e fshirë

Pipeline të Dhënash

Importoni nga depozitë të dhënash:

• Eksportoni të dhënat përkatëse në JSON
• Importoni në grupe përmes API
• Planifikoni përditësime të rregullta

Produkte E-commerce

Sinkronizoni të dhënat e produkteve nga sisteme të personalizuara:

• Përshkrimet e produkteve
• Specifikimet
• Informacioni mbi çmimet

Sistemet e Brendshme

Lidhni mjetet e brendshme që nuk mbështeten natyrshëm:

• Wiki të personalizuara
• Baza të dhënash të vjetra
• Aplikacione pronësore

---

Kufijtë e Normave

Endpoint	Kufiri i Normave
Importimi i Dokumenteve	100 kërkesa/minutë
Kërkesa	60 kërkesa/minutë
Kërkimi	60 kërkesa/minutë

Shënim: Kufijtë e normave ndryshojnë sipas planit. Kontaktoni mbështetje për kufij më të lartë.

---

Trajtimi i Gabimeve

Formati i Përgjigjes për Gabimin

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Tokeni i ofruar i API është i pavlefshëm ose ka skaduar"
  }
}

Kodet e zakonshme të Gabimeve

Kodi	Përshkrimi	Zgjidhja
INVALID_TOKEN	Token i keq ose i skaduar	Regjeneroni tokenin e API
INVALID_MODEL_ID	ID e modelit të bisedës e panjohur	Kontrolloni ID-në tuaj të Modelit të Bisedës
RATE_LIMITED	Shumë kërkesa	Zbatoni një strategji prapambetje, provoni më vonë
INVALID_REQUEST	Trupi i kërkesës është i deformuar	Kontrolloni strukturën e JSON-it
DOCUMENT_TOO_LARGE	Përmbajtja tejkalon kufirin	Ndani në dokumente më të vogla
QUOTA_EXCEEDED	Kufijtë e planit janë arritur	Përmirësoni ose kontaktoni mbështetje

---

Zgjidhja e Problemeve

Dështimi i Autentifikimit

Problemi	Zgjidhja
401 Pa autorizim	Kontrolloni që tokeni është i saktë dhe aktiv
Tokeni nuk funksionon	Regjeneroni tokenin në cilësime
Token i skaduar	Tokenët nuk skadojnë, por mund të revokohen

Probleme me Importimin

Problemi	Zgjidhja
Përgjigje e zbrazët	Kontrolloni që Content-Type është application/json
Dokumenti nuk po shfaqet	Prisni për përpunim; kontrolloni seksionin e Njohurive
Importim i pjesshëm	Disa dokumente mund të kenë gabime validimi

Probleme me Performancën

Problemi	Zgjidhja
Importime të ngadalta	Gruponi dokumentet (maksimum 100 për kërkesë)
Kohëzgjatjet	Reduktoni madhësinë e grupit, provoni përsëri me prapambetje
Kufizuar nga norma	Zbatoni prapambetje eksponenciale

---

Praktikat më të Mira

1. Importime në grup: Dërgoni shumë dokumente për kërkesë (deri në 100)
2. Tituj unikë: Përdorni tituj përshkrues dhe unikë për çdo dokument
3. Përmbajtje e strukturuar: Përmbajtja e mirëformatuar përmirëson përgjigjet e AI
4. Etiketimi i metadatas: Përdorni metadata për kategorizim dhe filtrimin
5. Tokenë të sigurt: Ruani tokenët në variablat e mjedisit
6. Trajtoni gabimet: Zbatoni logjikën e rikthimit me prapambetje eksponenciale
7. Monitoroni përdorimin: Ndjekni thirrjet e API-së në raport me kufijtë e planit tuaj

---

Dokumentacioni i Lidhuar

• Përmbledhja e Integrimeve
• Dokumentacioni i Plotë i API
• Menaxhimi i Bazës së Njohurive
• Webhook-et e SmartFlow — Merrni ngjarje