API per codici QR: come integrare la generazione nella tua app

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 }`. In caso di errore, `data` è null e `error` contiene `code` e `message`.

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 in un password manager o in una variabile d'ambiente.

Aggiungi questo header a ogni richiesta:

```bash curl https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_il_tuo_token" ```

Se la key non è valida o il piano è scaduto, l'API restituisce `401 UNAUTHORIZED` o `403 PLAN_REQUIRED`. Puoi revocare la key in qualsiasi momento dal pannello; smette di funzionare immediatamente.

L'endpoint pubblico è il modo più veloce per testare l'API o generare QR semplici da uno script senza gestire l'autenticazione:

```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): il contenuto del QR. Può essere un URL, testo, un'email o dati WiFi.
• `format`: `"png"` (predefinito) o `"svg"`
• `size`: `256`, `512` (predefinito) o `1024`

La risposta restituisce l'immagine in base64 dentro l'envelope JSON:

```json { "data": { "image": "iVBORw0KGgo...", "format": "png", "size": 512 }, "error": null } ```

Se superi le 50 richieste al giorno dalla stessa IP, ricevi `429 RATE_LIMITED` con l'header `Retry-After` che indica quando si resetta il contatore.

Un QR dinamico codifica un URL breve fisso (`/r/{slug}`), ma la sua destinazione finale può essere cambiata quando vuoi. Il codice stampato non cambia mai.

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"}' ```

Scaricare l'immagine del QR:

```bash curl -o mio-qr.png \ "https://codigo-qr.es/api/v1/qr/{id}/image?format=png&size=1024" \ -H "Authorization: Bearer cqr_il_tuo_token" ```

Vedere le statistiche di scansione:

```bash curl "https://codigo-qr.es/api/v1/qr/{id}/stats?period=30d" \ -H "Authorization: Bearer cqr_il_tuo_token" ```

Risposta: ```json { "data": { "total": 312, "period": "30d", "by_day": [{"date": "2026-05-01", "count": 18}], "by_country": [{"country": "IT", "count": 260}] }, "error": null } ```

L'API è utile quando il volume o l'automazione rendono impraticabile generare QR a mano dal pannello.

E-commerce: QR su bolle e fatture

Il gestionale ERP genera il PDF della bolla. Con una chiamata a `POST /api/v1/qr` ottiene un QR che punta all'URL di tracciamento dell'ordine. Se l'URL cambia, `PATCH /api/v1/qr/{id}` aggiorna la destinazione senza rigenerare né ristampare nulla.

Ristoranti: menu per tavolo dal POS

Il sistema di cassa crea un QR per tavolo all'apertura del turno. Punta al menu del giorno, che lo chef aggiorna nel CMS. Il QR sul tavolo non cambia mai, cambia solo la destinazione. Niente più plastificazione di menu ogni settimana.

Eventi: biglietti personalizzati in massa

Un sistema di biglietteria genera un QR univoco per biglietto con `POST /api/v1/qr` e lo incorpora nel PDF. All'ingresso, lo scanner verifica il QR leggendo `GET /api/v1/qr/{id}` per confermarne la validità.

Logistica: pacchi con tracciamento

Ogni pacco riceve un QR che punta alla sua pagina di tracciamento. Il cliente lo scansiona dalla busta e vede lo stato in tempo reale. Le scansioni restano registrate in `GET /api/v1/qr/{id}/stats`.

L'API applica limiti di frequenza per garantire disponibilità.

Livello pubblico (`/api/v1/qr/render`):
• Limite: 50 richieste al giorno per IP
• Finestra: 24 ore
• Nessuna registrazione richiesta

Livello Pro (endpoint con API key):
• Limite: 60 richieste al minuto per utente
• Nessun limite giornaliero totale

Superato il limite, l'API restituisce `429 Too Many Requests` con questi header:

``` X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1747612800 Retry-After: 43 ```

`X-RateLimit-Reset` è il timestamp Unix in cui si resetta il contatore. `Retry-After` sono i secondi mancanti a quel momento.

Consulta la documentazione completa dell'API per tutti i parametri e le risposte di errore.