API Integration

Προγραμματίστε την αποστολή δεδομένων στη βάση γνώσεων AI SmartTalk χρησιμοποιώντας το REST API μας. Ιδανικό για προσαρμοσμένες ενσωματώσεις, αυτοματοποιημένες ροές εργασίας και οποιαδήποτε πηγή δεδομένων που δεν καλύπτεται από τους εγγενείς συνδέσμους μας.

---

Overview

Η ενσωμάτωση API σας επιτρέπει να:

• Προωθείτε έγγραφα απευθείας στη βάση γνώσεών σας
• Ενημερώνετε περιεχόμενο προγραμματισμένα
• Διαγράφετε παρωχημένες καταχωρίσεις
• Δημιουργείτε προσαρμοσμένες ροές δεδομένων
• Ενσωματώνεστε με οποιοδήποτε σύστημα μπορεί να κάνει HTTP αιτήσεις

---

Prerequisites

Πριν ξεκινήσετε, βεβαιωθείτε ότι έχετε:

• Έναν ενεργό λογαριασμό AI SmartTalk
• Ενεργοποιημένη πρόσβαση API (ελέγξτε το πλάνο σας)
• Βασικές γνώσεις για REST APIs
• Ένα εργαλείο για την εκτέλεση HTTP αιτήσεων (curl, Postman ή τον κωδικό της εφαρμογής σας)

---

Getting Your API Credentials

Step 1: Access API Settings

1. Συνδεθείτε στον λογαριασμό σας AI SmartTalk
2. Μεταβείτε στις Ρυθμίσεις → Ενσωματώσεις
3. Βρείτε το API και κάντε κλικ στο Ρύθμιση

Step 2: Generate API Token

1. Κάντε κλικ στο Δημιουργία Νέου Τοκέν
2. Αντιγράψτε το Chat Model ID και το API Token
3. Αποθηκεύστε τα με ασφάλεια—το τοκέν εμφανίζεται μόνο μία φορά!

⚠️ Προειδοποίηση Ασφαλείας: Ποτέ μην εκθέτετε το API token σας σε κωδικό πελάτη ή δημόσιες αποθήκες.

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Όλες οι αιτήσεις απαιτούν το API token σας στο header:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Όλες οι αιτήσεις απαιτούν το API token σας στην κεφαλίδα:

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' => 'Το widget μας έχει τις παρακάτω προδιαγραφές...',
            '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
• Προγραμματισμός τακτικών ενημερώσεων

Προϊόντα Ηλεκτρονικού Εμπορίου

Συγχρονίστε δεδομένα προϊόντων από προσαρμοσμένα συστήματα:

• Περιγραφές προϊόντων
• Προδιαγραφές
• Πληροφορίες τιμολόγησης

Εσωτερικά Συστήματα

Συνδέστε εσωτερικά εργαλεία που δεν υποστηρίζονται εγγενώς:

• Προσαρμοσμένα wiki
• Παλιές βάσεις δεδομένων
• Ιδιόκτητες εφαρμογές

---

Όρια Ρυθμίσεων

Τερματικό	Όριο Ρυθμίσεων
Εισαγωγή Εγγράφου	100 αιτήσεις/λεπτό
Ερώτηση	60 αιτήσεις/λεπτό
Αναζήτηση	60 αιτήσεις/λεπτό

Σημείωση: Τα όρια ρυθμίσεων διαφέρουν ανάλογα με το σχέδιο. Επικοινωνήστε με την υποστήριξη για υψηλότερα όρια.

---

Διαχείριση Σφαλμάτων

Μορφή Απόκρισης Σφάλματος

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

Κοινά Κωδικοί Σφαλμάτων

Κωδικός	Περιγραφή	Λύση
INVALID_TOKEN	Κακός ή ληγμένος κωδικός	Αναγεννήστε τον API κωδικό
INVALID_MODEL_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 — Λάβετε γεγονότα