Gestire le chiavi API
Una chiave API consente a uno strumento esterno (CRM, automazione Zapier o Make, script interno, agente IA) di creare, leggere, modificare, archiviare, riattivare o eliminare i codici QR del Suo account e di leggerne le statistiche e la quota di creazioni rimanente, senza passare dalla dashboard. Il funzionamento tecnico dell'API (indirizzi, formati, codici di errore) è descritto nella documentazione API. Questa pagina di aiuto spiega come gestire le Sue chiavi.
L'accesso all'API è compreso nei piani Pro ed Entreprise. Il piano Gratuito non dà accesso né all'API né ad alcuna chiave.
Dove gestire le chiavi
Le chiavi si gestiscono nella schermata Chiavi API, accessibile dalla scheda Chiavi API della schermata Abbonamento (pulsante Gestisci le mie chiavi API).
- La schermata Chiavi API è riservata ai membri che dispongono del permesso Gestore delle chiavi API (o Amministratore).
- La scheda Chiavi API della schermata Abbonamento compare solo ai membri che dispongono sia di Gestore dell'abbonamento sia di Gestore delle chiavi API (o Amministratore).
| Piano Pro | Piano Entreprise | |
|---|---|---|
| Chiavi API attive contemporaneamente | 1 | 10 |
| Creazioni di codici QR tramite l'API, per mese civile | 5 | 100 |
Creare una chiave
- Nella schermata Chiavi API, nel modulo Crea una chiave API, inserisca un Nome della chiave che Le permetta di riconoscerla, ad esempio «Integrazione Zapier».
- In Diritti della chiave, scelga un'impostazione predefinita o Personalizzato (cfr. qui sotto).
- Clicchi su Crea la chiave.
- La schermata Copi ora la Sua chiave API mostra la chiave completa, che inizia con
qrs_live_. Clicchi su Copia e la conservi in un luogo sicuro, ad esempio nel gestore di password o di segreti del Suo strumento. Selezioni Ho copiato la mia chiave in un luogo sicuro., poi clicchi su Fatto.
La chiave completa viene mostrata una sola volta. Non la conserviamo in chiaro e non possiamo inviargliela di nuovo. In seguito, la schermata ne mostra solo gli ultimi 4 caratteri (
qrs_live_••••abcd). Se la perde, ne esegua la rotazione (cfr. «Eseguire la rotazione di una chiave») o ne crei una nuova.
La creazione di una chiave non viene mai conteggiata nella Sua quota mensile: questa si applica solo ai codici QR creati tramite l'API.
Se il numero massimo di chiavi del Suo piano è raggiunto, il modulo di creazione non compare più. Attenzione: per creare una chiave, anche le chiavi congelate contano in questo limite (cfr. «Chiavi congelate»). Revochi prima le chiavi di cui non ha più bisogno.
Utilizzare la chiave
Il Suo strumento invia la chiave nell'intestazione di ogni richiesta: Authorization: Bearer qrs_live_…. La documentazione API descrive le operazioni disponibili e il diritto necessario per ciascuna.
Nella schermata Chiavi API, ogni chiave indica la data di creazione, la data dell'ultima rotazione e quella dell'ultimo utilizzo (o Mai utilizzata): utile per individuare una chiave che nessuno strumento utilizza più. Questa data viene aggiornata al massimo una volta al minuto. Una richiesta rifiutata per mancanza di un diritto o perché supera il limite di frequenza non la modifica.
Le date della schermata Chiavi API sono visualizzate in ora svizzera. L'API, invece, riporta tutte le date in UTC, nel formato ISO 8601: la Z finale significa UTC. Ad esempio, 2026-10-17T22:12:00.000Z corrisponde al 18 ottobre 2026 alle 0:12 in Svizzera. È il Suo strumento a dover convertire queste date nel fuso orario desiderato.
Scegliere i diritti di una chiave
Una chiave può fare solo ciò che i suoi diritti consentono. Le attribuisca solo i diritti di cui lo strumento ha bisogno: una chiave che si limita a leggere non può né creare né eliminare codici QR, anche se viene incollata per errore nel posto sbagliato.
| Impostazione predefinita | Diritti concessi |
|---|---|
| Lettura / Reporting | Leggere i codici QR, Leggere le statistiche |
| Agente assistente IA | Leggere i codici QR, Leggere le statistiche (gli stessi diritti di Lettura / Reporting, per un agente IA che consulta i Suoi codici QR) |
| Integrazione CRM | Leggere i codici QR, Creare codici QR, Leggere le statistiche |
| Integrazione CRM con aggiornamento | Leggere i codici QR, Creare codici QR, Modificare codici QR, Leggere le statistiche |
| Gestione completa | Tutti e 5 i diritti, compreso Eliminare codici QR |
Con Personalizzato, seleziona Lei stesso i diritti desiderati tra i 5, almeno uno.
Può modificare i diritti di una chiave esistente in qualsiasi momento, poi cliccare su Salva i diritti. La modifica si applica immediatamente, senza cambiare la chiave: lo strumento che la utilizza non deve essere riconfigurato, può semplicemente fare più o meno cose.
Una chiamata che richiede un'operazione non consentita dai diritti della chiave viene rifiutata (errore 403 forbidden).
Due operazioni richiedono un diritto meno evidente:
- archiviare o riattivare un codice QR richiede Modificare codici QR;
- leggere la quota di creazioni (creazioni del mese, saldo dei pacchetti) richiede Creare codici QR. Le impostazioni predefinite Lettura / Reporting e Agente assistente IA non permettono quindi di leggere questo saldo.
Quote di creazioni e pacchetti
Viene conteggiata solo la creazione di un codice QR tramite l'API: leggere, modificare, archiviare, riattivare o eliminare un codice QR, scaricarne l'immagine o leggerne le statistiche non viene conteggiato. Nemmeno i codici QR creati dalla dashboard vengono conteggiati.
- La quota è di 5 creazioni per mese civile con il piano Pro e di 100 con il piano Entreprise, per l'intero account (tutte le chiavi insieme).
- Una creazione resta conteggiata anche se elimina il codice QR in seguito: eliminare un codice QR non Le restituisce alcuna creazione.
- Viene azzerata il 1° di ogni mese alle 00:00 UTC, cioè all'1:00 in Svizzera (alle 2:00 con l'ora legale). Le creazioni non utilizzate non vengono riportate.
- Una volta esaurita la quota del mese, ogni creazione consuma una creazione dei Suoi pacchetti di creazioni API, a partire dal pacchetto più vecchio.
- Quando la quota del mese e tutti i Suoi pacchetti sono esauriti, la creazione viene rifiutata con l'errore
429 quota_exceeded, che indica la data di azzeramento della quota. Nulla viene fatturato a consumo.
La schermata Chiavi API mostra a che punto è: creazioni del mese utilizzate sulla quota, creazioni prelevate dai Suoi pacchetti, creazioni rimanenti nei Suoi pacchetti e data del prossimo azzeramento. Il Suo strumento può leggere le stesse cifre con GET /usage, con una chiave che ha il diritto Creare codici QR (cfr. la documentazione API).
I pacchetti (+50, +100, +500, +1000 o +5000 creazioni) si acquistano in un'unica soluzione dalla scheda Pacchetti di creazioni API della schermata Abbonamento, con un abbonamento Pro o Entreprise attivo. Non scadono finché il Suo account resta nel piano Pro o Entreprise. I prezzi figurano nella pagina Prezzi; le condizioni di acquisto e il congelamento nel piano Gratuito sono descritti in Gestire l'abbonamento.
Eseguire la rotazione di una chiave
Il pulsante Rotazione genera un nuovo segreto per la chiave e invalida immediatamente quello vecchio. La chiave conserva il nome e i diritti, e non conta come una chiave in più.
- Clicchi su Rotazione accanto alla chiave, poi confermi.
- Copi la nuova chiave nella schermata Copi ora la Sua chiave API: come alla creazione, viene mostrata una sola volta.
- Sostituisca la vecchia chiave in tutti gli strumenti che la utilizzano: finché non l'ha fatto, le loro chiamate vengono rifiutate.
Esegua la rotazione di una chiave se l'ha persa, se pensa che possa essere stata esposta (inviata per e-mail, pubblicata in un repository di codice, visibile in uno screenshot) o semplicemente a intervalli regolari.
Revocare una chiave
Il pulsante Revoca rende la chiave inutilizzabile immediatamente e definitivamente. Gli strumenti che la utilizzano smettono subito di funzionare. Una chiave revocata scompare dall'elenco e non può essere né riattivata né rigenerata.
La revoca non tocca né i Suoi codici QR, compresi quelli creati con questa chiave, né la Sua quota, né i Suoi pacchetti. Libera un posto nel limite di chiavi del Suo piano: può poi creare una nuova chiave.
Revochi una chiave non appena uno strumento non ne ha più bisogno, oppure se può essere stata esposta e nessuno strumento deve più utilizzarla.
Chiavi congelate
Una chiave congelata rifiuta tutte le chiamate all'API, anche in lettura, con lo stesso errore di una chiave non valida (401 unauthorized). Non è né revocata né eliminata: il nome e i diritti vengono conservati. Una chiave viene congelata quando il Suo piano consente meno chiavi di quelle che possiede. Gli amministratori dell'account ne vengono informati per e-mail, e un banner lo indica nella dashboard.
Quando il Suo account passa al piano Gratuito
Se il Suo abbonamento Pro o Entreprise termina (disdetta giunta a scadenza o pagamento definitivamente fallito), tutte le Sue chiavi vengono congelate: gli strumenti che le utilizzano smettono di funzionare. Anche il saldo dei Suoi pacchetti di creazioni viene congelato, senza andare perso.
Nel piano Gratuito, la schermata Chiavi API non mostra le Sue chiavi: non può né consultarle, né revocarle, né eseguirne la rotazione, né riattivarle.
Non appena sottoscrive di nuovo un abbonamento Pro o Entreprise, le Sue chiavi congelate ridiventano automaticamente utilizzabili, entro il limite del nuovo piano: prima quelle che erano attive al momento del congelamento, poi le più vecchie. Le eventuali chiavi oltre il limite restano congelate.
Quando passa dal piano Entreprise al piano Pro
Il piano Pro consente una sola chiave attiva. Alla data del cambiamento, la chiave più vecchia (per data di creazione) resta attiva e le altre vengono congelate. Restano visibili nella schermata Chiavi API con il badge Congelata. Se torna al piano Entreprise, ridiventano attive automaticamente.
Scegliere la chiave attiva
Finché il Suo piano non cambia, nessuna chiave congelata viene riattivata automaticamente. È Lei a scegliere:
- Il pulsante Riattiva compare accanto a ogni chiave congelata finché il numero delle Sue chiavi attive è inferiore al limite del Suo piano. Nel piano Pro, revochi quindi prima la chiave attiva, se ce n'è una (la revoca è definitiva).
- La chiave riattivata funziona di nuovo immediatamente, con lo stesso valore e gli stessi diritti. Se può essere stata esposta, ne esegua la rotazione subito dopo.
- Una rotazione non riattiva una chiave congelata: resta congelata.
Revoca da parte di QR Suisse
QR Suisse può revocare tutte le chiavi API del Suo account, attive o congelate, su richiesta di un amministratore dell'account (scriva a contact@qrsuisse.ch dall'indirizzo e-mail che utilizza per QR Suisse) oppure se una chiave può essere stata esposta a terzi o utilizzata senza il Suo consenso. È in particolare la soluzione se una chiave è stata divulgata mentre il Suo account è nel piano Gratuito, nel quale non può revocarla Lei stesso.
Questa revoca è immediata e definitiva, come quella che effettua Lei stesso. Gli amministratori dell'account ne vengono informati per e-mail. I Suoi codici QR, la Sua quota e i Suoi pacchetti non vengono toccati. Nel piano Pro o Entreprise, può creare subito nuove chiavi. Una chiave congelata revocata non viene riattivata quando sottoscrive di nuovo un abbonamento.
Limite di frequenza ed errore 429
Per proteggere il servizio, il numero di chiamate è limitato, su finestre di 60 secondi:
| Limite | Numero massimo |
|---|---|
| Tutte le richieste | 30 al minuto per chiave |
| Creazioni di codici QR | 8 al minuto per chiave, in aggiunta al limite qui sopra |
| Immagini PNG di un codice QR | 10 al minuto per l'intero account (il formato SVG non è soggetto a questo limite) |
Oltre questi limiti, l'API risponde 429 rate_limited, con un'intestazione Retry-After che indica in secondi quando riprovare. Programmi il Suo strumento in modo che attenda questo intervallo prima di riprovare, invece di ripetere subito la chiamata.
Anche le chiamate rifiutate per una chiave non valida (401 unauthorized) sono limitate, a 60 al minuto dallo stesso indirizzo IP e a 300 al minuto per un'intera rete IPv6 /48. Oltre questo limite, l'API risponde 429 rate_limited per il resto del minuto, anche con una chiave valida. Uno strumento configurato male che insiste con una vecchia chiave può quindi bloccare temporaneamente gli altri strumenti che chiamano l'API dallo stesso indirizzo.
Non confonda i due errori 429: rate_limited significa «troppe chiamate in poco tempo, riprovi tra qualche secondo», quota_exceeded significa «nessuna creazione più disponibile questo mese» (cfr. «Quote di creazioni e pacchetti»).
Domande frequenti
Ho perso la mia chiave: posso recuperarla?
No. La chiave completa viene mostrata una sola volta e non la conserviamo in chiaro. Ne esegua la rotazione con il pulsante Rotazione: ottiene una nuova chiave, con lo stesso nome e gli stessi diritti. Si ricordi di sostituirla in tutti gli strumenti che utilizzavano quella vecchia.
Perché l'API risponde 401 quando utilizzo la mia chiave?
L'API risponde 401 unauthorized in tutti questi casi, senza distinguerli: chiave copiata male o incompleta, chiave revocata, chiave il cui segreto è cambiato dopo una rotazione, oppure chiave congelata (ad esempio perché il Suo account è passato al piano Gratuito). Verifichi nella schermata Chiavi API che la chiave esista ancora, che non porti il badge Congelata e che i suoi ultimi 4 caratteri corrispondano a quelli della chiave utilizzata.
Perché l'API risponde 403?
Con forbidden, la chiave è valida ma i suoi diritti non consentono l'operazione richiesta: aggiunga il diritto mancante in Diritti della chiave, poi clicchi su Salva i diritti. Con account_disabled, l'account è sospeso o in attesa di eliminazione: la chiave non è la causa, scriva a contact@qrsuisse.ch. Con plan_required, l'account non ha più un piano Pro o Entreprise attivo. Con https_required, il Suo strumento ha chiamato l'API in http:// invece di https://: la richiesta non è stata elaborata, ma la chiave ha viaggiato in chiaro. Corregga l'indirizzo in https://app.qrsuisse.ch/api/v1, poi ruoti la chiave con il pulsante Rotazione.
Che cosa significa l'errore 429?
Con rate_limited, il Suo strumento ha inviato troppe richieste in poco tempo: attenda l'intervallo indicato dall'intestazione Retry-After, poi riprovi. Con quota_exceeded, la quota di creazioni del mese e i Suoi pacchetti sono esauriti: la creazione torna possibile il 1° del mese successivo, oppure non appena acquista un pacchetto.
Una creazione è stata interrotta da un'interruzione di rete: come inviarla di nuovo senza duplicati?
Se il Suo strumento invia l'intestazione Idempotency-Key con ogni creazione (un nuovo valore casuale per ogni creazione), può inviare di nuovo la stessa richiesta con lo stesso valore entro 24 ore: l'API restituisce il codice QR già creato, senza crearne un secondo né conteggiare un'altra creazione. Senza questa intestazione, verifichi l'elenco dei Suoi codici QR prima di inviarla di nuovo: una creazione riuscita resta conteggiata, anche se poi elimina il duplicato. I dettagli si trovano nella documentazione API.
La creazione di una chiave consuma la mia quota?
No. Solo i codici QR creati tramite l'API vengono conteggiati nella quota mensile.
I miei codici QR creati tramite l'API vengono eliminati se revoco la chiave?
No. La revoca di una chiave non modifica né elimina alcun codice QR. I codici QR creati con questa chiave continuano a funzionare.
Perché non vedo la schermata Chiavi API?
La schermata Chiavi API è riservata ai membri che dispongono del permesso Gestore delle chiavi API (o Amministratore). Nel piano Gratuito, indica che l'accesso API è disponibile con i piani Pro ed Entreprise, e le eventuali chiavi congelate non vi sono mostrate. Chieda a un amministratore dell'account di assegnarLe il permesso o di passare al piano Pro.
La mia chiave potrebbe essere stata esposta: che cosa devo fare?
Ne esegua subito la rotazione con il pulsante Rotazione se i Suoi strumenti devono continuare a utilizzarla, altrimenti la revochi con il pulsante Revoca. In entrambi i casi, la vecchia chiave smette subito di funzionare. Se non può farlo Lei stesso, ad esempio perché il Suo account è nel piano Gratuito, scriva a contact@qrsuisse.ch dall'indirizzo e-mail di un amministratore dell'account.
Quante chiavi posso avere?
Una chiave attiva con il piano Pro, fino a 10 chiavi attive contemporaneamente con il piano Entreprise. Per creare una nuova chiave, anche le Sue chiavi congelate contano in questo limite, finché non le ha revocate.