Quickstart API REST
- 1
Crei una chiave API
Nella dashboard: Impostazioni → Chiavi API → Nuova chiave. La chiave in chiaro viene mostrata una sola volta e non viene più memorizzata — restano solo un hash HMAC-SHA-256 e un breve prefisso di visualizzazione. Formato: `qrs_live_<64 caratteri hex>`; la memorizzi come `QCS_API_KEY`. Scelga gli scope alla creazione: `qrcodes:read`, `qrcodes:write`, `scans:read`, `conversions:write`. Il form preseleziona i due di lettura, il default prudente per una credenziale che finisce in un job CI. L'accesso API è una funzione del piano Business; una chiave su un piano inferiore si autentica ma riceve 403 `plan_limit`. Ogni chiave è limitata a 300 richieste al minuto.
- 2
Crei un codice QR dinamico
POST su `/api/v1/qrcodes` con header `Authorization: Bearer $QCS_API_KEY` e body `{"name": "Volantino primavera", "type": "url", "destination_url": "https://example.com/landing"}`. La risposta `{"data": {…}}` contiene l'id del codice, lo slug generato e `scan_url` — l'indirizzo tracciato `/q/{slug}` codificato nel codice stampato. `status` accetta `draft`, `active` o `paused`, e `campaign_id` collega il codice a una campagna esistente. Se il workspace ha esaurito la quota di QR dinamici, la chiamata risponde 403 `plan_limit` con `details.limit` e `details.current` invece di un errore generico. I tipi statici non consumano mai quella quota.
- 3
Legga gli eventi di scan
GET `/api/v1/scans?qr_id={id}&days=30&per_page=50` restituisce una pagina di eventi di scan più un blocco `pagination`. Ogni evento porta `device_type`, `os`, `browser`, `country`, `region`, `city`, `language`, `referrer`, `is_bot`, `ab_variant` e la `destination` verso cui il visitatore è stato inviato. `days` accetta da 1 a 365 e vale 30 di default. Nella risposta non ci sono indirizzi IP perché la piattaforma non li memorizza: in database arriva solo un hash con chiave. Ometta `qr_id` per leggere tutti gli scan del workspace.
- 4
Cambi la destinazione
PATCH `/api/v1/qrcodes/{id}` con body `{"destination_url": "https://example.com/new-destination"}`. Lo stesso endpoint accetta `name`, `payload`, `campaign_id` e `status` con `draft`, `active`, `paused` o `archived`; serve almeno un campo. Risponde 200 con il record aggiornato. Il codice stampato risolve al nuovo URL già dallo scan successivo — senza ristampa, senza purge della cache. `DELETE /api/v1/qrcodes/{id}` risponde 204 e ritira il codice.
- 5
Registri una conversione lato server
POST `/api/v1/conversions` con body `{"event_name": "purchase", "external_id": "order-1042", "amount": 49.9, "currency": "EUR", "qr_slug": "volantino-primavera"}`. Un evento nuovo risponde 201 `{"id": …, "created": true}`; ripetere lo stesso `external_id` risponde 200 `{"duplicate": true}`, quindi un job che riprova non può contare due volte il fatturato. L'attribuzione accetta `qr_slug` oppure il valore `session_ref` catturato sulla landing page. La chiamata richiede lo scope `conversions:write`.
- 6
Errori, e dove si colloca il plugin WordPress
Ogni errore restituisce `{"error": {"code": …, "message": …}}` con un codice stabile su cui ramificare: `unauthorized`, `insufficient_scope`, `plan_limit`, `validation_error`, `not_found`, `rate_limited`. Gli errori di validazione aggiungono `details.issues` indicizzato per campo. Il plugin WordPress è un connettore, non una seconda API: si sincronizza nello stesso workspace via `/api/v1/wp/*` con la sua chiave di licenza, così i codici creati in WordPress compaiono nella stessa lista `GET /api/v1/qrcodes` di quelli creati qui. Non serve il plugin per usare l'API, né l'API per usare il plugin.
Domande frequenti
Che cos'è QRCode Suite?
QRCode Suite è una piattaforma QR indipendente: crei un account gratuito e generi QR code dinamici e personalizzati nel browser — senza bisogno di WordPress. I connettori portano gli stessi codici su WordPress e WooCommerce, dove gli ordini possono essere attribuiti a specifici QR code.
QRCode Suite funziona senza WordPress?
Sì. QRCode Suite è un SaaS indipendente: si registri, crei i QR code e monitori le scansioni interamente su qrcode-suite.com. Il plugin WordPress è un connettore opzionale che porta i Suoi codici in wp-admin e aggiunge l'attribuzione degli ordini WooCommerce.
QRCode Suite richiede un abbonamento separato?
Il piano Free è disponibile senza costi — senza carta di credito. I piani a pagamento (Pro 9 €, Business 29 €, Agency 79 € al mese) sbloccano codici illimitati, regole di redirect e altro. Non ci sono costi per singola scansione.
Quali tipi di QR code supporta QRCode Suite?
QRCode Suite supporta 22 tipi di QR code: URL statico, URL dinamico, Testo semplice, Telefono, Email, Posizione, Link Hub, SMS, WhatsApp, Wi-Fi, vCard, Profilo social, PDF, Download di file, Download di app, Coupon, Evento calendario, Modulo di raccolta lead, Raccolta recensioni, Richiesta all'ingrosso, Premio fedeltà e Payload personalizzato.
Posso modificare la destinazione di un QR code dopo averlo stampato?
Sì. I QR code dinamici usano un URL di redirect breve. Può aggiornare la destinazione dalla dashboard in qualsiasi momento, senza rigenerare o ristampare il codice.