Creare un QR code per l'API REST: guida con esempi curl

Passo 1: creare la chiave

Nella dashboard, sotto Account, sezione «Accesso per CLI, script e agenti», crea una chiave. Per le prime prove basta «solo lettura». Scegli una durata breve, ad esempio 30 giorni. La chiave inizia con sqr_live_ e viene mostrata una sola volta. Salvala come variabile d’ambiente, così non finisce nella cronologia della shell, ad esempio tramite il tuo gestore di password.

Passo 2: La prima richiesta

L'API si trova all'indirizzo https://sameqr.com/api/v1. La chiave va inserita nell'header Authorization, mai nell'indirizzo:

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

La prima richiesta mostra il tuo account, il tuo piano tariffario e i limiti; la seconda mostra i codici QR con identificativo, nome, destinazione, etichette, numero di scansioni e lo stato _rev.

Passo 3: Creare un codice QR

Per la creazione è necessaria una seconda chiave con „lettura + scrittura“. Con una chiave di sola lettura, l'API risponde alle richieste di modifica con 403 e il codice NUR_LESEN. Un nuovo codice QR richiede almeno un nome e una destinazione:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Scansiona il nuovo codice QR con il telefono prima di procedere. Per la creazione è necessario che l'indirizzo email sia confermato e il codice QR viene conteggiato nel contingente del piano tariffario.

Passo 4: Modificare la destinazione

Le modifiche alla destinazione sono particolarmente protette. È necessaria una chiave „completo“ e si invia lo stato corrente del codice QR come intestazione X-Confirm. Lo stato è fornito dalla richiesta di lettura:

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

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

Vengono modificate solo le campi inviati. Se lo stato differisce perché qualcuno ha già modificato il codice QR, nulla viene sovrascritto. Tramite l'API, al massimo 10 modifiche alla destinazione all'ora e 30 al giorno; nella dashboard non esiste questo limite. Nel piano gratuito, il numero di modifiche alla destinazione per codice QR è limitato.

Passo 5: Comprendere errori e limiti

Gli errori tornano sempre nella stessa forma: un oggetto error con status, code e message. Valuta nel tuo programma, invece di continuare semplicemente.

• 401: La chiave manca, è errata, scaduta o revocata.
• 403: La chiave non ha il livello necessario o il piano non consente l'azione.
• 400 con BESTAETIGUNG_FEHLT: Per la modifica della destinazione, offline o eliminazione, manca X-Confirm con lo stato corrente.
• 409: Qualcuno ha modificato il codice QR nel frattempo.
• 429: Troppe richieste. Per chiave si possono inviare 120 al minuto, 60 all'ora nel piano gratuito, 300 in Start, 1.000 in Pro e 5.000 in Agentur.

Tutte le richieste sono descritte in /api/v1/openapi.json, la documentazione si trova su sameqr.com/entwickler.

Conclusione: perché Same-QR

L'API REST di Same-QR è ordinata, ben documentata e inclusa in ogni piano. Puoi fare tutto ciò che può la dashboard, protegge i codici QR stampati con conferma e limiti contro modifiche accidentali alla destinazione, consente chiavi in tre livelli e risponde con errori comprensibili.

Inizi subito: registrati gratuitamente su sameqr.com, 20 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