API Pubblica per Avatar e Integrazioni

ReportIA come motore AI per le tue app

Il modulo API Pubblica di ReportIA permette di esporre la potenza dell'AI conversazionale ai tuoi software esterni: chatbot del sito web, avatar virtuali, app mobile, dispositivi vocali (Alexa, Google Home), bot Telegram. L'utente fa una domanda al bot, il bot la inoltra a ReportIA via API, ReportIA risponde con i dati dal database, il bot li mostra. Tutto via REST.

L'endpoint principale

POST /api/reportia/avatar/ask

Body:

{
  "domanda": "Quanto abbiamo fatturato a marzo 2026?",
  "context_id": "session-abc123" // opzionale per memoria
}

Header:

Authorization: Bearer YOUR_API_TOKEN

Response:

{
  "risposta_testo": "A marzo 2026 hai fatturato 245.300 €, in crescita del 12% rispetto a febbraio.",
  "dati": [
    {"mese": "Marzo 2026", "fatturato": 245300}
  ],
  "sql": "SELECT...",
  "tempo_esecuzione_ms": 1240
}

Generazione API Key

Dal pannello admin:

1. Sezione "API Pubbliche".
2. "Genera nuovo token".
3. Configurazione:
   • Nome (es. "Chatbot sito web").
   • Scadenza (90 gg, 1 anno, mai).
   • Rate limit (es. 100 req/min).
   • Permessi (solo lettura, scrittura, ecc.).
4. Token generato.
5. Mostrato una sola volta: copia subito.

Rate limiting

Per evitare abusi:

• Limite richieste per minuto/ora configurabile.
• Risposta HTTP 429 se superato.
• Header con limite residuo.
• Reset finestra dopo periodo configurato.

Default: 60 richieste/minuto.

IP logging

Per ogni richiesta API:

• IP di provenienza salvato.
• User-Agent.
• Geolocalizzazione (paese).
• Audit log per sicurezza.

Eventuale whitelist IP per token critici.

Tracking analytics

Dashboard analytics per ogni token:

• Richieste totali.
• Successo vs errori.
• Tempo medio risposta.
• Costi OpenAI generati.
• Top domande.
• Anomalie (improvviso aumento richieste).

Output plain-text

Per integrazioni con bot/avatar che richiedono testo pulito:

• Markdown stripped: rimosso bold, italic, link.
• Tabelle convertite in testo formattato.
• Numeri formattati per locale italiano.
• Compatibile con TTS (Text-to-Speech) per dispositivi vocali.

Esempio per Alexa: "Il fatturato di marzo è duecentoquarantacinquemilatrecento euro".

Visualizzazione preparata per frontend

Per integrazioni con UI custom, la response include:

• tipo_grafico_suggerito: bar, line, pie...
• dati_strutturati: array pronto per chart.js o ECharts.
• colore_palette: palette consigliata.
• titolo_grafico: testo per il grafico.

L'app frontend riceve dati e li visualizza con la propria grafica.

Autenticazione token-based

• Bearer Token nell'header HTTP.
• Validazione server-side ad ogni richiesta.
• Token revocabili in qualsiasi momento.
• Rotation manuale o automatica.

CORS supportato

Per chiamate cross-origin (chatbot su domini diversi):

• CORS configurabile per token.
• Whitelist domini ammessi.
• Sicurezza: solo domini autorizzati possono chiamare.

Esempio integrazione: chatbot sul sito

HTML/JS sul sito web:

async function chiediAReportIA(domanda) {
  const response = await fetch('https://reportia.azienda.it/api/reportia/avatar/ask', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN'
    },
    body: JSON.stringify({ domanda: domanda })
  });
  const data = await response.json();
  return data.risposta_testo;
}

Chatbot front-end mostra la risposta nel widget chat.

Casi d'uso pratici

Chatbot del sito aziendale

Chatbot che risponde a domande dei clienti:

• "Quanti articoli avete in stock di X?" → query DB magazzino.
• "Quando arriva l'ordine 12345?" → query DB ordini.

Avatar virtuale aziendale

Avatar 3D in reception che risponde:

• "Mostra le statistiche del mese".
• "Chi è il top venditore?".

Vedi AIAvatar Ingenia.

App mobile aziendale

App iOS/Android che integra ReportIA come backend AI:

• Manager chiede da app: "fatturato di oggi?".
• App chiama API ReportIA.
• Mostra risultato.

Bot Telegram per direzione

Bot Telegram dedicato:

• Direttore manda messaggio "vendite di marzo".
• Bot risponde con grafico embeddato.

Dispositivi vocali

Skill Alexa / Google Home:

• "Alexa, chiedi a ReportIA il fatturato".
• Alexa interroga API ReportIA.
• Risposta vocale.

Documentazione tecnica

Per integratori:

• Specification OpenAPI/Swagger.
• Esempi in PHP, Node.js, Python, Java.
• Sandbox per test.
• Error codes documentati.
• Best practice integrazione.

I moduli ReportIA correlati

• Chat AI (motore alla base).
• Multi-Tenant.
• Logging.

Scopri ReportIA e integra l'AI nelle tue app.