Довідник QrConfig

Тіло, яке ви надсилаєте методом POST на /api/qr/generate (і яке перевизначають шаблони та ендпоінт ШІ). Усе, що не задано, бере значення рушія за замовчуванням — крім content, обов’язкових полів немає.

Джерело істини: Models/QrModels.cs у бекенді .NET. Наведений нижче список охоплює всі публічні поля; щоб отримати повну схему з типами й допустимістю null, виконайте pnpm docs:schema у репозиторії фронтенду — команда заново згенерує цю сторінку з моделей C#.

Вміст

Поле	Тип	За замовчуванням	Примітки
`content`	string	обов’язкове	URL або текст для кодування. Максимум 4296 символів.
`eccLevel`	enum	`M`	Корекція помилок. `L 7%` · `M 15%` · `Q 25%` · `H 30%`. Підвищуйте до `H`, коли додаєте логотип.

Вивід

Поле	Тип	За замовчуванням	Примітки
`fileFormat`	enum	`png`	`png`, `jpg`, `svg`, `pdf`, `webp`.
`responseType`	enum	`base64`	`base64` повертає JSON; `binary` повертає сирий файл.
`outputWidth`	int	`800`	Пікселі. До `4096`.
`outputHeight`	int	—	За замовчуванням дорівнює `outputWidth`. Перевизначайте, лише якщо потрібен неквадратний формат.
`pixelsPerModule`	int	`10`	Роздільна здатність на один модуль QR. Збільшує `outputWidth`, якщо його не задано.
`quality`	int	`90`	Якість JPG/WebP, 1–100.
`transparentBackground`	bool	`false`	Лише PNG/SVG/WebP.

Кольори

Поле	Тип	За замовчуванням	Примітки
`primaryColor`	hex	`#000000`	Колір модулів. `#RGB`, `#RRGGBB`, `#RRGGBBAA`.
`secondaryColor`	hex	—	Використовується градієнтами та з’єднаними модулями.
`backgroundColor`	hex	`#FFFFFF`	Колір тихої зони.
`foregroundStyle`	enum	`solid`	`solid`, `linearGradient`, `radialGradient`, `sweepGradient`.
`gradientType`	enum	`linear`	Скорочений відповідник `foregroundStyle`.
`gradientDirection`	enum	`vertical`	`vertical`, `horizontal`, `diagonal`, `diagonal-reverse`.
`gradientColors`	hex[]	—	2–6 опорних кольорів.
`gradientStops`	float[]	рівномірно	Позиції 0–1. Мають відповідати `gradientColors.length`.
`gradientAngle`	int	`0`	Градуси; якщо задано, перевизначає `gradientDirection`.

Модулі (точки)

Поле	Тип	За замовчуванням	Примітки
`qrShape`	enum	`square`	Зовнішнє полотно: `square`, `roundedsquare`, `circle`.
`qrShapeRadius`	int	`0`	Радіус кутів, коли `qrShape: roundedsquare`.
`moduleShape`	enum	`square`	Одна з 27 форм. Див. Візерунки.
`moduleScale`	float	`1.0`	`0.5–1.0`. Зменшує кожен модуль для легшого вигляду.
`moduleRotation`	float	`0`	Градуси.
`moduleStyle`	enum	`solid`	`solid`, `outline`, `striped`.
`modulePattern`	enum	`standard`	`standard`, `checker`, `alternating`.
`moduleSizeVariation`	float	`0`	`0–0.3` додає органічну варіацію розміру кожного модуля.
`connectedStyle`	enum	`none`	`none`, `fluid`, `sharp`, `round`. З’єднує сусідні модулі.

Шукачі (finder patterns) — 3 великі «очі»

Поле	Тип	За замовчуванням	Примітки
`finderOuterShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `octagon`, `target`, `double`.
`finderInnerShape`	enum	`square`	`square`, `roundedsquare`, `circle`, `diamond`, `star`, `dot`.
`finderOuterColor`	hex	—	За замовчуванням `primaryColor`.
`finderInnerColor`	hex	—	За замовчуванням `primaryColor`.
`finderStyle`	enum	`standard`	`standard`, `flat`, `embossed`.

Логотип

Поле	Тип	За замовчуванням	Примітки
`logoUrl`	url	—	Публічний URL, який завантажує сервер. PNG/JPG/GIF/BMP/WebP, ≤ 10 MB.
`logoBase64`	string	—	Альтернатива: вбудований data URI.
`logoFile`	multipart	—	Двійкова частина, якщо використовується `multipart/form-data`.
`logoShape`	enum	`square`	`square`, `circle`, `rounded`.
`logoSizePercent`	float	`18`	`5–30`. Якщо ≥ 20, завжди підвищуйте `eccLevel` до `H`.
`logoBorderWidth`	int	`0`	Товщина рамки в пікселях.
`logoBorderColor`	hex	`#FFFFFF`
`logoShadow`	bool	`false`	Тінь під логотипом.
`logoBackground`	enum	`none`	`none`, `solid`, `match-bg`.
`cleanBehindLogo`	bool	`true`	Прибирає модулі під логотипом, щоб він не конфліктував із QR.

Текстові накладки

Поле	Тип	Примітки
`centerText`	object	Банер через центр: `{ text, color?, backgroundColor?, height?, fontSize?, bold?, fontFamily? }`.
`circularText`	object	Текст, вигнутий навколо QR: `{ text, color?, fontSize?, position? }`.
`ctaText`	string	Підпис під QR (наприклад, «SCAN ME»).
`ctaTextStyle`	object	`{ color?, fontSize?, fontFamily?, bold?, italic? }`.

Рамки

Поле	Тип	Примітки
`frame`	object	`{ enabled, shape, color, width, padding, cornerRadius, fillColor? }`. Форми: `rectangle`, `speech-bubble`, `badge`, `shield`, `circle`.

Фонове зображення

Поле	Тип	Примітки
`backgroundImageUrl` / `backgroundImageBase64`	url/string	М’яке зображення позаду QR.
`backgroundImageBlendMode`	enum	`normal`, `multiply`, `screen`, `overlay`.
`backgroundImageOpacity`	float	`0–1`.
`backgroundImageBlur`	int	Пікселі.
`backgroundImageFit`	enum	`cover`, `contain`, `stretch`.

Ефекти

Поле	Тип	Примітки
`shadow`	object	`{ color, blur, offsetX, offsetY }`.
`glow`	object	`{ color, blur, intensity }`.
`emboss`	object	`{ depth, lightAngle, lightColor?, shadowColor? }`.
`noise`	float	`0–0.3` додає плівкове зерно.
`blur`	int	Пікселі.
`edgeFade`	float	`0–0.5` розчиняє краї полотна.
`colorFilter`	enum	`none`, `sepia`, `bw`, `cool`, `warm`.

Лише для ШІ (тільки в `/api/qr/ai/generate*`)

Поле	Тип	Примітки
`prompt`	string	Опис звичайною мовою.
`stylePreset`	enum	`minimal`, `artistic`, `corporate`, `playful`, `luxury`, `tech`, `nature`.
`creativity`	float	`0–1`. Керує temperature LLM і сміливістю.
`strictScannability`	bool	Якщо `true`, рушій автоматично виправляє ECC/контраст.
`llmProvider`	enum	Лише маркетплейс: `openai`, `anthropic`, `google`, `mistral`, `cohere`, `groq`.
`llmApiKey`	string	Лише маркетплейс. Пересилається один раз, ніколи не журналюється.
`llmModel`	string	Необов’язкове; за замовчуванням дешева флагманська модель провайдера.

Порядок перевірки

Коректність JSON → інакше INVALID_JSON.
Типи й межі полів → VALIDATION_ERROR з details[].
Контраст кольорів → LOW_CONTRAST, якщо < 4:1 і strictScannability: true.
Розмір логотипа відносно ECC → LOGO_TOO_LARGE, якщо надто агресивно.
Цикл декодування ISO 18004 → QR_GENERATION_FAILED, якщо відрендерений результат не вдається прочитати знову.

Повну таблицю кодів помилок див. у розділі Помилки.

Повторна генерація цієї сторінки

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

Скрипт — tools/gen-docs-schema.ts. Будь-яке поле, додане до моделі C# з атрибутом [Description], автоматично з’являється тут.