Integracja API

Przesyłaj dane programowo do swojej bazy wiedzy AI SmartTalk za pomocą naszego API REST. Idealne do niestandardowych integracji, zautomatyzowanych procesów i wszelkich źródeł danych, które nie są obsługiwane przez nasze natywne konektory.

---

Przegląd

Integracja API umożliwia:

• Przesyłanie dokumentów bezpośrednio do bazy wiedzy
• Aktualizację treści programowo
• Usuwanie przestarzałych wpisów
• Budowanie niestandardowych procesów danych
• Integrację z dowolnym systemem, który może wysyłać żądania HTTP

---

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

• Aktywne konto AI SmartTalk
• Włączony dostęp do API (sprawdź swój plan)
• Podstawową wiedzę o API REST
• Narzędzie do wysyłania żądań HTTP (curl, Postman lub kod aplikacji)

---

Uzyskiwanie danych uwierzytelniających API

Krok 1: Uzyskaj ustawienia API

1. Zaloguj się na swoje konto AI SmartTalk
2. Przejdź do Ustawienia → Integracje
3. Znajdź API i kliknij Konfiguruj

Krok 2: Wygeneruj token API

1. Kliknij Wygeneruj nowy token
2. Skopiuj swój ID modelu czatu i token API
3. Przechowuj je w bezpiecznym miejscu—token jest wyświetlany tylko raz!

⚠️ Ostrzeżenie o bezpieczeństwie: Nigdy nie ujawniaj swojego tokena API w kodzie po stronie klienta ani w publicznych repozytoriach.

---

Punkty końcowe API

Podstawowy URL

https://api.aismarttalk.tech/v1

Uwierzytelnianie

Wszystkie żądania wymagają twojego tokena API w nagłówku:

Authorization: Bearer YOUR_API_TOKEN

---

Importowanie dokumentów

Punkt końcowy

POST /documents/import

Treść żądania

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Dokumentacja produktu",
      "content": "Pełna treść twojego dokumentu znajduje się tutaj...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametry

Pole	Typ	Wymagane	Opis
chatModelId	string	✅	Twój unikalny identyfikator modelu czatu
documents	array	✅	Tablica obiektów dokumentów
documents[].title	string	✅	Tytuł dokumentu do identyfikacji
documents[].content	string	✅	Pełna treść tekstowa
documents[].url	string	❌	URL źródłowy (do odniesienia)
documents[].metadata	object	❌	Niestandardowe pary klucz-wartość

Odpowiedź

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Dokumentacja produktu",
      "status": "processing"
    }
  ]
}

Przykład: 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": "Przewodnik po rozpoczęciu",
        "content": "Witamy na naszej platformie. Oto jak zacząć...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Zapytania o dokumenty

Zadawaj pytania dotyczące swojej bazy wiedzy programowo.

Punkt końcowy

POST /chat/query

Treść żądania

{
  "chatModelId": "your-chat-model-id",
  "query": "Jak zresetować hasło?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Odpowiedź

{
  "success": true,
  "response": "Aby zresetować hasło, przejdź do Ustawienia > Bezpieczeństwo > Zmień hasło...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Przewodnik po bezpieczeństwie",
      "relevance": 0.95
    }
  ]
}

---

Pobieranie dokumentów

Uzyskaj dokumenty pasujące do zapytania (bez odpowiedzi AI).

Punkt końcowy

POST /documents/search

Treść żądania

{
  "chatModelId": "your-chat-model-id",
  "query": "bezpieczeństwo hasła",
  "limit": 10
}

Odpowiedź

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Najlepsze praktyki bezpieczeństwa",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Przykłady kodu

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

# Importuj dokument
result = import_document(
    title="FAQ: Wysyłka",
    content="Oferujemy darmową wysyłkę na zamówienia powyżej 50 USD...",
    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();
}

// Importuj dokument
importDocument(
  'FAQ: Zwróty',
  'Możesz zwrócić przedmioty w ciągu 30 dni od zakupu...',
  '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' => 'Specyfikacje produktu',
            'content' => 'Nasz widget ma następujące specyfikacje...',
            '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));

---

Przykłady użycia

Niestandardowa integracja CMS

Synchronizuj treści z własnego CMS:

• Podłącz się do zdarzeń publikacji CMS
• Przesyłaj nowe/aktualizowane treści do AI SmartTalk
• Usuwaj usunięte treści

Proces danych

Importuj z hurtowni danych:

• Eksportuj odpowiednie dane do JSON
• Importuj wsadowo za pomocą API
• Zaplanuj regularne aktualizacje

Produkty e-commerce

Synchronizuj dane produktów z niestandardowych systemów:

• Opisy produktów
• Specyfikacje
• Informacje o cenach

Systemy wewnętrzne

Połącz narzędzia wewnętrzne, które nie są obsługiwane natywnie:

• Niestandardowe wiki
• Stare bazy danych
• Własne aplikacje

---

Limity żądań

Punkt końcowy	Limit żądań
Import dokumentów	100 żądań/minutę
Zapytanie	60 żądań/minutę
Wyszukiwanie	60 żądań/minutę

Uwaga: Limity żądań różnią się w zależności od planu. Skontaktuj się z pomocą techniczną w celu uzyskania wyższych limitów.

---

Obsługa błędów

Format odpowiedzi błędu

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Podany token API jest nieprawidłowy lub wygasł"
  }
}

Typowe kody błędów

Kod	Opis	Rozwiązanie
INVALID_TOKEN	Zły lub wygasły token	Wygeneruj ponownie token API
INVALID_MODEL_ID	Nieznany identyfikator modelu czatu	Sprawdź swój identyfikator modelu czatu
RATE_LIMITED	Zbyt wiele żądań	Wprowadź opóźnienie, spróbuj później
INVALID_REQUEST	Źle sformatowane ciało żądania	Sprawdź strukturę JSON
DOCUMENT_TOO_LARGE	Zawartość przekracza limit	Podziel na mniejsze dokumenty
QUOTA_EXCEEDED	Osiągnięto limity planu	Uaktualnij lub skontaktuj się z pomocą techniczną

---

Rozwiązywanie problemów

Nieudana autoryzacja

Problem	Rozwiązanie
401 Unauthorized	Sprawdź, czy token jest poprawny i aktywny
Token nie działa	Wygeneruj ponownie token w ustawieniach
Wygasły token	Tokeny nie wygasają, ale mogą zostać unieważnione

Problemy z importem

Problem	Rozwiązanie
Pusta odpowiedź	Sprawdź, czy Content-Type to application/json
Dokument się nie pojawia	Poczekaj na przetwarzanie; sprawdź sekcję Wiedza
Częściowy import	Niektóre dokumenty mogą mieć błędy walidacji

Problemy z wydajnością

Problem	Rozwiązanie
Wolne importy	Grupy dokumentów (maks. 100 na żądanie)
Przekroczenie czasu	Zmniejsz rozmiar grupy, spróbuj ponownie z opóźnieniem
Ograniczenie szybkości	Wprowadź wykładnicze opóźnienie

---

Najlepsze praktyki

1. Importy grupowe: Wysyłaj wiele dokumentów na żądanie (do 100)
2. Unikalne tytuły: Używaj opisowych, unikalnych tytułów dla każdego dokumentu
3. Strukturalna zawartość: Dobrze sformatowana zawartość poprawia odpowiedzi AI
4. Tagowanie metadanymi: Używaj metadanych do kategoryzacji i filtrowania
5. Bezpieczne tokeny: Przechowuj tokeny w zmiennych środowiskowych
6. Obsługa błędów: Wprowadź logikę ponownego próbowania z wykładniczym opóźnieniem
7. Monitorowanie użycia: Śledź wywołania API w odniesieniu do limitów swojego planu

---

Powiązana dokumentacja

• Przegląd integracji
• Pełna dokumentacja API
• Zarządzanie bazą wiedzy
• Webhooks SmartFlow — Odbieraj zdarzenia