Integracja API

Przesyłaj dane programowo do swojej bazy wiedzy AI SmartTalk za pomocą naszego API REST. Idealne do niestandardowych integracji, zautomatyzowanych pipeline'ów oraz wszelkich źródeł danych, które nie są objęte naszymi natywnymi konektorami.

---

Przegląd

Integracja API umożliwia Ci:

• Przesyłanie dokumentów bezpośrednio do bazy wiedzy
• Aktualizowanie treści programowo
• Usuwanie przestarzałych wpisów
• Budowanie niestandardowych pipeline'ó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 Skonfiguruj

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

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

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

Authorization: Bearer YOUR_API_TOKEN

---

Import Documents

Endpoint

POST /documents/import

Request Body

{
  "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"
      }
    }
  ]
}

Parameters

Field	Type	Required	Description
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	❌	Źródłowy URL (dla odniesienia)
documents[].metadata	object	❌	Niestandardowe pary klucz-wartość

Response

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Dokumentacja Produktu",
      "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": "Przewodnik po rozpoczęciu",
        "content": "Witamy na naszej platformie. Oto jak zacząć...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Query Documents

Zadawaj pytania dotyczące swojej bazy wiedzy programowo.

Endpoint

POST /chat/query

Request Body

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

Response

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

---

Retrieve Documents

Pobierz dokumenty odpowiadające zapytaniu (bez odpowiedzi AI).

Endpoint

POST /documents/search

Request Body

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

Response

{
  "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ę przy zamówieniach powyżej 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();
}

// Importuj dokument
importDocument(
  'FAQ: Zwroty',
  '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));

---

Przypadki użycia

Integracja z niestandardowym CMS

Synchronizacja treści z własnego CMS:

• Połączenie z wydarzeniami publikacji CMS
• Przesyłanie nowych/aktualizowanych treści do AI SmartTalk
• Usuwanie usuniętych treści

Pipeline danych

Import z hurtowni danych:

• Eksport odpowiednich danych do JSON
• Import wsadowy przez API
• Planowanie regularnych aktualizacji

Produkty e-commerce

Synchronizacja danych produktów z niestandardowych systemów:

• Opisy produktów
• Specyfikacje
• Informacje o cenach

Systemy wewnętrzne

Połączenie z narzędziami wewnętrznymi, które nie są wspierane natywnie:

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

---

Limity Żądań

Endpoint	Limit Żądań
Import Dokumentu	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łędów

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

Problemy z Uwierzytelnieniem

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ą być unieważnione

Problemy z Importem

Problem	Rozwiązanie
Pusta odpowiedź	Sprawdź, czy Content-Type to application/json
Dokument nie pojawia się	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	Grupuj dokumenty (maks. 100 na żądanie)
Przekroczenie czasu	Zmniejsz rozmiar grupy, spróbuj ponownie z opóźnieniem
Ograniczenie żądań	Wprowadź wykładnicze opóźnienie

---

Najlepsze Praktyki

1. Grupowanie importów: 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