API per codici QR: crea, modifica e analizza automaticamente i codici QR

A cosa serve un'API per codici QR

Un'API per codici QR è un'interfaccia di programmazione: invece di cliccare nel browser, il tuo programma invia richieste al servizio di codici QR e riceve risposte. In questo modo, i codici vengono generati direttamente da un negozio, da un sistema di gestione magazzino, da uno script o da un foglio di calcolo.

Ciò è vantaggioso non appena il lavoro si ripete: centinaia di codici per tavoli o prodotti, report mensili di scansione, la modifica di molte destinazioni dopo un rilancio. E funziona solo con codici dinamici. Un codice QR dinamico di Same-QR contiene un indirizzo breve e costante; la destinazione sottostante è gestita da noi e può essere modificata in qualsiasi momento senza dover stampare nuovamente.

Cosa copre l'API per codici QR di Same-QR

L'API REST si trova su https://sameqr.com/api/v1. Essa richiama le stesse funzionalità della dashboard, con gli stessi limiti tariffari e controlli:

• Elencare, leggere, creare, modificare ed eliminare codici QR.
• Le statistiche di un codice: scansioni, data di creazione, numero di modifiche alla destinazione.
• Crea, modifica, pubblica e disattiva pagine ospitate come menù, listini prezzi, orari di apertura, pagine link, azioni, cantine, etichette e-Label per vini e contatti.
• Importa un menù da fino a quattro foto o da un PDF.
• Gestisci etichette e progetti cliente e leggi richieste dai moduli di contatto.

Una descrizione leggibile dalle macchine di tutte le richieste è disponibile su /api/v1/openapi.json; le istruzioni si trovano su sameqr.com/entwickler.

Chiave API e permessi

La tua chiave si crea nella dashboard sotto Account, sezione "Accesso per CLI, script e agenti". Si sceglie uno dei tre livelli, "solo lettura", "lettura + scrittura" (creare, modificare nomi e testi) o "completo" (inoltre modificare destinazioni, mettere offline, eliminare), e una durata di 30, 90, 180 o 365 giorni, se necessario anche illimitata. La chiave inizia con sqr_live_ e viene visualizzata esattamente una volta. Viene memorizzato da noi solo un checksum.

Una chiave che può solo leggere riceve un chiaro rifiuto a ogni richiesta modificante. Per report e valutazioni è la scelta giusta. Tutto ciò che viene modificato, verso dove porta un codice stampato, è protetto ulteriormente: modifiche alla destinazione, messa offline ed eliminazione richiedono il livello "completo" e una conferma con lo stato precedentemente letto, e tramite l'API ne avvengono al massimo 10 all'ora e 30 al giorno. Nella dashboard questo limite non esiste. Ogni chiave può essere revocata in qualsiasi momento e diventa immediatamente non valida.

Un tipico flusso di lavoro

La chiave va inserita nell'header Authorization, mai in un URL. La chiave va precedentemente impostata come variabile d'ambiente. In questo modo si elencano i codici e si modifica la destinazione di un codice:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

Il valore per X-Confirm, lo stato, viene fornito dalla richiesta di lettura su /api/v1/qr/<id>. Viene modificato solo ciò che si invia. Chi vuole assicurarsi che nessuno nel frattempo abbia modificato lo stesso codice, invia lo stato letto come _rev. Se è cambiato qualcosa, nulla viene sovrascritto e la risposta contiene lo stato corrente. Gli errori tornano sempre nello stesso formato, con status, codice e un messaggio comprensibile.

Limiti e buone pratiche

Per chiave si possono effettuare al massimo 120 richieste al minuto. Si aggiunge un limite orario dipendente dal piano: 60 nel piano gratuito, 300 in Start, 1.000 in Pro e 5.000 in Agentur. I limiti catturano errori, come uno script in un loop infinito, e non disturbano un uso onesto.

• Prova prima con una chiave di sola lettura, poi scrivi.
• Testa nuovi flussi su un singolo codice e scansiona con il telefono.
• Evita l'eliminazione, dove basta una nuova destinazione. I codici eliminati e i loro short link non vengono ripristinati.
• Crea una chiave separata per ogni programma e mantienila in un gestore di password o in una variabile d'ambiente.

Conclusione: perché Same-QR

Same-QR offre l'API non come un extra costoso, ma in ogni piano, con le stesse funzionalità della dashboard: codici, statistiche, menù, pagine ospitate, etichette e progetti. Si aggiungono permessi chiari per chiave, messaggi di errore onesti e una verifica notturna di tutte le destinazioni che segnala per email se una non è raggiungibile.

Inizi subito: registrati gratuitamente su sameqr.com, due codici QR dinamici sono gratuiti per sempre. API, CLI e server MCP sono inclusi in ogni piano, la documentazione è su sameqr.com/entwickler.

Domande frequenti