Referencia de QrConfig

El cuerpo que envías con POST a /api/qr/generate (y el que sobrescriben las plantillas y el endpoint de IA). Todo lo que no indiques toma el valor por defecto del motor: no hay ningún campo obligatorio aparte de content.

Fuente de verdad: Models/QrModels.cs en el backend .NET. La lista de abajo cubre todos los campos públicos; para obtener el esquema completo con tipos y nulabilidad, ejecuta pnpm docs:schema en el repositorio del frontend, que regenera esta página a partir de los modelos de C#.

Contenido

Campo	Tipo	Por defecto	Notas
`content`	string	obligatorio	URL o texto que se codifica. Máximo 4296 caracteres.
`eccLevel`	enum	`M`	Corrección de errores (ECC). `L 7%` · `M 15%` · `Q 25%` · `H 30%`. Súbela a `H` si añades un logo.

Salida

Campo	Tipo	Por defecto	Notas
`fileFormat`	enum	`png`	`png`, `jpg`, `svg`, `pdf`, `webp`.
`responseType`	enum	`base64`	`base64` devuelve JSON; `binary` devuelve el archivo tal cual.
`outputWidth`	int	`800`	Píxeles. Hasta `4096`.
`outputHeight`	int	—	Por defecto, igual a `outputWidth`. Cámbialo solo si necesitas un formato no cuadrado.
`pixelsPerModule`	int	`10`	Resolución por módulo del QR. Aumenta `outputWidth` si este no está definido.
`quality`	int	`90`	Calidad JPG/WebP de 1 a 100.
`transparentBackground`	bool	`false`	Solo PNG/SVG/WebP.

Colores

Campo	Tipo	Por defecto	Notas
`primaryColor`	hex	`#000000`	Color de los módulos. `#RGB`, `#RRGGBB`, `#RRGGBBAA`.
`secondaryColor`	hex	—	Lo usan los degradados y los módulos conectados.
`backgroundColor`	hex	`#FFFFFF`	Color de la zona silenciosa.
`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	Posiciones de 0 a 1. Debe coincidir con `gradientColors.length`.
`gradientAngle`	int	`0`	Grados; si se indica, prevalece sobre `gradientDirection`.

Módulos (los puntos)

Campo	Tipo	Por defecto	Notas
`qrShape`	enum	`square`	Lienzo exterior: `square`, `roundedsquare`, `circle`.
`qrShapeRadius`	int	`0`	Radio de las esquinas cuando `qrShape: roundedsquare`.
`moduleShape`	enum	`square`	Una de 27. Consulta Patrones.
`moduleScale`	float	`1.0`	`0.5–1.0`. Encoge cada módulo para un aspecto más aireado.
`moduleRotation`	float	`0`	Grados.
`moduleStyle`	enum	`solid`	`solid`, `outline`, `striped`.
`modulePattern`	enum	`standard`	`standard`, `checker`, `alternating`.
`moduleSizeVariation`	float	`0`	`0–0.3` añade una variación orgánica a cada módulo.
`connectedStyle`	enum	`none`	`none`, `fluid`, `sharp`, `round`. Une los módulos adyacentes.

Patrones de localización (los 3 ojos grandes)

Campo	Tipo	Por defecto	Notas
`finderOuterShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `octagon`, `target`, `double`.
`finderInnerShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `star`, `dot`.
`finderOuterColor`	hex	—	Por defecto, `primaryColor`.
`finderInnerColor`	hex	—	Por defecto, `primaryColor`.
`finderStyle`	enum	`standard`	`standard`, `flat`, `embossed`.

Logo

Campo	Tipo	Por defecto	Notas
`logoUrl`	url	—	URL pública que se descarga en el servidor. PNG/JPG/GIF/BMP/WebP, ≤ 10 MB.
`logoBase64`	string	—	Alternativa en línea como data URI.
`logoFile`	multipart	—	Parte binaria si usas `multipart/form-data`.
`logoShape`	enum	`square`	`square`, `circle`, `rounded`.
`logoSizePercent`	float	`18`	`5–30`. Sube siempre `eccLevel` a `H` cuando sea ≥ 20.
`logoBorderWidth`	int	`0`	Grosor del borde en píxeles.
`logoBorderColor`	hex	`#FFFFFF`
`logoShadow`	bool	`false`	Sombra bajo el logo.
`logoBackground`	enum	`none`	`none`, `solid`, `match-bg`.
`cleanBehindLogo`	bool	`true`	Borra los módulos que quedan bajo el logo para que no compita con el QR.

Textos superpuestos

Campo	Tipo	Notas
`centerText`	object	Banda en el centro: `{ text, color?, backgroundColor?, height?, fontSize?, bold?, fontFamily? }`.
`circularText`	object	Texto curvado alrededor del QR: `{ text, color?, fontSize?, position? }`.
`ctaText`	string	Texto bajo el QR (p. ej., «SCAN ME»).
`ctaTextStyle`	object	`{ color?, fontSize?, fontFamily?, bold?, italic? }`.

Marcos

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

Imagen de fondo

Campo	Tipo	Notas
`backgroundImageUrl` / `backgroundImageBase64`	url/string	Imagen suave que se renderiza detrás del QR.
`backgroundImageBlendMode`	enum	`normal`, `multiply`, `screen`, `overlay`.
`backgroundImageOpacity`	float	`0–1`.
`backgroundImageBlur`	int	Píxeles.
`backgroundImageFit`	enum	`cover`, `contain`, `stretch`.

Efectos

Campo	Tipo	Notas
`shadow`	object	`{ color, blur, offsetX, offsetY }`.
`glow`	object	`{ color, blur, intensity }`.
`emboss`	object	`{ depth, lightAngle, lightColor?, shadowColor? }`.
`noise`	float	`0–0.3` añade grano de película.
`blur`	int	Píxeles.
`edgeFade`	float	`0–0.5` difumina el borde del lienzo.
`colorFilter`	enum	`none`, `sepia`, `bw`, `cool`, `warm`.

Específicos de IA (solo en `/api/qr/ai/generate*`)

Campo	Tipo	Notas
`prompt`	string	Descripción en lenguaje natural.
`stylePreset`	enum	`minimal`, `artistic`, `corporate`, `playful`, `luxury`, `tech`, `nature`.
`creativity`	float	`0–1`. Controla la temperatura del LLM y lo atrevido del diseño.
`strictScannability`	bool	Con `true`, el motor corrige automáticamente ECC y contraste.
`llmProvider`	enum	Solo Marketplace: `openai`, `anthropic`, `google`, `mistral`, `cohere`, `groq`.
`llmApiKey`	string	Solo Marketplace. Se reenvía una vez y nunca se registra.
`llmModel`	string	Opcional; por defecto, el modelo económico de referencia del proveedor.

Orden de validación

JSON bien formado → INVALID_JSON si no lo es.
Tipos y límites de los campos → VALIDATION_ERROR con details[].
Contraste de color → LOW_CONTRAST si es < 4:1 y strictScannability: true.
Tamaño del logo frente a la ECC → LOGO_TOO_LARGE si es demasiado agresivo.
Decodificación de ida y vuelta según ISO 18004 → QR_GENERATION_FAILED si el resultado renderizado no se puede volver a leer.

Consulta Errores para ver la matriz completa de códigos de error.

Regenerar esta página

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

El script es tools/gen-docs-schema.ts. Cualquier campo que se añada al modelo de C# con un atributo [Description] aparece aquí automáticamente.