Integrazioni

Queria e progettata per essere integrata all'interno di applicazioni proprietarie. Questa guida illustra le modalita di integrazione disponibili, dal widget incorporabile alla comunicazione server-to-server.

Widget Incorporabile

Il modo piu rapido per aggiungere Queria a un sito web o portale aziendale.

Installazione base

Aggiungi il seguente codice HTML prima della chiusura del tag </body>:

<script src="https://cdn.queria.pro/widget.js"></script>
<script>
  Queria.init({
    apiKey: 'qk_live_abc123def456ghi789jkl012',
    theme: 'light',
    position: 'bottom-right',
    language: 'it'
  });
</script>

Opzioni di configurazione

Opzione	Tipo	Default	Descrizione
apiKey	string	-	API Key con restrizione dominio (obbligatorio)
theme	string	light	Tema: light, dark, auto
position	string	bottom-right	Posizione: bottom-right, bottom-left
language	string	it	Lingua interfaccia: it, en
primaryColor	string	#2563eb	Colore primario (esadecimale)
title	string	Assistente AI	Titolo mostrato nell'header
placeholder	string	Scrivi una domanda...	Placeholder del campo di input
topicId	string	-	Limita la ricerca a una categoria specifica
width	number	400	Larghezza del widget in pixel
height	number	600	Altezza del widget in pixel

Personalizzazione avanzata

<script>
  Queria.init({
    apiKey: 'qk_live_abc123def456ghi789jkl012',
    theme: 'dark',
    position: 'bottom-right',
    primaryColor: '#059669',
    title: 'Supporto Documentale',
    placeholder: 'Cerca nei documenti aziendali...',
    topicId: 'topic_contratti',
    onReady: function() {
      console.log('Widget Queria caricato');
    },
    onMessage: function(message) {
      // Callback per ogni messaggio ricevuto
      analytics.track('queria_response', { query: message.query });
    }
  });
</script>

Controllo programmatico

// Apri il widget
Queria.open();

// Chiudi il widget
Queria.close();

// Invia un messaggio programmaticamente
Queria.send('Qual e la policy di reso?');

// Distruggi l'istanza
Queria.destroy();

Integrazione REST API

Per integrazioni piu profonde, utilizza direttamente la REST API con autenticazione server-to-server.

Architettura consigliata

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  La tua App     │────>│  Il tuo Backend  │────>│  Queria API     │
│  (Frontend)     │     │  (Server)        │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘

L'API Key deve risiedere esclusivamente nel tuo backend. Il frontend della tua applicazione comunica con il tuo server, che a sua volta inoltra le richieste a Queria.

Esempio Node.js

const express = require('express');
const app = express();

const QUERIA_API_KEY = process.env.QUERIA_API_KEY; // qk_live_abc123...
const QUERIA_BASE_URL = 'https://api.queria.pro';

app.post('/api/ask', async (req, res) => {
  const { question, sessionId } = req.body;

  const response = await fetch(`${QUERIA_BASE_URL}/api/public/chat`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': QUERIA_API_KEY
    },
    body: JSON.stringify({
      message: question,
      sessionId: sessionId
    })
  });

  const data = await response.json();
  res.json({
    answer: data.data.response,
    sources: data.data.sources
  });
});

Esempio Python

import requests
import os

QUERIA_API_KEY = os.environ['QUERIA_API_KEY']
QUERIA_BASE_URL = 'https://api.queria.pro'

def ask_queria(question: str, session_id: str = None) -> dict:
    response = requests.post(
        f'{QUERIA_BASE_URL}/api/public/chat',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': QUERIA_API_KEY
        },
        json={
            'message': question,
            'sessionId': session_id
        }
    )
    response.raise_for_status()
    result = response.json()
    return {
        'answer': result['data']['response'],
        'sources': result['data']['sources']
    }

Casi d'Uso

Integrazione CRM

Incorpora la ricerca documentale nel tuo CRM per consentire agli operatori di trovare contratti, offerte e documentazione cliente direttamente dall'interfaccia di gestione.

// Cerca documenti relativi a un cliente specifico
const results = await fetch(`${QUERIA_BASE_URL}/api/public/chat`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': QUERIA_API_KEY
  },
  body: JSON.stringify({
    message: `Trova i contratti attivi per il cliente ${customerName}`,
    sessionId: `crm_${customerId}`
  })
});

Integrazione ERP

Collega i documenti finanziari (fatture, ordini, DDT) per consentire ricerche intelligenti sui dati contabili e di magazzino.

Portale aziendale

Aggiungi un assistente AI alla intranet aziendale per la consultazione della knowledge base interna: manuali, procedure operative, policy HR.

Supporto clienti

Automatizza le risposte alle domande frequenti con citazioni precise dai documenti ufficiali, riducendo i tempi di risposta e migliorando la qualita del supporto.

Autenticazione per Integrazioni

Scenario	Metodo	Note
Widget su sito pubblico	API Key + restrizione dominio	Il dominio deve corrispondere
Backend-to-backend	API Key	Conserva la chiave nel server
App con login utente	JWT	Ogni utente ha il proprio token
App mobile	JWT + refresh token	Gestisci il refresh automatico

Best Practice

Gestione degli errori

Implementa una strategia di retry con backoff esponenziale per gestire errori transitori:

async function queriaRequest(payload, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(`${QUERIA_BASE_URL}/api/public/chat`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': QUERIA_API_KEY
        },
        body: JSON.stringify(payload)
      });

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 5;
        await sleep(retryAfter * 1000);
        continue;
      }

      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

Gestione del rate limit

Monitora gli header X-RateLimit-Remaining e rallenta le richieste quando il budget si avvicina a zero. Per carichi elevati, contatta il supporto per limiti personalizzati.

Streaming per risposte in tempo reale

Per le interfacce utente interattive, utilizza sempre l'endpoint streaming (/api/public/chat/stream) per mostrare la risposta progressivamente, migliorando la percezione di reattivita.

Caching

Implementa una cache lato applicazione per le query ripetute. Queria applica gia un caching interno, ma una cache locale riduce la latenza e il consumo di quota:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minuti

async function cachedQuery(question) {
  const key = question.toLowerCase().trim();
  const cached = cache.get(key);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const result = await queriaRequest({ message: question });
  cache.set(key, { data: result, timestamp: Date.now() });
  return result;
}