API per codici QR: come integrare la generazione nella tua app
Guida con esempi curl per creare, gestire e scaricare codici QR dinamici tramite API REST
L'API REST di codigo-qr.es ti permette di generare, aggiornare e analizzare codici QR direttamente dalla tua applicazione, senza passare dal pannello. Puoi automatizzare la creazione di QR per fatture, menu digitali o biglietti evento, e cambiare la destinazione di un QR dinamico in produzione senza toccare il codice stampato. L'endpoint pubblico funziona senza registrazione. L'API completa, con CRUD e statistiche, richiede il piano Pro.
Quali endpoint ha l'API per codici QR?
L'API REST ha otto endpoint: generazione pubblica senza autenticazione e sette endpoint Pro per creare, elencare, aggiornare, eliminare, scaricare e analizzare i QR.
L'API di codigo-qr.es ha due livelli.
Endpoint pubblico (nessun account richiesto):
`POST /api/v1/qr/render` genera un QR statico e restituisce l'immagine in base64. Limite: 50 richieste al giorno per IP.
Endpoint Pro (richiedono API key):
| Metodo | Percorso | Scopo | |--------|----------|-------| | `GET` | `/api/v1/qr` | Elencare tutti i codici QR | | `POST` | `/api/v1/qr` | Creare QR statico o dinamico | | `GET` | `/api/v1/qr/{id}` | Dettagli di un codice QR | | `PATCH` | `/api/v1/qr/{id}` | Aggiornare destinazione o nome | | `DELETE` | `/api/v1/qr/{id}` | Eliminare un codice QR | | `GET` | `/api/v1/qr/{id}/image` | Scaricare immagine PNG o SVG | | `GET` | `/api/v1/qr/{id}/stats` | Statistiche di scansione |
Tutte le risposte Pro seguono il formato `{ "data": {...}, "error": null }`.
Come ottengo un API key per i codici QR?
L'API key si genera in /panel/account con un clic. È disponibile solo con piano Pro attivo e può essere revocata dallo stesso pannello.
Passo 1. Crea un account su codigo-qr.es.
Passo 2. Attiva il piano Pro. L'API completa è esclusiva Pro a 5,99€/mese.
Passo 3. Vai su /panel/account e clicca su «Genera API key». Il token viene mostrato una volta sola. Salvalo.
Aggiungi questo header a ogni richiesta:
```bash curl https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_il_tuo_token" ```
Come si genera un codice QR tramite API senza registrazione?
L'endpoint /api/v1/qr/render genera QR PNG o SVG senza account e senza API key, con un limite di 50 richieste al giorno per IP.
```bash curl -X POST https://codigo-qr.es/api/v1/qr/render \ -H "Content-Type: application/json" \ -d '{"value":"https://tuosito.it","format":"png","size":512}' ```
Parametri: `value` (obbligatorio), `format` (png o svg), `size` (256, 512 o 1024).
Oltre le 50 richieste al giorno ricevi `429 RATE_LIMITED` con l'header `Retry-After`.
Come si creano e aggiornano i QR dinamici tramite API?
POST /api/v1/qr crea il QR dinamico e restituisce il suo ID. PATCH /api/v1/qr/{id} cambia la destinazione senza rigenerare o ristampare il codice.
Creare un QR dinamico:
```bash curl -X POST https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_il_tuo_token" \ -H "Content-Type: application/json" \ -d '{ "label": "Menu maggio", "type": "url", "value": "https://tuoristorante.it/menu-maggio", "is_dynamic": true, "tracking_mode": "redirect" }' ```
Cambiare destinazione senza ristampare:
```bash curl -X PATCH https://codigo-qr.es/api/v1/qr/{id} \ -H "Authorization: Bearer cqr_il_tuo_token" \ -H "Content-Type: application/json" \ -d '{"destination": "https://tuoristorante.it/menu-giugno"}' ```
A cosa serve l'API per QR in un'azienda?
L'API per QR è utile quando devi generare o aggiornare più di dieci codici al mese: fatture, menu digitali o sistemi di biglietteria.
E-commerce: il gestionale crea un QR per ogni bolla di consegna. Se l'URL cambia, `PATCH` aggiorna la destinazione senza ristampare.
Ristoranti: il sistema di cassa genera un QR per ogni tavolo. Il cuoco aggiorna il menu nel CMS è il QR punta sempre alla versione aggiornata.
Eventi: il sistema di biglietteria genera un QR univoco per ogni biglietto. All'ingresso lo scanner verifica tramite API.
Logistica: ogni pacco ha un QR per la pagina di tracciamento. Le scansioni sono registrate in `GET /api/v1/qr/{id}/stats`.
Quante richieste permette l'API per QR?
L'endpoint pubblico accetta 50 richieste al giorno per IP. Gli endpoint Pro permettono 60 richieste al minuto per utente.
Livello pubblico: 50 al giorno per IP, senza registrazione.
Livello Pro: 60 al minuto per utente, nessun limite giornaliero totale.
In caso di superamento, l'API restituisce `429` con gli header `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `Retry-After`.
Consulta la documentazione completa per tutti i parametri.
§CODIGO-QR.ES / PRO
Inizia oggi l'integrazione con l'API per QR
Crea il tuo account, attiva il piano Pro e genera la tua prima API key in meno di 2 minuti.
Preguntas frecuentes
- L'API per codici QR è gratuita?
- L'endpoint pubblico è gratuito, limitato a 50 richieste al giorno per IP. L'API completa con API key, CRUD, immagine e statistiche richiede il piano Pro a 5,99€/mese.
- I codici QR generati tramite API sono leggibili da qualsiasi lettore?
- Sì. I codici seguono lo standard ISO/IEC 18004. Funzionano con la fotocamera del telefono e qualsiasi app di lettura QR.
- Posso cambiare la destinazione di un QR dinamico tramite API senza ristamparlo?
- Sì. PATCH /api/v1/qr/{id} aggiorna l'URL di destinazione in qualsiasi momento. Il codice QR stampato rimane invariato.
- Il token API è sicuro?
- Viene salvato solo l'hash SHA-256, mai il token in chiaro. Viene mostrato una volta sola al momento della generazione. Revocabile da /panel/account.
Jose Flores
Fundador de codigo-qr.es · codigo-qr.es
Jose Flores es fundador de codigo-qr.es, herramienta de generación de QR dinámicos y códigos de barras creada en Barcelona en 2026. Especializado en soluciones digitales para pequeños negocios, desarrolla herramientas que permiten a restaurantes, comercios y profesionales digitalizar su comunicación sin infraestructura técnica propia.
Más artículos