Referência de QrConfig

O corpo que você envia por POST para /api/qr/generate (e que os modelos e o endpoint de IA substituem). Tudo o que ficar sem valor usa o padrão do motor — não há nenhum campo obrigatório além de content.

Fonte de verdade: Models/QrModels.cs no backend .NET. A lista abaixo cobre todos os campos públicos; para um dump completo do esquema, com tipos e nulabilidade, execute pnpm docs:schema no repositório do frontend, que gera esta página de novo a partir dos modelos C#.

Conteúdo

Campo	Tipo	Padrão	Observações
`content`	string	obrigatório	URL ou texto a codificar. Máx. 4296 caracteres.
`eccLevel`	enum	`M`	Correção de erros. `L 7%` · `M 15%` · `Q 25%` · `H 30%`. Suba para `H` ao adicionar um logo.

Saída

Campo	Tipo	Padrão	Observações
`fileFormat`	enum	`png`	`png`, `jpg`, `svg`, `pdf`, `webp`.
`responseType`	enum	`base64`	`base64` devolve JSON; `binary` devolve o arquivo bruto.
`outputWidth`	int	`800`	Pixels. Até `4096`.
`outputHeight`	int	—	Por padrão, igual a `outputWidth`. Substitua só se precisar de um formato não quadrado.
`pixelsPerModule`	int	`10`	Resolução por módulo do QR. Aumenta `outputWidth` se este não estiver definido.
`quality`	int	`90`	Qualidade JPG/WebP de 1 a 100.
`transparentBackground`	bool	`false`	Só PNG/SVG/WebP.

Cores

Campo	Tipo	Padrão	Observações
`primaryColor`	hex	`#000000`	Cor dos módulos. `#RGB`, `#RRGGBB`, `#RRGGBBAA`.
`secondaryColor`	hex	—	Usada pelos degradês e pelos módulos conectados.
`backgroundColor`	hex	`#FFFFFF`	Cor da zona de silêncio.
`foregroundStyle`	enum	`solid`	`solid`, `linearGradient`, `radialGradient`, `sweepGradient`.
`gradientType`	enum	`linear`	Forma abreviada equivalente a `foregroundStyle`.
`gradientDirection`	enum	`vertical`	`vertical`, `horizontal`, `diagonal`, `diagonal-reverse`.
`gradientColors`	hex[]	—	De 2 a 6 paradas.
`gradientStops`	float[]	uniforme	Posições de 0 a 1. Deve coincidir com `gradientColors.length`.
`gradientAngle`	int	`0`	Graus; se definido, substitui `gradientDirection`.

Módulos (os pontos)

Campo	Tipo	Padrão	Observações
`qrShape`	enum	`square`	Tela externa: `square`, `roundedsquare`, `circle`.
`qrShapeRadius`	int	`0`	Raio dos cantos quando `qrShape: roundedsquare`.
`moduleShape`	enum	`square`	Uma de 27. Veja Padrões.
`moduleScale`	float	`1.0`	`0.5–1.0`. Reduz cada módulo para um visual mais arejado.
`moduleRotation`	float	`0`	Graus.
`moduleStyle`	enum	`solid`	`solid`, `outline`, `striped`.
`modulePattern`	enum	`standard`	`standard`, `checker`, `alternating`.
`moduleSizeVariation`	float	`0`	`0–0.3` adiciona uma variação orgânica a cada módulo.
`connectedStyle`	enum	`none`	`none`, `fluid`, `sharp`, `round`. Une módulos adjacentes.

Padrões localizadores (os 3 olhos grandes)

Campo	Tipo	Padrão	Observações
`finderOuterShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `octagon`, `target`, `double`.
`finderInnerShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `star`, `dot`.
`finderOuterColor`	hex	—	Por padrão, `primaryColor`.
`finderInnerColor`	hex	—	Por padrão, `primaryColor`.
`finderStyle`	enum	`standard`	`standard`, `flat`, `embossed`.

Logo

Campo	Tipo	Padrão	Observações
`logoUrl`	url	—	URL pública baixada pelo servidor. PNG/JPG/GIF/BMP/WebP, ≤ 10 MB.
`logoBase64`	string	—	Alternativa com data URI embutido.
`logoFile`	multipart	—	Parte binária se você usar `multipart/form-data`.
`logoShape`	enum	`square`	`square`, `circle`, `rounded`.
`logoSizePercent`	float	`18`	`5–30`. Suba sempre `eccLevel` para `H` quando for ≥ 20.
`logoBorderWidth`	int	`0`	Espessura da borda em pixels.
`logoBorderColor`	hex	`#FFFFFF`
`logoShadow`	bool	`false`	Sombra projetada sob o logo.
`logoBackground`	enum	`none`	`none`, `solid`, `match-bg`.
`cleanBehindLogo`	bool	`true`	Apaga os módulos sob o logo para que ele não brigue com o QR.

Textos sobrepostos

Campo	Tipo	Observações
`centerText`	object	Faixa atravessando o centro: `{ text, color?, backgroundColor?, height?, fontSize?, bold?, fontFamily? }`.
`circularText`	object	Texto curvado ao redor do QR: `{ text, color?, fontSize?, position? }`.
`ctaText`	string	Legenda embaixo do QR (por exemplo, "SCAN ME").
`ctaTextStyle`	object	`{ color?, fontSize?, fontFamily?, bold?, italic? }`.

Molduras

Campo	Tipo	Observações
`frame`	object	`{ enabled, shape, color, width, padding, cornerRadius, fillColor? }`. Formas: `rectangle`, `speech-bubble`, `badge`, `shield`, `circle`.

Imagem de fundo

Campo	Tipo	Observações
`backgroundImageUrl` / `backgroundImageBase64`	url/string	Imagem suave renderizada atrás do QR.
`backgroundImageBlendMode`	enum	`normal`, `multiply`, `screen`, `overlay`.
`backgroundImageOpacity`	float	`0–1`.
`backgroundImageBlur`	int	Pixels.
`backgroundImageFit`	enum	`cover`, `contain`, `stretch`.

Efeitos

Campo	Tipo	Observações
`shadow`	object	`{ color, blur, offsetX, offsetY }`.
`glow`	object	`{ color, blur, intensity }`.
`emboss`	object	`{ depth, lightAngle, lightColor?, shadowColor? }`.
`noise`	float	`0–0.3` adiciona granulação de filme.
`blur`	int	Pixels.
`edgeFade`	float	`0–0.5` esmaece a borda da tela.
`colorFilter`	enum	`none`, `sepia`, `bw`, `cool`, `warm`.

Específicos de IA (só em `/api/qr/ai/generate*`)

Campo	Tipo	Observações
`prompt`	string	Descrição em linguagem natural.
`stylePreset`	enum	`minimal`, `artistic`, `corporate`, `playful`, `luxury`, `tech`, `nature`.
`creativity`	float	`0–1`. Controla a temperatura do LLM e a ousadia.
`strictScannability`	bool	Quando `true`, o motor corrige automaticamente ECC/contraste.
`llmProvider`	enum	Só no marketplace: `openai`, `anthropic`, `google`, `mistral`, `cohere`, `groq`.
`llmApiKey`	string	Só no marketplace. Repassada uma única vez, nunca registrada em log.
`llmModel`	string	Opcional; por padrão, o modelo barato principal do provedor.

Ordem de validação

JSON bem formado → INVALID_JSON caso contrário.
Tipos e limites dos campos → VALIDATION_ERROR com details[].
Contraste de cores → LOW_CONTRAST se for menor que 4:1 e strictScannability: true.
Tamanho do logo vs ECC → LOGO_TOO_LARGE se for agressivo demais.
Decodificação de ida e volta ISO 18004 → QR_GENERATION_FAILED se a imagem renderizada não puder ser lida de novo.

Veja Erros para a matriz completa de códigos de erro.

Como gerar esta página de novo

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

O script é tools/gen-docs-schema.ts. Qualquer campo adicionado ao modelo C# com um atributo [Description] aparece aqui automaticamente.