Integrazione API

Invia dati programmaticamente alla tua base di conoscenza AI SmartTalk utilizzando la nostra REST API. 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
• Integrare con qualsiasi sistema in grado di 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 sulle 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

---

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": "it"
      }
    }
  ]
}

Parametri

Campo	Tipo	Richiesto	Descrizione
chatModelId	string	✅	Il tuo identificatore unico del modello 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 programmaticamente.

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 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 magazzini di dati:

• 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
Interrogazione	60 richieste/minuto
Ricerca	60 richieste/minuto

Nota: I limiti di richiesta variano in base al piano. Contatta il supporto per limiti superiori.

---

Gestione degli Errori

Formato della Risposta di Errore

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

Codici di Errore Comuni

Codice	Descrizione	Soluzione
INVALID_TOKEN	Token non valido 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	Troppi 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 appare	Attendi l'elaborazione; controlla la sezione Conoscenza
Importazione parziale	Alcuni documenti potrebbero avere errori di validazione

Problemi di Prestazioni

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

---

Migliori Pratiche

1. Importazioni 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 la logica di riprova 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