API di QR Suisse: documentazione dell'API REST
QR Suisse offre un'API REST che Le permette di creare, leggere, modificare, archiviare ed eliminare i Suoi codici QR dinamici tramite programmazione, cercarli nel Suo elenco, scaricarne l'immagine (PNG o SVG), oltre a consultarne le statistiche di scansione. Si integra con i Suoi strumenti esistenti — Zapier, Make, un CRM, uno script interno — ovunque sia sufficiente una richiesta HTTPS.
L'API è disponibile con i piani Pro ed Entreprise. Il piano Pro include 5 creazioni di codici QR tramite l'API al mese e 1 chiave API; il piano Entreprise include 100 creazioni al mese e fino a 10 chiavi API attive contemporaneamente. Con entrambi i piani è possibile acquistare pacchetti di creazioni API opzionali. Le chiavi si gestiscono dalla dashboard. Consulti i nostri prezzi per i dettagli dei piani e dei pacchetti.
Creare una chiave, sceglierne i diritti, eseguirne la rotazione o revocarla: la pagina di aiuto Gestire le chiavi API spiega tutto, comprese le quote, il congelamento nel piano Gratuito e il limite di frequenza.
Versione attuale dell'API: 1.1.1. Le novità di ogni versione e il nostro impegno di compatibilità figurano nella sezione Cronologia delle versioni del riferimento qui sotto.
Per iniziare
- Passi al piano Pro o Entreprise se non lo ha già fatto.
- Generi una chiave API dalla Sua dashboard e scelga i diritti necessari (lettura, creazione, modifica, eliminazione, statistiche).
- Autentichi ogni richiesta con l'header Authorization: Bearer <chiave>.
- Consulti il riferimento completo degli endpoint qui sotto.
Domande frequenti
Quali piani danno accesso all'API?
I piani Pro ed Entreprise, senza costi aggiuntivi. Il piano Pro include 5 creazioni di codici QR tramite l'API al mese e 1 chiave API; il piano Entreprise include 100 creazioni al mese e fino a 10 chiavi API attive contemporaneamente. Il piano Gratuito non dà accesso all'API.
Quali operazioni consente l'API oggi?
Creare, leggere, modificare, archiviare (e riattivare) ed eliminare codici QR (tipi URL e biglietto da visita), cercare, filtrare e ordinare il loro elenco, scaricarne l'immagine (PNG o SVG), consultarne le statistiche di scansione e leggere la quota di creazioni rimanente. Una creazione interrotta da un'interruzione di rete può essere inviata di nuovo senza duplicati, con l'header Idempotency-Key. La gestione dei codici QR già esistenti (lettura, modifica, archiviazione, eliminazione, download dell'immagine, statistiche) non è soggetta a quota.
Posso collegare l'API a un automatismo o a un agente IA?
L'API è un'API REST standard autenticata tramite chiave — può essere richiamata da qualsiasi strumento capace di inviare richieste HTTPS, Zapier o Make compresi, o da un agente che interroga direttamente questi endpoint. Un connettore dedicato per assistenti IA (MCP) non è disponibile ad oggi.
Esiste un limite al numero di chiamate o di creazioni?
Sì, due. Un limite di frequenza protegge il servizio: 30 richieste al minuto per chiave, di cui al massimo 8 creazioni, e 10 immagini PNG al minuto per l'intero account; oltre, l'API risponde 429 rate_limited con il tempo di attesa. Inoltre, solo la creazione di codici QR tramite l'API è soggetta a una quota mensile: 5 creazioni per mese civile con il piano Pro, 100 con il piano Entreprise, non riportabili da un mese all'altro. Se questa quota non basta, si aggiungono i pacchetti di creazioni API (acquisto unico, non rimborsabile, abbonamento Pro o Entreprise attivo richiesto). La lettura, la modifica, l'archiviazione, l'eliminazione, il download delle immagini e la consultazione delle statistiche non consumano questa quota. Il Suo strumento può leggere in qualsiasi momento le creazioni del mese e il saldo rimanente con GET /usage.
Cosa fa l'API, cosa fa la dashboard
L'API e la dashboard agiscono sugli stessi codici QR, ma non coprono le stesse operazioni. La tabella seguente descrive ciò che è disponibile oggi. L'API è riservata ai piani Pro ed Entreprise. La dashboard è disponibile con tutti i piani; le funzioni riservate ai piani Pro ed Entreprise sono indicate.
| Operazione | API | Dashboard |
|---|---|---|
| Creare un codice QR Link | Sì. Per un'e-mail, un telefono, un SMS o un server FTP, invii l'indirizzo completo (mailto:, tel:, sms:, ftp://). | Sì, con procedure guidate: oggetto e messaggio precompilati, parametri UTM. |
| Creare un biglietto da visita | Sì. | Sì. |
| Creare un QR Calendario | Non documentato: l'API non ha né campi per l'evento (titolo, orari, luogo) né un endpoint dedicato. Crei i QR Calendario nella dashboard. | Sì. |
| Modificare la destinazione, la denominazione o un biglietto da visita | Sì. Un biglietto da visita può essere modificato in parte: i campi non inviati restano invariati. | Sì, dalla pagina del codice QR. |
| Archiviare o riattivare | Sì, un codice QR alla volta, con il campo active della modifica. Né l'archiviazione né la riattivazione vengono conteggiate nella quota di creazioni. | Sì, un codice QR alla volta, o fino a 100 alla volta (Pro ed Entreprise). |
| Eliminare definitivamente | Sì. | Sì, un codice QR alla volta. |
| Elencare i codici QR | Sì, pagina per pagina, con ricerca nella denominazione, nella destinazione e nella fine dell'indirizzo breve, filtri (attivo o archiviato, tipo, periodo di creazione) e ordinamento (data di creazione, denominazione). Né filtro per autore o per tag, né ordinamento per numero di scansioni. | Sì, con ricerca, filtri (stato, tipo, autore, tag) e ordinamento. |
| Tag | No. | Sì (Pro ed Entreprise). |
| Azioni di gruppo, download in ZIP, esportazione CSV | No. Le immagini si scaricano una alla volta. | Sì, fino a 100 codici QR alla volta (Pro ed Entreprise). |
| Scaricare l'immagine in PNG o in SVG | Sì. PNG da 128 a 1024 pixel di lato, a scelta. | Sì. |
| Statistiche di scansione | Totale e scansioni al giorno di un codice QR, su 15 mesi, senza scelta del periodo. | Grafico di ogni codice QR e pagina Statistiche filtrabile per codice QR e per periodo. Cronologia: 7 giorni nel piano Gratuito, 15 mesi con Pro ed Entreprise. |
| Indirizzo con il Suo dominio personalizzato | Sì: quando il Suo dominio è attivo, l'indirizzo e l'immagine restituiti dall'API lo utilizzano. | Sì, configurazione compresa (Pro ed Entreprise). |
| Seguire le creazioni tramite l'API del mese | Sì, con GET /usage (diritto QR_CREATE): creazioni del mese, quota mensile, crediti rimanenti nei Suoi pacchetti e data di azzeramento. Una creazione rifiutata restituisce inoltre 429 quota_exceeded con la data di azzeramento. | Sì, nella schermata Chiavi API (permesso «Gestore delle chiavi API» o Amministratore). |
| Chiavi API, membri e permessi, abbonamento, acquisto di pacchetti | No. | Sì, secondo il Suo piano e i Suoi permessi. |
- Nella dashboard, il tipo di un codice QR (Link, Biglietto da visita o Calendario) è fissato alla creazione. Tramite l'API, la destinazione di un codice QR Link o Calendario può essere sostituita con qualsiasi indirizzo accettato: un Calendario può così diventare un Link, e viceversa. Un biglietto da visita resta un biglietto da visita. In entrambi i casi, l'indirizzo breve codificato nell'immagine non cambia mai.
- Né l'API né la dashboard inviano notifiche automatiche (webhook), ad esempio a una scansione o quando la quota è raggiunta.
- Per inviare di nuovo senza duplicati una creazione interrotta da un tempo scaduto o da un'interruzione di rete, la invii con l'header Idempotency-Key (un valore casuale per ogni creazione, UUID v4 consigliato): inviata di nuovo con lo stesso valore di Idempotency-Key e lo stesso contenuto entro 24 ore, restituisce il codice QR già creato, senza crearne un secondo né consumare un'altra creazione della quota. Senza questo header, verifichi l'elenco dei Suoi codici QR prima di inviarla di nuovo: una creazione riuscita resta conteggiata nella quota, anche se poi elimina il codice QR doppio.