Integrazione API

Invia dati programmaticamente alla tua base di conoscenza AI SmartTalk utilizzando la nostra API REST. Ideale per integrazioni personalizzate, pipeline automatizzate e qualsiasi fonte di dati non coperta dai nostri connettori nativi.

---

Panoramica

L'integrazione API ti consente di:

• Inviare documenti direttamente alla tua base di conoscenza
• Aggiornare contenuti programmaticamente
• Eliminare voci obsolete
• Costruire pipeline di dati personalizzate
• Integrarsi con qualsiasi sistema che può effettuare richieste HTTP

---

Requisiti

Prima di iniziare, assicurati di avere:

• Un account AI SmartTalk attivo
• Accesso API abilitato (controlla il tuo piano)
• Conoscenze di base delle API REST
• Uno strumento per effettuare richieste HTTP (curl, Postman o il codice della tua applicazione)

---

Ottenere le tue credenziali API

Passo 1: Accedi alle impostazioni API

1. Accedi al tuo account AI SmartTalk
2. Naviga su Impostazioni → Integrazioni
3. Trova API e clicca su Configura

Passo 2: Genera il token API

1. Clicca su Genera Nuovo Token
2. Copia il tuo ID Modello Chat e Token API
3. Conserva questi dati in modo sicuro: il token viene mostrato solo una volta!

⚠️ Avviso di Sicurezza: Non esporre mai il tuo token API nel codice lato client o in repository pubblici.

---

Endpoint API

URL di Base

https://api.aismarttalk.tech/v1

Autenticazione

Tutte le richieste richiedono il tuo token API nell'intestazione:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Tutte le richieste richiedono il tuo token API nell'intestazione:

Authorization: Bearer YOUR_API_TOKEN

---

Importa Documenti

Endpoint

POST /documents/import

Corpo della Richiesta

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Documentazione del Prodotto",
      "content": "Il contenuto completo del tuo documento va qui...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentazione",
        "language": "en"
      }
    }
  ]
}

Parametri

Campo	Tipo	Richiesto	Descrizione
chatModelId	string	✅	Il tuo identificatore unico del modello di chat
documents	array	✅	Array di oggetti documento
documents[].title	string	✅	Titolo del documento per identificazione
documents[].content	string	✅	Contenuto testuale completo
documents[].url	string	❌	URL di origine (per riferimento)
documents[].metadata	object	❌	Coppie chiave-valore personalizzate

Risposta

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Documentazione del Prodotto",
      "status": "processing"
    }
  ]
}

Esempio: 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": "Guida per Iniziare",
        "content": "Benvenuto sulla nostra piattaforma. Ecco come iniziare...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Interroga Documenti

Fai domande contro la tua base di conoscenza in modo programmatico.

Endpoint

POST /chat/query

Corpo della Richiesta

{
  "chatModelId": "your-chat-model-id",
  "query": "Come posso reimpostare la mia password?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Risposta

{
  "success": true,
  "response": "Per reimpostare la tua password, vai su Impostazioni > Sicurezza > Cambia Password...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Guida alla Sicurezza",
      "relevance": 0.95
    }
  ]
}

---

Recupera Documenti

Ottieni documenti che corrispondono a una query (senza risposta AI).

Endpoint

POST /documents/search

Corpo della Richiesta

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

Risposta

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Migliori Pratiche di Sicurezza",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Esempi di Codice

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

# Importa un documento
result = import_document(
    title="FAQ: Spedizione",
    content="Offriamo spedizione gratuita per ordini superiori a $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();
}

// Importa un documento
importDocument(
  'FAQ: Resi',
  'Puoi restituire articoli entro 30 giorni dall\'acquisto...',
  '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' => 'Specifiche del Prodotto',
            'content' => 'Il nostro widget ha le seguenti specifiche...',
            '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));

---

Casi d'Uso

Integrazione CMS Personalizzato

Sincronizza contenuti da un CMS proprietario:

• Collega agli eventi di pubblicazione del CMS
• Invia contenuti nuovi/aggiornati a AI SmartTalk
• Rimuovi contenuti eliminati

Pipeline di Dati

Importa da data warehouse:

• Esporta dati rilevanti in JSON
• Importazione batch tramite API
• Pianifica aggiornamenti regolari

Prodotti E-commerce

Sincronizza i dati dei prodotti da sistemi personalizzati:

• Descrizioni dei prodotti
• Specifiche
• Informazioni sui prezzi

Sistemi Interni

Collega strumenti interni non supportati nativamente:

• Wiki personalizzati
• Database legacy
• Applicazioni proprietarie

---

Limiti di Richiesta

Endpoint	Limite di Richiesta
Importazione Documenti	100 richieste/minuto
Query	60 richieste/minuto
Ricerca	60 richieste/minuto

Nota: I limiti di richiesta variano in base al piano. Contattare il supporto per limiti più elevati.

---

Gestione degli Errori

Formato di Risposta agli Errori

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Il token API fornito è invalido o scaduto"
  }
}

Codici di Errore Comuni

Codice	Descrizione	Soluzione
INVALID_TOKEN	Token errato o scaduto	Rigenera il token API
INVALID_MODEL_ID	ID del modello di chat sconosciuto	Controlla il tuo ID del Modello di Chat
RATE_LIMITED	Troppe richieste	Implementa un backoff, riprova più tardi
INVALID_REQUEST	Corpo della richiesta malformato	Controlla la struttura JSON
DOCUMENT_TOO_LARGE	Il contenuto supera il limite	Dividi in documenti più piccoli
QUOTA_EXCEEDED	Limiti del piano raggiunti	Aggiorna o contatta il supporto

---

Risoluzione dei Problemi

Autenticazione Fallita

Problema	Soluzione
401 Non autorizzato	Controlla che il token sia corretto e attivo
Token non funzionante	Rigenera il token nelle impostazioni
Token scaduto	I token non scadono, ma possono essere revocati

Problemi di Importazione

Problema	Soluzione
Risposta vuota	Controlla che il Content-Type sia application/json
Documento non apparente	Attendi l'elaborazione; controlla la sezione Conoscenza
Importazione parziale	Alcuni documenti potrebbero avere errori di convalida

Problemi di Prestazioni

Problema	Soluzione
Importazioni lente	Raggruppa i documenti (max 100 per richiesta)
Timeout	Riduci la dimensione del batch, riprova con backoff
Limitato da richieste	Implementa un backoff esponenziale

---

Migliori Pratiche

1. Importazioni in batch: Invia più documenti per richiesta (fino a 100)
2. Titoli unici: Usa titoli descrittivi e unici per ogni documento
3. Contenuto strutturato: Contenuti ben formattati migliorano le risposte dell'AI
4. Tagging dei metadati: Usa metadati per categorizzazione e filtraggio
5. Token sicuri: Conserva i token in variabili d'ambiente
6. Gestisci gli errori: Implementa una logica di ripetizione con backoff esponenziale
7. Monitora l'uso: Tieni traccia delle chiamate API rispetto ai limiti del tuo piano

---

Documentazione Correlata

• Panoramica delle Integrazioni
• Documentazione Completa dell'API
• Gestione della Base di Conoscenza
• Webhook SmartFlow — Ricevi eventi