Manuale per sviluppatori di CreateQR.app

Automatizza la creazione di codici QR dinamici con l'API CreateQR

Usa endpoint JSON per creare, elencare ed eliminare codici QR dai tuoi sistemi. Genera codici QR dinamici per campagne e destinazioni gestite, oltre a codici QR statici per WiFi e wallet crypto dove supportati.

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

Crea codici QR

Crea un codice QR dinamico per URL e destinazioni gestite, oppure un codice QR statico per WiFi e wallet crypto.

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 esempio di URL dinamico è 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":"dynamic"}'

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. Il QR dinamico richiede un URL valido. Il QR statico accetta solo stringhe WiFi o indirizzi wallet crypto.
qrtype String dynamic Modalità QR: dynamic per URL e destinazioni gestite, oppure static solo per WiFi e wallet crypto.
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 della cornice attorno ai punti angolari in #RRGGBB format.
marker_in_color String #000000 Colore dei punti angolari in #RRGGBB format.
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 Stile della cornice attorno ai punti angolari.
corner_1 corner_2 corner_3 corner_4 corner_5 corner_6 corner_7 corner_8
marker_in String default Tipo dei punti angolari.
corner_in_1 corner_in_2 corner_in_3 corner_in_4 corner_in_5 corner_in_6 corner_in_7 corner_in_8
optionlogo String none none, percorso consigliato a una filigrana SVG locale, percorso legacy a un PNG locale oppure dati immagine base64.
none /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 data:image/*;base64,...
no_logo_bg String/Bool on Rimuove lo sfondo del logo.

Parametri cornice

Parametro Tipo Predefinito Descrizione
outer_frame String none Preset di stile della cornice.
none svg_frame_01 svg_frame_02 svg_frame_03 svg_frame_04 svg_frame_05 svg_frame_06 svg_frame_07 svg_frame_08 svg_frame_09 svg_frame_10 svg_frame_11 svg_frame_12 svg_frame_13 svg_frame_14 svg_frame_15 svg_frame_16 svg_frame_19 svg_frame_22 svg_frame_23 svg_frame_26 svg_frame_27 svg_frame_28 svg_frame_29 svg_frame_30 svg_frame_31 svg_frame_33 svg_frame_34 svg_frame_35 svg_frame_36 svg_frame_38 svg_frame_42
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

No-frills, fast scan

Request Method:
POST
Request URL:
https://createqr.app/api/v1/create
Request Parameters:

All parameters need to be sent as a JSON object in the request body.

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

Esempio: QR WiFi statico

Built for distance

Request Method:
POST
Request URL:
https://createqr.app/api/v1/create
Request Parameters:

All parameters need to be sent as a JSON object in the request body.

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "WIFI:T:WPA;S:CreateQR Guest;P:guest-2026;H:false;;",
    "qrtype": "static",
    "title": "Guest Wi-Fi QR",
    "transparent": "off",
    "backcolor": "#0B1220",
    "frontcolor": "#FFFFFF",
    "marker_out_color": "#F4C84A",
    "marker_in_color": "#F4C84A",
    "pattern": "circle",
    "marker": "corner_3",
    "marker_in": "corner_in_3",
    "optionlogo": "none"
}
Request Outcome
Anteprima dell'output di esempio

Brand Color

Theme-aligned campaign

Request Method:
POST
Request URL:
https://createqr.app/api/v1/create
Request Parameters:

All parameters need to be sent as a JSON object in the request body.

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/pricing",
    "qrtype": "dynamic",
    "title": "Pricing QR",
    "transparent": "off",
    "backcolor": "#EAF4FF",
    "frontcolor": "#033895",
    "marker_out_color": "#15A97C",
    "marker_in_color": "#15A97C",
    "pattern": "special-circle-orizz",
    "marker": "corner_4",
    "marker_in": "corner_in_4",
    "optionlogo": "none"
}
Request Outcome
Anteprima dell'output di esempio

Esempio: Colore + logo

Preset watermark icon

Request Method:
POST
Request URL:
https://createqr.app/api/v1/create
Request Parameters:

All parameters need to be sent as a JSON object in the request body.

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

Esempio: QR campagna con cornice

Poster-ready "SCAN ME"

Request Method:
POST
Request URL:
https://createqr.app/api/v1/create
Request Parameters:

All parameters need to be sent as a JSON object in the request body.

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

Gradient Mood

Extra style for socials

Request Method:
POST
Request URL:
https://createqr.app/api/v1/create
Request Parameters:

All parameters need to be sent as a JSON object in the request body.

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/why-us",
    "qrtype": "dynamic",
    "title": "Brand Story QR",
    "transparent": "off",
    "backcolor": "#FFFFFF",
    "frontcolor": "#4B1EFF",
    "gradient": "on",
    "radial": "off",
    "gradient_color": "#FF7A00",
    "marker_out_color": "#101828",
    "marker_in_color": "#101828",
    "pattern": "special-diamond",
    "marker": "corner_6",
    "marker_in": "corner_in_8",
    "optionlogo": "none"
}
Request Outcome
Anteprima dell'output di esempio

Esempio: QR statico per wallet crypto

Static crypto address

Request Method:
POST
Request URL:
https://createqr.app/api/v1/create
Request Parameters:

All parameters need to be sent as a JSON object in the request body.

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "bitcoin:bc1qexampleaddress",
    "qrtype": "static",
    "title": "Bitcoin Wallet QR",
    "transparent": "off",
    "backcolor": "#FFF7ED",
    "frontcolor": "#1F2937",
    "marker_out_color": "#F7931A",
    "marker_in_color": "#F7931A",
    "pattern": "circle",
    "marker": "corner_2",
    "marker_in": "corner_in_2",
    "optionlogo": "/images/watermarks/v2/16-bitcoin.svg"
}
Request Outcome
Anteprima dell'output di esempio

Struttura della risposta di successo

{
    "success": true,
    "data": {
        "qrid": "1284",
        "svg": "<svg ...>...</svg>",
        "type": "dynamic",
        "title": "Launch Landing 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": "Guest Wi-Fi 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": "Static QR is only available for WiFi payloads or crypto wallet addresses."
    },
    "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, payload statico, colore o folderid Usa dynamic per URL e destinazioni gestite; usa static solo per WiFi o wallet crypto.
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.

Posso creare codici QR statici tramite API?

Sì, ma il modo statico è limitato a stringhe WiFi e indirizzi wallet crypto. Usa il modo dinamico per URL, PDF, menu, app, pagine social e altre destinazioni gestite.

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