> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Оформлення

> Оформлюйте QR-коди через API: форми точок і кутів, кольори, рамки й логотипи.

> [!NOTE]
>
> API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.

Оформлюйте QR-код за допомогою необов'язкових об'єктів `styles`, `frameOptions` і `logoOptions` під час створення або оновлення. Усі поля необов'язкові, а для всього, що ви пропустите, діють значення за замовчуванням.

Ті самі три об'єкти працюють для [QR-кодів](https://docs.getqr.com/ua/api/endpoints/qr-codes.md), [шаблонів](https://docs.getqr.com/ua/api/endpoints/templates.md) і [масового створення](https://docs.getqr.com/ua/api/endpoints/bulk-qr-creations.md). Невідомі форми, рамки чи логотипи відхиляються з `422`.

## Приклад об'єкта дизайну

```json theme={null}
{
  "styles": {
    "dotsOptions": { "type": "rounded", "color": "#000000" },
    "backgroundOptions": { "color": "#ffffff" },
    "cornersSquareOptions": { "type": "dot", "color": "#000000" },
    "cornersDotOptions": { "type": "dot", "color": "#000000" }
  },
  "frameOptions": { "id": "card", "text": "Scan me!", "color": "#000000", "textColor": "#ffffff" },
  "logoOptions": { "type": "suggested", "id": "logo-google", "scalePercent": 25 }
}
```

Надсилайте його разом з іншими полями QR-коду:

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" } },
    "frameOptions": { "id": "card", "text": "Scan me!" },
    "logoOptions": { "type": "suggested", "id": "logo-website-3" }
  }'
```

## Стилі

Об'єкт `styles` задає форми й кольори візерунка.

| Поле | Значення |
| - | - |
| `dotsOptions.type` | Форма точок тіла: `square`, `dots`, `rounded`, `classy`, `classy-rounded`, `extra-rounded` |
| `cornersSquareOptions.type` | Форма кутового квадрата (рамки «ока»): `square`, `rounded`, `dot`, `classy-rounded` |
| `cornersDotOptions.type` | Форма кутової точки («зіниці»): `square`, `dot`, `dots`, `rounded`, `classy` |
| `dotsOptions.color` | Колір переднього плану. За замовчуванням `#000000`. |
| `backgroundOptions.color` | Колір фону. За замовчуванням `#ffffff`. |
| `cornersSquareOptions.color`, `cornersDotOptions.color` | Приймаються, але ні на що не впливають: кути завжди використовують `dotsOptions.color`. |

* **Кольори.** Лише шістнадцяткові значення: `#RGB` або `#RRGGBB`.
* **Корекція помилок.** Завжди `Q`, і це не вхідний параметр. Надсилання `styles.qrOptions` повертає `422`.
* **Дизайни Branded і AI.** Їх не можна задати через API. Надсилання `styles.logoQrArt` повертає `422`.
* **Вміст.** `styles.data` ігнорується. Зображення завжди кодує вміст QR-коду.

> [!TIP]
>
> Забезпечте достатній контраст між кольорами переднього плану й фону: темний передній план на світлому фоні. Коди з низьким контрастом можуть не скануватися. Див. [Кольори](https://docs.getqr.com/ua/design/colors.md).

## Рамки

Об'єкт `frameOptions` додає навколо QR-коду декоративну рамку із закликом до дії.

| Поле | Опис |
| - | - |
| `id` | Обов'язкове, якщо ви надсилаєте `frameOptions`. Тип рамки зі списків нижче. `none` означає без рамки. |
| `text` | Підпис із закликом до дії, до 12 символів. За замовчуванням `Scan me!`. |
| `color` | Колір рамки, hex. |
| `textColor` | Колір підпису, hex. Має відрізнятися від `color`, якщо рамка показує підпис, крім випадків, коли пара є однією з вбудованих колірних схем рамки. |
| `borderColor` | Колір контуру, hex. |
| `fingerPrintColor` | Акцентний колір іконки рамки, hex. |

> [accordion] Загальні рамки
>
> `none`, `card`, `card-1`, `card-2`, `card-3`, `card-4`, `card-5`, `card-7`, `card-8`, `card-9`, `card-10`, `card-11`, `card-12`, `card-13`, `card-14`, `card-15`, `card-hor`, `wreath`, `envelope`, `waitress`, `coffee-cup`, `scooter`, `clipboard`
>
> `card-hor` не показує підпису.

> [accordion] Рамки за типом QR-коду
>
> | Тип | Рамки з підписом | Рамки без підпису |
> | - | - | - |
> | App Link | `app-3` | `app-1`, `app-2` |
> | vCard | `contact-1`, `contact-5` | `contact-2`, `contact-3`, `contact-4` |
> | Email | `email-1` | `email-2`, `email-3`, `email-4`, `email-5` |
> | Feedback | — | `feedback-1`, `feedback-2`, `feedback-3`, `feedback-4`, `feedback-5` |
> | Image | — | `image-1`, `image-2`, `image-3`, `image-4`, `image-5`, `image-6` |
> | Location | `location-3` | `location-1`, `location-2`, `location-4`, `location-5`, `location-6` |
> | Multi-Link | `multilink-3` | `multilink-1`, `multilink-2` |
> | Payment | — | `payment-1`, `payment-2`, `payment-3`, `payment-4`, `payment-5` |
> | PDF | `pdf-1` | `pdf-2`, `pdf-3`, `pdf-4` |
> | SMS | `sms-3`, `sms-5`, `sms-7` | `sms-1`, `sms-2`, `sms-4`, `sms-6` |
> | Social Media | `social-3` | `social-1`, `social-2`, `social-4` |
> | Video | `video-1`, `video-3` | `video-2`, `video-4`, `video-5`, `video-6` |
> | Website | `website-1` | `website-2`, `website-3`, `website-4`, `website-5` |
> | WhatsApp | `whatsapp-2` | `whatsapp-1`, `whatsapp-3`, `whatsapp-4` |
> | WiFi | — | `wifi-1`, `wifi-2`, `wifi-3`, `wifi-4` |
>
> Будь-яка рамка працює з будь-яким типом QR-коду. Групування відповідає панелі керування.

Рамки без підпису не мають поля для заклику до дії в панелі керування, і правило, що `textColor` має відрізнятися від `color`, до них не застосовується.

## Логотипи

Об'єкт `logoOptions` розміщує логотип у центрі QR-коду. Задайте `type`, щоб вибрати вид логотипа.

### Запропонований логотип

Задайте `type` значення `suggested` і виберіть `id` з каталогу. Щоб обійтися без логотипа, використовуйте `logo-none`.

```json theme={null}
{ "logoOptions": { "type": "suggested", "id": "logo-instagram", "scalePercent": 25 } }
```

> [accordion] Усі ID запропонованих логотипів
>
> `logo-none`, `logo-website-3`, `logo-website-4`, `logo-link`, `logo-pdf-1`, `logo-pdf-2`, `logo-pdf-3`, `logo-picture-1`, `logo-picture-2`, `logo-picture-3`, `logo-picture-5`, `logo-picture-7`, `logo-picture-8`, `logo-video-1`, `logo-video-5`, `logo-whatsapp-1`, `logo-whatsapp-2`, `logo-whatsapp`, `logo-wifi-1`, `logo-wifi-2`, `logo-wifi-3`, `logo-wifi`, `logo-airbnb`, `logo-apple`, `logo-binance`, `logo-bitcoin`, `logo-bolt-food`, `logo-booking`, `logo-facebook`, `logo-glovo`, `logo-google`, `logo-google-maps`, `logo-google-play`, `logo-instagram`, `logo-linkedin`, `logo-location`, `logo-mail`, `logo-paypal`, `logo-stripe`, `logo-venmo`, `logo-cashapp`, `logo-braintree`, `logo-square`, `logo-verifone`, `logo-google-pay`, `logo-apple-pay`, `logo-klarna`, `logo-ayden`, `logo-giropay`, `logo-cartes-bancaires`, `logo-restaurant`, `logo-scan-me`, `logo-tripadvisor`, `logo-trustpilot`, `logo-uber-eats`, `logo-youtube`, `logo-spotify`, `logo-spotify-black`

### Власний логотип

**1. Завантажте зображення**

Зареєструйте його через [Файли](https://docs.getqr.com/ua/api/endpoints/files.md) з `"target": "logo"`, а потім завантажте файл на отриманий `uploadUrl`.

**2. Пошліться на файл**

Задайте `type` значення `uploaded`, а `fileId` — отриманий `fileId`. `fileId` обов'язковий і має бути ID, який повернув ендпоінт Files.

```json theme={null}
{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }
```

Невідомий файл, незавершене завантаження або файл, завантажений для іншого target, відхиляються.

### Розмір логотипа

`scalePercent` задає розмір логотипа у відсотках від QR-коду. Приймає ціле число від 15 до 45. За замовчуванням 25. Інші значення, зокрема частки на кшталт `0.25`, повертають `422`.

## Оновлення дизайну

* **Часткові оновлення.** В [Оновленні QR-коду](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#оновлення-qr-коду) об'єкти `styles`, `frameOptions` і `logoOptions` об'єднуються зі збереженим дизайном. Частковий об'єкт змінює лише те, що в ньому вказано.
* **Зміна логотипа.** Вибір іншого логотипа замінює збережений, але зберігає його `scalePercent`.
* **Шаблони.** Якщо під час створення передано `templateId`, надіслані поля накладаються поверх дизайну шаблону. Див. [Шаблони](https://docs.getqr.com/ua/api/endpoints/templates.md).
* **Дизайни Branded і AI.** QR-код із `designKind` `branded` або `ai` створено в панелі керування. API не може редагувати його зображення, але зберігає його, коли ви змінюєте інші поля.
* **Читання дизайну.** Відповіді повертають збережений дизайн у `design` у тій самій структурі, що й поля запиту, тож його можна надіслати назад.

## Поширені проблеми

> [accordion] 422 "Error correction is always Q and is not an input"
>
> Приберіть `styles.qrOptions` із запиту.

> [accordion] 422 "Frame caption is at most 12 characters"
>
> Скоротіть `frameOptions.text` до 12 символів або менше.

> [accordion] 422 "Frame caption color must differ from the frame color"
>
> `textColor` і `color` однакові на рамці, яка показує підпис. Виберіть контрастний `textColor`.

> [accordion] 422 "Logo scale is a whole number from 15 to 45"
>
> Надсилайте `scalePercent` як цілий відсоток, наприклад `25`, а не `0.25`.

> [accordion] Колір кутів не змінюється
>
> Кути завжди використовують `dotsOptions.color`. `cornersSquareOptions.color` і `cornersDotOptions.color` ні на що не впливають.

## Що далі

> [card] [QR-коди](https://docs.getqr.com/ua/api/endpoints/qr-codes.md)

> [card] [Шаблони](https://docs.getqr.com/ua/api/endpoints/templates.md)

> [card] [Файли](https://docs.getqr.com/ua/api/endpoints/files.md)

> [card] [Огляд оформлення](https://docs.getqr.com/ua/design/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.