Manuale per sviluppatori di CreateQR.app

Automatizza la creazione di QR senza le parti noiose

Usa tre endpoint per creare, elencare ed eliminare codici QR con controllo completo dello stile. Integrazione in giornata, JSON pulito e i tuoi QR restano nella dashboard.

Ottieni la chiave API Visualizza i piani
Percorso base: /api/v1 Autenticazione: Authorization: Bearer <key> (consigliato)

Esempi di codici QR generati con la nostra API

Stesso endpoint, stili diversi. Mantienilo semplice, personalizzalo con il tuo brand o incornicialo per campagne offline.

Semplice

Semplice

Essenziale, scansione rapida

Alto contrasto

Alto contrasto

Progettato per la distanza

Colore del brand

Colore del brand

Campagna in linea con il tema

Logo al centro

Icona filigrana preimpostata

Etichetta con cornice

Etichetta con cornice

Pronto per poster "SCANSIONAMI"

Atmosfera sfumata

Atmosfera sfumata

Stile extra per i social

Crea codici QR

Crea un codice QR statico o dinamico e salvalo nel tuo account.

POST https://createqr.app/api/v1/create

Invia solo JSON. Per l'autenticazione tramite chiave, l'header è la best practice. I campi della chiave nel body sono presenti per compatibilità con le integrazioni esistenti.

Guida rapida (cURL)

Questo è il modo più veloce per iniziare.

curl -sS -X POST 'https://createqr.app/api/v1/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ck_live_XXXXXXXXXXXXXXXXXXXXXXXX' \
  -d '{"data":"https://createqr.app","qrtype":"static"}'

Autenticazione e compatibilità

  • Consigliato: Authorization: Bearer <key>
  • Accettato anche: X-API-Key
  • Fallback JSON: apikey o api_key
  • Content-Type deve essere application/json
  • I metodi non POST restituiscono 405 method_not_allowed

Parametri principali

Parametro Tipo Predefinito Descrizione
apikey String Obbligatorio Chiave API segreta. Consigliata nell'header Authorization (Bearer). Sono accettati anche apikey/api_key nel body JSON.
data String Obbligatorio Contenuto da codificare. Per i QR dinamici, deve essere un URL valido.
qrtype String static Modalità QR: statico o dinamico.
title String Facoltativo Titolo del QR mostrato nella dashboard (troncato a 120 caratteri).
folderid Number Facoltativo ID numerico positivo della cartella associata al tuo account.

Parametri colore e forma

Parametro Tipo Predefinito Descrizione
transparent String/Bool off Sono accettati on/off, true/false, 1/0, yes/no.
backcolor String #FFFFFF Colore esadecimale di sfondo nel formato #RRGGBB.
frontcolor String #000000 Colore esadecimale principale dei punti nel formato #RRGGBB.
gradient String/Bool off Abilita il gradiente a due colori dei punti.
radial String/Bool off Abilita il gradiente radiale (funziona quando il gradiente è attivo).
gradient_color String #15A97C Secondo colore del gradiente in #RRGGBB.
marker_out_color String #000000 Colore del marcatore di rilevamento esterno.
marker_in_color String #000000 Colore del marcatore di rilevamento interno.
pattern String default Preset di stile dei punti del corpo.
default circle star diamond sparkle danger cross plus x heart shake blob special-circle-orizz special-circle-vert special-circle special-diamond ribbon oriental ellipse
marker String default Preset di stile del marcatore esterno.
default flurry sdoz drop_in drop dropeye dropeyeleft dropeyeleaf dropeyeright squarecircle circle rounded flower flower_in leaf
marker_in String default Preset di stile del marcatore interno.
default flurry sdoz drop_in drop dropeye circle rounded sun star diamond danger cross plus x heart
optionlogo String none none, percorso consigliato a una filigrana SVG locale, percorso legacy a un PNG locale oppure dati immagine base64.
none data:image/*;base64,... /images/watermarks/v2/01-link.svg /images/watermarks/v2/02-location.svg /images/watermarks/v2/03-email.svg /images/watermarks/v2/04-whatsapp.svg /images/watermarks/v2/05-wifi.svg /images/watermarks/v2/06-vcard.svg /images/watermarks/v2/07-menu.svg /images/watermarks/v2/08-app.svg /images/watermarks/v2/09-video.svg /images/watermarks/v2/10-feedback.svg /images/watermarks/v2/11-event.svg /images/watermarks/v2/12-coupon.svg /images/watermarks/v2/13-music.svg /images/watermarks/v2/14-social.svg /images/watermarks/v2/15-paypal.svg /images/watermarks/v2/16-bitcoin.svg /images/watermarks/v2/17-scan.svg
no_logo_bg String/Bool off Disattiva lo sfondo del logo.

Parametri cornice

Parametro Tipo Predefinito Descrizione
outer_frame String none Preset di stile della cornice.
none bottom top balloon-bottom balloon-top ribbon-bottom ribbon-top phone cine
framelabel String SCAN ME Etichetta di testo della cornice (troncata a 80 caratteri).
label_font String Arial, Helvetica, sans-serif Stack di font per l'etichetta della cornice.
custom_frame_color String/Bool off Abilita un colore personalizzato per la cornice.
framecolor String #000000 Colore esadecimale della cornice nel formato #RRGGBB.

Esempi di richieste di creazione

Esempio: QR semplice

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app",
    "qrtype": "static",
    "title": "Launch Landing QR",
    "transparent": "off",
    "backcolor": "#FFFFFF",
    "frontcolor": "#000000",
    "marker_out_color": "#000000",
    "marker_in_color": "#000000",
    "pattern": "default",
    "marker": "default",
    "marker_in": "default",
    "optionlogo": "none"
}
Anteprima dell'output di esempio

Esempio: Colore + logo

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/features",
    "qrtype": "static",
    "title": "Feature Tour QR",
    "transparent": "off",
    "backcolor": "#033895",
    "frontcolor": "#FFFFFF",
    "marker_out_color": "#669DF4",
    "marker_in_color": "#669DF4",
    "pattern": "oriental",
    "marker": "flower",
    "marker_in": "circle",
    "optionlogo": "/images/watermarks/v2/01-link.svg"
}

Esempio: QR campagna con cornice

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/pricing",
    "qrtype": "static",
    "title": "Pricing Poster QR",
    "transparent": "off",
    "frontcolor": "#2B0011",
    "marker_out_color": "#3B0001",
    "marker_in_color": "#3B0001",
    "pattern": "ellipse",
    "marker": "sdoz",
    "marker_in": "sdoz",
    "optionlogo": "none",
    "outer_frame": "balloon-top",
    "framelabel": "SCAN ME",
    "label_font": "Arial, Helvetica, sans-serif",
    "custom_frame_color": "on",
    "framecolor": "#3B0001"
}
Anteprima dell'output di esempio

Struttura della risposta di successo

{
    "success": true,
    "data": {
        "qrid": "1284",
        "svg": "<svg ...>...</svg>",
        "type": "static",
        "title": "Pricing Poster QR",
        "dashboard_url": "https://createqr.app/app/qrs/1284",
        "download_url": "https://createqr.app/app/qrs/1284/download/svg"
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

Elimina codici QR

Elimina un QR tramite ID (solo proprietario).

POST https://createqr.app/api/v1/delete

Corpo della richiesta

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "qrid": "1284"
}

Risposta

{
    "success": true,
    "data": {
        "deleted": true,
        "qrid": "1284"
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

Elenca codici QR

Elenca i tuoi QR in pagine da 100, dai più recenti.

POST https://createqr.app/api/v1/list

Usa la paginazione a partire da 1. I risultati restituiscono fino a 100 elementi per pagina.

Corpo della richiesta

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "pagination": "1"
}

Risposta

{
    "success": true,
    "data": {
        "pagination": "1",
        "page_size": 100,
        "total": 2,
        "items": [
            {
                "qrid": "1284",
                "title": "Campaign QR",
                "type": "dynamic",
                "created_at": "2026-02-17 09:12:30",
                "short_url": "https://createqr.app/r/a1b2c3",
                "dashboard_url": "https://createqr.app/app/qrs/1284"
            },
            {
                "qrid": "1269",
                "title": "Storefront QR",
                "type": "static",
                "created_at": "2026-02-17 08:02:08",
                "dashboard_url": "https://createqr.app/app/qrs/1269"
            }
        ]
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

Risposte di errore, limiti e tentativi

Ogni risposta include request_id. Conservalo quando contatti l'assistenza così possiamo eseguire il debug rapidamente.

Struttura tipica dell'errore

{
    "success": false,
    "error": {
        "code": "validation_error",
        "message": "Dynamic QR requires a valid URL in data."
    },
    "request_id": "5f5fbd38-f82f-49ad-bf11-f7f04ca9747a"
}

Strategia di tentativi

  • 429 rate_limited: riprova con backoff esponenziale più jitter.
  • Rispetta Retry-After quando presente.
  • 429 monthly_quota_exceeded: attendi il ripristino della quota o usa una chiave con quota residua.
  • 5xx: riprova con un numero limitato di tentativi, poi avvisa il tuo team.
Codice errore HTTP Quando si verifica Cosa fare
invalid_api_key 401 Chiave API mancante o non valida Fornisci una chiave valida tramite Bearer, X-API-Key o il campo nel body JSON.
invalid_content_type 415 Il body non è application/json Invia Content-Type: application/json.
request_too_large 413 Il payload supera il limite configurato Riduci la dimensione del body, in particolare i loghi in base64.
plan_upgrade_required 403 Il piano non è abilitato per l'API Passa a Business dalla sezione Fatturazione.
validation_error 422 Campi non validi come URL, colore o folderid Correggi il formato del payload e invialo di nuovo.
rate_limited 429 Raggiunto il limite per minuto Riprova con backoff esponenziale e rispetta Retry-After.
monthly_quota_exceeded 429 Quota mensile esaurita Attendi il ripristino o modifica le impostazioni di quota e della chiave.
qr_not_found 404 La destinazione di eliminazione è mancante o non ti appartiene Verifica la proprietà di qrid e riprova.
internal_error 500 Problema imprevisto lato server Riprova con backoff e conserva request_id per l'assistenza.

FAQ

Risposte brevi alle domande che vediamo più spesso nelle integrazioni.

Quante richieste API posso eseguire?

L'API è disponibile solo per Business. La quota mensile dipende dal tuo piano attivo e dalle impostazioni specifiche della chiave. La dotazione predefinita di Business è elevata e gli amministratori possono regolarla nel dettaglio per ogni chiave.

Posso inviare le chiavi API nel body JSON?

Sì. L'autenticazione tramite header è consigliata, ma sono accettati anche i campi di compatibilità nel body apikey o api_key.

I QR creati tramite API compaiono nella mia dashboard?

Sì. Ogni creazione andata a buon fine viene salvata nel tuo account e può essere gestita come qualsiasi altro QR.

Cosa succede quando raggiungo i limiti?

Ricevi errori JSON. Per le risposte 429, rispetta Retry-After e usa un backoff esponenziale con jitter.

Posso eliminare un QR da un altro account?

No. Le operazioni di eliminazione e visualizzazione elenco sono limitate al proprietario della chiave API autenticata.

Best practice di sicurezza

  • Non esporre mai chiavi API non protette nel JavaScript del browser, nei bundle mobile o nei repository pubblici.
  • Usa le allowlist IP delle chiavi API per limitare l'utilizzo ai server attendibili.
  • Registra request_id insieme ai tuoi ID di tracciamento per velocizzare la gestione degli incidenti.
  • Ruota le chiavi regolarmente e immediatamente dopo eventuali compromissioni delle credenziali.
Apri il gestore delle chiavi API