Panoramica
Le chiavi API ti permettono di collegare Dashboardly a un assistente AI come ChatGPT, Claude o Cursor, così che l'assistente possa rispondere a domande sui dati del tuo TikTok Shop in linguaggio naturale. Chiedi "Qual è stato il mio net profit la settimana scorsa?" oppure "Quale SKU ha venduto di più ieri nel mio shop del Regno Unito?" e l'assistente ricava la risposta direttamente dai tuoi dati Dashboardly in tempo reale.
La connessione utilizza uno standard aperto chiamato Model Context Protocol (MCP), che qualsiasi assistente AI moderno è in grado di gestire. Generi una chiave API per ciascun assistente (oppure una per shop), la incolli nelle impostazioni dell'assistente e la conversazione viene collegata ai tuoi dati.
Le chiavi API sono in sola lettura. Un assistente AI può leggere ogni metrica che puoi vedere in Dashboardly, ma non può creare ordini, modificare i costi dei prodotti, modificare le impostazioni, inviare rimborsi o modificare alcunché nel tuo TikTok Shop o nel tuo account Dashboardly.
Gestisci tutte le chiavi nella pagina Settings > API Keys.
Requisiti di piano
Le chiavi API fanno parte della funzionalità AI Integrations di Dashboardly, disponibile sui seguenti piani:
| Piano | Chiavi API incluse |
|---|---|
| Brand Starter | Non disponibile |
| Brand Growth | Disponibile |
| Brand Pro | Disponibile |
| Brand Elite | Disponibile |
Se sei sul piano Brand Starter, la scheda API Keys in Settings mostra un invito all'upgrade. Aggiorna il tuo abbonamento nella pagina Settings > Subscriptions per abilitare la funzionalità.
Non è prevista alcuna tariffa per chiave. Puoi creare tutte le chiavi che vuoi su un piano idoneo, senza costi aggiuntivi per le query effettuate dal tuo assistente AI.
Come funziona
Quando crei una chiave API in Dashboardly, accadono due cose:
- La chiave viene generata. Ha l'aspetto di
dk_live_...seguito da una lunga stringa casuale. Vedi la chiave completa esattamente una volta, nel momento della creazione. Successivamente, Dashboardly memorizza solo una sua impronta, quindi nemmeno il nostro team di supporto può recuperare la chiave completa in seguito. - La chiave è associata al tuo account. Ogni chiave è collegata al tuo accesso a Dashboardly e, facoltativamente, a un singolo TikTok Shop. Quando un assistente AI utilizza la chiave per richiedere dati, ottiene esattamente ciò che vedresti tu aprendo quello shop nel tuo browser.
Il tuo assistente AI si connette a un endpoint Dashboardly (il server MCP) e presenta la chiave. L'endpoint verifica la chiave, individua quale shop la chiave è autorizzata a leggere e restituisce i dati richiesti. Ogni richiesta viene registrata così puoi vedere con quale frequenza il tuo assistente usa la chiave e quali domande pone.
Poiché la chiave è in sola lettura, l'assistente non ha alcun modo di modificare nulla. L'azione più "distruttiva" che può compiere è leggere una metrica.
Passo dopo passo: crea la tua prima chiave API
Passo 1: apri la pagina API Keys
Vai a Settings > API Keys nella barra laterale sinistra. Se non vedi la scheda, verifica che il tuo abbonamento sia su Brand Growth o superiore.
Passo 2: clicca su "New API key"
Nell'angolo in alto a destra della pagina, clicca sul pulsante + New API key. Si apre un piccolo modulo.
Passo 3: compila i dettagli
- Name -- Un'etichetta per riconoscere la chiave in seguito. Usa qualcosa di descrittivo come "Claude Desktop -- US Shop" o "ChatGPT for John". I nomi sono visibili solo a te.
- Shop -- Scegli un singolo shop oppure lascia il campo su "All shops" per dare alla chiave accesso a ogni shop che hai collegato. La maggior parte degli utenti preferisce una chiave per shop, così ogni conversazione AI è automaticamente limitata ai dati giusti.
- Expires in -- Dopo quanti giorni la chiave smette automaticamente di funzionare. Il valore predefinito è 365 giorni. Scadenze più brevi sono più sicure; scadenze più lunghe significano che non devi ruotare la chiave così spesso. Puoi revocare una chiave in qualsiasi momento, indipendentemente dalla sua scadenza.
Passo 4: clicca su "Create key"
Dashboardly genera la chiave e la mostra in un pannello di conferma. La chiave viene mostrata per intero solo questa volta.
Passo 5: copia subito la chiave
Clicca sul pulsante Copy per copiare la chiave negli appunti. Incollala in un luogo sicuro (il file di configurazione del tuo assistente, un password manager o una nota protetta). Se chiudi il pannello senza copiarla, dovrai revocare la chiave e crearne una nuova -- non c'è modo di recuperarla nuovamente.
Passo 6: collega il tuo assistente AI
Apri le impostazioni del tuo assistente AI e aggiungi Dashboardly come connessione (il percorso esatto varia in base all'assistente; vedi la sezione successiva per le indicazioni su ciascuno).
Passo 7: conferma la connessione
Poni al tuo assistente una semplice domanda come "Qual è il mio net profit della settimana scorsa?". Se tutto è impostato correttamente, l'assistente risponde con la risposta ricavata dai tuoi dati Dashboardly in tempo reale. Se vedi un errore, consulta Perché il mio assistente AI non funziona?.
Collegare un assistente AI
La configurazione esatta dipende da quale assistente usi. Dopo aver creato la chiave in Dashboardly, il pannello di conferma mostra snippet di configurazione pronti da incollare per gli strumenti più diffusi.
Claude (Desktop e Web)
Nelle impostazioni di Claude, cerca una sezione chiamata Connectors, Integrations o MCP servers. Aggiungi una nuova connessione incollando l'URL dell'endpoint di Dashboardly e la tua chiave API. Una volta salvata, Claude mostra Dashboardly come connessione disponibile in qualsiasi conversazione.
Se usi Claude Desktop, la connessione viene aggiunta a un file di configurazione che si carica all'avvio di Claude. Il pannello di conferma in Dashboardly mostra il testo esatto da incollare.
ChatGPT
In ChatGPT, apri il menu Apps & Connectors e aggiungi Dashboardly come connettore personalizzato. Incolla l'URL dell'endpoint e la chiave API quando richiesto. ChatGPT ricorda la connessione in tutte le tue conversazioni.
Cursor
In Cursor, apri Settings > MCP, clicca su Add new MCP server e incolla l'endpoint e la chiave di Dashboardly. Cursor usa la connessione mentre scrivi codice, così puoi porre domande come "Qual è il mio SKU più venduto questo mese?" senza lasciare l'editor.
Altri assistenti AI
Qualsiasi assistente in grado di gestire il Model Context Protocol può connettersi. Fornisci all'assistente l'URL dell'endpoint MCP di Dashboardly e la chiave API (trattala come una password). L'assistente dovrebbe scoprire automaticamente quali dati sono disponibili.
Cosa può fare il tuo assistente AI
Una volta collegato, il tuo assistente può rispondere a domande su ogni area principale dei dati del tuo shop. Poni le domande in linguaggio naturale (o in qualsiasi lingua supportata dal tuo assistente) e l'assistente decide quali dati ricavare.
| Argomento | Domande di esempio |
|---|---|
| Account e shop | "Quali shop sono collegati?" "Qual è l'email del mio account?" |
| Riepilogo Dashboard | "Dammi una rapida panoramica della settimana scorsa." "Come stanno andando le vendite rispetto al mese scorso?" |
| Profit & loss | "Qual è stato il mio net profit a marzo?" "Suddividi il mio P&L per settimana per l'ultimo trimestre." |
| Ordini | "Quanti ordini ho ricevuto ieri?" "Mostrami gli ordini annullati degli ultimi 7 giorni." |
| Prodotti principali | "Quali SKU hanno venduto di più il mese scorso?" "Quali sono stati i miei 10 prodotti più redditizi per fatturato questo trimestre?" |
| Rimborsi | "Quanto ho rimborsato la settimana scorsa?" "Quali prodotti hanno il tasso di reso più alto?" |
| Clienti | "Quanti clienti abituali ho?" "Qual è il lifetime value del mio cliente medio?" |
| Marketing e annunci | "Qual è stato il mio ROAS su TikTok Ads la settimana scorsa?" "Come stanno andando le mie campagne pubblicitarie?" |
| Live stream e promozioni | "Quali live stream hanno generato più vendite il mese scorso?" "Quanto ho risparmiato con i sussidi della piattaforma ad aprile?" |
| Inventario | "Quali SKU stanno per esaurirsi?" "Qual è il valore attuale del mio inventario?" |
| Suddivisione geografica | "Da dove proviene la maggior parte dei miei ordini?" "Come stanno andando le vendite in Germania questo mese?" |
| Metriche orarie | "In quale ora del giorno ricevo più ordini?" "Mostrami le vendite di ieri ora per ora." |
L'assistente non può eseguire azioni nel tuo TikTok Shop o in Dashboardly. Può solo leggere.
Gestire le tue chiavi
Visualizzare le chiavi
La pagina Settings > API Keys elenca ogni chiave che hai creato con il suo nome, i primi caratteri della chiave (così puoi riconoscerla), lo shop a cui è associata, quando è stata creata, quando è stata usata l'ultima volta e quando scade.
Ispezionare l'utilizzo
Clicca su una qualsiasi chiave attiva per espandere un pannello di utilizzo che mostra:
- Chiamate totali negli ultimi 30 giorni
- Tasso di successo (chiamate che hanno restituito dati con successo)
- Tempo di risposta medio così sai che la connessione è veloce
- Un grafico dell'attività giornaliera degli ultimi 7 giorni
- Gli strumenti dati più utilizzati così puoi vedere cosa richiede più spesso l'assistente
Questo è utile per confermare che una chiave è in uso, individuare attività insolite o vedere su cosa tende a concentrarsi il tuo assistente.
Revocare una chiave
Se una chiave viene persa, esposta o non è più necessaria, clicca sull'icona Revoke accanto ad essa. Dashboardly blocca immediatamente qualsiasi ulteriore richiesta che utilizza quella chiave. Gli assistenti AI collegati con la chiave revocata vedranno un errore alla loro domanda successiva.
La revoca è istantanea. Non c'è alcun periodo di tolleranza.
Scadenza della chiave
Ogni chiave ha una data di scadenza impostata al momento della creazione. Dashboardly mostra un badge di avviso nella pagina API Keys quando a una chiave rimangono 14 giorni o meno. Le chiavi scadute smettono di funzionare automaticamente -- non è necessario revocarle.
Per ruotare una chiave secondo una pianificazione ricorrente, crea una nuova chiave, aggiorna il tuo assistente AI affinché la utilizzi, quindi revoca quella vecchia.
Connected Apps
Alcuni assistenti AI (in particolare ChatGPT) si connettono tramite un flusso di accesso con un clic anziché richiederti di copiare una chiave API. Quando concedi a uno di questi assistenti l'accesso a Dashboardly, esso appare nella sezione Connected Apps in fondo alla pagina API Keys.
Per ciascuna app connessa puoi vedere il suo nome, quando si è connessa la prima volta, quando è stata attiva l'ultima volta e due modi per disconnetterla:
- Revoke -- Blocca i nuovi accessi da quell'assistente. Le sessioni attive rimangono valide fino a un'ora e poi scadono.
- Sign out now -- Disconnette immediatamente l'assistente, terminando qualsiasi sessione attiva. Usalo se sospetti che la connessione venga usata in modo improprio.
Sicurezza e privacy
Le chiavi API sono sensibili. Tratta ogni chiave come una password.
- Non inserire mai una chiave in un repository di codice pubblico. Se lo fai accidentalmente, revocala da Dashboardly e generane una nuova.
- Non condividere mai una chiave in un messaggio di chat, in un'email o in uno screenshot. Chiunque possieda la chiave può leggere i tuoi dati finché non la revochi.
- Usa una chiave per assistente o per dispositivo. In questo modo, se una chiave viene compromessa su un dispositivo, puoi revocare solo quella chiave senza disturbare le altre connessioni.
- Imposta una scadenza ragionevole. Una chiave che scade in 90 giorni è più sicura di una che dura per sempre. Puoi sempre crearne una nuova.
Dashboardly non mostra mai la chiave completa dopo la creazione. L'unico posto in cui trovarla è dove l'hai salvata al momento della sua generazione.
Tutte le richieste degli assistenti AI vengono effettuate tramite HTTPS. Ogni richiesta viene registrata con un timestamp e l'area dati che ha interrogato. Puoi controllare questa cronologia per ciascuna chiave dal pannello di utilizzo descritto sopra.
Sola lettura significa sola lettura: anche se una chiave fosse compromessa, un malintenzionato potrebbe vedere i tuoi dati ma non potrebbe modificare nemmeno un costo di prodotto, inviare un rimborso o influire in alcun modo sul tuo TikTok Shop.
Domande frequenti
Il mio assistente AI vede tutto il mio account Dashboardly oppure un solo shop?
Dipende da come hai configurato la chiave. Se hai associato la chiave a un singolo shop, l'assistente vede solo quello shop. Se hai lasciato selezionato "All shops", l'assistente può leggere i dati di ogni shop del tuo account. La maggior parte degli utenti preferisce una chiave per shop per maggiore chiarezza.
Posso creare chiavi diverse per diversi membri del team?
Sì. Crea una chiave nominale per persona ("Claude -- Maria", "ChatGPT -- John") e condividi ogni chiave solo con la persona che ne ha bisogno. Se qualcuno lascia il team, revoca la sua chiave senza influire su nessun altro.
L'uso di un assistente AI mi costerà di più?
No. Non è prevista alcuna tariffa per query da parte di Dashboardly. Il fornitore del tuo assistente AI (OpenAI, Anthropic, ecc.) ti fattura separatamente l'assistente stesso in base ai propri prezzi.
Quanto sono aggiornati i dati che vede il mio assistente?
Esattamente quanto quelli che vedi tu in Dashboardly. Se la dashboard mostra una metrica aggiornata 2 minuti fa, è ciò che ottiene l'assistente. I numeri basati sul settlement (commissioni, tasse) possono essere stimati per gli ordini molto recenti -- consulta Perché i miei dati sono in ritardo? per la spiegazione completa.
Il mio assistente AI può apportare modifiche al mio shop?
No. Ogni chiave API è in sola lettura. Non esiste una modalità "scrittura" né alcun piano per aggiungerla. Il massimo che un assistente può fare è riepilogare i numeri che legge.
Cosa succede alle mie vecchie chiavi se effettuo il downgrade del mio piano?
Se effettui il downgrade a Brand Starter, tutte le chiavi API esistenti smettono immediatamente di funzionare. Effettua di nuovo l'upgrade a Brand Growth o superiore per riattivarle, oppure crea nuove chiavi dopo l'upgrade.
Posso vedere cosa ha chiesto il mio assistente AI?
Sì. Il pannello di utilizzo di ciascuna chiave mostra le aree dati più utilizzate (ordini, P&L, prodotti principali, ecc.) e un grafico dell'attività di 7 giorni. Non registriamo le domande in linguaggio naturale digitate dall'utente -- solo quali strumenti dati l'assistente ha richiamato.