Sviluppatori
Riferimento API e integrazioni
Tutto ciò che serve per chiamare la Business API, gestire le chiavi e ricevere i webhook.
Autenticazione
La Business API autentica ogni richiesta con una chiave API. Inviala nell'header X-Api-Key oppure come token Bearer nell'header Authorization.
Le chiavi hanno il prefisso qrg_ e vengono mostrate una sola volta, al momento della creazione. Conservale in un luogo sicuro: in seguito non potrai più recuperarle.
Le richieste senza una chiave valida restituiscono 401. Una chiave senza l'autorizzazione richiesta riceve 403 con l'errore insufficient_scope. Le risorse esterne alla tua area di lavoro restituiscono 404, come se non esistessero.
URL di base
Tutti gli endpoint della Business API si trovano sotto il prefisso /v1.
Ad esempio, puoi elencare i tuoi codici QR su https://qr-global.com/api/v1/qr-codes.
- URL di base risolto
- https://qr-global.com
Endpoint
Tutti gli endpoint si trovano sotto /api/v1 e richiedono una chiave con l'autorizzazione indicata.
| Metodo | Percorso | Autorizzazione | Cosa fa |
|---|---|---|---|
| GET | /qr-codes | qr:read | Elencare i codici QR (filtri: type, search, folder_id, tag, archived) |
| POST | /qr-codes | qr:write | Creare un codice QR |
| POST | /qr-codes/bulk | qr:write | Creare fino a 100 codici QR in una volta |
| GET | /qr-codes/{id} | qr:read | Ottenere un codice QR |
| PUT | /qr-codes/{id} | qr:write | Aggiornare un codice QR, la sua cartella e i tag |
| DELETE | /qr-codes/{id} | qr:write | Eliminare un codice QR |
| GET | /qr-codes/{id}/image | qr:read | Generare l'immagine (PNG o SVG) |
| GET | /qr-codes/{id}/stats | analytics:read | Statistiche delle scansioni |
| GET | /qr-codes/{id}/scans | analytics:read | Registro delle scansioni |
| GET | /folders | qr:read | Elencare le cartelle |
| GET | /tags | qr:read | Elencare i tag |
| GET | /webhooks | webhooks:manage | Elencare le sottoscrizioni webhook |
| POST | /webhooks | webhooks:manage | Sottoscrivere eventi |
| DELETE | /webhooks/{id} | webhooks:manage | Annullare la sottoscrizione |
Una descrizione leggibile dalle macchine (OpenAPI 3.1) per Postman, generatori di codice e strumenti no-code: Scarica openapi.json
Chiavi API
Crea e revoca le chiavi nella pagina Chiavi API della tua dashboard.
Ogni chiave appartiene alla tua area di lavoro ed eredita il limite di richieste del tuo piano.
La revoca di una chiave ha effetto immediato.
Autorizzazioni (scope)
Quando crei una chiave, assegnale l'accesso completo o solo le autorizzazioni necessarie a un'integrazione. Una chiave priva di un'autorizzazione riceve 403 con l'errore insufficient_scope e required_scope nella risposta.
qr:read— Leggere i codici QR- Elencare e visualizzare i codici QR, le loro immagini, cartelle e tag.
qr:write— Gestire i codici QR- Creare codici QR (anche in blocco), modificarli, spostarli tra cartelle, assegnare tag ed eliminarli.
analytics:read— Leggere le statistiche- Statistiche e registro delle scansioni di ogni codice QR.
webhooks:manage— Gestire i webhook- Sottoscrivere eventi per gli endpoint e annullare le sottoscrizioni (Zapier, Make).
Le chiavi create prima dell'introduzione delle autorizzazioni mantengono l'accesso completo. L'accesso completo include anche le autorizzazioni aggiunte in futuro.
Esempi
Comandi curl pronti da copiare e incollare per iniziare. Sostituisci YOUR_API_KEY con una chiave dalla pagina Chiavi API.
Elencare i codici QR
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
Creare un codice QR
Invia il tipo di QR e il contenuto: il server genera e salva il codice.
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"url","content":"https://example.com","display_name":"Example link"}'Generare un'immagine
Ottieni un file PNG o SVG pronto: passa ?format=png
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.png # SVG (vector, no size limit on scale): curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.svg
Esempio di payload webhook
{
"event": "qr.scan.created",
"timestamp": "2026-04-03T12:00:00+00:00",
"data": {
"qr_code_id": 7,
"qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
"type": "url",
"scan_id": 42,
"country": "UA",
"device_type": "mobile",
"scanned_at": "2026-04-03T12:00:00+00:00"
}
}Analisi delle scansioni
GET /qr-codes/{id}/stats restituisce totali, visitatori unici, paesi principali, dispositivi, browser e scansioni al giorno. GET /qr-codes/{id}/scans restituisce il registro delle scansioni, dalla più recente, 50 per pagina (per_page fino a 100).
Entrambi accettano from e to (una data come 2026-10-01 o un timestamp completo) e timezone (UTC per impostazione predefinita). Una data senza orario copre l'intera giornata in quel fuso orario.
È disponibile solo il periodo di cronologia del tuo piano: le scansioni più vecchie vengono eliminate. Indirizzi IP e user agent dei visitatori non vengono mai restituiti.
Statistiche delle scansioni per un periodo
curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Registro delle scansioni, seconda pagina
curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Cartelle e tag
GET /folders e GET /tags elencano le cartelle e i tag della tua area di lavoro. Passa folder_id e tags (slug dei tag) quando crei o aggiorni un codice QR: folder_id null toglie il codice dalla sua cartella e tags sostituisce l'intero insieme.
Filtra l'elenco dei codici QR con ?folder_id= o ?tag=.
Spostare un codice QR in una cartella e assegnargli dei tag
curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 4,
"tags": [
"campaign",
"priority"
]
}'Creazione in blocco
POST /qr-codes/bulk crea fino a 100 codici QR in una sola richiesta. Richiede un piano con la creazione in blocco, come l'importazione CSV nella dashboard, e rispetta il tuo limite di codici QR attivi.
Ogni elemento viene elaborato separatamente: la risposta elenca ogni elemento con lo stato created (e il nuovo codice) o failed (con error ed errors). Non reinviare l'intero lotto, solo gli elementi non riusciti.
Creare due codici QR
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"codes": [
{
"type": "url",
"content": "https://example.com/spring",
"display_name": "Spring flyer",
"tags": [
"campaign"
]
},
{
"type": "url",
"content": "https://example.com/menu",
"display_name": "Table menu",
"folder_id": 4
}
]
}'Sottoscrizioni webhook (REST hooks)
Zapier, Make e i tuoi servizi possono sottoscrivere eventi tramite l'API: POST /webhooks con url ed events, poi DELETE /webhooks/{id} per annullare la sottoscrizione. Sono gli stessi endpoint che vedi nella pagina Webhook.
La risposta a POST contiene secret, mostrato una sola volta: usalo per verificare l'header X-Webhook-Signature. Se non invii un tuo secret (almeno 16 caratteri), ne generiamo uno noi.
Eventi: qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. Per sottoscrivere serve un piano con i webhook; l'annullamento funziona sempre. Un'area di lavoro può avere fino a 25 endpoint.
Sottoscrivere le scansioni
curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"qr.scan.created"
]
}'Annullare la sottoscrizione
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Webhook
I webhook inviano gli eventi al tuo endpoint nel momento in cui si verificano, così non devi fare polling.
Configura gli endpoint nella pagina Webhook della tua dashboard.
Ogni consegna è firmata e, in caso di errore, viene ritentata con backoff esponenziale.
L'evento scan si attiva quando qualcuno scansiona uno dei tuoi codici QR.
Controlla tentativi di consegna, payload e risposte nel registro delle consegne.
Restituisci uno stato 2xx per confermare una consegna; qualsiasi altro stato viene considerato un errore.
Tracciamento delle conversioni
Le conversioni dicono al test A/B quale destinazione porta ordini o iscrizioni, non solo scansioni. Con l'ottimizzazione automatica attiva, il traffico passa alla variante che converte meglio.
Aggiungi lo script alla pagina che il visitatore vede dopo la conversione: conferma d'ordine, pagina di ringraziamento o di successo. Funziona su qualsiasi dominio e non richiede una chiave API.
Snippet
<script src="https://qr-global.com/c.js" async></script>
- Ogni scansione aggiunge all'URL di destinazione un parametro firmato qrg_v, così la conversione viene collegata al codice QR e alla variante.
- Lo script salva il token in un cookie di prima parte per 30 giorni, quindi la conversione conta anche se il visitatore prima naviga su altre pagine.
- Ogni scansione conta una sola volta: ricaricare la pagina di ringraziamento non aggiunge conversioni.
- Funziona con i codici QR che reindirizzano a una pagina http(s).
Esportazioni
Esporta in CSV i tuoi codici QR, le scansioni, le località e le attività dalla pagina Esportazioni.
Le esportazioni usano la sessione della dashboard, non una chiave API: aprile dopo aver effettuato l'accesso.
Consigli ed errori comuni
- 401 Unauthorized — la chiave API manca o non è valida. Controlla l'header X-Api-Key.
- 403 Forbidden — alla chiave manca l'autorizzazione richiesta (insufficient_scope) oppure il tuo piano non include la funzionalità (api_access_required, bulk_not_available, webhooks_not_available).
- 404 Not Found — la risorsa non esiste o appartiene a un'altra area di lavoro.
- 429 Too Many Requests — hai raggiunto il limite al minuto del tuo piano. Attendi il numero di secondi indicato nell'header Retry-After.
- Alcune funzionalità (come i webhook) dipendono dal tuo piano. Passa a un piano superiore se un endpoint restituisce un errore di funzionalità.
- Ancora nessuna consegna webhook? Scansiona uno dei tuoi codici QR per generarne una.
- Le consegne webhook non riuscite vengono ritentate automaticamente; puoi anche ritentarle manualmente dal registro delle consegne.
- I membri del team operano all'interno della tua area di lavoro; chiavi e dati sono legati al proprietario dell'area di lavoro.