API ინტეგრაცია

გადაიტანეთ მონაცემები პროგრამულად თქვენს AI SmartTalk ცოდნის ბაზაში ჩვენი REST API-ის გამოყენებით. იდეალურია მორგებული ინტეგრაციისთვის, ავტომატური pipelines-ისთვის და ნებისმიერი მონაცემთა წყაროსთვის, რომელიც არ არის დაფარული ჩვენი ადგილობრივი კავშირებით.

---

მიმოხილვა

API ინტეგრაცია საშუალებას გაწვდით:

• დოკუმენტების პირდაპირ გადატანას თქვენს ცოდნის ბაზაში
• შინაარსის პროგრამულად განახლებას
• ძველ ჩანაწერების წაშლას
• მორგებული მონაცემთა pipelines-ის შექმნას
• ინტეგრაციას ნებისმიერი სისტემისთან, რომელიც HTTP მოთხოვნებს აკეთებს

---

წინაპირობები

წინასწარ დარწმუნდით, რომ გაქვთ:

• აქტიური AI SmartTalk ანგარიში
• API ხელმისაწვდომობა ჩართული (გადახედეთ თქვენს გეგმას)
• REST API-ების საფუძვლიანი ცოდნა
• HTTP მოთხოვნების გაკეთების ინსტრუმენტი (curl, Postman, ან თქვენი აპლიკაციის კოდი)

---

თქვენი API სერტიფიკატების მიღება

ნაბიჯი 1: API პარამეტრების წვდომა

1. შედით თქვენს AI SmartTalk ანგარიშში
2. გადადით პარამეტრები → ინტეგრაციები
3. მოიძიეთ API და დააწკაპეთ კონფიგურაცია

ნაბიჯი 2: API ტოკენის გენერირება

1. დააწკაპეთ ახალი ტოკენის გენერირება
2. ასწერეთ თქვენი ჩატ მოდელის ID და API ტოკენი
3. შეინახეთ ეს უსაფრთხოდ—ტოკენი მხოლოდ ერთხელ ჩანს!

⚠️ უსაფრთხოების გაფრთხილება: არასოდეს გაამჟღავნოთ თქვენი API ტოკენი კლიენტური კოდის ან საჯარო რეპოზიტორიუმების შიგნით.

---

API ბოლო წერტილები

ბაზური URL

https://api.aismarttalk.tech/v1

ავტორიზაცია

ყველა მოთხოვნა მოითხოვს თქვენს API ტოკენს სათაურის შიგნით:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

ყველა მოთხოვნა საჭიროებს თქვენს API ტოკენს სათაურებში:

Authorization: Bearer YOUR_API_TOKEN

---

Import Documents

Endpoint

POST /documents/import

Request Body

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Product Documentation",
      "content": "Full content of your document goes here...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parameters

Field	Type	Required	Description
chatModelId	string	✅	თქვენი უნიკალური ჩატის მოდელის იდენტიფიკატორი
documents	array	✅	დოკუმენტების ობიექტების მასივი
documents[].title	string	✅	დოკუმენტის სათაური იდენტიფიკაციისთვის
documents[].content	string	✅	სრული ტექსტური შინაარსი
documents[].url	string	❌	წყაროს URL (საკონტროლო)
documents[].metadata	object	❌	მომხმარებლის მიერ განსაზღვრული გასაღები-ფასების წყვილები

Response

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Product Documentation",
      "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": "Getting Started Guide",
        "content": "Welcome to our platform. Here is how to get started...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Query Documents

დაყენეთ კითხვები თქვენი ცოდნის ბაზის წინააღმდეგ პროგრამულად.

Endpoint

POST /chat/query

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "How do I reset my password?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Response

{
  "success": true,
  "response": "To reset your password, navigate to Settings > Security > Change Password...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Security Guide",
      "relevance": 0.95
    }
  ]
}

---

Retrieve Documents

მიიღეთ დოკუმენტები, რომლებიც შეესაბამება კითხვას (AI პასუხის გარეშე).

Endpoint

POST /documents/search

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "password security",
  "limit": 10
}

Response

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Security Best Practices",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

კოდის მაგალითები

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

# დოკუმენტის იმპორტი
result = import_document(
    title="FAQ: გადაზიდვა",
    content="ჩვენ ვთავაზობთ უფასო გადაზიდვას $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();
}

// დოკუმენტის იმპორტი
importDocument(
  'FAQ: დაბრუნება',
  'თქვენ შეგიძლიათ დაბრუნოთ ნივთები 30 დღის განმავლობაში შეძენის შემდეგ...',
  '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' => 'პროდუქტის სპეციფიკაციები',
            'content' => 'ჩვენი ვიჯეტი აქვს შემდეგი სპეციფიკაციები...',
            '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));

---

გამოყენების შემთხვევები

მორგებული CMS ინტეგრაცია

შინაარსის სინქრონიზაცია საკუთრების CMS-დან:

• ჩართეთ CMS-ის გამოქვეყნების მოვლენებში
• ახალი/განახლებული შინაარსის გადაგზავნა AI SmartTalk-ში
• წაშლილი შინაარსის ამოღება

მონაცემთა pipeline

იმპორტი მონაცემთა საწყობებიდან:

• შესაბამისი მონაცემების ექსპორტი JSON-ის ფორმატში
• ჯგუფური იმპორტი API-ის მეშვეობით
• რეგულარული განახლებების განრიგი

ელექტრონული კომერციის პროდუქტები

პროდუქტის მონაცემების სინქრონიზაცია მორგებული სისტემებიდან:

• პროდუქტის აღწერილობები
• სპეციფიკაციები
• ფასების ინფორმაცია

შიდა სისტემები

შიდა ინსტრუმენტების დაკავშირება, რომლებიც ბუნებრივად არ არის მხარდაჭერილი:

• მორგებული ვიკი
• ძველი მონაცემთა ბაზები
• საკუთრების აპლიკაციები

---

სიჩქარის შეზღუდვები

Endpoint	სიჩქარის შეზღუდვა
დოკუმენტის იმპორტი	100 მოთხოვნა/წუთში
კითხვები	60 მოთხოვნა/წუთში
ძიება	60 მოთხოვნა/წუთში

შენიშვნა: სიჩქარის შეზღუდვები განსხვავდება გეგმების მიხედვით. მაღალი შეზღუდვებისათვის დაუკავშირდით მხარდაჭერას.

---

შეცდომების მართვა

შეცდომის პასუხის ფორმატი

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "მოცემული API ტოკენი არასწორია ან ვადა გაუვიდა"
  }
}

გავრცელებული შეცდომის კოდები

კოდი	აღწერა	გადაწყვეტა
INVALID_TOKEN	ცუდი ან ვადა გასული ტოკენი	გენერირება API ტოკენის
INVALID_MODEL_ID	უცნობი ჩატ მოდელის ID	შეამოწმეთ თქვენი ჩატ მოდელის ID
RATE_LIMITED	ძალიან ბევრი მოთხოვნა	შეასრულეთ უკან დახევა, სცადეთ მოგვიანებით
INVALID_REQUEST	არასწორი მოთხოვნის სხეული	შეამოწმეთ JSON სტრუქტურა
DOCUMENT_TOO_LARGE	შინაარსი აღემატება შეზღუდვას	გაყავით უფრო მცირე დოკუმენტებად
QUOTA_EXCEEDED	გეგმის შეზღუდვები მიღწეულია	განაახლეთ ან დაუკავშირდით მხარდაჭერას

---

პრობლემების გადაჭრა

ავტორიზაციის წარუმატებლობა

პრობლემა	გადაწყვეტა
401 ავტორიზაცია უარყოფილია	შეამოწმეთ, რომ ტოკენი სწორია და აქტიურია
ტოკენი არ მუშაობს	გენერირება ტოკენის პარამეტრებში
ვადა გასული ტოკენი	ტოკენები არ ვადა გასდის, მაგრამ შეიძლება გაუქმდეს

იმპორტის პრობლემები

პრობლემა	გადაწყვეტა
ცარიელი პასუხი	შეამოწმეთ Content-Type არის application/json
დოკუმენტი არ ჩანს	დაელოდეთ პროცესირებას; შეამოწმეთ ცოდნის განყოფილება
ნაწილობრივი იმპორტი	ზოგი დოკუმენტი შეიძლება შეიცავდეს ვალიდაციის შეცდომებს

შესრულების პრობლემები

პრობლემა	გადაწყვეტა
ნელი იმპორტი	ჯგუფური დოკუმენტები (მაქსიმუმ 100 თითო მოთხოვნაზე)
დროის გასვლის პრობლემა	შეამცირეთ ჯგუფის ზომა, სცადეთ უკან დახევით
სიჩქარის შეზღუდვა	შეასრულეთ ექსპონენტური უკან დახევა

---

საუკეთესო პრაქტიკა

1. ჯგუფური იმპორტი: გააგზავნეთ რამდენიმე დოკუმენტი თითო მოთხოვნაზე (მაქსიმუმ 100)
2. უნიკალური სათაურები: გამოიყენეთ აღწერითი, უნიკალური სათაურები თითო დოკუმენტისთვის
3. სტრუქტურირებული შინაარსი: კარგად ფორმატირებული შინაარსი აუმჯობესებს AI პასუხებს
4. მეტადატა ტეგირება: გამოიყენეთ მეტადატა კატეგორიზაციისა და ფილტრაციისათვის
5. უსაფრთხო ტოკენები: შეინახეთ ტოკენები გარემოს ცვლადებში
6. შეცდომების მართვა: შეასრულეთ ხელახალი მცდელობის ლოგიკა ექსპონენტური უკან დახევით
7. გამოყენების მონიტორინგი: დააკვირდით API ზარებზე თქვენი გეგმის შეზღუდვებთან მიმართებაში

---

დაკავშირებული დოკუმენტაცია

• ინტეგრაციების მიმოხილვა
• სრული API დოკუმენტაცია
• ცოდნის ბაზის მართვა
• SmartFlow Webhooks — მიიღეთ მოვლენები