Question 1

Quali possibilità di integrazione offre empirio.ai?

Accepted Answer

empirio.ai può essere collegato ad altri sistemi in quattro modi:

* REST API – Gestire i sondaggi e recuperare le risposte tramite HTTPS.
* Webhook – Inviare automaticamente in tempo reale le nuove risposte al tuo sistema.
* MCP-Server – Consentire ad agenti IA come ChatGPT o Claude di lavorare direttamente con i tuoi sondaggi e le tue risposte.
* CLI – Lo strumento da riga di comando @empirio-ai/cli per script, automazioni o azioni rapide dal terminale.

Tutte le integrazioni sono attualmente in beta – endpoint e comportamento possono ancora cambiare.

Puoi trovare maggiori informazioni su https://www.empirio.ai/integrations, inclusa una documentazione completa per sviluppatori.

Question 2

Per chi sono pensate le integrazioni?

Accepted Answer

Per tutti coloro che non vogliono usare empirio.ai solo tramite l’interfaccia web, ma desiderano integrarlo nei propri sistemi o flussi di lavoro. Casi d’uso tipici:

Sviluppatori e sviluppatrici che vogliono creare sondaggi in modo automatizzato o importare le risposte nei propri strumenti (CRM, Data Warehouse, strumenti di BI).

Aziende che desiderano trasferire le risposte ai sondaggi direttamente nei sistemi interni – ad esempio inviando un messaggio Slack dopo ogni risposta o passando i dati al sistema di reporting.

Data analyst che vogliono elaborare regolarmente le risposte in SPSS, R o Python e automatizzare le esportazioni.

Team che lavorano con agenti di IA e vogliono dare ai loro agenti accesso diretto a empirio.ai – tramite il server MCP.

Question 3

Di quale pacchetto ho bisogno per le integrazioni?

Accepted Answer

Le integrazioni sono disponibili a partire dal pacchetto Pro. Per un utilizzo esteso o a livello aziendale è inoltre disponibile un pacchetto Enterprise con limiti e condizioni avanzati. Per maggiori informazioni contatta il team di supporto all’indirizzo info@empirio.ai

Question 4

Che cos’è l’API REST e a cosa mi serve?

Accepted Answer

L’API REST è l’interfaccia classica per la gestione programmatica dei sondaggi. Tramite HTTPS puoi:

* creare, modificare, pubblicare, duplicare ed eliminare sondaggi
* recuperare, filtrare, esportare e analizzare le risposte
* calcolare aggregati, statistiche e tabelle incrociate
* esportare grafici in vari formati (PowerPoint, PDF, Word, PNG)

L’autenticazione avviene tramite API key (per applicazioni server‑to‑server) oppure tramite OAuth 2.1 (per applicazioni che agiscono per conto degli utenti).

Base URL: https://platform.empirio.ai/rest/v1

La documentazione completa degli endpoint è disponibile nella documentazione per sviluppatori.

Question 5

Dove posso creare una chiave API?

Accepted Answer

Nel dashboard di empirio.ai, sotto "Integrationen". Con un clic generi una nuova chiave. Importante: la chiave viene mostrata una sola volta – salvala subito in modo sicuro (ad esempio in un password manager o in un secret store).
Le API key hanno degli scope: surveys per le operazioni sui sondaggi, responses per l’accesso alle risposte. Quando le crei puoi definire quali permessi deve avere la chiave.

Question 6

Cosa sono i webhook e come posso usarli?

Accepted Answer

I webhook sono il complemento dell’API: invece di richiedere i dati a intervalli regolari, empirio.ai ti invia attivamente i dati non appena succede qualcosa.
In concreto: non appena una persona completa un sondaggio, empirio.ai invia un payload JSON firmato all’URL che hai configurato. Puoi reagire immediatamente – ad esempio inviando email di follow-up automatiche, scrivendo i dati nel tuo CRM o alimentando dashboard in tempo reale.

Per ogni sondaggio puoi registrare fino a tre endpoint webhook.
I webhook si configurano nella sezione "Integrazioni".

Question 7

Cosa succede se il mio endpoint Webhook non è temporaneamente raggiungibile?

Accepted Answer

In caso di errore (timeout, errore del server, risposta non valida) empirio.ai tenta la consegna fino a tre volte con intervalli crescenti: immediatamente, poi dopo 1 minuto, poi dopo 10 minuti.
Importante: i webhook vengono recapitati con una garanzia di almeno-una-volta. In caso di dubbio, quindi, un messaggio verrà recapitato piuttosto due volte che per niente. Usa l’header X-Empirio-Delivery-Id per riconoscere e ignorare i duplicati dalla tua parte.

Question 8

Che cos'è il server MCP?

Accepted Answer

MCP sta per Model Context Protocol – uno standard che permette agli agenti di IA di accedere direttamente a sistemi esterni. Con il nostro server MCP puoi collegare ChatGPT, Claude o altri host di IA compatibili ai tuoi dati empirio.ai.

Ecco alcuni esempi concreti di ciò che il tuo agente di IA può fare:
"Mostrami le risposte della mia ultima indagine sulla soddisfazione dei clienti."
"Crea un questionario NPS con 5 domande per il nostro nuovo prodotto e pubblicalo."
"Esporta le risposte del sondaggio X in un deck PowerPoint."
"Elimina le ultime 10 risposte incomplete."

L’agente richiamerà automaticamente gli strumenti corretti e ti fornirà il risultato.

URL del server: https://platform.empirio.ai/mcp. L’autenticazione avviene tramite OAuth 2.1 con PKCE ed è negoziata automaticamente – non devi configurare nulla manualmente.

Question 9

Come collego Claude o ChatGPT a empirio.ai?

Accepted Answer

Per Claude: vai nelle impostazioni su "Connectors", aggiungi empirio.ai come server MCP remoto con l’URL https://platform.empirio.ai/mcp. L’autenticazione avviene automaticamente.

Per ChatGPT (tramite la Responses API): utilizza la voce del server MCP nella configurazione dei tuoi strumenti con lo stesso URL.

Una volta stabilita la connessione, l’agente AI avrà accesso a tutte le funzionalità per le quali gli concedi le autorizzazioni necessarie (scope: surveys e/o responses).

Question 10

Che cos’è la CLI e quando ha senso usarla?

Accepted Answer

Lo strumento da riga di comando @empirio-ai/cli è un’interfaccia installabile via npm pensata per sviluppatori e sviluppatrici che preferiscono lavorare nel terminale o che vogliono integrare empirio.ai in script e pipeline CI.

Installazione:
npm install -g @empirio-ai/cli

La CLI copre tutte le operazioni dell’API REST. L’autenticazione avviene tramite empirio login (OAuth, per l’uso interattivo) oppure tramite la variabile d’ambiente EMPIRIO_API_KEY (per scenari CI e di automazione).

Requisito: Node.js versione 20 o successiva.

Question 11

Quali limiti di frequenza si applicano alle integrazioni?

Accepted Answer

Per mantenere la nostra piattaforma stabile per tutti, abbiamo definito limiti chiari:

* Operazioni di lettura: 60 richieste al minuto per chiave o utente.
* Operazioni di scrittura: 20 richieste al minuto per chiave o utente.
* Creazione di sondaggi: inoltre massimo 10 all’ora e 50 al giorno per account.

Se superi un limite, l’API risponde con uno status 429 e un header Retry-After che indica per quanto tempo devi attendere.

Per i clienti Enterprise con esigenze particolarmente elevate possiamo concordare limiti personalizzati.

Question 12

I miei dati vengono trasmessi in modo sicuro quando utilizzo le integrazioni?

Accepted Answer

Sì. Le integrazioni seguono gli stessi standard di sicurezza del resto della piattaforma:

Solo HTTPS: le connessioni non crittografate vengono rifiutate.

Autenticazione tramite bearer token: API key o token OAuth con ambiti chiaramente definiti.

Webhook firmati: ogni consegna di webhook è firmata con HMAC e può essere verificata per autenticità.

Rate limit e chiavi di idempotenza: proteggono da esecuzioni doppie accidentali e da utilizzi impropri.

Hosting nell’UE: anche gli endpoint di integrazione operano sulla nostra infrastruttura con base nell’UE.

Question 13

Dove posso trovare la documentazione tecnica completa?

Accepted Answer

La documentazione completa per sviluppatori – con tutti gli endpoint, esempi, payload dei webhook e codici di errore – è disponibile su empirio.ai/docs.
Lì puoi anche vedere quali tipi di domande sono supportati dall’API, come sono strutturate le risposte e come richiamare filtri, aggregazioni ed esportazioni.

Question 14

A chi posso rivolgermi per domande tecniche sull’integrazione?

Accepted Answer

Scrivici a info@empirio.ai. Per domande sull’API o sulle integrazioni saremo lieti di aiutarti – l’ideale è indicarci direttamente:

Cosa vuoi ottenere
Quali endpoint utilizzi
Il codice di errore esatto e il messaggio di errore (se presenti)

In questo modo possiamo ricostruire rapidamente il caso.

Centro assistenza