Riferimento QrConfig

Il corpo che invii con POST a /api/qr/generate (e che i modelli e l'endpoint IA sovrascrivono). Tutto ciò che non imposti prende il valore predefinito del motore: l'unico campo obbligatorio è content.

Fonte di verità: Models/QrModels.cs nel backend .NET. L'elenco qui sotto copre tutti i campi pubblici; per un dump completo dello schema con tipi e nullabilità esegui pnpm docs:schema nel repository del frontend, che rigenera questa pagina dai modelli C#.

Contenuto

Campo	Tipo	Predefinito	Note
`content`	string	obbligatorio	URL o testo da codificare. Massimo 4296 caratteri.
`eccLevel`	enum	`M`	Correzione degli errori. `L 7%` · `M 15%` · `Q 25%` · `H 30%`. Passa a `H` quando aggiungi un logo.

Output

Campo	Tipo	Predefinito	Note
`fileFormat`	enum	`png`	`png`, `jpg`, `svg`, `pdf`, `webp`.
`responseType`	enum	`base64`	`base64` restituisce JSON; `binary` restituisce il file grezzo.
`outputWidth`	int	`800`	Pixel. Fino a `4096`.
`outputHeight`	int	—	Per impostazione predefinita uguale a `outputWidth`. Sovrascrivilo solo se ti serve un formato non quadrato.
`pixelsPerModule`	int	`10`	Risoluzione per modulo QR. Aumenta `outputWidth` se non è impostato.
`quality`	int	`90`	Qualità JPG/WebP 1–100.
`transparentBackground`	bool	`false`	Solo PNG/SVG/WebP.

Colori

Campo	Tipo	Predefinito	Note
`primaryColor`	hex	`#000000`	Colore dei moduli. `#RGB`, `#RRGGBB`, `#RRGGBBAA`.
`secondaryColor`	hex	—	Usato dai gradienti e dai moduli connessi.
`backgroundColor`	hex	`#FFFFFF`	Colore della zona di rispetto.
`foregroundStyle`	enum	`solid`	`solid`, `linearGradient`, `radialGradient`, `sweepGradient`.
`gradientType`	enum	`linear`	Forma abbreviata equivalente a `foregroundStyle`.
`gradientDirection`	enum	`vertical`	`vertical`, `horizontal`, `diagonal`, `diagonal-reverse`.
`gradientColors`	hex[]	—	Da 2 a 6 punti di colore.
`gradientStops`	float[]	uniformi	Posizioni 0–1. Deve corrispondere a `gradientColors.length`.
`gradientAngle`	int	`0`	Gradi; se impostato, sostituisce `gradientDirection`.

Moduli (i punti)

Campo	Tipo	Predefinito	Note
`qrShape`	enum	`square`	Tela esterna: `square`, `roundedsquare`, `circle`.
`qrShapeRadius`	int	`0`	Raggio degli angoli quando `qrShape: roundedsquare`.
`moduleShape`	enum	`square`	Una tra 27. Vedi Pattern.
`moduleScale`	float	`1.0`	`0.5–1.0`. Rimpicciolisce ogni modulo per un aspetto più arioso.
`moduleRotation`	float	`0`	Gradi.
`moduleStyle`	enum	`solid`	`solid`, `outline`, `striped`.
`modulePattern`	enum	`standard`	`standard`, `checker`, `alternating`.
`moduleSizeVariation`	float	`0`	`0–0.3` aggiunge una variazione organica a ogni modulo.
`connectedStyle`	enum	`none`	`none`, `fluid`, `sharp`, `round`. Unisce i moduli adiacenti.

Pattern di posizionamento (i 3 occhi grandi)

Campo	Tipo	Predefinito	Note
`finderOuterShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `octagon`, `target`, `double`.
`finderInnerShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `star`, `dot`.
`finderOuterColor`	hex	—	Per impostazione predefinita `primaryColor`.
`finderInnerColor`	hex	—	Per impostazione predefinita `primaryColor`.
`finderStyle`	enum	`standard`	`standard`, `flat`, `embossed`.

Logo

Campo	Tipo	Predefinito	Note
`logoUrl`	url	—	URL pubblico scaricato lato server. PNG/JPG/GIF/BMP/WebP, ≤ 10 MB.
`logoBase64`	string	—	Alternativa inline con data URI.
`logoFile`	multipart	—	Parte binaria se usi `multipart/form-data`.
`logoShape`	enum	`square`	`square`, `circle`, `rounded`.
`logoSizePercent`	float	`18`	`5–30`. Alza sempre `eccLevel` a `H` quando è ≥ 20.
`logoBorderWidth`	int	`0`	Spessore del bordo in pixel.
`logoBorderColor`	hex	`#FFFFFF`
`logoShadow`	bool	`false`	Ombra sotto il logo.
`logoBackground`	enum	`none`	`none`, `solid`, `match-bg`.
`cleanBehindLogo`	bool	`true`	Cancella i moduli sotto il logo perché non entri in conflitto con il QR.

Testi sovrapposti

Campo	Tipo	Note
`centerText`	object	Banner che attraversa il centro: `{ text, color?, backgroundColor?, height?, fontSize?, bold?, fontFamily? }`.
`circularText`	object	Testo curvato intorno al QR: `{ text, color?, fontSize?, position? }`.
`ctaText`	string	Didascalia sotto il QR (ad es. "SCAN ME").
`ctaTextStyle`	object	`{ color?, fontSize?, fontFamily?, bold?, italic? }`.

Cornici

Campo	Tipo	Note
`frame`	object	`{ enabled, shape, color, width, padding, cornerRadius, fillColor? }`. Forme: `rectangle`, `speech-bubble`, `badge`, `shield`, `circle`.

Immagine di sfondo

Campo	Tipo	Note
`backgroundImageUrl` / `backgroundImageBase64`	url/string	Immagine tenue generata dietro il QR.
`backgroundImageBlendMode`	enum	`normal`, `multiply`, `screen`, `overlay`.
`backgroundImageOpacity`	float	`0–1`.
`backgroundImageBlur`	int	Pixel.
`backgroundImageFit`	enum	`cover`, `contain`, `stretch`.

Effetti

Campo	Tipo	Note
`shadow`	object	`{ color, blur, offsetX, offsetY }`.
`glow`	object	`{ color, blur, intensity }`.
`emboss`	object	`{ depth, lightAngle, lightColor?, shadowColor? }`.
`noise`	float	`0–0.3` aggiunge grana da pellicola.
`blur`	int	Pixel.
`edgeFade`	float	`0–0.5` sfuma il bordo della tela.
`colorFilter`	enum	`none`, `sepia`, `bw`, `cool`, `warm`.

Specifici dell'IA (solo su `/api/qr/ai/generate*`)

Campo	Tipo	Note
`prompt`	string	Descrizione in linguaggio naturale.
`stylePreset`	enum	`minimal`, `artistic`, `corporate`, `playful`, `luxury`, `tech`, `nature`.
`creativity`	float	`0–1`. Controlla la temperatura dell'LLM e l'audacia.
`strictScannability`	bool	Se `true`, il motore corregge in automatico ECC/contrasto.
`llmProvider`	enum	Solo marketplace: `openai`, `anthropic`, `google`, `mistral`, `cohere`, `groq`.
`llmApiKey`	string	Solo marketplace. Inoltrata una sola volta, mai registrata nei log.
`llmModel`	string	Facoltativo; per impostazione predefinita, il modello economico di punta del provider.

Ordine di convalida

JSON ben formato → altrimenti INVALID_JSON.
Tipi dei campi + limiti → VALIDATION_ERROR con details[].
Contrasto dei colori → LOW_CONTRAST se < 4:1 e strictScannability: true.
Dimensione del logo rispetto all'ECC → LOGO_TOO_LARGE se è troppo aggressiva.
Ciclo di decodifica ISO 18004 → QR_GENERATION_FAILED se l'immagine generata non può essere riletta.

Consulta Errori per la matrice completa dei codici di errore.

Rigenerare questa pagina

cd frontend
pnpm docs:schema   # reads ../Models/QrModels.cs and rewrites this file

Lo script è tools/gen-docs-schema.ts. Qualsiasi campo aggiunto al modello C# con un attributo [Description] compare qui in automatico.