API Интеграција

Пуштете податоци програмски во вашата AI SmartTalk база на знаење користејќи ја нашата REST API. Идеално за прилагодени интеграции, автоматизирани канали и секој извор на податоци кој не е покриен од нашите вградени конектори.

---

Преглед

API интеграцијата ви овозможува:

• Да пуштите документи директно во вашата база на знаење
• Да ажурирате содржина програмски
• Да избришете застарени записи
• Да изградите прилагодени канали за податоци
• Да интегрирате со било кој систем кој може да прави HTTP барања

---

Предуслови

Пред да започнете, осигурајте се дека имате:

• Активен AI SmartTalk акаунт
• Вклучен API пристап (проверете го вашиот план)
• Основно знаење за REST APIs
• Алатка за правење HTTP барања (curl, Postman, или вашиот апликациски код)

---

Како да ги добиете вашите API акредитиви

Чекор 1: Достап до API Поставки

1. Најавете се во вашиот AI SmartTalk акаунт
2. Отидете на Поставки → Интеграции
3. Најдете API и кликнете Конфигурирај

Чекор 2: Генерирајте API Токен

1. Кликнете Генерирај Нов Токен
2. Копирајте го вашиот Chat Model 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="ЧПП: Испорака",
    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(
  'ЧПП: Враќања',
  'Можете да ги вратите артиклите во рок од 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
• Отстранете избришана содржина

Податочен Провод

Импорт од складишта на податоци:

• Извезете релевантни податоци во JSON
• Импорт во серија преку API
• Планирајте редовни ажурирања

Производи за електронска трговија

Синхронизирајте податоци за производи од прилагодени системи:

• Опис на производи
• Спецификации
• Информации за цени

Внатрешни системи

Поврзете внатрешни алатки кои не се поддржани нативно:

• Прилагодени вики
• Наследни бази на податоци
• Сопствени апликации

---

Ограничувања на стапките

Ендпоинт	Ограничување на стапките
Увоз на документи	100 барања/минута
Запрашување	60 барања/минута
Пребарување	60 барања/минута

Забелешка: Ограничувањата на стапките варираат во зависност од планот. Контактирајте ја поддршката за повисоки ограничувања.

---

Управување со грешки

Формат на одговор на грешка

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided API token is invalid or expired"
  }
}

Чести кодови на грешки

Код	Опис	Решение
INVALID_TOKEN	Лош или истечен токен	Регегенерирајте го API токенот
INVALID_MODEL_ID	Непознат ID на модел за разговор	Проверете го вашиот ID на моделот за разговор
RATE_LIMITED	Превише барања	Имплементирајте backoff, обидете се повторно подоцна
INVALID_REQUEST	Неправилно оформено тело на барањето	Проверете ја JSON структурата
DOCUMENT_TOO_LARGE	Содржината ја надминува границата	Поделете на помали документи
QUOTA_EXCEEDED	Достигнати ограничувања на планот	Надградете или контактирајте ја поддршката

---

Решавање проблеми

Неуспех на автентикација

Проблем	Решение
401 Неовластен	Проверете дали токенот е точен и активен
Токенот не работи	Регегенерирајте го токенот во поставките
Истечен токен	Токените не истекуваат, но можат да бидат поништени

Проблеми со увоз

Проблем	Решение
Празен одговор	Проверете дали Content-Type е application/json
Документот не се појавува	Чекајте за обработка; проверете ја секцијата за знаење
Делумен увоз	Некои документи можеби имаат грешки во валидацијата

Проблеми со перформанси

Проблем	Решение
Бавен увоз	Групирајте документи (максимум 100 по барање)
Време на чекање	Намалете ја големината на групата, обидете се повторно со backoff
Ограничени стапки	Имплементирајте експоненцијален backoff

---

Најдобри практики

1. Групирање на увоз: Испратете повеќе документи по барање (до 100)
2. Уникатни наслови: Користете описни, уникатни наслови за секој документ
3. Структурирана содржина: Добро оформената содржина ги подобрува одговорите на AI
4. Тагирање на метаподатоци: Користете метаподатоци за категоризација и филтрирање
5. Сигурни токени: Чувајте ги токените во променливи на средината
6. Управување со грешки: Имплементирајте логика за повторување со експоненцијален backoff
7. Следете го користењето: Следете ги API повиците во однос на ограничувањата на вашиот план

---

Поврзана документација

• Преглед на интеграции
• Целосна документација за API
• Управување со база на знаење
• SmartFlow Webhooks — Примете настани